From 40e34deb7a055c3338b67d9118944858d1c4f974 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Thu, 14 May 2026 11:35:32 -0400 Subject: [PATCH] v1.35.0.0 feat: add /document-generate skill + enhance /document-release with Diataxis coverage map (#1477) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat(document-release): add Diataxis coverage map, diagram drift detection, and docs debt tracking 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 * 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 * chore(docs): regenerate gstack/llms.txt with /document-generate entry CI's check-freshness step ran gen:skill-docs and found llms.txt stale — the index wasn't regenerated when /document-generate was added in the preceding commit. Co-Authored-By: Claude Opus 4.7 (1M context) * chore(docs): regen document-generate/SKILL.md after merging main Main brought in the Non-ASCII characters directive in the AskUserQuestion Format resolver (scripts/resolvers/preamble/generate-ask-user-format.ts). Regenerating document-generate/SKILL.md propagates the new section into the generated output. check-freshness should now pass. Co-Authored-By: Claude Opus 4.7 (1M context) * docs(CLAUDE.md): add workflow for fork PRs from garrytan-agents Fork PRs from non-collaborators don't get base-repo secrets passed to their CI workflows, so eval/E2E jobs fail with empty-env auth. New section: when checking out a PR from garrytan-agents, push the branch to garrytan/gstack and re-target the PR from there. Co-Authored-By: Claude Opus 4.7 (1M context) * docs: sync project docs for v1.35.0.0 + bump VERSION - README.md: add /document-generate to skills table (Technical Writer category) + install-command skill lists - CLAUDE.md: add document-generate/ to project structure tree - SKILL.md.tmpl + regenerated SKILL.md: add /document-generate routing line ("write docs from scratch") - VERSION: 1.34.0.0 → 1.35.0.0 (MINOR: new skill + enhancement) CHANGELOG entry deferred to /ship. Co-Authored-By: Claude Opus 4.7 (1M context) * chore: bump version and changelog (v1.35.0.0) CHANGELOG entry for the document-generate skill + document-release Diataxis enhancements. package.json synced to VERSION (drift repair after merging main which had bumped pkg to 1.34.2.0). Co-Authored-By: Claude Opus 4.7 (1M context) * docs: generate /document-generate Diataxis docs (tutorial + how-to + explanation) Fills the documentation debt items flagged by /document-release in PR #1477: critical-gap tutorial coverage and common-gap explanation coverage for the new /document-generate skill. Quadrants: tutorial, how-to, explanation (reference already covered by document-generate/SKILL.md). - docs/tutorial-document-generate.md (1009 words): newcomer 90-second flow - docs/howto-document-a-shipped-feature.md (770 words): post-ship audit + fill workflow - docs/explanation-diataxis-in-gstack.md (1106 words): why Diataxis, trade-offs, alternatives - README.md: links the three docs from the /document-generate skills-table row All cross-links verified — every Related section points at an existing file. Co-Authored-By: Claude Opus 4.7 (1M context) --------- Co-authored-by: Hermes Agent Co-authored-by: Claude Opus 4.7 (1M context) --- CHANGELOG.md | 49 + CLAUDE.md | 33 +- README.md | 10 +- SKILL.md | 1 + SKILL.md.tmpl | 1 + VERSION | 2 +- docs/explanation-diataxis-in-gstack.md | 79 ++ docs/howto-document-a-shipped-feature.md | 105 ++ docs/tutorial-document-generate.md | 142 +++ document-generate/SKILL.md | 1205 ++++++++++++++++++++++ document-generate/SKILL.md.tmpl | 446 ++++++++ document-release/SKILL.md | 96 +- document-release/SKILL.md.tmpl | 96 +- gstack/llms.txt | 1 + package.json | 2 +- 15 files changed, 2243 insertions(+), 25 deletions(-) create mode 100644 docs/explanation-diataxis-in-gstack.md create mode 100644 docs/howto-document-a-shipped-feature.md create mode 100644 docs/tutorial-document-generate.md create mode 100644 document-generate/SKILL.md create mode 100644 document-generate/SKILL.md.tmpl diff --git a/CHANGELOG.md b/CHANGELOG.md index 3652415a6..55cc068f9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,54 @@ # Changelog +## [1.35.0.0] - 2026-05-13 + +## **Docs become a tracked surface, not an afterthought. `/document-generate` writes them from scratch, `/document-release` audits coverage in four Diataxis quadrants.** +## **Every PR now ships a coverage map of what got documented vs what shipped. New skill generates tutorials, how-tos, references, and explanations from code. Both speak the same vocabulary, so gaps become visible in the PR body instead of accumulating silently.** + +You can now run `/document-generate` to write missing documentation from scratch. The skill reads your code first (the codebase archaeology step is non-skippable), maps the public surface, then writes docs in the four Diataxis quadrants: tutorial (newcomer walkthrough), how-to (task-oriented), reference (factual API description), explanation (design rationale). It runs standalone or chains automatically from `/document-release` when the coverage map finds gaps. `/document-release` got a Step 1.5 coverage map that scores every new entity across the four quadrants. Items with zero coverage show up as critical gaps in the PR body. Items with reference-only coverage show up as common gaps. Architecture diagrams get scanned for entity-name drift against the diff. The CHANGELOG voice check now uses a 0-3 sell-test rubric: 1 point each for "what changed?", "why care?", and "how to use it?". Entries below 2 get rewritten. + +A new section in CLAUDE.md documents the fork-PR workflow for `garrytan-agents` PRs: push the branch to `garrytan/gstack` and re-target so eval CI can access secrets. The pattern keeps secret distribution scoped to one branch instead of broadening it to all forks. + +### The numbers that matter + +Source: this PR's diff against `origin/main` and the new skill template at `document-generate/SKILL.md.tmpl`. + +| Surface | Before | After | +|---------|--------|-------| +| Doc-generation skills | 1 (`/document-release`) | 2 (`/document-generate` + enhanced `/document-release`) | +| Diataxis quadrants surfaced in PR body | 0 | 4 (tutorial / how-to / reference / explanation) | +| `/document-release` workflow steps | 9 | 9 + new Step 1.5 (coverage map) | +| CHANGELOG voice scoring | gut-check ("would a user think 'oh nice'?") | 0-3 rubric (3 = reference + explanation + how-to all present) | +| Architecture diagram drift detection | none | scans ARCHITECTURE.md against diff for renamed/removed entities | +| Doc-debt visibility in PR | none | `### Documentation Debt` subsection with critical + common gaps per Diataxis quadrant | + +`/document-generate` is 446 lines of new template producing a 1184-line generated SKILL.md. The Diataxis vocabulary makes "did docs get updated?" a visible answer instead of an implicit one. + +### What this means for downstream gstack users + +You stop guessing whether your docs are complete. When you ship a new skill, `/document-release` shows you which quadrants you covered and which you skipped, and the gaps land in the PR body where reviewers see them. When you want to bootstrap docs for an existing project, `/document-generate` walks you from zero to four-quadrant coverage in one session. Diataxis becomes the shared vocabulary across `/ship`, `/document-release`, `/document-generate`, and whatever skill comes next that needs to know whether you have a tutorial. + +To use: run `/document-release` after `/ship` (or let `/ship` auto-invoke it), see the coverage map in the PR body, then run `/document-generate` if it flags critical gaps. + +### Itemized changes + +#### Added +- **`/document-generate` skill** (`document-generate/SKILL.md.tmpl`, 446 lines): Diataxis-based documentation generator with 9-step workflow — scope, codebase archaeology, partition, reference, explanation, how-to, tutorial, cross-linking, quality self-review. Reads the full codebase before writing a single line of docs. +- **`/document-release` Step 1.5 — Coverage Map**: scans diff for new public surface (skills, CLI flags, config options, API endpoints), classifies each entity by Diataxis quadrant coverage, flags zero-coverage items as critical gaps and reference-only as common gaps. Output feeds the PR body. +- **`/document-release` Architecture diagram drift detection**: extracts entity names from ASCII/Mermaid blocks in ARCHITECTURE.md, cross-references against the diff, flags renamed/removed entities. +- **`/document-release` `### Documentation Debt` section in PR body**: surfaces critical gaps, common gaps, and stale diagrams with a one-line description + Diataxis quadrant per item. Suggests adding a `docs-debt` label. +- **`/document-release` CHANGELOG sell-test rubric**: 0-3 scoring per entry (1 point each for reference / explanation / how-to coverage). Entries below 2 get rewritten. +- **Skill routing entry**: `/document-generate` added to `SKILL.md` routing rules and `README.md` skills table (Technical Writer category). +- **CLAUDE.md fork-PR workflow section**: documents how to handle "check out " when the PR is from a non-collaborator fork. Push the branch to `garrytan/gstack`, close the fork PR, open a new PR from the base-repo branch. Keeps secret distribution scoped. + +#### Changed +- `/document-release` description and triggers updated to reference the coverage map and `/document-generate` chaining. +- README.md skills table grouping: `/document-release` and `/document-generate` now appear under the Technical Writer category. + +#### For contributors +- `document-generate/SKILL.md` is generated from `document-generate/SKILL.md.tmpl`. Do not edit the `.md` directly. Run `bun run gen:skill-docs` after template edits. +- `gstack/llms.txt` now lists `/document-generate` (auto-regenerated from the skill template). + ## [1.34.2.0] - 2026-05-13 ## **Three filed bugs land in one PR. `/codex review`, `/investigate` learnings, and `/sync-gbrain` engine detection all work again.** diff --git a/CLAUDE.md b/CLAUDE.md index af3c58a02..11d85dc78 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -122,7 +122,8 @@ gstack/ ├── investigate/ # /investigate skill (systematic root-cause debugging) ├── retro/ # Retrospective skill (includes /retro global cross-project mode) ├── bin/ # CLI utilities (gstack-repo-mode, gstack-slug, gstack-config, etc.) -├── document-release/ # /document-release skill (post-ship doc updates) +├── document-release/ # /document-release skill (post-ship doc updates + Diataxis coverage map) +├── document-generate/ # /document-generate skill (Diataxis doc generator: tutorial/how-to/reference/explanation) ├── cso/ # /cso skill (OWASP Top 10 + STRIDE security audit) ├── design-consultation/ # /design-consultation skill (design system from scratch) ├── design-shotgun/ # /design-shotgun skill (visual design exploration) @@ -452,6 +453,36 @@ Even if the agent strongly believes a change improves the project, these three categories require explicit user approval via AskUserQuestion. No exceptions. No auto-merging. No "I'll just clean this up." +## Checking out PRs from garrytan-agents + +When the user says "check out " and the PR is from `garrytan-agents/gstack` +(or any other fork that is NOT a collaborator on `garrytan/gstack`), do NOT just +`gh pr checkout`. Fork PRs don't receive base-repo secrets (`ANTHROPIC_API_KEY`, +`OPENAI_API_KEY`, etc.), so the eval/E2E CI jobs fail with empty-env auth errors +regardless of what's set on the base repo. + +**Workflow:** push the branch to `garrytan/gstack` (the base repo) and re-target +the PR from there. + +Concretely, after `gh pr checkout `: + +1. Note the original PR number and head branch name. +2. Push the same branch to the base repo: `git push origin HEAD:` + (origin = `garrytan/gstack`, since the worktree is set up with that remote). +3. Close the fork PR (`gh pr close --comment "moving to base-repo branch for secret access"`). +4. Open a new PR from the base-repo branch: `gh pr create --base main --head `. +5. New PR's workflows will get secrets automatically. + +Why not fix it on the fork side? `garrytan-agents` isn't a collaborator on +`garrytan/gstack`. Adding it as a collaborator (option A) or flipping the +repo-wide "send secrets to fork PRs" toggle (option B) would let secrets reach +fork PRs from anyone — broader blast radius than just moving this one branch. +Option C (this section) keeps secret-distribution scope tight. + +If the user asks you to skip the move (e.g., "just leave it as a fork PR"), +respect that — eval CI will fail with empty-env auth, but check-freshness, +workflow-lint, and windows-tests will still pass on the fork PR. + ## CHANGELOG + VERSION style **Versioning invariant (workspace-aware ship).** VERSION is a monotonic ordered diff --git a/README.md b/README.md index 87f2d5ddd..4e2b792ec 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, /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-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) @@ -198,7 +198,8 @@ Each skill feeds into the next. `/office-hours` writes a design doc that `/plan- | `/land-and-deploy` | **Release Engineer** | Merge the PR, wait for CI and deploy, verify production health. One command from "approved" to "verified in production." | | `/canary` | **SRE** | Post-deploy monitoring loop. Watches for console errors, performance regressions, and page failures. | | `/benchmark` | **Performance Engineer** | Baseline page load times, Core Web Vitals, and resource sizes. Compare before/after on every PR. | -| `/document-release` | **Technical Writer** | Update all project docs to match what you just shipped. Catches stale READMEs automatically. | +| `/document-release` | **Technical Writer** | Update all project docs to match what you just shipped. Catches stale READMEs automatically. Builds a Diataxis coverage map (reference / how-to / tutorial / explanation) so gaps are visible in the PR body. | +| `/document-generate` | **Documentation Author** | Generate missing docs from scratch using the Diataxis framework. Researches the codebase first, then writes reference / how-to / tutorial / explanation docs that actually match the code. Invokable standalone or chained from `/document-release` when the coverage map finds gaps. Learn more: [tutorial](docs/tutorial-document-generate.md) • [how-to](docs/howto-document-a-shipped-feature.md) • [why Diataxis](docs/explanation-diataxis-in-gstack.md). | | `/retro` | **Eng Manager** | Team-aware weekly retro. Per-person breakdowns, shipping streaks, test health trends, growth opportunities. `/retro global` runs across all your projects and AI tools (Claude Code, Codex, Gemini). | | `/browse` | **QA Engineer** | Give the agent eyes. Real Chromium browser, real clicks, real screenshots. ~100ms per command. `/open-gstack-browser` launches GStack Browser with sidebar, anti-bot stealth, and auto model routing. | | `/setup-browser-cookies` | **Session Manager** | Import cookies from your real browser (Chrome, Arc, Brave, Edge) into the headless session. Test authenticated pages. | @@ -466,8 +467,9 @@ Use /browse from gstack for all web browsing. Never use mcp__claude-in-chrome__* 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, /open-gstack-browser, /qa, /qa-only, /design-review, -/setup-browser-cookies, /setup-deploy, /setup-gbrain, /sync-gbrain, /retro, /investigate, /document-release, -/codex, /cso, /autoplan, /pair-agent, /careful, /freeze, /guard, /unfreeze, /gstack-upgrade, /learn. +/setup-browser-cookies, /setup-deploy, /setup-gbrain, /sync-gbrain, /retro, /investigate, +/document-release, /document-generate, /codex, /cso, /autoplan, /pair-agent, /careful, /freeze, +/guard, /unfreeze, /gstack-upgrade, /learn. ``` ## License diff --git a/SKILL.md b/SKILL.md index 5ee5de76e..1a61ac96f 100644 --- a/SKILL.md +++ b/SKILL.md @@ -505,6 +505,7 @@ quality gates that produce better results than answering inline. - User asks to configure deployment for the project → invoke `/setup-deploy` - User asks to monitor prod after shipping, post-deploy checks → invoke `/canary` - User asks to update docs after shipping → invoke `/document-release` +- User asks to write docs from scratch, generate documentation, "document this feature/module" → invoke `/document-generate` - User asks for a weekly retro, what did we ship, "how'd we do" → invoke `/retro` - User asks for a second opinion, codex review → invoke `/codex` - User asks for safety mode, careful mode → invoke `/careful` or `/guard` diff --git a/SKILL.md.tmpl b/SKILL.md.tmpl index a248cbfa3..d382863a4 100644 --- a/SKILL.md.tmpl +++ b/SKILL.md.tmpl @@ -49,6 +49,7 @@ quality gates that produce better results than answering inline. - User asks to configure deployment for the project → invoke `/setup-deploy` - User asks to monitor prod after shipping, post-deploy checks → invoke `/canary` - User asks to update docs after shipping → invoke `/document-release` +- User asks to write docs from scratch, generate documentation, "document this feature/module" → invoke `/document-generate` - User asks for a weekly retro, what did we ship, "how'd we do" → invoke `/retro` - User asks for a second opinion, codex review → invoke `/codex` - User asks for safety mode, careful mode → invoke `/careful` or `/guard` diff --git a/VERSION b/VERSION index 3137b12a8..c25c8ba4b 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.34.2.0 +1.35.0.0 diff --git a/docs/explanation-diataxis-in-gstack.md b/docs/explanation-diataxis-in-gstack.md new file mode 100644 index 000000000..0e201d5ea --- /dev/null +++ b/docs/explanation-diataxis-in-gstack.md @@ -0,0 +1,79 @@ +# Why gstack uses Diataxis for documentation + +The two doc skills in gstack — `/document-release` and `/document-generate` — both speak Diataxis. New entities get scored across four quadrants. Coverage gaps surface in PR bodies tagged by quadrant. This doc explains why that vocabulary is load-bearing, and why a simpler "just write markdown" approach falls down at the scale gstack operates at. + +## The problem + +Documentation rot is the easiest kind of rot to ignore. Code stops compiling and you notice immediately. A test fails and CI screams. Docs go stale silently — the README still parses, the install command still copy-pastes — and the only signal is a confused user weeks later filing an issue or quietly walking away. + +gstack has more than 45 skills. Every one is a SKILL.md plus a `.tmpl` template plus, ideally, a getting-started tutorial somewhere and an explanation of why it works the way it does. Multiply that by however many gstack users have similar surface-area in their own projects and the maintenance load is real. + +The naive failure mode is "every team writes docs in their own format." One project has a Wiki. Another has nested README files. A third has reference-only API docs and no tutorials. A fourth has tutorials that no longer compile. You can't write tooling that audits across all of those because there's no shared vocabulary for what good coverage means. + +The second failure mode is more subtle: even when a team is disciplined, they tend to write the kind of doc that matches their current state of mind. Engineers in build mode write reference. Engineers in launch mode write tutorials. Engineers in maintenance mode write troubleshooting how-tos. No one wakes up and says "today I'll write the explanation doc for why we chose this architecture" — so explanation rot accumulates fastest. + +## The approach + +Diataxis (Daniele Procida, originally at Divio, now adopted across CPython, Django, NumPy, FastAPI, GitHub docs, and many others) splits documentation into four quadrants based on **reader intent**: + +``` + THEORETICAL PRACTICAL + (understanding) (doing) + + STUDY +-----------------------------+----------------------------+ + (learning) | | | + | EXPLANATION | TUTORIAL | + | "Why does X exist?" | "Walk me through X | + | | for the first time" | + | discusses code | teaches code | + | | | + +-----------------------------+----------------------------+ + + WORK +-----------------------------+----------------------------+ + (using) | | | + | REFERENCE | HOW-TO | + | "What is the exact | "How do I accomplish Y | + | signature of Y?" | using X?" | + | | | + | describes code | uses code | + | | | + +-----------------------------+----------------------------+ +``` + +A reader in tutorial mode is learning by doing. They want a guided path with guaranteed success. A reader in how-to mode already knows the basics and wants the recipe for a specific task. A reader in reference mode wants accurate, complete, fact-table coverage of the API. A reader in explanation mode wants to understand a design decision. + +The same person reads a project from each of these modes at different times. The same paragraph cannot serve all four — tutorials need handholding that would slow down a reference reader; reference needs completeness that would overwhelm a tutorial reader. + +## Why this matters as a coverage lens + +A coverage map written in Diataxis terms gives you a deterministic answer to "did docs get updated?" — not "is there a README" but "is there a tutorial for this new skill, a how-to for the common task, a reference for the API, and an explanation for the non-obvious design choice?" + +`/document-release` Step 1.5 walks the diff, extracts new public surface (skills, CLI flags, config options, API endpoints), and scores each entity across the four quadrants. Items with zero coverage become **critical gaps**. Items with only reference coverage (the most common failure mode in gstack's own history) become **common gaps**. Both land in the PR body where reviewers see them. + +`/document-generate` writes docs in the four quadrants intentionally. It refuses to mix them: a tutorial does not get a "Configuration" section, a reference doc does not get a "What you'll build" paragraph. The skill's 9 steps go reference → explanation → how-to → tutorial because that ordering matches the dependency: reference fixes the vocabulary, explanation justifies the design, how-tos build on both, tutorials are the last and hardest. + +## Trade-offs + +**Diataxis adds vocabulary that readers must learn.** A user who's never heard of "reference vs explanation" might find the labels strange at first. The mitigation is that Diataxis labels are self-explanatory once you've seen them once, and the labels never appear in the docs themselves — they appear in the coverage map and PR body, where reviewers see them, not end users. + +**Four files instead of one.** A small skill might have one `docs/SKILL.md` file that mixes all four modes. Diataxis splits that into four. The mitigation: AI generation makes the four-file structure cheap, the cross-linking between quadrants is mechanical (every reference doc links to its how-to, every how-to links to its reference, etc.), and the gains in audit-ability are substantial — `/document-release` can score coverage automatically. + +**Diataxis is not the only good framework.** "Every page is page one" (Mark Baker), the four kinds of docs in the *Write the Docs* community, the Google developer documentation style guide — all have different cuts. gstack picked Diataxis because it has the strongest external adoption (CPython, Django, NumPy, FastAPI, etc.), which means downstream users have the highest chance of having seen the vocabulary before, and the quadrant labels translate cleanly to coverage-map signals. + +## Alternatives considered + +**"Just write README sections."** Tried implicitly across gstack's history. Failure mode: tutorials accumulated in README until READMEs were 800+ lines and nobody read them past line 50. Diataxis splits them into dedicated files, each discoverable from README's table of contents. + +**Custom in-house taxonomy.** Tempting because it could be tailored. Rejected because every team would invent their own vocabulary and `/document-release` would lose its cross-project audit power. Diataxis is the lingua franca. + +**Auto-generated reference only.** Tried via tools like JSDoc / TypeDoc / Sphinx for many projects. Reference docs without explanation become impenetrable for newcomers; without tutorials, the API is hard to onboard onto. Reference is necessary but not sufficient. + +**No documentation framework at all, just gut-check.** The status quo for most projects. Fails silently — users walk away rather than file issues, so the feedback loop is broken. Diataxis gives a structured signal even before users complain. + +## Related + +- **Reference for the skill that implements this:** [`document-generate/SKILL.md`](../document-generate/SKILL.md) +- **Reference for the audit that uses this taxonomy:** [`document-release/SKILL.md`](../document-release/SKILL.md) +- **Tutorial for using `/document-generate`:** [`tutorial-document-generate.md`](./tutorial-document-generate.md) +- **How-to: document a shipped feature:** [`howto-document-a-shipped-feature.md`](./howto-document-a-shipped-feature.md) +- **Diataxis homepage:** https://diataxis.fr/ — Procida's canonical reference for the framework diff --git a/docs/howto-document-a-shipped-feature.md b/docs/howto-document-a-shipped-feature.md new file mode 100644 index 000000000..f2959eb5d --- /dev/null +++ b/docs/howto-document-a-shipped-feature.md @@ -0,0 +1,105 @@ +# How to document a feature you just shipped + +This is the post-ship workflow: you merged a PR, the docs are stale, and you want a coverage map plus filled gaps in one pass. You'll run `/document-release` to audit, then `/document-generate` to fill the gaps it finds. + +## Prerequisites + +- gstack installed (`./setup` complete; verify with `which gstack` or by typing `/` in Claude Code and seeing skills listed) +- The branch with your shipped feature is checked out +- A PR exists on GitHub or GitLab (recommended — the workflow updates the PR body with a coverage map) + +If no PR exists yet, run `/ship` first to create one; that's what `/document-release` is designed to run against. + +## Steps + +### 1. Audit current coverage + +Run: + +``` +/document-release +``` + +The skill walks your diff against the base branch, extracts new public surface (skills, CLI flags, config options, API endpoints, new modules), and scores each entity across the four Diataxis quadrants. You'll see a coverage map like: + +``` +Coverage map: + [entity] [reference?] [how-to?] [tutorial?] [explanation?] + /new-skill ✅ AGENTS.md ❌ ❌ ❌ + --new-flag ✅ README ✅ README ❌ ❌ + FooProcessor ❌ ❌ ❌ ❌ +``` + +Items with zero coverage are **critical gaps**. Items with only reference coverage are **common gaps**. Both land in the PR body as a `### Documentation Debt` subsection so reviewers see them. + +If `/document-release` reports everything is covered, you're done. Skip the rest of this how-to. + +### 2. Read the documentation debt section in the PR body + +Open your PR (the skill prints the URL). Scroll to `## Documentation` → `### Documentation Debt`. Each item is tagged with the Diataxis quadrant that would fill it: + +``` +### Documentation Debt + +- ⚠️ /new-skill — has reference in AGENTS.md but no how-to example in README. Diataxis quadrant: how-to. +- ⚠️ FooProcessor — zero coverage. Diataxis quadrants: reference, explanation. +``` + +This is the input to the next step. Each line tells you what's missing and which quadrant fills it. + +### 3. Fill the gaps with /document-generate + +Run: + +``` +/document-generate +``` + +When the skill asks about scope, tell it the specific entities flagged in the debt section. The skill reads the codebase (its Step 1 archaeology phase is mandatory), partitions by Diataxis quadrant, and writes the missing docs. + +You can also let the skill auto-discover: if /document-release passed you the gaps explicitly (it does this when chained), `/document-generate` already knows what to write. + +### 4. Verify the gaps closed + +Re-run `/document-release`: + +``` +/document-release +``` + +The coverage map should now show the previously-flagged entities with green checkmarks in the previously-empty quadrants. The PR body's Documentation Debt section should be empty or reduced to items you intentionally deferred. + +## Verification + +Open your PR and confirm: + +1. The PR body has a `## Documentation` section with a doc-diff preview. +2. The `### Documentation Debt` subsection lists zero critical gaps (or only items you knowingly deferred). +3. Each generated doc file in `docs/` opens cleanly and cross-links to siblings (reference → how-to → tutorial → explanation). +4. Run `grep -rE '\]\([^)]*\.md\)' docs/` and verify no link points to a missing file. + +If all four check, your PR is ready to land with complete documentation. + +## Troubleshooting + +**`/document-release` reports "No public surface changes detected."** +The diff is internal-only (refactors, tests, infra). No docs are needed. Skip to landing. + +**The Diataxis quadrant tag on a gap doesn't match what you'd expect.** +The skill uses an entity taxonomy to decide which quadrants matter (CLI flags want reference + how-to; internal modules want reference + explanation; user-facing features want all four). If you disagree, you can override by hand-editing the docs after generation. The audit is a guide, not a constraint. + +**`/document-generate` writes a tutorial that takes 8 steps to reach a working result.** +Tutorials should hit a working result in 3 steps or fewer. Re-run the skill and ask it to compress, or hand-edit. The Step 8 Quality Self-Review catches some of these but not all. + +**You want to document a feature but no PR exists yet.** +Run `/ship` first to create the PR, then this workflow. Without a PR, `/document-release` can still audit but skips the PR-body update. + +**A generated reference doc has hallucinated API signatures.** +File a bug. The skill's Step 1 archaeology is supposed to read implementation files end-to-end, not just signatures, specifically to prevent this. Include the generated text and the actual code so we can trace why the archaeology missed it. + +## Related + +- **Tutorial: first time using `/document-generate`:** [tutorial-document-generate.md](./tutorial-document-generate.md) +- **Why gstack uses the Diataxis framework:** [explanation-diataxis-in-gstack.md](./explanation-diataxis-in-gstack.md) +- **Reference for the audit skill:** [`document-release/SKILL.md`](../document-release/SKILL.md) +- **Reference for the generation skill:** [`document-generate/SKILL.md`](../document-generate/SKILL.md) diff --git a/docs/tutorial-document-generate.md b/docs/tutorial-document-generate.md new file mode 100644 index 000000000..7e8e78f45 --- /dev/null +++ b/docs/tutorial-document-generate.md @@ -0,0 +1,142 @@ +# Tutorial: generate docs for a feature in 90 seconds + +You'll run `/document-generate` against a project you already have, watch it write tutorial / how-to / reference / explanation docs in the right places, and end with a coverage map you can drop into a PR. By the end, you'll know the four moves: scope, archaeology, partition, write. + +## What you'll need + +- gstack installed (`git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup`) +- Claude Code running in any project that has at least one piece of public surface (a CLI command, an exported function, a config option, a skill, an API endpoint) +- About 90 seconds + +You do not need a `docs/` directory in advance — the skill creates one if it's missing. You do not need to know Diataxis terminology — the skill labels the output for you. + +## Step 1: Invoke the skill in any project + +Open Claude Code in the project you want to document. Type: + +``` +/document-generate +``` + +You'll see the skill ask one question about output target: + +``` +A) Write documentation inline in existing files (README, ARCHITECTURE, etc.) +B) Create standalone documentation files (e.g., docs/ directory) +C) Both — inline summaries in existing files + deep docs in standalone files + +RECOMMENDATION: Choose C because it maximizes both discoverability and depth. +``` + +Pick C. You'll get a README pointer plus a full set of standalone docs. + +## Step 2: Watch the archaeology run + +The skill goes silent for ~30 seconds while it reads the codebase. This is intentional — the Step 1 "Codebase Archaeology" phase is the most important step in the workflow. The skill is reading: + +- The full repository structure +- README, ARCHITECTURE, CONTRIBUTING, CLAUDE.md (the entry points) +- The implementation files for whatever you're documenting (full file, not just signatures) +- The tests (which reveal edge cases and intended behavior) +- Inline comments tagged `// NOTE:`, `// DESIGN:`, `// WHY:` + +When it finishes, you'll see a line like: + +``` +Researched 47 files, identified 12 public surface items, 8 concepts, and 4 design decisions. +``` + +That number tells you the skill actually read the code rather than guessing from filenames. + +## Step 3: See the Diataxis partition plan + +The skill prints a partition plan showing which quadrants it'll write for which entity: + +``` +Documentation plan: + [entity] [tutorial] [how-to] [reference] [explanation] + WidgetService ✅ new ✅ new ✅ new ✅ new + --verbose flag ❌ ✅ new ✅ inline ❌ + Bayesian scheduler ❌ ❌ ✅ new ✅ new +``` + +Not every entity needs all four quadrants. CLI flags get reference + how-to. Internal modules get reference + explanation. User-facing features get all four. The skill picks based on entity type. + +If the plan has more than 5 documents, the skill asks you to confirm before proceeding. Otherwise it goes. + +## Step 4: Read the first doc that lands + +Reference docs land first because they fix the vocabulary. You'll see lines like: + +``` +GENERATED: docs/reference-widget-service.md +``` + +Open that file. It has a strict structure: one-paragraph intro, complete API listing with types and defaults, 2-3 runnable examples, and a Related section linking to the how-to and tutorial that will land next. + +This is what reference docs look like in Diataxis: factual, exhaustive, no narrative. If you find yourself wanting to explain *why* an option exists, that belongs in the explanation doc the skill will write next. + +## Step 5: See the explanation, how-to, and tutorial appear + +In quick succession (each ~5-10 seconds), the skill writes the remaining quadrants: + +``` +GENERATED: docs/explanation-widget-architecture.md +GENERATED: docs/howto-create-a-custom-widget.md +GENERATED: docs/tutorial-build-your-first-widget.md +``` + +Open each one. Notice they don't repeat each other: + +- **Explanation** leads with the problem, then the approach, then trade-offs and alternatives considered +- **How-to** has prerequisites, numbered steps with exact commands, a verification section, and a troubleshooting section +- **Tutorial** gets you to a working result in under 3 steps, ends with "What you built" + +The skill enforces these structures. If a how-to was missing a verification section, the Step 8 Quality Self-Review caught it before commit. + +## Step 6: Check cross-linking + +Every doc links to the others. Reference doc Related section: links to how-to and tutorial. How-to Related section: links to reference. Tutorial "What you built" section: links to reference for deeper exploration. + +Run a grep to verify no broken links: + +```bash +grep -rE '\]\([^)]*\.md\)' docs/ | head -10 +``` + +Every linked file should exist. The skill's Step 7 "Cross-Document Linking & Discoverability" checks this before commit. + +## Step 7: See the coverage summary in the PR body + +If you're on a feature branch with an open PR, the skill updates the PR body with a `## Documentation Generated` table: + +``` +## Documentation Generated + +| File | Quadrant | Description | +|------|----------|-------------| +| docs/tutorial-build-your-first-widget.md | Tutorial | Walk-through from install to first working widget | +| docs/reference-widget-service.md | Reference | Complete widget API with types, defaults, examples | +| docs/explanation-widget-architecture.md | Explanation | Why widgets are isolated services | +| docs/howto-create-a-custom-widget.md | How-to | Creating and registering custom widgets | +``` + +A reviewer opening the PR sees the table and knows immediately what kind of coverage shipped. + +## What you built + +You now have four documents that serve four different readers: + +- A newcomer to your project can read `tutorial-*.md` and get something working +- An experienced user can read `howto-*.md` to accomplish a specific task +- An API caller can read `reference-*.md` for exact signatures +- A code reviewer can read `explanation-*.md` to understand the design + +Each one is short enough to maintain. Each one has a single job. The PR body shows which quadrants were covered. If you run `/document-release` later, the Diataxis coverage map will report this entity as fully covered (4/4 quadrants). + +## What to do next + +- **If you have gaps** /document-release flagged but didn't fill: run `/document-generate` again, scoped to those entities specifically. +- **If you want to understand why the four quadrants exist:** read [explanation-diataxis-in-gstack.md](./explanation-diataxis-in-gstack.md). +- **If you want to document one specific shipped feature** (not the whole project): read [howto-document-a-shipped-feature.md](./howto-document-a-shipped-feature.md). +- **Reference for the skill itself:** [`document-generate/SKILL.md`](../document-generate/SKILL.md). diff --git a/document-generate/SKILL.md b/document-generate/SKILL.md new file mode 100644 index 000000000..d9e0ddeb8 --- /dev/null +++ b/document-generate/SKILL.md @@ -0,0 +1,1205 @@ +--- +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)