From 1730a06135dcb3aefc042e6ced39b8b7c83b602e Mon Sep 17 00:00:00 2001 From: Hermes Agent Date: Mon, 11 May 2026 12:07:15 +0000 Subject: [PATCH 1/7] feat(document-release): add Diataxis coverage map, diagram drift detection, and docs debt tracking MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Inspired by @doodlestein's documentation-website skill. Three key ideas incorporated: 1. Step 1.5: Coverage Map (Blast-Radius Analysis) — before editing any docs, scan the diff for new public surface and assess documentation coverage across Diataxis quadrants (reference/how-to/tutorial/explanation). Flags gaps without auto-generating content. 2. Architecture diagram drift detection — extracts entity names from ASCII/Mermaid diagrams and cross-references against the diff to catch stale diagrams. 3. Enhanced CHANGELOG sell test — Diataxis rubric scoring (0-3) replaces the subjective 'would a user want this?' check. 4. Documentation Debt section in PR body — surfaces coverage gaps and diagram drift as actionable items for future work. All changes are audit-only: the skill flags what's missing, never auto-generates missing documentation pages. Stays in its lane as a post-ship updater. Co-Authored-By: Hermes Agent --- document-release/SKILL.md | 95 ++++++++++++++++++++++++++++++---- document-release/SKILL.md.tmpl | 95 ++++++++++++++++++++++++++++++---- 2 files changed, 172 insertions(+), 18 deletions(-) diff --git a/document-release/SKILL.md b/document-release/SKILL.md index 9fa7f5ad50..0354172602 100644 --- a/document-release/SKILL.md +++ b/document-release/SKILL.md @@ -4,10 +4,12 @@ preamble-tier: 2 version: 1.0.0 description: | Post-ship documentation update. Reads all project docs, cross-references the - diff, updates README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md to match what shipped, - polishes CHANGELOG voice, cleans up TODOS, and optionally bumps VERSION. Use when - asked to "update the docs", "sync documentation", or "post-ship docs". - Proactively suggest after a PR is merged or code is shipped. (gstack) + diff, builds a Diataxis coverage map (reference/how-to/tutorial/explanation), + updates README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md to match what shipped, + detects architecture diagram drift, polishes CHANGELOG voice with a sell-test + rubric, cleans up TODOS, and optionally bumps VERSION. Surfaces documentation + debt in the PR body. Use when asked to "update the docs", "sync documentation", + or "post-ship docs". Proactively suggest after a PR is merged or code is shipped. (gstack) allowed-tools: - Bash - Read @@ -829,6 +831,47 @@ find . -maxdepth 2 -name "*.md" -not -path "./.git/*" -not -path "./node_modules --- +## Step 1.5: Coverage Map (Blast-Radius Analysis) + +Before touching any documentation file, build a **coverage map** of what shipped vs what's +documented. This is inspired by the Diataxis framework (tutorial / how-to / reference / explanation) +— but applied as an audit lens, not a generation tool. + +1. **Extract public surface changes from the diff.** Scan `git diff ...HEAD` for: + - New exported functions, classes, commands, CLI flags, config options, API endpoints + - New skills, workflows, or user-facing capabilities + - Renamed or removed public surface (modules, commands, features) + - New environment variables, feature flags, or configuration knobs + +2. **For each new/changed public surface item, assess documentation coverage:** + +``` +Coverage map: + [entity] [reference?] [how-to?] [tutorial?] [explanation?] + /new-skill ✅ AGENTS.md ❌ ❌ ❌ + --new-flag ✅ README ✅ README ❌ ❌ + FooProcessor ❌ ❌ ❌ ❌ +``` + +Use these definitions: +- **Reference** — factual description of what it is, its API, its options (README tables, AGENTS.md skill lists, API docs) +- **How-to** — task-oriented: "how to do X with this" (README examples, CONTRIBUTING workflows) +- **Tutorial** — learning-oriented: step-by-step walkthrough for newcomers (getting started guides) +- **Explanation** — understanding-oriented: "why this works this way" (ARCHITECTURE decisions, design rationale) + +3. **Output the coverage map.** Items with zero coverage are **critical gaps** — flag them for + Step 3. Items with reference-only coverage are **common gaps** — note them for the PR body. + +4. **Architecture diagram drift detection.** If ARCHITECTURE.md (or any doc) contains ASCII + diagrams or Mermaid blocks, extract entity names (modules, services, data flows) from the + diagrams. Cross-reference against the diff. Flag any diagram entities that were renamed, + split, removed, or moved in the code. + +The coverage map feeds into Steps 2-3 (what to audit and fix) and Step 9 (documentation debt +summary in the PR body). Do NOT auto-generate missing documentation pages — flag gaps only. + +--- + ## Step 2: Per-File Documentation Audit Read each documentation file and cross-reference it against the diff. Use these generic heuristics @@ -921,8 +964,11 @@ preserved them. This skill must NEVER do that. **If CHANGELOG was modified in this branch**, review the entry for voice: -- **Sell test:** Would a user reading each bullet think "oh nice, I want to try that"? If not, - rewrite the wording (not the content). +- **Sell test (Diataxis rubric):** Score each CHANGELOG entry 0-3: + - **1 point** — answers "What changed?" (reference: names the feature/fix) + - **1 point** — answers "Why should I care?" (explanation: user impact, pain removed) + - **1 point** — answers "How do I use it?" (how-to: command, flag, or link to docs) + - Entries scoring <2 need a rewrite. Entries scoring 3 are gold. - Lead with what the user can now **do** — not implementation details. - "You can now..." not "Refactored the..." - Flag and rewrite any entry that reads like a commit message. @@ -1050,9 +1096,21 @@ glab mr view -F json 2>/dev/null | python3 -c "import sys,json; print(json.load( 2. If the tempfile already contains a `## Documentation` section, replace that section with the updated content. If it does not contain one, append a `## Documentation` section at the end. -3. The Documentation section should include a **doc diff preview** — for each file modified, - describe what specifically changed (e.g., "README.md: added /document-release to skills - table, updated skill count from 9 to 10"). +3. The Documentation section should include: + + a. **Doc diff preview** — for each file modified, describe what specifically changed (e.g., + "README.md: added /document-release to skills table, updated skill count from 9 to 10"). + + b. **Documentation debt** — if the coverage map from Step 1.5 found gaps, append a + `### Documentation Debt` subsection listing: + - Critical gaps: new public surface with zero documentation coverage + - Common gaps: features with reference-only coverage (no how-to or tutorial) + - Stale diagrams: architecture diagrams with entity names that drifted from the code + - Each item should include a one-line description of what's missing and which Diataxis + quadrant would fill it (e.g., "⚠️ `/new-skill` — has reference in AGENTS.md but no + how-to example in README") + + If there are any documentation debt items, suggest adding a `docs-debt` label to the PR. 4. Write the updated body back: @@ -1150,6 +1208,20 @@ Where status is one of: - Already bumped — version was set by /ship - Skipped — file does not exist +If the coverage map from Step 1.5 identified any gaps, append: + +``` +Documentation coverage: + [entity] [reference] [how-to] [tutorial] [explanation] + /new-skill ✅ ❌ ❌ ❌ + --new-flag ✅ ✅ ❌ ❌ + +Diagram drift: + ARCHITECTURE.md: "FooProcessor" renamed to "BarProcessor" in code — diagram may be stale +``` + +If all coverage is complete and no diagrams drifted, output: "Coverage: all shipped features have adequate documentation." + --- ## Important Rules @@ -1160,5 +1232,10 @@ Where status is one of: - **Be explicit about what changed.** Every edit gets a one-line summary. - **Generic heuristics, not project-specific.** The audit checks work on any repo. - **Discoverability matters.** Every doc file should be reachable from README or CLAUDE.md. +- **Coverage map informs, never generates.** The Diataxis coverage map flags gaps for the PR body + and future work. It does NOT auto-generate missing documentation pages or sections. The coverage + map is an audit tool, not a content generator. +- **Diagram drift is advisory.** Flag stale architecture diagrams in the PR body but do not + auto-edit ASCII art or Mermaid blocks — they require human judgment to update correctly. - **Voice: friendly, user-forward, not obscure.** Write like you're explaining to a smart person who hasn't seen the code. diff --git a/document-release/SKILL.md.tmpl b/document-release/SKILL.md.tmpl index 8e2b705916..8aa31a3d8d 100644 --- a/document-release/SKILL.md.tmpl +++ b/document-release/SKILL.md.tmpl @@ -4,10 +4,12 @@ preamble-tier: 2 version: 1.0.0 description: | Post-ship documentation update. Reads all project docs, cross-references the - diff, updates README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md to match what shipped, - polishes CHANGELOG voice, cleans up TODOS, and optionally bumps VERSION. Use when - asked to "update the docs", "sync documentation", or "post-ship docs". - Proactively suggest after a PR is merged or code is shipped. (gstack) + diff, builds a Diataxis coverage map (reference/how-to/tutorial/explanation), + updates README/ARCHITECTURE/CONTRIBUTING/CLAUDE.md to match what shipped, + detects architecture diagram drift, polishes CHANGELOG voice with a sell-test + rubric, cleans up TODOS, and optionally bumps VERSION. Surfaces documentation + debt in the PR body. Use when asked to "update the docs", "sync documentation", + or "post-ship docs". Proactively suggest after a PR is merged or code is shipped. (gstack) allowed-tools: - Bash - Read @@ -91,6 +93,47 @@ find . -maxdepth 2 -name "*.md" -not -path "./.git/*" -not -path "./node_modules --- +## Step 1.5: Coverage Map (Blast-Radius Analysis) + +Before touching any documentation file, build a **coverage map** of what shipped vs what's +documented. This is inspired by the Diataxis framework (tutorial / how-to / reference / explanation) +— but applied as an audit lens, not a generation tool. + +1. **Extract public surface changes from the diff.** Scan `git diff ...HEAD` for: + - New exported functions, classes, commands, CLI flags, config options, API endpoints + - New skills, workflows, or user-facing capabilities + - Renamed or removed public surface (modules, commands, features) + - New environment variables, feature flags, or configuration knobs + +2. **For each new/changed public surface item, assess documentation coverage:** + +``` +Coverage map: + [entity] [reference?] [how-to?] [tutorial?] [explanation?] + /new-skill ✅ AGENTS.md ❌ ❌ ❌ + --new-flag ✅ README ✅ README ❌ ❌ + FooProcessor ❌ ❌ ❌ ❌ +``` + +Use these definitions: +- **Reference** — factual description of what it is, its API, its options (README tables, AGENTS.md skill lists, API docs) +- **How-to** — task-oriented: "how to do X with this" (README examples, CONTRIBUTING workflows) +- **Tutorial** — learning-oriented: step-by-step walkthrough for newcomers (getting started guides) +- **Explanation** — understanding-oriented: "why this works this way" (ARCHITECTURE decisions, design rationale) + +3. **Output the coverage map.** Items with zero coverage are **critical gaps** — flag them for + Step 3. Items with reference-only coverage are **common gaps** — note them for the PR body. + +4. **Architecture diagram drift detection.** If ARCHITECTURE.md (or any doc) contains ASCII + diagrams or Mermaid blocks, extract entity names (modules, services, data flows) from the + diagrams. Cross-reference against the diff. Flag any diagram entities that were renamed, + split, removed, or moved in the code. + +The coverage map feeds into Steps 2-3 (what to audit and fix) and Step 9 (documentation debt +summary in the PR body). Do NOT auto-generate missing documentation pages — flag gaps only. + +--- + ## Step 2: Per-File Documentation Audit Read each documentation file and cross-reference it against the diff. Use these generic heuristics @@ -183,8 +226,11 @@ preserved them. This skill must NEVER do that. **If CHANGELOG was modified in this branch**, review the entry for voice: -- **Sell test:** Would a user reading each bullet think "oh nice, I want to try that"? If not, - rewrite the wording (not the content). +- **Sell test (Diataxis rubric):** Score each CHANGELOG entry 0-3: + - **1 point** — answers "What changed?" (reference: names the feature/fix) + - **1 point** — answers "Why should I care?" (explanation: user impact, pain removed) + - **1 point** — answers "How do I use it?" (how-to: command, flag, or link to docs) + - Entries scoring <2 need a rewrite. Entries scoring 3 are gold. - Lead with what the user can now **do** — not implementation details. - "You can now..." not "Refactored the..." - Flag and rewrite any entry that reads like a commit message. @@ -312,9 +358,21 @@ glab mr view -F json 2>/dev/null | python3 -c "import sys,json; print(json.load( 2. If the tempfile already contains a `## Documentation` section, replace that section with the updated content. If it does not contain one, append a `## Documentation` section at the end. -3. The Documentation section should include a **doc diff preview** — for each file modified, - describe what specifically changed (e.g., "README.md: added /document-release to skills - table, updated skill count from 9 to 10"). +3. The Documentation section should include: + + a. **Doc diff preview** — for each file modified, describe what specifically changed (e.g., + "README.md: added /document-release to skills table, updated skill count from 9 to 10"). + + b. **Documentation debt** — if the coverage map from Step 1.5 found gaps, append a + `### Documentation Debt` subsection listing: + - Critical gaps: new public surface with zero documentation coverage + - Common gaps: features with reference-only coverage (no how-to or tutorial) + - Stale diagrams: architecture diagrams with entity names that drifted from the code + - Each item should include a one-line description of what's missing and which Diataxis + quadrant would fill it (e.g., "⚠️ `/new-skill` — has reference in AGENTS.md but no + how-to example in README") + + If there are any documentation debt items, suggest adding a `docs-debt` label to the PR. 4. Write the updated body back: @@ -412,6 +470,20 @@ Where status is one of: - Already bumped — version was set by /ship - Skipped — file does not exist +If the coverage map from Step 1.5 identified any gaps, append: + +``` +Documentation coverage: + [entity] [reference] [how-to] [tutorial] [explanation] + /new-skill ✅ ❌ ❌ ❌ + --new-flag ✅ ✅ ❌ ❌ + +Diagram drift: + ARCHITECTURE.md: "FooProcessor" renamed to "BarProcessor" in code — diagram may be stale +``` + +If all coverage is complete and no diagrams drifted, output: "Coverage: all shipped features have adequate documentation." + --- ## Important Rules @@ -422,5 +494,10 @@ Where status is one of: - **Be explicit about what changed.** Every edit gets a one-line summary. - **Generic heuristics, not project-specific.** The audit checks work on any repo. - **Discoverability matters.** Every doc file should be reachable from README or CLAUDE.md. +- **Coverage map informs, never generates.** The Diataxis coverage map flags gaps for the PR body + and future work. It does NOT auto-generate missing documentation pages or sections. The coverage + map is an audit tool, not a content generator. +- **Diagram drift is advisory.** Flag stale architecture diagrams in the PR body but do not + auto-edit ASCII art or Mermaid blocks — they require human judgment to update correctly. - **Voice: friendly, user-forward, not obscure.** Write like you're explaining to a smart person who hasn't seen the code. From 369bc62cf78ca1a9930e3dd36836e6d050abefa2 Mon Sep 17 00:00:00 2001 From: Hermes Agent Date: Mon, 11 May 2026 12:34:01 +0000 Subject: [PATCH 2/7] feat(document-generate): add Diataxis documentation generation skill New /document-generate skill, the companion to /document-release. While /document-release audits and fixes existing docs post-ship, /document-generate writes missing documentation from scratch using the Diataxis framework. Inspired by doodlestein documentation-website-for-software-project skill. Co-Authored-By: Hermes Agent --- document-generate/SKILL.md | 1184 +++++++++++++++++++++++++++++++ document-generate/SKILL.md.tmpl | 446 ++++++++++++ document-release/SKILL.md | 5 +- document-release/SKILL.md.tmpl | 5 +- 4 files changed, 1636 insertions(+), 4 deletions(-) create mode 100644 document-generate/SKILL.md create mode 100644 document-generate/SKILL.md.tmpl diff --git a/document-generate/SKILL.md b/document-generate/SKILL.md new file mode 100644 index 0000000000..f86bfe9ecb --- /dev/null +++ b/document-generate/SKILL.md @@ -0,0 +1,1184 @@ +--- +name: document-generate +preamble-tier: 2 +version: 1.0.0 +description: | + Generate missing documentation from scratch for a feature, module, or entire project. + Uses the Diataxis framework (tutorial / how-to / reference / explanation) to produce + complete, structured documentation. Can be invoked standalone or called by + /document-release when it finds coverage gaps. Use when asked to "write docs", + "generate documentation", "document this feature", "create a tutorial", or + "explain this module". (gstack) +allowed-tools: + - Bash + - Read + - Write + - Edit + - Grep + - Glob + - AskUserQuestion +triggers: + - write docs for this + - generate documentation + - document this feature + - create a tutorial + - write a how-to + - explain this module + - docs for this project +--- + + + +## 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" +_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":"document-generate","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 +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":"document-generate","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" +[ -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 no variant is callable, the skill is BLOCKED — stop and report `BLOCKED — AskUserQuestion unavailable` per the AskUserQuestion Format rule. 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 Lake** 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, file paths, or repo names. + +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`. + +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 +``` + +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. + +**Rule:** if any `mcp__*__AskUserQuestion` variant is in your tool list, prefer it. Hosts may disable native AUQ via `--disallowedTools AskUserQuestion` (Conductor does, by default) and route through their MCP variant; calling native there silently fails. Same questions/options shape; same decision-brief format applies. + +**If no AskUserQuestion variant appears in your tool list, this skill is BLOCKED.** Stop, report `BLOCKED — AskUserQuestion unavailable`, and wait for the user. Do not write decisions to the plan file as a substitute, do not emit them as prose and stop, and do not silently auto-decide (only `/plan-tune` AUTO_DECIDE opt-ins authorize auto-picking). + +### Format + +Every AskUserQuestion is a decision brief and must be sent as tool_use, not prose. + +``` +D — +Project/branch/task: <1 short grounding sentence using _BRANCH> +ELI10: +Stakes if we pick wrong: +Recommendation: because +Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score) +Pros / cons: +A)