mirror of
https://github.com/garrytan/gstack.git
synced 2026-07-13 03:06:36 +02:00
Merge branch 'main' into garrytan/team-supabase-store
Brings in 48 commits from main (v0.15.7–v0.15.16): deterministic slugs, TabSession refactor, pair-agent tunnel fix, content security layers, community security wave, team-friendly install, interactive snapshots. Conflict resolution: - .gitignore: merged both sides (kept .factory/ + added .kiro/.opencode/ .slate/.cursor/.openclaw/ from main) - open-gstack-browser/SKILL.md: accepted main (renamed from .factory/) - setup-team-sync/SKILL.md: regenerated via gen:skill-docs - test/fixtures/golden/*: updated golden baselines for ship SKILL.md - codex-ship-SKILL.md: accepted main (renamed from .factory/) - package.json version: synced to VERSION (0.15.16.0) - bin/gstack-uninstall: check settings file exists before claiming SessionStart hook removal (fixes false positive on clean systems) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Garry Tan
+360
-58
@@ -9,7 +9,7 @@ description: |
|
||||
visual audits, use /design-review. Use when asked to "review the design plan"
|
||||
or "design critique".
|
||||
Proactively suggest when the user has a plan with UI/UX components that
|
||||
should be reviewed before implementation.
|
||||
should be reviewed before implementation. (gstack)
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Edit
|
||||
@@ -29,8 +29,7 @@ _UPD=$(~/.claude/skills/gstack/bin/gstack-update-check 2>/dev/null || .claude/sk
|
||||
mkdir -p ~/.gstack/sessions
|
||||
touch ~/.gstack/sessions/"$PPID"
|
||||
_SESSIONS=$(find ~/.gstack/sessions -mmin -120 -type f 2>/dev/null | wc -l | tr -d ' ')
|
||||
find ~/.gstack/sessions -mmin +120 -type f -delete 2>/dev/null || true
|
||||
_CONTRIB=$(~/.claude/skills/gstack/bin/gstack-config get gstack_contributor 2>/dev/null || true)
|
||||
find ~/.gstack/sessions -mmin +120 -type f -exec rm {} + 2>/dev/null || true
|
||||
_PROACTIVE=$(~/.claude/skills/gstack/bin/gstack-config get proactive 2>/dev/null || echo "true")
|
||||
_PROACTIVE_PROMPTED=$([ -f ~/.gstack/.proactive-prompted ] && echo "yes" || echo "no")
|
||||
_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
|
||||
@@ -51,7 +50,9 @@ _SESSION_ID="$$-$(date +%s)"
|
||||
echo "TELEMETRY: ${_TEL:-off}"
|
||||
echo "TEL_PROMPTED: $_TEL_PROMPTED"
|
||||
mkdir -p ~/.gstack/analytics
|
||||
if [ "$_TEL" != "off" ]; then
|
||||
echo '{"skill":"plan-design-review","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
|
||||
fi
|
||||
# zsh-compatible: use find instead of glob to avoid NOMATCH error
|
||||
for _PF in $(find ~/.gstack/analytics -maxdepth 1 -name '.pending-*' 2>/dev/null); do
|
||||
if [ -f "$_PF" ]; then
|
||||
@@ -62,6 +63,38 @@ for _PF in $(find ~/.gstack/analytics -maxdepth 1 -name '.pending-*' 2>/dev/null
|
||||
fi
|
||||
break
|
||||
done
|
||||
# Learnings count
|
||||
eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true
|
||||
_LEARN_FILE="${GSTACK_HOME:-$HOME/.gstack}/projects/${SLUG:-unknown}/learnings.jsonl"
|
||||
if [ -f "$_LEARN_FILE" ]; then
|
||||
_LEARN_COUNT=$(wc -l < "$_LEARN_FILE" 2>/dev/null | tr -d ' ')
|
||||
echo "LEARNINGS: $_LEARN_COUNT entries loaded"
|
||||
if [ "$_LEARN_COUNT" -gt 5 ] 2>/dev/null; then
|
||||
~/.claude/skills/gstack/bin/gstack-learnings-search --limit 3 2>/dev/null || true
|
||||
fi
|
||||
else
|
||||
echo "LEARNINGS: 0"
|
||||
fi
|
||||
# Session timeline: record skill start (local-only, never sent anywhere)
|
||||
~/.claude/skills/gstack/bin/gstack-timeline-log '{"skill":"plan-design-review","event":"started","branch":"'"$_BRANCH"'","session":"'"$_SESSION_ID"'"}' 2>/dev/null &
|
||||
# Check if CLAUDE.md has routing rules
|
||||
_HAS_ROUTING="no"
|
||||
if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md 2>/dev/null; then
|
||||
_HAS_ROUTING="yes"
|
||||
fi
|
||||
_ROUTING_DECLINED=$(~/.claude/skills/gstack/bin/gstack-config get routing_declined 2>/dev/null || echo "false")
|
||||
echo "HAS_ROUTING: $_HAS_ROUTING"
|
||||
echo "ROUTING_DECLINED: $_ROUTING_DECLINED"
|
||||
# Vendoring deprecation: detect if CWD has a vendored gstack copy
|
||||
_VENDORED="no"
|
||||
if [ -d ".claude/skills/gstack" ] && [ ! -L ".claude/skills/gstack" ]; then
|
||||
if [ -f ".claude/skills/gstack/VERSION" ] || [ -d ".claude/skills/gstack/.git" ]; then
|
||||
_VENDORED="yes"
|
||||
fi
|
||||
fi
|
||||
echo "VENDORED_GSTACK: $_VENDORED"
|
||||
# Detect spawned session (OpenClaw or other orchestrator)
|
||||
[ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true
|
||||
```
|
||||
|
||||
If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills AND do not
|
||||
@@ -143,6 +176,90 @@ touch ~/.gstack/.proactive-prompted
|
||||
|
||||
This only happens once. If `PROACTIVE_PROMPTED` is `yes`, skip this entirely.
|
||||
|
||||
If `HAS_ROUTING` is `no` AND `ROUTING_DECLINED` is `false` AND `PROACTIVE_PROMPTED` is `yes`:
|
||||
Check if a CLAUDE.md file exists in the project root. If it does not exist, create it.
|
||||
|
||||
Use AskUserQuestion:
|
||||
|
||||
> gstack works best when your project's CLAUDE.md includes skill routing rules.
|
||||
> This tells Claude to use specialized workflows (like /ship, /investigate, /qa)
|
||||
> instead of answering directly. It's a one-time addition, about 15 lines.
|
||||
|
||||
Options:
|
||||
- A) Add routing rules to CLAUDE.md (recommended)
|
||||
- B) No thanks, I'll invoke skills manually
|
||||
|
||||
If A: Append this section to the end of CLAUDE.md:
|
||||
|
||||
```markdown
|
||||
|
||||
## Skill routing
|
||||
|
||||
When the user's request matches an available skill, ALWAYS invoke it using the Skill
|
||||
tool as your FIRST action. Do NOT answer directly, do NOT use other tools first.
|
||||
The skill has specialized workflows that produce better results than ad-hoc answers.
|
||||
|
||||
Key routing rules:
|
||||
- Product ideas, "is this worth building", brainstorming → invoke office-hours
|
||||
- Bugs, errors, "why is this broken", 500 errors → invoke investigate
|
||||
- Ship, deploy, push, create PR → invoke ship
|
||||
- QA, test the site, find bugs → invoke qa
|
||||
- Code review, check my diff → invoke review
|
||||
- Update docs after shipping → invoke document-release
|
||||
- Weekly retro → invoke retro
|
||||
- Design system, brand → invoke design-consultation
|
||||
- Visual audit, design polish → invoke design-review
|
||||
- Architecture review → invoke plan-eng-review
|
||||
- Save progress, checkpoint, resume → invoke checkpoint
|
||||
- Code quality, health check → invoke health
|
||||
```
|
||||
|
||||
Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"`
|
||||
|
||||
If B: run `~/.claude/skills/gstack/bin/gstack-config set routing_declined true`
|
||||
Say "No problem. You can add routing rules later by running `gstack-config set routing_declined false` and re-running any skill."
|
||||
|
||||
This only happens once per project. If `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`, skip this entirely.
|
||||
|
||||
If `VENDORED_GSTACK` is `yes`: This project has a vendored copy of gstack at
|
||||
`.claude/skills/gstack/`. Vendoring is deprecated. We will not keep vendored copies
|
||||
up to date, so this project's gstack will fall behind.
|
||||
|
||||
Use AskUserQuestion (one-time per project, check for `~/.gstack/.vendoring-warned-$SLUG` marker):
|
||||
|
||||
> This project has gstack vendored in `.claude/skills/gstack/`. Vendoring is deprecated.
|
||||
> We won't keep this copy up to date, so you'll fall behind on new features and fixes.
|
||||
>
|
||||
> Want to migrate to team mode? It takes about 30 seconds.
|
||||
|
||||
Options:
|
||||
- A) Yes, migrate to team mode now
|
||||
- B) No, I'll handle it myself
|
||||
|
||||
If A:
|
||||
1. Run `git rm -r .claude/skills/gstack/`
|
||||
2. Run `echo '.claude/skills/gstack/' >> .gitignore`
|
||||
3. Run `~/.claude/skills/gstack/bin/gstack-team-init required` (or `optional`)
|
||||
4. Run `git add .claude/ .gitignore CLAUDE.md && git commit -m "chore: migrate gstack from vendored to team mode"`
|
||||
5. Tell the user: "Done. Each developer now runs: `cd ~/.claude/skills/gstack && ./setup --team`"
|
||||
|
||||
If B: say "OK, you're on your own to keep the vendored copy up to date."
|
||||
|
||||
Always run (regardless of choice):
|
||||
```bash
|
||||
eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true
|
||||
touch ~/.gstack/.vendoring-warned-${SLUG:-unknown}
|
||||
```
|
||||
|
||||
This only happens once per project. If the marker file exists, skip entirely.
|
||||
|
||||
If `SPAWNED_SESSION` is `"true"`, you are running inside a session spawned by an
|
||||
AI orchestrator (e.g., OpenClaw). In spawned sessions:
|
||||
- Do NOT use AskUserQuestion for interactive prompts. Auto-choose the recommended option.
|
||||
- Do NOT run upgrade checks, telemetry prompts, routing injection, or lake intro.
|
||||
- Focus on completing the task and reporting results via prose output.
|
||||
- End with a completion report: what shipped, decisions made, anything uncertain.
|
||||
|
||||
## Voice
|
||||
|
||||
You are GStack, an open source AI builder framework shaped by Garry Tan's product, startup, and engineering judgment. Encode how he thinks, not his biography.
|
||||
@@ -189,6 +306,51 @@ Avoid filler, throat-clearing, generic optimism, founder cosplay, and unsupporte
|
||||
|
||||
**Final test:** does this sound like a real cross-functional builder who wants to help someone make something people want, ship it, and make it actually work?
|
||||
|
||||
## Context Recovery
|
||||
|
||||
After compaction or at session start, check for recent project artifacts.
|
||||
This ensures decisions, plans, and progress survive context window compaction.
|
||||
|
||||
```bash
|
||||
eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)"
|
||||
_PROJ="${GSTACK_HOME:-$HOME/.gstack}/projects/${SLUG:-unknown}"
|
||||
if [ -d "$_PROJ" ]; then
|
||||
echo "--- RECENT ARTIFACTS ---"
|
||||
# Last 3 artifacts across ceo-plans/ and checkpoints/
|
||||
find "$_PROJ/ceo-plans" "$_PROJ/checkpoints" -type f -name "*.md" 2>/dev/null | xargs ls -t 2>/dev/null | head -3
|
||||
# Reviews for this branch
|
||||
[ -f "$_PROJ/${_BRANCH}-reviews.jsonl" ] && echo "REVIEWS: $(wc -l < "$_PROJ/${_BRANCH}-reviews.jsonl" | tr -d ' ') entries"
|
||||
# Timeline summary (last 5 events)
|
||||
[ -f "$_PROJ/timeline.jsonl" ] && tail -5 "$_PROJ/timeline.jsonl"
|
||||
# Cross-session injection
|
||||
if [ -f "$_PROJ/timeline.jsonl" ]; then
|
||||
_LAST=$(grep "\"branch\":\"${_BRANCH}\"" "$_PROJ/timeline.jsonl" 2>/dev/null | grep '"event":"completed"' | tail -1)
|
||||
[ -n "$_LAST" ] && echo "LAST_SESSION: $_LAST"
|
||||
# Predictive skill suggestion: check last 3 completed skills for patterns
|
||||
_RECENT_SKILLS=$(grep "\"branch\":\"${_BRANCH}\"" "$_PROJ/timeline.jsonl" 2>/dev/null | grep '"event":"completed"' | tail -3 | grep -o '"skill":"[^"]*"' | sed 's/"skill":"//;s/"//' | tr '\n' ',')
|
||||
[ -n "$_RECENT_SKILLS" ] && echo "RECENT_PATTERN: $_RECENT_SKILLS"
|
||||
fi
|
||||
_LATEST_CP=$(find "$_PROJ/checkpoints" -name "*.md" -type f 2>/dev/null | xargs ls -t 2>/dev/null | head -1)
|
||||
[ -n "$_LATEST_CP" ] && echo "LATEST_CHECKPOINT: $_LATEST_CP"
|
||||
echo "--- END ARTIFACTS ---"
|
||||
fi
|
||||
```
|
||||
|
||||
If artifacts are listed, read the most recent one to recover context.
|
||||
|
||||
If `LAST_SESSION` is shown, mention it briefly: "Last session on this branch ran
|
||||
/[skill] with [outcome]." If `LATEST_CHECKPOINT` exists, read it for full context
|
||||
on where work left off.
|
||||
|
||||
If `RECENT_PATTERN` is shown, look at the skill sequence. If a pattern repeats
|
||||
(e.g., review,ship,review), suggest: "Based on your recent pattern, you probably
|
||||
want /[next skill]."
|
||||
|
||||
**Welcome back message:** If any of LAST_SESSION, LATEST_CHECKPOINT, or RECENT ARTIFACTS
|
||||
are shown, synthesize a one-paragraph welcome briefing before proceeding:
|
||||
"Welcome back to {branch}. Last session: /{skill} ({outcome}). [Checkpoint summary if
|
||||
available]. [Health score if available]." Keep it to 2-3 sentences.
|
||||
|
||||
## AskUserQuestion Format
|
||||
|
||||
**ALWAYS follow this structure for every AskUserQuestion call:**
|
||||
@@ -234,24 +396,6 @@ Before building anything unfamiliar, **search first.** See `~/.claude/skills/gst
|
||||
jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true
|
||||
```
|
||||
|
||||
## Contributor Mode
|
||||
|
||||
If `_CONTRIB` is `true`: you are in **contributor mode**. At the end of each major workflow step, rate your gstack experience 0-10. If not a 10 and there's an actionable bug or improvement — file a field report.
|
||||
|
||||
**File only:** gstack tooling bugs where the input was reasonable but gstack failed. **Skip:** user app bugs, network errors, auth failures on user's site.
|
||||
|
||||
**To file:** write `~/.gstack/contributor-logs/{slug}.md`:
|
||||
```
|
||||
# {Title}
|
||||
**What I tried:** {action} | **What happened:** {result} | **Rating:** {0-10}
|
||||
## Repro
|
||||
1. {step}
|
||||
## What would make this a 10
|
||||
{one sentence}
|
||||
**Date:** {YYYY-MM-DD} | **Version:** {version} | **Skill:** /{skill}
|
||||
```
|
||||
Slug: lowercase hyphens, max 60 chars. Skip if exists. Max 3/session. File inline, don't stop.
|
||||
|
||||
## Completion Status Protocol
|
||||
|
||||
When completing a skill workflow, report status using one of:
|
||||
@@ -277,6 +421,24 @@ ATTEMPTED: [what you tried]
|
||||
RECOMMENDATION: [what the user should do next]
|
||||
```
|
||||
|
||||
## Operational Self-Improvement
|
||||
|
||||
Before completing, reflect on this session:
|
||||
- Did any commands fail unexpectedly?
|
||||
- Did you take a wrong approach and have to backtrack?
|
||||
- Did you discover a project-specific quirk (build order, env vars, timing, auth)?
|
||||
- Did something take longer than expected because of a missing flag or config?
|
||||
|
||||
If yes, log an operational learning for future sessions:
|
||||
|
||||
```bash
|
||||
~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}'
|
||||
```
|
||||
|
||||
Replace SKILL_NAME with the current skill name. Only log genuine operational discoveries.
|
||||
Don't log obvious things or one-time transient errors (network blips, rate limits).
|
||||
A good test: would knowing this save 5+ minutes in a future session? If yes, log it.
|
||||
|
||||
## Telemetry (run last)
|
||||
|
||||
After the skill workflow completes (success, error, or abort), log the telemetry event.
|
||||
@@ -295,8 +457,12 @@ Run this bash:
|
||||
_TEL_END=$(date +%s)
|
||||
_TEL_DUR=$(( _TEL_END - _TEL_START ))
|
||||
rm -f ~/.gstack/analytics/.pending-"$_SESSION_ID" 2>/dev/null || true
|
||||
# Local analytics (always available, no binary needed)
|
||||
# Session timeline: record skill completion (local-only, never sent anywhere)
|
||||
~/.claude/skills/gstack/bin/gstack-timeline-log '{"skill":"SKILL_NAME","event":"completed","branch":"'$(git branch --show-current 2>/dev/null || echo unknown)'","outcome":"OUTCOME","duration_s":"'"$_TEL_DUR"'","session":"'"$_SESSION_ID"'"}' 2>/dev/null || true
|
||||
# Local analytics (gated on telemetry setting)
|
||||
if [ "$_TEL" != "off" ]; then
|
||||
echo '{"skill":"SKILL_NAME","duration_s":"'"$_TEL_DUR"'","outcome":"OUTCOME","browse":"USED_BROWSE","session":"'"$_SESSION_ID"'","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
|
||||
fi
|
||||
# Remote telemetry (opt-in, requires binary)
|
||||
if [ "$_TEL" != "off" ] && [ -x ~/.claude/skills/gstack/bin/gstack-telemetry-log ]; then
|
||||
~/.claude/skills/gstack/bin/gstack-telemetry-log \
|
||||
@@ -310,6 +476,46 @@ success/error/abort, and `USED_BROWSE` with true/false based on whether `$B` was
|
||||
If you cannot determine the outcome, use "unknown". The local JSONL always logs. The
|
||||
remote binary only runs if telemetry is not off and the binary exists.
|
||||
|
||||
## Plan Mode Safe Operations
|
||||
|
||||
When in plan mode, these operations are always allowed because they produce
|
||||
artifacts that inform the plan, not code changes:
|
||||
|
||||
- `$B` commands (browse: screenshots, page inspection, navigation, snapshots)
|
||||
- `$D` commands (design: generate mockups, variants, comparison boards, iterate)
|
||||
- `codex exec` / `codex review` (outside voice, plan review, adversarial challenge)
|
||||
- Writing to `~/.gstack/` (config, analytics, review logs, design artifacts, learnings)
|
||||
- Writing to the plan file (already allowed by plan mode)
|
||||
- `open` commands for viewing generated artifacts (comparison boards, HTML previews)
|
||||
|
||||
These are read-only in spirit — they inspect the live site, generate visual artifacts,
|
||||
or get independent opinions. They do NOT modify project source files.
|
||||
|
||||
## Skill Invocation During Plan Mode
|
||||
|
||||
If a user invokes a skill during plan mode, that invoked skill workflow takes
|
||||
precedence over generic plan mode behavior until it finishes or the user explicitly
|
||||
cancels that skill.
|
||||
|
||||
Treat the loaded skill as executable instructions, not reference material. Follow
|
||||
it step by step. Do not summarize, skip, reorder, or shortcut its steps.
|
||||
|
||||
If the skill says to use AskUserQuestion, do that. Those AskUserQuestion calls
|
||||
satisfy plan mode's requirement to end turns with AskUserQuestion.
|
||||
|
||||
If the skill reaches a STOP point, stop immediately at that point, ask the required
|
||||
question if any, and wait for the user's response. Do not continue the workflow
|
||||
past a STOP point, and do not call ExitPlanMode at that point.
|
||||
|
||||
If the skill includes commands marked "PLAN MODE EXCEPTION — ALWAYS RUN," execute
|
||||
them. The skill may edit the plan file, and other writes are allowed only if they
|
||||
are already permitted by Plan Mode Safe Operations or explicitly marked as a plan
|
||||
mode exception.
|
||||
|
||||
Only call ExitPlanMode after the active skill workflow is complete and there are no
|
||||
other invoked skill workflows left to run, or if the user explicitly tells you to
|
||||
cancel the skill or leave plan mode.
|
||||
|
||||
## Plan Status Footer
|
||||
|
||||
When you are in plan mode and about to call ExitPlanMode:
|
||||
@@ -338,6 +544,7 @@ Then write a `## GSTACK REVIEW REPORT` section to the end of the plan file:
|
||||
| Codex Review | \`/codex review\` | Independent 2nd opinion | 0 | — | — |
|
||||
| Eng Review | \`/plan-eng-review\` | Architecture & tests (required) | 0 | — | — |
|
||||
| Design Review | \`/plan-design-review\` | UI/UX gaps | 0 | — | — |
|
||||
| DX Review | \`/plan-devex-review\` | Developer experience gaps | 0 | — | — |
|
||||
|
||||
**VERDICT:** NO REVIEWS YET — run \`/autoplan\` for full review pipeline, or individual reviews above.
|
||||
\`\`\`
|
||||
@@ -611,11 +818,10 @@ $D check --image "$_DESIGN_DIR/variant-A.png" --brief "<the original brief>"
|
||||
|
||||
Flag any variants that fail the quality check. Offer to regenerate failures.
|
||||
|
||||
Show each variant inline (Read tool on each PNG) so the user sees them immediately.
|
||||
|
||||
Tell the user: "I've generated design directions. Take a look at the variants above,
|
||||
then use the comparison board that just opened in your browser to pick your favorite,
|
||||
rate the others, remix elements, and click Submit when you're done."
|
||||
**Do NOT show variants inline via Read tool and ask for preferences.** Proceed
|
||||
directly to the Comparison Board + Feedback Loop section below. The comparison board
|
||||
IS the chooser — it has rating controls, comments, remix/regenerate, and structured
|
||||
feedback output. Showing mockups inline is a degraded experience.
|
||||
|
||||
### Comparison Board + Feedback Loop
|
||||
|
||||
@@ -627,31 +833,42 @@ $D compare --images "$_DESIGN_DIR/variant-A.png,$_DESIGN_DIR/variant-B.png,$_DES
|
||||
|
||||
This command generates the board HTML, starts an HTTP server on a random port,
|
||||
and opens it in the user's default browser. **Run it in the background** with `&`
|
||||
because the agent needs to keep running while the user interacts with the board.
|
||||
because the server needs to stay running while the user interacts with the board.
|
||||
|
||||
**IMPORTANT: Reading feedback via file polling (not stdout):**
|
||||
Parse the port from stderr output: `SERVE_STARTED: port=XXXXX`. You need this
|
||||
for the board URL and for reloading during regeneration cycles.
|
||||
|
||||
The server writes feedback to files next to the board HTML. The agent polls for these:
|
||||
**PRIMARY WAIT: AskUserQuestion with board URL**
|
||||
|
||||
After the board is serving, use AskUserQuestion to wait for the user. Include the
|
||||
board URL so they can click it if they lost the browser tab:
|
||||
|
||||
"I've opened a comparison board with the design variants:
|
||||
http://127.0.0.1:<PORT>/ — Rate them, leave comments, remix
|
||||
elements you like, and click Submit when you're done. Let me know when you've
|
||||
submitted your feedback (or paste your preferences here). If you clicked
|
||||
Regenerate or Remix on the board, tell me and I'll generate new variants."
|
||||
|
||||
**Do NOT use AskUserQuestion to ask which variant the user prefers.** The comparison
|
||||
board IS the chooser. AskUserQuestion is just the blocking wait mechanism.
|
||||
|
||||
**After the user responds to AskUserQuestion:**
|
||||
|
||||
Check for feedback files next to the board HTML:
|
||||
- `$_DESIGN_DIR/feedback.json` — written when user clicks Submit (final choice)
|
||||
- `$_DESIGN_DIR/feedback-pending.json` — written when user clicks Regenerate/Remix/More Like This
|
||||
|
||||
**Polling loop** (run after launching `$D serve` in background):
|
||||
|
||||
```bash
|
||||
# Poll for feedback files every 5 seconds (up to 10 minutes)
|
||||
for i in $(seq 1 120); do
|
||||
if [ -f "$_DESIGN_DIR/feedback.json" ]; then
|
||||
echo "SUBMIT_RECEIVED"
|
||||
cat "$_DESIGN_DIR/feedback.json"
|
||||
break
|
||||
elif [ -f "$_DESIGN_DIR/feedback-pending.json" ]; then
|
||||
echo "REGENERATE_RECEIVED"
|
||||
cat "$_DESIGN_DIR/feedback-pending.json"
|
||||
rm "$_DESIGN_DIR/feedback-pending.json"
|
||||
break
|
||||
fi
|
||||
sleep 5
|
||||
done
|
||||
if [ -f "$_DESIGN_DIR/feedback.json" ]; then
|
||||
echo "SUBMIT_RECEIVED"
|
||||
cat "$_DESIGN_DIR/feedback.json"
|
||||
elif [ -f "$_DESIGN_DIR/feedback-pending.json" ]; then
|
||||
echo "REGENERATE_RECEIVED"
|
||||
cat "$_DESIGN_DIR/feedback-pending.json"
|
||||
rm "$_DESIGN_DIR/feedback-pending.json"
|
||||
else
|
||||
echo "NO_FEEDBACK_FILE"
|
||||
fi
|
||||
```
|
||||
|
||||
The feedback JSON has this shape:
|
||||
@@ -665,24 +882,30 @@ The feedback JSON has this shape:
|
||||
}
|
||||
```
|
||||
|
||||
**If `feedback-pending.json` found (`"regenerated": true`):**
|
||||
**If `feedback.json` found:** The user clicked Submit on the board.
|
||||
Read `preferred`, `ratings`, `comments`, `overall` from the JSON. Proceed with
|
||||
the approved variant.
|
||||
|
||||
**If `feedback-pending.json` found:** The user clicked Regenerate/Remix on the board.
|
||||
1. Read `regenerateAction` from the JSON (`"different"`, `"match"`, `"more_like_B"`,
|
||||
`"remix"`, or custom text)
|
||||
2. If `regenerateAction` is `"remix"`, read `remixSpec` (e.g. `{"layout":"A","colors":"B"}`)
|
||||
3. Generate new variants with `$D iterate` or `$D variants` using updated brief
|
||||
4. Create new board: `$D compare --images "..." --output "$_DESIGN_DIR/design-board.html"`
|
||||
5. Parse the port from the `$D serve` stderr output (`SERVE_STARTED: port=XXXXX`),
|
||||
then reload the board in the user's browser (same tab):
|
||||
5. Reload the board in the user's browser (same tab):
|
||||
`curl -s -X POST http://127.0.0.1:PORT/api/reload -H 'Content-Type: application/json' -d '{"html":"$_DESIGN_DIR/design-board.html"}'`
|
||||
6. The board auto-refreshes. **Poll again** for the next feedback file.
|
||||
7. Repeat until `feedback.json` appears (user clicked Submit).
|
||||
6. The board auto-refreshes. **AskUserQuestion again** with the same board URL to
|
||||
wait for the next round of feedback. Repeat until `feedback.json` appears.
|
||||
|
||||
**If `feedback.json` found (`"regenerated": false`):**
|
||||
1. Read `preferred`, `ratings`, `comments`, `overall` from the JSON
|
||||
2. Proceed with the approved variant
|
||||
**If `NO_FEEDBACK_FILE`:** The user typed their preferences directly in the
|
||||
AskUserQuestion response instead of using the board. Use their text response
|
||||
as the feedback.
|
||||
|
||||
**If `$D serve` fails or no feedback within 10 minutes:** Fall back to AskUserQuestion:
|
||||
"I've opened the design board. Which variant do you prefer? Any feedback?"
|
||||
**POLLING FALLBACK:** Only use polling if `$D serve` fails (no port available).
|
||||
In that case, show each variant inline using the Read tool (so the user can see them),
|
||||
then use AskUserQuestion:
|
||||
"The comparison board server failed to start. I've shown the variants above.
|
||||
Which do you prefer? Any feedback?"
|
||||
|
||||
**After receiving feedback (any path):** Output a clear summary confirming
|
||||
what was understood:
|
||||
@@ -849,6 +1072,46 @@ descriptions of what 10/10 looks like.
|
||||
|
||||
## Review Sections (7 passes, after scope is agreed)
|
||||
|
||||
**Anti-skip rule:** Never condense, abbreviate, or skip any review pass (1-7) regardless of plan type (strategy, spec, code, infra). Every pass in this skill exists for a reason. "This is a strategy doc so design passes don't apply" is always wrong — design gaps are where implementation breaks down. If a pass genuinely has zero findings, say "No issues found" and move on — but you must evaluate it.
|
||||
|
||||
## Prior Learnings
|
||||
|
||||
Search for relevant learnings from previous sessions:
|
||||
|
||||
```bash
|
||||
_CROSS_PROJ=$(~/.claude/skills/gstack/bin/gstack-config get cross_project_learnings 2>/dev/null || echo "unset")
|
||||
echo "CROSS_PROJECT: $_CROSS_PROJ"
|
||||
if [ "$_CROSS_PROJ" = "true" ]; then
|
||||
~/.claude/skills/gstack/bin/gstack-learnings-search --limit 10 --cross-project 2>/dev/null || true
|
||||
else
|
||||
~/.claude/skills/gstack/bin/gstack-learnings-search --limit 10 2>/dev/null || true
|
||||
fi
|
||||
```
|
||||
|
||||
If `CROSS_PROJECT` is `unset` (first time): Use AskUserQuestion:
|
||||
|
||||
> gstack can search learnings from your other projects on this machine to find
|
||||
> patterns that might apply here. This stays local (no data leaves your machine).
|
||||
> Recommended for solo developers. Skip if you work on multiple client codebases
|
||||
> where cross-contamination would be a concern.
|
||||
|
||||
Options:
|
||||
- A) Enable cross-project learnings (recommended)
|
||||
- B) Keep learnings project-scoped only
|
||||
|
||||
If A: run `~/.claude/skills/gstack/bin/gstack-config set cross_project_learnings true`
|
||||
If B: run `~/.claude/skills/gstack/bin/gstack-config set cross_project_learnings false`
|
||||
|
||||
Then re-run the search with the appropriate flag.
|
||||
|
||||
If learnings are found, incorporate them into your analysis. When a review finding
|
||||
matches a past learning, display:
|
||||
|
||||
**"Prior learning applied: [key] (confidence N/10, from [date])"**
|
||||
|
||||
This makes the compounding visible. The user should see that gstack is getting
|
||||
smarter on their codebase over time.
|
||||
|
||||
### Pass 1: Information Architecture
|
||||
Rate 0-10: Does the plan define what the user sees first, second, third?
|
||||
FIX TO 10: Add information hierarchy to the plan. Include ASCII diagram of screen/page structure and navigation flow. Apply "constraint worship" — if you can only show 3 things, which 3?
|
||||
@@ -996,6 +1259,7 @@ Follow the AskUserQuestion format from the Preamble above. Additional rules for
|
||||
* **Map to Design Principles above.** One sentence connecting your recommendation to a specific principle.
|
||||
* Label with issue NUMBER + option LETTER (e.g., "3A", "3B").
|
||||
* **Escape hatch:** If a section has no issues, say so and move on. If a gap has an obvious fix, state what you'll add and move on — don't waste a question on it. Only use AskUserQuestion when there is a genuine design choice with meaningful tradeoffs.
|
||||
* **NEVER use AskUserQuestion to ask which variant the user prefers.** Always create a comparison board first (`$D compare --serve`) and open it in the browser. The board has rating controls, comments, remix/regenerate buttons, and structured feedback output. Use AskUserQuestion ONLY to notify the user the board is open and wait for them to finish — not to present variants inline and ask "which do you prefer?" That is a degraded experience.
|
||||
|
||||
## Required Outputs
|
||||
|
||||
@@ -1124,7 +1388,7 @@ Display:
|
||||
- **Eng Review (required by default):** The only review that gates shipping. Covers architecture, code quality, tests, performance. Can be disabled globally with \`gstack-config set skip_eng_review true\` (the "don't bother me" setting).
|
||||
- **CEO Review (optional):** Use your judgment. Recommend it for big product/business changes, new user-facing features, or scope decisions. Skip for bug fixes, refactors, infra, and cleanup.
|
||||
- **Design Review (optional):** Use your judgment. Recommend it for UI/UX changes. Skip for backend-only, infra, or prompt-only changes.
|
||||
- **Adversarial Review (automatic):** Auto-scales by diff size. Small diffs (<50 lines) skip adversarial. Medium diffs (50–199) get cross-model adversarial. Large diffs (200+) get all 4 passes: Claude structured, Codex structured, Claude adversarial subagent, Codex adversarial. No configuration needed.
|
||||
- **Adversarial Review (automatic):** Always-on for every review. Every diff gets both Claude adversarial subagent and Codex adversarial challenge. Large diffs (200+ lines) additionally get Codex structured review with P1 gate. No configuration needed.
|
||||
- **Outside Voice (optional):** Independent plan review from a different AI model. Offered after all review sections complete in /plan-ceo-review and /plan-eng-review. Falls back to Claude subagent if Codex is unavailable. Never gates shipping.
|
||||
|
||||
**Verdict logic:**
|
||||
@@ -1162,6 +1426,10 @@ Parse each JSONL entry. Each skill logs different fields:
|
||||
→ Findings: "{issues_found} issues, {critical_gaps} critical gaps"
|
||||
- **plan-design-review**: \`status\`, \`initial_score\`, \`overall_score\`, \`unresolved\`, \`decisions_made\`, \`commit\`
|
||||
→ Findings: "score: {initial_score}/10 → {overall_score}/10, {decisions_made} decisions"
|
||||
- **plan-devex-review**: \`status\`, \`initial_score\`, \`overall_score\`, \`product_type\`, \`tthw_current\`, \`tthw_target\`, \`mode\`, \`persona\`, \`competitive_tier\`, \`unresolved\`, \`commit\`
|
||||
→ Findings: "score: {initial_score}/10 → {overall_score}/10, TTHW: {tthw_current} → {tthw_target}"
|
||||
- **devex-review**: \`status\`, \`overall_score\`, \`product_type\`, \`tthw_measured\`, \`dimensions_tested\`, \`dimensions_inferred\`, \`boomerang\`, \`commit\`
|
||||
→ Findings: "score: {overall_score}/10, TTHW: {tthw_measured}, {dimensions_tested} tested/{dimensions_inferred} inferred"
|
||||
- **codex-review**: \`status\`, \`gate\`, \`findings\`, \`findings_fixed\`
|
||||
→ Findings: "{findings} findings, {findings_fixed}/{findings} fixed"
|
||||
|
||||
@@ -1180,6 +1448,7 @@ Produce this markdown table:
|
||||
| Codex Review | \`/codex review\` | Independent 2nd opinion | {runs} | {status} | {findings} |
|
||||
| Eng Review | \`/plan-eng-review\` | Architecture & tests (required) | {runs} | {status} | {findings} |
|
||||
| Design Review | \`/plan-design-review\` | UI/UX gaps | {runs} | {status} | {findings} |
|
||||
| DX Review | \`/plan-devex-review\` | Developer experience gaps | {runs} | {status} | {findings} |
|
||||
\`\`\`
|
||||
|
||||
Below the table, add these lines (omit any that are empty/not applicable):
|
||||
@@ -1206,6 +1475,31 @@ plan's living status.
|
||||
- Always place it as the very last section in the plan file. If it was found mid-file,
|
||||
move it: delete the old location and append at the end.
|
||||
|
||||
## Capture Learnings
|
||||
|
||||
If you discovered a non-obvious pattern, pitfall, or architectural insight during
|
||||
this session, log it for future sessions:
|
||||
|
||||
```bash
|
||||
~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"plan-design-review","type":"TYPE","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"SOURCE","files":["path/to/relevant/file"]}'
|
||||
```
|
||||
|
||||
**Types:** `pattern` (reusable approach), `pitfall` (what NOT to do), `preference`
|
||||
(user stated), `architecture` (structural decision), `tool` (library/framework insight),
|
||||
`operational` (project environment/CLI/workflow knowledge).
|
||||
|
||||
**Sources:** `observed` (you found this in the code), `user-stated` (user told you),
|
||||
`inferred` (AI deduction), `cross-model` (both Claude and Codex agree).
|
||||
|
||||
**Confidence:** 1-10. Be honest. An observed pattern you verified in the code is 8-9.
|
||||
An inference you're not sure about is 4-5. A user preference they explicitly stated is 10.
|
||||
|
||||
**files:** Include the specific file paths this learning references. This enables
|
||||
staleness detection: if those files are later deleted, the learning can be flagged.
|
||||
|
||||
**Only log genuine discoveries.** Don't log obvious things. Don't log things the user
|
||||
already knows. A good test: would this insight save time in a future session? If yes, log it.
|
||||
|
||||
## Next Steps — Review Chaining
|
||||
|
||||
After displaying the Review Readiness Dashboard, recommend the next review(s) based on what this design review discovered. Read the dashboard output to see which reviews have already been run and whether they are stale.
|
||||
@@ -1216,10 +1510,18 @@ After displaying the Review Readiness Dashboard, recommend the next review(s) ba
|
||||
|
||||
**If both are needed, recommend eng review first** (required gate).
|
||||
|
||||
**Recommend design exploration skills when appropriate** — /design-shotgun and /design-html
|
||||
produce design artifacts (mockups, HTML previews), not application code. They belong in
|
||||
plan mode alongside reviews. If this design review found visual issues that would benefit
|
||||
from exploring new directions, recommend /design-shotgun. If approved mockups exist and
|
||||
need to be turned into working HTML, recommend /design-html.
|
||||
|
||||
Use AskUserQuestion to present the next step. Include only applicable options:
|
||||
- **A)** Run /plan-eng-review next (required gate)
|
||||
- **B)** Run /plan-ceo-review (only if fundamental product gaps found)
|
||||
- **C)** Skip — I'll handle reviews manually
|
||||
- **C)** Run /design-shotgun — explore visual design variants for issues found
|
||||
- **D)** Run /design-html — generate Pretext-native HTML from approved mockups
|
||||
- **E)** Skip — I'll handle next steps manually
|
||||
|
||||
## Formatting Rules
|
||||
* NUMBER issues (1, 2, 3...) and LETTERS for options (A, B, C...).
|
||||
|
||||
@@ -9,7 +9,7 @@ description: |
|
||||
visual audits, use /design-review. Use when asked to "review the design plan"
|
||||
or "design critique".
|
||||
Proactively suggest when the user has a plan with UI/UX components that
|
||||
should be reviewed before implementation.
|
||||
should be reviewed before implementation. (gstack)
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Edit
|
||||
@@ -208,11 +208,10 @@ $D check --image "$_DESIGN_DIR/variant-A.png" --brief "<the original brief>"
|
||||
|
||||
Flag any variants that fail the quality check. Offer to regenerate failures.
|
||||
|
||||
Show each variant inline (Read tool on each PNG) so the user sees them immediately.
|
||||
|
||||
Tell the user: "I've generated design directions. Take a look at the variants above,
|
||||
then use the comparison board that just opened in your browser to pick your favorite,
|
||||
rate the others, remix elements, and click Submit when you're done."
|
||||
**Do NOT show variants inline via Read tool and ask for preferences.** Proceed
|
||||
directly to the Comparison Board + Feedback Loop section below. The comparison board
|
||||
IS the chooser — it has rating controls, comments, remix/regenerate, and structured
|
||||
feedback output. Showing mockups inline is a degraded experience.
|
||||
|
||||
{{DESIGN_SHOTGUN_LOOP}}
|
||||
|
||||
@@ -257,6 +256,10 @@ descriptions of what 10/10 looks like.
|
||||
|
||||
## Review Sections (7 passes, after scope is agreed)
|
||||
|
||||
**Anti-skip rule:** Never condense, abbreviate, or skip any review pass (1-7) regardless of plan type (strategy, spec, code, infra). Every pass in this skill exists for a reason. "This is a strategy doc so design passes don't apply" is always wrong — design gaps are where implementation breaks down. If a pass genuinely has zero findings, say "No issues found" and move on — but you must evaluate it.
|
||||
|
||||
{{LEARNINGS_SEARCH}}
|
||||
|
||||
### Pass 1: Information Architecture
|
||||
Rate 0-10: Does the plan define what the user sees first, second, third?
|
||||
FIX TO 10: Add information hierarchy to the plan. Include ASCII diagram of screen/page structure and navigation flow. Apply "constraint worship" — if you can only show 3 things, which 3?
|
||||
@@ -337,6 +340,7 @@ Follow the AskUserQuestion format from the Preamble above. Additional rules for
|
||||
* **Map to Design Principles above.** One sentence connecting your recommendation to a specific principle.
|
||||
* Label with issue NUMBER + option LETTER (e.g., "3A", "3B").
|
||||
* **Escape hatch:** If a section has no issues, say so and move on. If a gap has an obvious fix, state what you'll add and move on — don't waste a question on it. Only use AskUserQuestion when there is a genuine design choice with meaningful tradeoffs.
|
||||
* **NEVER use AskUserQuestion to ask which variant the user prefers.** Always create a comparison board first (`$D compare --serve`) and open it in the browser. The board has rating controls, comments, remix/regenerate buttons, and structured feedback output. Use AskUserQuestion ONLY to notify the user the board is open and wait for them to finish — not to present variants inline and ask "which do you prefer?" That is a degraded experience.
|
||||
|
||||
## Required Outputs
|
||||
|
||||
@@ -433,6 +437,8 @@ Substitute values from the Completion Summary:
|
||||
|
||||
{{PLAN_FILE_REVIEW_REPORT}}
|
||||
|
||||
{{LEARNINGS_LOG}}
|
||||
|
||||
## Next Steps — Review Chaining
|
||||
|
||||
After displaying the Review Readiness Dashboard, recommend the next review(s) based on what this design review discovered. Read the dashboard output to see which reviews have already been run and whether they are stale.
|
||||
@@ -443,10 +449,18 @@ After displaying the Review Readiness Dashboard, recommend the next review(s) ba
|
||||
|
||||
**If both are needed, recommend eng review first** (required gate).
|
||||
|
||||
**Recommend design exploration skills when appropriate** — /design-shotgun and /design-html
|
||||
produce design artifacts (mockups, HTML previews), not application code. They belong in
|
||||
plan mode alongside reviews. If this design review found visual issues that would benefit
|
||||
from exploring new directions, recommend /design-shotgun. If approved mockups exist and
|
||||
need to be turned into working HTML, recommend /design-html.
|
||||
|
||||
Use AskUserQuestion to present the next step. Include only applicable options:
|
||||
- **A)** Run /plan-eng-review next (required gate)
|
||||
- **B)** Run /plan-ceo-review (only if fundamental product gaps found)
|
||||
- **C)** Skip — I'll handle reviews manually
|
||||
- **C)** Run /design-shotgun — explore visual design variants for issues found
|
||||
- **D)** Run /design-html — generate Pretext-native HTML from approved mockups
|
||||
- **E)** Skip — I'll handle next steps manually
|
||||
|
||||
## Formatting Rules
|
||||
* NUMBER issues (1, 2, 3...) and LETTERS for options (A, B, C...).
|
||||
|
||||
Reference in New Issue
Block a user