From e7b545143166ea4af1794d8a3585c0c59e6630ba Mon Sep 17 00:00:00 2001 From: Stefan Andrei <89592870+sneakygriff@users.noreply.github.com> Date: Wed, 15 Jul 2026 15:45:03 +0300 Subject: [PATCH] Add /plan-deliverables skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Authors per-milestone acceptance criteria — each measurable and paired with the check that validates it (the deliverable) — into the design doc, in a format /autobuilder-loop parses. Closes a real gap: autobuilder-loop re-reads per-milestone {next_milestone, acceptance_criteria} from the plan each iteration, but nothing upstream authored that field. Runs after /office-hours, before the plan reviews. Per-piece loop: draft criteria -> default-on cross-model gap-check (Codex gpt-5.6-sol ultra + Grok grok-build, honoring the existing codex_reviews/grok_reviews kill-switches) -> probe the user for judgment calls -> pair each criterion with a repo-native validating check (or an explicit manual-verification) -> write the block. Idempotent and resume-safe. Wires the two skills together via milestone markers: autobuilder-loop step 1.0 selects the first pending milestone; step e and the deferral valve write status back. Registered in the router, coverage matrix, office-hours/plan-eng-review chaining, README and CLAUDE.md. Co-Authored-By: Claude Opus 4.8 --- CLAUDE.md | 2 + README.md | 5 +- SKILL.md | 1 + SKILL.md.tmpl | 1 + autobuilder-loop/SKILL.md | 18 +- autobuilder-loop/SKILL.md.tmpl | 18 +- gstack/llms.txt | 1 + office-hours/sections/design-and-handoff.md | 3 +- .../sections/design-and-handoff.md.tmpl | 3 +- plan-deliverables/SKILL.md | 1237 +++++++++++++++++ plan-deliverables/SKILL.md.tmpl | 358 +++++ plan-eng-review/sections/review-sections.md | 5 +- .../sections/review-sections.md.tmpl | 5 +- scripts/proactive-suggestions.json | 5 + test/skill-coverage-matrix.ts | 5 + 15 files changed, 1651 insertions(+), 16 deletions(-) create mode 100644 plan-deliverables/SKILL.md create mode 100644 plan-deliverables/SKILL.md.tmpl diff --git a/CLAUDE.md b/CLAUDE.md index 984844902..4c272c951 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -119,6 +119,7 @@ gstack/ ├── review/ # PR review skill ├── plan-ceo-review/ # /plan-ceo-review skill ├── plan-eng-review/ # /plan-eng-review skill +├── plan-deliverables/ # /plan-deliverables skill ├── autoplan/ # /autoplan skill (auto-review pipeline: CEO → design → eng) ├── benchmark/ # /benchmark skill (performance regression detection) ├── canary/ # /canary skill (post-deploy monitoring loop) @@ -942,6 +943,7 @@ When the user's request matches an available skill, invoke it via the Skill tool Key routing rules: - Product ideas/brainstorming → invoke /office-hours +- Acceptance criteria / deliverables / definition of done for a plan → invoke /plan-deliverables - Strategy/scope → invoke /plan-ceo-review - Architecture → invoke /plan-eng-review - Design system/plan review → invoke /design-consultation or /plan-design-review diff --git a/README.md b/README.md index 4bb177c3a..2326b7f5f 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,7 @@ Fork it. Improve it. Make it yours. And if you want to hate on free open source Open Claude Code and paste this. Claude does the rest. -> Install gstack: run **`git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup`** then add a "gstack" section to CLAUDE.md that says to use the /browse skill from gstack for all web browsing, never use mcp\_\_claude-in-chrome\_\_\* tools, and lists the available skills: /office-hours, /plan-ceo-review, /plan-eng-review, /plan-design-review, /design-consultation, /design-shotgun, /design-html, /review, /ship, /land-and-deploy, /canary, /benchmark, /browse, /connect-chrome, /qa, /qa-only, /design-review, /setup-browser-cookies, /setup-deploy, /setup-gbrain, /retro, /investigate, /document-release, /document-generate, /codex, /cso, /autoplan, /plan-devex-review, /devex-review, /careful, /freeze, /guard, /unfreeze, /gstack-upgrade, /learn. Then ask the user if they also want to add gstack to the current project so teammates get it. +> Install gstack: run **`git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup`** then add a "gstack" section to CLAUDE.md that says to use the /browse skill from gstack for all web browsing, never use mcp\_\_claude-in-chrome\_\_\* tools, and lists the available skills: /office-hours, /plan-deliverables, /plan-ceo-review, /plan-eng-review, /plan-design-review, /design-consultation, /design-shotgun, /design-html, /review, /ship, /land-and-deploy, /canary, /benchmark, /browse, /connect-chrome, /qa, /qa-only, /design-review, /setup-browser-cookies, /setup-deploy, /setup-gbrain, /retro, /investigate, /document-release, /document-generate, /codex, /cso, /autoplan, /plan-devex-review, /devex-review, /careful, /freeze, /guard, /unfreeze, /gstack-upgrade, /learn. Then ask the user if they also want to add gstack to the current project so teammates get it. ### Step 2: Team mode — auto-update for shared repos (recommended) @@ -179,6 +179,7 @@ Each skill feeds into the next. `/office-hours` writes a design doc that `/plan- | Skill | Your specialist | What they do | |-------|----------------|--------------| | `/office-hours` | **YC Office Hours** | Start here. Six forcing questions that reframe your product before you write code. Pushes back on your framing, challenges premises, generates implementation alternatives. Design doc feeds into every downstream skill. | +| `/plan-deliverables` | **Planner** | Author per-milestone acceptance criteria, each paired with a validating test (the deliverable), and bake them into the plan. | | `/plan-ceo-review` | **CEO / Founder** | Rethink the problem. Find the 10-star product hiding inside the request. Four modes: Expansion, Selective Expansion, Hold Scope, Reduction. | | `/plan-eng-review` | **Eng Manager** | Lock in architecture, data flow, diagrams, edge cases, and tests. Forces hidden assumptions into the open. | | `/plan-design-review` | **Senior Designer** | Rates each design dimension 0-10, explains what a 10 looks like, then edits the plan to get there. AI Slop detection. Interactive — one AskUserQuestion per design choice. | @@ -477,7 +478,7 @@ On Windows without Developer Mode (MSYS2 / Git Bash), `setup` falls back to file ``` ## gstack Use /browse from gstack for all web browsing. Never use mcp__claude-in-chrome__* tools. -Available skills: /office-hours, /plan-ceo-review, /plan-eng-review, /plan-design-review, +Available skills: /office-hours, /plan-deliverables, /plan-ceo-review, /plan-eng-review, /plan-design-review, /design-consultation, /design-shotgun, /design-html, /review, /ship, /land-and-deploy, /canary, /benchmark, /browse, /open-gstack-browser, /qa, /qa-only, /design-review, /setup-browser-cookies, /setup-deploy, /setup-gbrain, /sync-gbrain, /retro, /investigate, diff --git a/SKILL.md b/SKILL.md index dccdf7c34..050c9055f 100644 --- a/SKILL.md +++ b/SKILL.md @@ -558,6 +558,7 @@ quality gates that produce better results than answering inline. **Routing rules — when you see these patterns, INVOKE the skill via the Skill tool:** - User describes a new idea, asks "is this worth building", brainstorms, pitches a concept → invoke `/office-hours` - User asks to spec something out, file an issue, write up a ticket, "turn this into a GitHub issue", "backlog item" → invoke `/spec` +- User asks to define acceptance criteria, deliverables, or "definition of done" for a plan, after /office-hours and before coding → invoke `/plan-deliverables` - User asks about strategy, scope, ambition, "think bigger", "what should we build" → invoke `/plan-ceo-review` - User asks to review architecture, lock in the plan, "does this design make sense" → invoke `/plan-eng-review` - User asks about design system, brand, visual identity, "how should this look" → invoke `/design-consultation` diff --git a/SKILL.md.tmpl b/SKILL.md.tmpl index f6bde5e8b..0dd063709 100644 --- a/SKILL.md.tmpl +++ b/SKILL.md.tmpl @@ -47,6 +47,7 @@ quality gates that produce better results than answering inline. **Routing rules — when you see these patterns, INVOKE the skill via the Skill tool:** - User describes a new idea, asks "is this worth building", brainstorms, pitches a concept → invoke `/office-hours` - User asks to spec something out, file an issue, write up a ticket, "turn this into a GitHub issue", "backlog item" → invoke `/spec` +- User asks to define acceptance criteria, deliverables, or "definition of done" for a plan, after /office-hours and before coding → invoke `/plan-deliverables` - User asks about strategy, scope, ambition, "think bigger", "what should we build" → invoke `/plan-ceo-review` - User asks to review architecture, lock in the plan, "does this design make sense" → invoke `/plan-eng-review` - User asks about design system, brand, visual identity, "how should this look" → invoke `/design-consultation` diff --git a/autobuilder-loop/SKILL.md b/autobuilder-loop/SKILL.md index 775a81ef0..5cc3e14f6 100644 --- a/autobuilder-loop/SKILL.md +++ b/autobuilder-loop/SKILL.md @@ -1,7 +1,7 @@ --- name: autobuilder-loop preamble-tier: 3 -version: 1.2.0 +version: 1.3.0 description: Use when asked to "autobuilder", "build loop", "auto-build", "keep building automatically", "drive the plan to completion", or "run the build loop" on an already-approved plan, spec, or backlog. (gstack) triggers: - autobuilder loop @@ -1003,7 +1003,11 @@ contract in Quick reference). **1.0. Re-parse from disk.** Each iteration, dispatch the **Sonnet-low** parse subagent to re-extract `{next_milestone, acceptance_criteria}` from the frozen plan on disk. This catches in-place edits to a milestone's criteria and keeps you honest — never work the next milestone -from memory. +from memory. When the plan carries per-milestone status markers +(``, authored by `/plan-deliverables`), +`next_milestone` is the FIRST milestone still marked `pending` — a durable selector that +survives re-parsing instead of inferring "next" from unchecked criteria. Plans without markers +fall back to the first milestone with unmet acceptance criteria. **a. Decompose.** A **Fable-or-Opus-max** orchestrator subagent decomposes the milestone into tasks, classifies each by complexity (hard / moderate / mechanical), and returns the compact @@ -1270,8 +1274,9 @@ into the NEXT milestone's gate under strict bounds, all four of which hold: recreates the "defects compound across milestones" failure this gate exists to prevent). 2. NEVER batch a milestone that touches security, auth, migrations, or public interfaces. 3. The FINAL milestone's gate is never deferrable. -4. A batched milestone is marked **"built — gate pending"** in the plan, NOT complete, until - its covering gate runs clean. +4. A batched milestone is marked **"built — gate pending"** in the plan (set its status marker + to `` when the plan carries one), NOT complete, until its + covering gate runs clean. Say so explicitly when you batch. If you cannot satisfy all four, gate the milestone now. **d. LOCAL DOCKER VERIFICATION (MANDATORY — before a milestone counts as done).** @@ -1308,7 +1313,10 @@ Say so explicitly when you batch. If you cannot satisfy all four, gate the miles **e. Mark complete.** A **Sonnet-low** subagent marks the milestone complete in the plan/ TODOS.md (or **"built — gate pending"** if its gate was batched per the deferral valve) and -returns confirmation. Append a row to the Build Audit Trail (`$RUN_DIR/audit-trail.md`) via a +returns confirmation. When the milestone carries a `/plan-deliverables` status marker, update it +in place — set `` on a gated-clean milestone, or +`` on a batched one — so step 1.0's next-milestone selection +advances past it. Append a row to the Build Audit Trail (`$RUN_DIR/audit-trail.md`) via a subagent — not in your context. **f. Report.** Emit a one-line milestone summary to the user (what shipped, gate status, diff --git a/autobuilder-loop/SKILL.md.tmpl b/autobuilder-loop/SKILL.md.tmpl index 9fca3e1d7..9d6c4ccf1 100644 --- a/autobuilder-loop/SKILL.md.tmpl +++ b/autobuilder-loop/SKILL.md.tmpl @@ -1,7 +1,7 @@ --- name: autobuilder-loop preamble-tier: 3 -version: 1.2.0 +version: 1.3.0 description: | Use when asked to "autobuilder", "build loop", "auto-build", "keep building automatically", "drive the plan to completion", or "run the build loop" on an @@ -197,7 +197,11 @@ contract in Quick reference). **1.0. Re-parse from disk.** Each iteration, dispatch the **Sonnet-low** parse subagent to re-extract `{next_milestone, acceptance_criteria}` from the frozen plan on disk. This catches in-place edits to a milestone's criteria and keeps you honest — never work the next milestone -from memory. +from memory. When the plan carries per-milestone status markers +(``, authored by `/plan-deliverables`), +`next_milestone` is the FIRST milestone still marked `pending` — a durable selector that +survives re-parsing instead of inferring "next" from unchecked criteria. Plans without markers +fall back to the first milestone with unmet acceptance criteria. **a. Decompose.** A **Fable-or-Opus-max** orchestrator subagent decomposes the milestone into tasks, classifies each by complexity (hard / moderate / mechanical), and returns the compact @@ -262,8 +266,9 @@ into the NEXT milestone's gate under strict bounds, all four of which hold: recreates the "defects compound across milestones" failure this gate exists to prevent). 2. NEVER batch a milestone that touches security, auth, migrations, or public interfaces. 3. The FINAL milestone's gate is never deferrable. -4. A batched milestone is marked **"built — gate pending"** in the plan, NOT complete, until - its covering gate runs clean. +4. A batched milestone is marked **"built — gate pending"** in the plan (set its status marker + to `` when the plan carries one), NOT complete, until its + covering gate runs clean. Say so explicitly when you batch. If you cannot satisfy all four, gate the milestone now. **d. LOCAL DOCKER VERIFICATION (MANDATORY — before a milestone counts as done).** @@ -300,7 +305,10 @@ Say so explicitly when you batch. If you cannot satisfy all four, gate the miles **e. Mark complete.** A **Sonnet-low** subagent marks the milestone complete in the plan/ TODOS.md (or **"built — gate pending"** if its gate was batched per the deferral valve) and -returns confirmation. Append a row to the Build Audit Trail (`$RUN_DIR/audit-trail.md`) via a +returns confirmation. When the milestone carries a `/plan-deliverables` status marker, update it +in place — set `` on a gated-clean milestone, or +`` on a batched one — so step 1.0's next-milestone selection +advances past it. Append a row to the Build Audit Trail (`$RUN_DIR/audit-trail.md`) via a subagent — not in your context. **f. Report.** Emit a one-line milestone summary to the user (what shipped, gate status, diff --git a/gstack/llms.txt b/gstack/llms.txt index 05e6ef994..c76f26ba3 100644 --- a/gstack/llms.txt +++ b/gstack/llms.txt @@ -49,6 +49,7 @@ Conventions: - [/open-gstack-browser](open-gstack-browser/SKILL.md): Launch GStack Browser — AI-controlled Chromium with the sidebar extension baked in. - [/pair-agent](pair-agent/SKILL.md): Pair a remote AI agent with your browser. - [/plan-ceo-review](plan-ceo-review/SKILL.md): CEO/founder-mode plan review. +- [/plan-deliverables](plan-deliverables/SKILL.md): Turn an approved design/plan into per-milestone acceptance criteria, each measurable and paired with the specific check that validates it (the deliverable). - [/plan-design-review](plan-design-review/SKILL.md): Designer's eye plan review — interactive, like CEO and Eng review. - [/plan-devex-review](plan-devex-review/SKILL.md): Interactive developer experience plan review. - [/plan-eng-review](plan-eng-review/SKILL.md): Eng manager-mode plan review. diff --git a/office-hours/sections/design-and-handoff.md b/office-hours/sections/design-and-handoff.md index 4c253e96a..d466cf306 100644 --- a/office-hours/sections/design-and-handoff.md +++ b/office-hours/sections/design-and-handoff.md @@ -20,7 +20,7 @@ If `$PRIOR` exists, the new doc gets a `Supersedes:` field referencing it. This Write to `~/.gstack/projects/{slug}/{user}-{branch}-design-{datetime}.md`. After writing the design doc, tell the user: -**"Design doc saved to: {full path}. Other skills (/plan-ceo-review, /plan-eng-review) will find it automatically."** +**"Design doc saved to: {full path}. Other skills (/plan-deliverables, /plan-ceo-review, /plan-eng-review) will find it automatically. A good next step is /plan-deliverables — it bakes measurable acceptance criteria and a paired test into each milestone before the reviews."** ### Startup mode design doc template: @@ -540,6 +540,7 @@ strongest retention). **If `PROACTIVE` is `false` OR `CONDUCTOR_SESSION: true`:** do NOT auto-launch. Recommend in one line and stop, letting the user invoke: +- any mode → "Next: `/plan-deliverables` to bake measurable acceptance criteria + a paired test into each milestone before the reviews." - EXPANSION / ambitious → "Next: `/plan-ceo-review` to pressure-test scope and find the 10-star product." - well-scoped → "Next: `/plan-eng-review` to lock architecture, tests, and edge cases." - visual/UX-heavy → "Next: `/plan-design-review` for a visual/UX pass." diff --git a/office-hours/sections/design-and-handoff.md.tmpl b/office-hours/sections/design-and-handoff.md.tmpl index a8f8c5aac..b63e41664 100644 --- a/office-hours/sections/design-and-handoff.md.tmpl +++ b/office-hours/sections/design-and-handoff.md.tmpl @@ -18,7 +18,7 @@ If `$PRIOR` exists, the new doc gets a `Supersedes:` field referencing it. This Write to `~/.gstack/projects/{slug}/{user}-{branch}-design-{datetime}.md`. After writing the design doc, tell the user: -**"Design doc saved to: {full path}. Other skills (/plan-ceo-review, /plan-eng-review) will find it automatically."** +**"Design doc saved to: {full path}. Other skills (/plan-deliverables, /plan-ceo-review, /plan-eng-review) will find it automatically. A good next step is /plan-deliverables — it bakes measurable acceptance criteria and a paired test into each milestone before the reviews."** ### Startup mode design doc template: @@ -429,6 +429,7 @@ strongest retention). **If `PROACTIVE` is `false` OR `CONDUCTOR_SESSION: true`:** do NOT auto-launch. Recommend in one line and stop, letting the user invoke: +- any mode → "Next: `/plan-deliverables` to bake measurable acceptance criteria + a paired test into each milestone before the reviews." - EXPANSION / ambitious → "Next: `/plan-ceo-review` to pressure-test scope and find the 10-star product." - well-scoped → "Next: `/plan-eng-review` to lock architecture, tests, and edge cases." - visual/UX-heavy → "Next: `/plan-design-review` for a visual/UX pass." diff --git a/plan-deliverables/SKILL.md b/plan-deliverables/SKILL.md new file mode 100644 index 000000000..4e15b745b --- /dev/null +++ b/plan-deliverables/SKILL.md @@ -0,0 +1,1237 @@ +--- +name: plan-deliverables +preamble-tier: 3 +interactive: true +version: 1.0.0 +description: Turn an approved design/plan into per-milestone acceptance criteria, each measurable and paired with the specific check that validates it (the deliverable). (gstack) +benefits-from: [office-hours] +allowed-tools: + - Read + - Write + - Edit + - Grep + - Glob + - AskUserQuestion + - Bash +triggers: + - acceptance criteria + - define deliverables + - definition of done + - bake in success criteria +--- + + + + +## When to invoke this skill + +Bridges the gap between office-hours and the plan reviews: +/autobuilder-loop already reads per-milestone {next_milestone, +acceptance_criteria} from the plan on disk, but nothing upstream authors that +field — this skill does. Use when asked to "define acceptance criteria", +"define deliverables", "definition of done", or "bake in success criteria" +for a plan. Proactively suggest after /office-hours and before the plan +reviews / before coding — so every milestone has a testable definition of +done before a line of code is written. + +Voice triggers (speech-to-text aliases): "acceptance criteria", "define deliverables", "definition of done", "plan deliverables". + +## Preamble (run first) + +```bash +_UPD=$(~/.claude/skills/gstack/bin/gstack-update-check 2>/dev/null || .claude/skills/gstack/bin/gstack-update-check 2>/dev/null || true) +[ -n "$_UPD" ] && echo "$_UPD" || true +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 -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") +echo "BRANCH: $_BRANCH" +_SKILL_PREFIX=$(~/.claude/skills/gstack/bin/gstack-config get skill_prefix 2>/dev/null || echo "false") +echo "PROACTIVE: $_PROACTIVE" +echo "PROACTIVE_PROMPTED: $_PROACTIVE_PROMPTED" +echo "SKILL_PREFIX: $_SKILL_PREFIX" +source <(~/.claude/skills/gstack/bin/gstack-repo-mode 2>/dev/null) || true +REPO_MODE=${REPO_MODE:-unknown} +echo "REPO_MODE: $REPO_MODE" +_SESSION_KIND=$(~/.claude/skills/gstack/bin/gstack-session-kind 2>/dev/null || echo "interactive") +case "$_SESSION_KIND" in spawned|headless|interactive) ;; *) _SESSION_KIND="interactive" ;; esac +echo "SESSION_KIND: $_SESSION_KIND" +# Conductor host: AskUserQuestion is unreliable here (native disabled, MCP +# variant flaky), so skills render decisions as prose instead of calling the +# tool. Gated on !headless so an eval/CI run INSIDE Conductor (GSTACK_HEADLESS) +# still BLOCKs rather than rendering prose to nobody. +if [ "$_SESSION_KIND" != "headless" ] && { [ -n "${CONDUCTOR_WORKSPACE_PATH:-}" ] || [ -n "${CONDUCTOR_PORT:-}" ]; }; then + echo "CONDUCTOR_SESSION: true" +fi +_ACTIVATED=$([ -f ~/.gstack/.activated ] && echo "yes" || echo "no") +_FIRST_LOOP_SHOWN=$([ -f ~/.gstack/.first-loop-tip-shown ] && echo "yes" || echo "no") +echo "ACTIVATED: $_ACTIVATED" +echo "FIRST_LOOP_SHOWN: $_FIRST_LOOP_SHOWN" +# First-run project detection: run the detector ONLY on the first-ever skill run +# (ACTIVATED=no, interactive) so it stays off the hot path for every run after. +_FIRST_TASK="" +if [ "$_ACTIVATED" = "no" ] && [ "$_SESSION_KIND" != "headless" ]; then + _FIRST_TASK=$(~/.claude/skills/gstack/bin/gstack-first-task-detect 2>/dev/null || true) +fi +echo "FIRST_TASK: $_FIRST_TASK" +_LAKE_SEEN=$([ -f ~/.gstack/.completeness-intro-seen ] && echo "yes" || echo "no") +echo "LAKE_INTRO: $_LAKE_SEEN" +_TEL=$(~/.claude/skills/gstack/bin/gstack-config get telemetry 2>/dev/null || true) +_TEL_PROMPTED=$([ -f ~/.gstack/.telemetry-prompted ] && echo "yes" || echo "no") +_TEL_START=$(date +%s) +_SESSION_ID="$$-$(date +%s)" +echo "TELEMETRY: ${_TEL:-off}" +echo "TEL_PROMPTED: $_TEL_PROMPTED" +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +_QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") +echo "QUESTION_TUNING: $_QUESTION_TUNING" +mkdir -p ~/.gstack/analytics +if [ "$_TEL" != "off" ]; then +echo '{"skill":"plan-deliverables","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(_repo=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null | tr -cd 'a-zA-Z0-9._-'); echo "${_repo:-unknown}")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true +fi +for _PF in $(find ~/.gstack/analytics -maxdepth 1 -name '.pending-*' 2>/dev/null); do + if [ -f "$_PF" ]; then + if [ "$_TEL" != "off" ] && [ -x "~/.claude/skills/gstack/bin/gstack-telemetry-log" ]; then + ~/.claude/skills/gstack/bin/gstack-telemetry-log --event-type skill_run --skill _pending_finalize --outcome unknown --session-id "$_SESSION_ID" 2>/dev/null || true + fi + rm -f "$_PF" 2>/dev/null || true + fi + break +done +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 +~/.claude/skills/gstack/bin/gstack-timeline-log '{"skill":"plan-deliverables","event":"started","branch":"'"$_BRANCH"'","session":"'"$_SESSION_ID"'"}' 2>/dev/null & +_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" +_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" +echo "MODEL_OVERLAY: claude" +_CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode 2>/dev/null || echo "explicit") +_CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") +echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" +echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" +[ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true +``` + +## Plan Mode Safe Operations + +In plan mode, allowed because they inform the plan: `$B`, `$D`, `codex exec`/`codex review`, writes to `~/.gstack/`, writes to the plan file, and `open` for generated artifacts. + +## Skill Invocation During Plan Mode + +If the user invokes a skill in plan mode, the skill takes precedence over generic plan mode behavior. **Treat the skill file as executable instructions, not reference.** Follow it step by step starting from Step 0; the first AskUserQuestion is the workflow entering plan mode, not a violation of it. AskUserQuestion (any variant — `mcp__*__AskUserQuestion` or native; see "AskUserQuestion Format → Tool resolution") satisfies plan mode's end-of-turn requirement. If AskUserQuestion is unavailable or a call fails, follow the AskUserQuestion Format failure fallback: `headless` → BLOCKED; `interactive` → the prose fallback (also satisfies end-of-turn). At a STOP point, stop immediately. Do not continue the workflow or call ExitPlanMode there. Commands marked "PLAN MODE EXCEPTION — ALWAYS RUN" execute. Call ExitPlanMode only after the skill workflow completes, or if the user tells you to cancel the skill or leave plan mode. + +If `PROACTIVE` is `"false"`, do not auto-invoke or proactively suggest skills. If a skill seems useful, ask: "I think /skillname might help here — want me to run it?" + +If `SKILL_PREFIX` is `"true"`, suggest/invoke `/gstack-*` names. Disk paths stay `~/.claude/skills/gstack/[skill-name]/SKILL.md`. + +If output shows `UPGRADE_AVAILABLE `: read `~/.claude/skills/gstack/gstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (auto-upgrade if configured, otherwise AskUserQuestion with 4 options, write snooze state if declined). + +If output shows `JUST_UPGRADED `: print "Running gstack v{to} (just updated!)". If `SPAWNED_SESSION` is true, skip feature discovery. + +Feature discovery, max one prompt per session: +- Missing `~/.claude/skills/gstack/.feature-prompted-continuous-checkpoint`: AskUserQuestion for Continuous checkpoint auto-commits. If accepted, run `~/.claude/skills/gstack/bin/gstack-config set checkpoint_mode continuous`. Always touch marker. +- Missing `~/.claude/skills/gstack/.feature-prompted-model-overlay`: inform "Model overlays are active. MODEL_OVERLAY shows the patch." Always touch marker. + +After upgrade prompts, continue workflow. + +If `WRITING_STYLE_PENDING` is `yes`: ask once about writing style: + +> v1 prompts are simpler: first-use jargon glosses, outcome-framed questions, shorter prose. Keep default or restore terse? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +Skip if `WRITING_STYLE_PENDING` is `no`. + +If `LAKE_INTRO` is `no`: say "gstack follows the **Boil the Ocean** principle — do the complete thing when AI makes marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" Offer to open: + +```bash +open https://garryslist.org/posts/boil-the-ocean +touch ~/.gstack/.completeness-intro-seen +``` + +Only run `open` if yes. Always run `touch`. + +If `TEL_PROMPTED` is `no` AND `LAKE_INTRO` is `yes`: ask telemetry once via AskUserQuestion: + +> Help gstack get better. Share usage data only: skill, duration, crashes, stable device ID. No code or file paths. Your repo name is recorded locally only and stripped before any upload. + +Options: +- A) Help gstack get better! (recommended) +- B) No thanks + +If A: run `~/.claude/skills/gstack/bin/gstack-config set telemetry community` + +If B: ask follow-up: + +> Anonymous mode sends only aggregate usage, no unique ID. + +Options: +- A) Sure, anonymous is fine +- B) No thanks, fully off + +If B→A: run `~/.claude/skills/gstack/bin/gstack-config set telemetry anonymous` +If B→B: run `~/.claude/skills/gstack/bin/gstack-config set telemetry off` + +Always run: +```bash +touch ~/.gstack/.telemetry-prompted +``` + +Skip if `TEL_PROMPTED` is `yes`. + +If `PROACTIVE_PROMPTED` is `no` AND `TEL_PROMPTED` is `yes`: ask once: + +> Let gstack proactively suggest skills, like /qa for "does this work?" or /investigate for bugs? + +Options: +- A) Keep it on (recommended) +- B) Turn it off — I'll type /commands myself + +If A: run `~/.claude/skills/gstack/bin/gstack-config set proactive true` +If B: run `~/.claude/skills/gstack/bin/gstack-config set proactive false` + +Always run: +```bash +touch ~/.gstack/.proactive-prompted +``` + +Skip if `PROACTIVE_PROMPTED` is `yes`. + +## First-run guidance (one-time) + +If `ACTIVATED` is `no` (first skill run on this machine) AND the preamble printed a non-empty `FIRST_TASK:` value that is NOT `nongit`: show ONE short, project-specific line mapped from the token, as a heads-up, then CONTINUE with whatever the user actually asked — do NOT halt their task. Map the token: `greenfield` → "Fresh repo — shape it first with `/spec` or `/office-hours`." `code_node`/`code_python`/`code_rust`/`code_go`/`code_ruby`/`code_ios` → "There's code here — `/qa` to see it work, or `/investigate` if something's off." `branch_ahead` → "Unshipped work on this branch — `/review` then `/ship`." `dirty_default` → "Uncommitted changes — `/review` before committing." `clean_default` → "Pick one: `/spec`, `/investigate`, or `/qa`." Then substitute the token you saw for TASK_TOKEN and run (best-effort), and mark activated: +```bash +~/.claude/skills/gstack/bin/gstack-telemetry-log --event-type first_task_scaffold_shown --skill "TASK_TOKEN" --outcome shown 2>/dev/null || true +touch ~/.gstack/.activated 2>/dev/null || true +``` + +If `ACTIVATED` is `no` but `FIRST_TASK:` is empty or `nongit` (headless, non-git, or nothing actionable): show nothing, just run `touch ~/.gstack/.activated 2>/dev/null || true`. + +Else if `ACTIVATED` is `yes` AND `FIRST_LOOP_SHOWN` is `no`: say once as a heads-up (then continue): + +> Tip: gstack pays off when you complete one loop — **plan → review → ship**. A common first loop: `/office-hours` or `/spec` to shape it, `/plan-eng-review` to lock it, then `/ship`. + +Then run `touch ~/.gstack/.first-loop-tip-shown 2>/dev/null || true`. + +Skip this section if `ACTIVATED` and `FIRST_LOOP_SHOWN` are both `yes`. + +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. + +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, invoke it via the Skill tool. When in doubt, invoke the skill. + +Key routing rules: +- Product ideas/brainstorming → invoke /office-hours +- Strategy/scope → invoke /plan-ceo-review +- Architecture → invoke /plan-eng-review +- Design system/plan review → invoke /design-consultation or /plan-design-review +- Full review pipeline → invoke /autoplan +- Bugs/errors → invoke /investigate +- QA/testing site behavior → invoke /qa or /qa-only +- Code review/diff check → invoke /review +- Visual polish → invoke /design-review +- Ship/deploy/PR → invoke /ship or /land-and-deploy +- Save progress → invoke /context-save +- Resume context → invoke /context-restore +- Author a backlog-ready spec/issue → invoke /spec +``` + +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` and say they can re-enable with `gstack-config set routing_declined false`. + +This only happens once per project. Skip if `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`. + +If `VENDORED_GSTACK` is `yes`, warn once via AskUserQuestion unless `~/.gstack/.vendoring-warned-$SLUG` exists: + +> This project has gstack vendored in `.claude/skills/gstack/`. Vendoring is deprecated. +> Migrate to team mode? + +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} +``` + +If marker exists, skip. + +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. + +## AskUserQuestion Format + +### Tool resolution (read first) + +"AskUserQuestion" can resolve to two tools at runtime: the **host MCP variant** (e.g. `mcp__conductor__AskUserQuestion` — appears in your tool list when the host registers it) or the **native** Claude Code tool. + +**Conductor rule (read before the MCP rule):** if `CONDUCTOR_SESSION: true` was echoed by the preamble, do NOT call AskUserQuestion at all — neither native nor any `mcp__*__AskUserQuestion` variant. Render EVERY decision brief as the **prose form** below and STOP. This is proactive, not a reaction to a failure: Conductor disables native AUQ and its MCP variant is flaky (it returns `[Tool result missing due to internal error]`), so prose is the reliable path. **Auto-decide preferences still apply first:** if a `[plan-tune auto-decide] →