golem15/msd-core
4
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

chore(#604): rename get-shit-done/ runtime directory to gsd-core/ (#615)

Browse Source 
* chore(#604): rename get-shit-done/ runtime directory to gsd-core/

Renames the installed runtime directory `get-shit-done/` to `gsd-core/` so the
on-disk name matches the package (`@opengsd/gsd-core`), repo, and binary
(`gsd-tools`). The npm package name and binary are unchanged; npx/npm consumers
are unaffected.

Mechanical (bulk, ~90% of the diff):
- `git mv get-shit-done gsd-core`
- Swept path/identifier references across the repo via
  `perl -pe 's/get-shit-done(?!-\w)/gsd-core/g'`. The negative lookahead
  preserves the five legitimate slug variants that are NOT the directory:
  get-shit-done-{OLD,cc,classic,cli,redux} (old package/repo names).
- Build/manifest wiring: package.json (bin, files, coverage globs),
  tsconfig.build.json (outDir), ~86 .gitignore build-output entries,
  stryker.config.mjs, scan-ignore files, install.js path strings.
- Frozen (not rewritten): CHANGELOG.md history; translated docs
  (README.<locale>.md and docs/{ja-JP,ko-KR,pt-BR,zh-CN}/).

New logic (review here):
- src/installer-migrations/003-rename-get-shit-done-to-gsd-core.cts: a proper
  ADR-0008 installer migration. On upgrade it walks the legacy
  `~/.claude/get-shit-done/` tree, classifies each file via the prior install
  manifest, and emits remove-managed / backup-and-remove for managed files
  while PRESERVING unknown user-added files. Symlink-safe (skips a symlinked
  root and symlinked entries; bounds-checks every path under configDir). The
  framework rolls back on install failure. Emptied dirs may remain (framework
  has no recursive dir-removal primitive) — documented.
- scripts/lint-legacy-dir-name.cjs: CI regression guard forbidding the bare
  `get-shit-done` directory token (split token to avoid self-match; case-
  insensitive; `(?!-\w)` lookahead allows the slug variants; allowlists
  CHANGELOG, translated docs, and `gsd-allow-legacy-name` marker lines).
  Wired into the lint-tests CI job.
- Restored scripts/lint-package-identity-drift.cjs detection regexes (the
  mechanical sweep had wrongly rewritten the old-name patterns it exists to
  detect) and marked them as intentional legacy references.
- TDD tests for the migration and the guard; do.md slash-command guard regex
  tightened so a `/gsd-core/bin` path segment is not mistaken for a command;
  changeset + docs/installer-migrations.md row added.

Breaking: the installed runtime path moves `~/.claude/get-shit-done/` ->
`~/.claude/gsd-core/`. Migration 003 removes the stale legacy dir's managed
files (preserving user files) on upgrade. Users with custom hooks/configs
hardcoding the old path must update them.

Closes #604

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(#604): unsweep pending changesets + allowlist injection-example docs

CI fixes for the rename PR:
- Do not sweep pending .changeset/*.md (ephemeral release-note fragments,
  like CHANGELOG); reverted those body edits so 5 pre-existing malformed
  fragments (missing type/pr) no longer enter the PR diff and trip docs-lint.
  Allowlisted .changeset/ in the legacy-name guard accordingly.
- Allowlisted TEST-EXAMPLES.md and docs/explanation/security-model.md in
  prompt-injection-scan.sh: they contain intentional injection examples /
  security-model prose; the path-reference rewrites are kept.

CodeQL alerts on this PR are pre-existing (alert lines unchanged by this PR;
none in the new migration/guard) and are out of scope for the rename.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(#604): resolve CodeQL alerts surfaced on this PR

The rename diff touched files carrying pre-existing CodeQL findings; per the
no-pre-existing-dismissal rule, fixing every surfaced alert rather than waving
them off. All behavior-preserving:

- scripts/ci-test-scope.cjs: build the config-path match from string
  .includes() instead of a RegExp over an arg-derived value (js/regex-injection).
- src/profile-output.cts: escape backslashes before pipe-escaping desc/safeName
  so the table-cell escape is complete (js/incomplete-sanitization).
- tests/{bug-2643,bug-2808,docs-parity-live-registry}: two-pass HTML-comment
  strip so a bare/unclosed `<!--` cannot survive (js/incomplete-multi-character-sanitization).
- tests/inline-plan-threshold: drop the no-op `\s`->`\s` identity replace,
  keep the meaningful POSIX-class conversion (js/identity-replacement).

Verified: build:lib green; the touched test files + ci-test-scope + profile-output
suites pass; lint:legacy-name clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(#604): correctly resolve remaining CodeQL alerts (regex-injection + sanitization)

The prior commit's fixes for two alerts were ineffective:
- ci-test-scope.cjs js/regex-injection: the alert is the CLI-arg-derived `file`
  reaching static regex `.test(file)` calls (not the config rule). Removed ALL
  regex over file/t — startsWith/includes/=== string checks + an isWindowsHint
  helper — so there is no regex sink for the tainted value.
- js/incomplete-multi-character-sanitization (3 test files): a single
  `.replace(/<!--...-->/g,'')` can let `<!--` re-form. Replaced with a fixpoint
  loop (replace until stable) plus a final bare-opener strip.

Verified: no regex over file/t remains; ci-test-scope + the 3 test suites pass;
lint:legacy-name clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(#604): make ci-test-scope + comment-strippers regex-free to clear CodeQL

CodeQL flags the regex PATTERNS syntactically (regex-injection on the
--files arg split; incomplete-multi-character-sanitization on the <!--...-->
replace), so loop fixes do not satisfy it. Made these paths regex-free:
- ci-test-scope.cjs splitFiles: char-by-char separator tokenizer (no /[,\\s]+/).
- 3 test files: indexOf/slice HTML-comment stripper (no .replace(/<!--/)).
Behavior preserved; ci-test-scope + the 3 suites pass; guard clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(#604): unblock security base64 scan on the large rename diff

The security job hit its 10m timeout: base64-scan.sh choked on the binary
test fixture tests/feat-3594-parser-property-style.test.cjs (embedded NUL/
non-UTF8 bytes -> thousands of bogus blobs + "ignored null byte" warnings),
and the ~800-file rename diff is slow to scan regardless.

- scripts/base64-scan.sh: skip binary-by-content files (grep -Iq .) — they
  can't carry base64-obfuscated *text* and feeding NUL bytes through the
  per-line scanner is pathologically slow. collect_files already filtered
  binary *extensions*; this catches binary *content* in text extensions.
- .github/workflows/security-scan.yml: raise the security job timeout 10m->30m
  to accommodate very large diffs (the scan itself is unchanged).

Verified locally: scan skips the fixture, 0 "ignored null byte" warnings,
0 findings, exit 0.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(#604): sweep get-shit-done refs introduced by merging next

The branch was updated with next (#614/#384/#618 etc.), which reference the
get-shit-done/ dir (still named that on next). Swept the stale references in
the merged files to gsd-core so the rename stays consistent and lint:legacy-name
passes:
- commands/gsd/discuss-phase.md (runtime-launcher shim paths)
- src/core.cts (getAgentsDir layout comments)
- tests/bug-384-agents-runtime-aware.test.cjs (require path to runtime lib)

Verified: guard 0 violations; build green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(#604): exclude gsd-core/ path segments from bug-3683 command cross-ref invariant

The #614 runtime-launcher shim added to discuss-phase.md references
`${_GSD_RUNTIME_ROOT}/gsd-core/bin/...`. bug-3683's REF_PATTERN excluded path-y
refs only via lookbehind, but `}` precedes `/gsd-core/` in the shim, so it
mis-read the directory path as a dangling `/gsd-core` command ref (same class as
the #604 bug-2954 fix). Added a trailing `(?![\w-]*\/)` so `/gsd-<x>/...` path
segments are not treated as slash-command references.

Verified locally on BOTH platforms before pushing:
- mac (node 26) full suite: 0 failures
- gsd-test-runner (linux, node22 image) full suite: 0 failures
- bug-3683 + bug-2954 pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(#604): lazily resolve findProjectRoot in gsd-tools (harden flaky CI)

CI intermittently failed state.test's gsd-tools subprocess with
"findProjectRoot is not a function" (flip-flopping across legs; not reproducible
on mac full suite, gsd-test linux full suite, test:unit, or state.test x8).
findProjectRoot is a re-export from core.cjs (sourced from project-root.cjs);
binding it via destructure at module-load can be undefined under a load-ordering
edge. Resolve it lazily at call time via a small wrapper so the lookup happens
after core.cjs is fully initialized.

Verified green on BOTH platforms before pushing:
- mac (node 26) full suite: 0 failures
- gsd-test-runner (linux, node22) full suite: 0 failures
- state.test.cjs: 106/106; gsd-tools loads cleanly.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(#604): allowlist verification-patterns.md placeholder examples in secret scan

The rename git-mv'd references/verification-patterns.md into gsd-core/, pulling
it into the secret-scan diff. It documents stub/placeholder RED-FLAG env-var
examples (illustrative Stripe test-key / database-URL / API-key placeholders) —
not real credentials. Added it to .secretscanignore with the strict annotation,
mirroring the existing gsd-core/workflows/plan-phase.md exception.

Verified locally: secret-scan-lint --strict OK; secret-scan --diff origin/next
exits 0 with 0 findings.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-06-02 18:35:29 -04:00
committed by GitHub
parent b177c1704f
commit 463cffd894
845 changed files with 3316 additions and 2373 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
gsd-core/workflows/help/modes/brief.md Normal file
View File

@@ -0,0 +1,22 @@
<purpose>
One-liner refresher for returning users. Output ONLY the `<reference>` content below. No additions.
</purpose>
<reference>
**GSD — top commands**
```text
/gsd:new-project Initialize a project (greenfield)
/gsd:map-codebase Map an existing codebase (brownfield)
/gsd:plan-phase <N> Create a phase plan
/gsd:execute-phase <N> Execute a phase
/gsd:progress Where am I, what's next
/gsd:quick Small ad-hoc task with GSD guarantees
/gsd:fast "<task>" Trivial inline task — no subagents
/gsd:debug "<symptom>" Persistent debug session (survives /clear)
/gsd:capture Save an idea / todo / note
/gsd:ship <N> Open a PR from a completed phase
```
More: `/gsd:help` (default tour) · `/gsd:help --full` (everything) · `/gsd:help <topic>` (one section)
</reference>

50
gsd-core/workflows/help/modes/default.md Normal file
View File

@@ -0,0 +1,50 @@
<purpose>
One-page newcomer-oriented tour of GSD Core. Output ONLY the `<reference>` content below. No additions.
</purpose>
<reference>
# GSD Core — Git. Ship. Done.
Plan-driven development for solo agentic work with Claude Code. GSD Core turns a vague idea into a hierarchical plan, then executes it phase by phase with state tracking and atomic commits.
## Start here (3 commands)
```text
/gsd:new-project # Greenfield: questioning → research → requirements → roadmap
/gsd:plan-phase 1 # Create a detailed plan for phase 1
/gsd:execute-phase 1 # Execute all plans in the phase
```
Existing codebase? Run `/gsd:map-codebase` first to ground GSD in your code.
## Common commands
| Command | Purpose |
|---|---|
| `/gsd:progress` | Where am I, what's next — also routes freeform intent with `--do "..."` |
| `/gsd:quick` | Small ad-hoc task with GSD guarantees (planning dir + atomic commit) |
| `/gsd:fast "<task>"` | Trivial inline change — no subagents, ≤3 file edits |
| `/gsd:discuss-phase <N>` | Capture vision and decisions before planning |
| `/gsd:debug "<symptom>"` | Persistent debug session, survives `/clear` |
| `/gsd:capture` | Save an idea, todo, note, seed, or backlog item |
| `/gsd:verify-work <N>` | Conversational UAT for a completed phase |
| `/gsd:ship <N>` | Open a PR from a completed phase |
| `/gsd:help --full` | Complete reference (every command, every flag) |
## Want more?
```text
/gsd:help --brief # 10-line refresher of top commands
/gsd:help --full # complete reference
/gsd:help <topic> # one section only — see topics below
/gsd:help --brief <topic> # compact scoped lookup — signature + one-line summary
```
Topics: `workflow` · `planning` · `execute` · `quick` · `debug` · `capture` · `ship` · `config` · `milestones` · `spike` · `sketch` · `review` · `audit` · `progress`
## Update GSD
```bash
npx @opengsd/gsd-core@latest
```
</reference>

784
gsd-core/workflows/help/modes/full.md Normal file
View File

@@ -0,0 +1,784 @@
<purpose>
Display the complete GSD Core command reference. Output ONLY the reference content. Do NOT add project-specific analysis, git status, next-step suggestions, or any commentary beyond the reference.
</purpose>
<reference>
# GSD Core Command Reference
**GSD Core** (Git. Ship. Done.) creates hierarchical project plans optimized for solo agentic development with Claude Code.
## Quick Start
1. `/gsd:new-project` - Initialize project (includes research, requirements, roadmap)
2. `/gsd:plan-phase 1` - Create detailed plan for first phase
3. `/gsd:execute-phase 1` - Execute the phase
## Staying Updated
GSD evolves fast. Update periodically:
```bash
npx @opengsd/gsd-core@latest
```
## Core Workflow
```text
/gsd:new-project → /gsd:plan-phase → /gsd:execute-phase → repeat
```
### Project Initialization
**`/gsd:new-project`**
Initialize new project through unified flow.
One command takes you from idea to ready-for-planning:
- Deep questioning to understand what you're building
- Optional domain research (spawns 4 parallel researcher agents)
- Requirements definition with v1/v2/out-of-scope scoping
- Roadmap creation with phase breakdown and success criteria
Creates all `.planning/` artifacts:
- `PROJECT.md` — vision and requirements
- `config.json` — workflow mode (interactive/yolo)
- `research/` — domain research (if selected)
- `REQUIREMENTS.md` — scoped requirements with REQ-IDs
- `ROADMAP.md` — phases mapped to requirements
- `STATE.md` — project memory
Usage: `/gsd:new-project`
**`/gsd:map-codebase [--fast] [--focus <area>] [--query <term>]`**
Map an existing codebase for brownfield projects.
- `--fast` — rapid lightweight assessment (replaces the former `gsd-scan`)
- `--focus <area>` — scope the map to a specific area
- `--query <term>` — query the codebase intelligence index in `.planning/intel/` (replaces the former `gsd-intel`)
- Analyzes codebase with parallel Explore agents
- Creates `.planning/codebase/` with 7 focused documents
- Covers stack, architecture, structure, conventions, testing, integrations, concerns
- Use before `/gsd:new-project` on existing codebases
Usage: `/gsd:map-codebase`
### Phase Planning
**`/gsd:discuss-phase <number> [--chain | --analyze | --power | --assumptions] [--batch[=N]]`**
Help articulate your vision for a phase before planning.
- `--chain` — chained-prompt discuss flow
- `--analyze` — deep assumption analysis pass
- `--power` — power-user mode with extended question set
- `--assumptions` — surface Claude's implementation assumptions about the phase without an interactive session
- Captures how you imagine this phase working
- Creates CONTEXT.md with your vision, essentials, and boundaries
- Use when you have ideas about how something should look/feel
- Optional `--batch` asks 2-5 related questions at a time instead of one-by-one
Usage: `/gsd:discuss-phase 2`
Usage: `/gsd:discuss-phase 2 --batch`
Usage: `/gsd:discuss-phase 2 --batch=3`
**`/gsd:plan-phase <number> [--research] [--skip-research] [--research-phase <N>] [--view] [--gaps] [--skip-verify] [--prd <file>] [--ingest <path-or-glob>] [--ingest-format <auto|nygard|madr|narrative>] [--reviews] [--text] [--tdd] [--mvp]`**
Create detailed execution plan for a specific phase.
- `--skip-research` — bypass the research subagent
- `--research-phase <N>` — research-only mode. Spawns the research agent for phase `<N>`, writes `RESEARCH.md`, then exits before the planner runs. Useful for cross-phase research, doc review before committing to a planning approach, and correction-without-replanning loops. Replaces the deleted `gsd-research-phase` standalone command (#3042).
- Modifiers: `--research` forces refresh (re-spawn researcher, no prompt). `--view` prints existing `RESEARCH.md` to stdout without spawning. With neither, prompts `update / view / skip` if `RESEARCH.md` already exists.
- `--gaps` — focus only on closing gaps from a prior plan-check
- `--skip-verify` — skip the post-plan verifier loop
- `--ingest <path-or-glob>` — pre-ingest external ADRs/PRDs/SPECs before planning (see *PRD Express Path* below)
- `--ingest-format <auto|nygard|madr|narrative>` — hint the ADR ingester's parser when `--ingest` is set; defaults to `auto`
- `--tdd` — plan in test-driven order (tests before code)
- `--mvp` — vertical-slice MVP planning mode (see also `/gsd:mvp-phase`)
- Generates `.planning/phases/XX-phase-name/XX-YY-PLAN.md`
- Breaks phase into concrete, actionable tasks
- Includes verification criteria and success measures
- Multiple plans per phase supported (XX-01, XX-02, etc.)
Usage: `/gsd:plan-phase 1`
Usage: `/gsd:plan-phase --research-phase 2` — research only on phase 2 (prompts if `RESEARCH.md` exists)
Usage: `/gsd:plan-phase --research-phase 2 --view` — print existing `RESEARCH.md`, no spawn
Usage: `/gsd:plan-phase --research-phase 2 --research` — force-refresh, no prompt
Result: Creates `.planning/phases/01-foundation/01-01-PLAN.md`
**PRD Express Path:** Pass `--prd path/to/requirements.md` to skip discuss-phase entirely. Your PRD becomes locked decisions in CONTEXT.md. Useful when you already have clear acceptance criteria.
### Execution
**`/gsd:execute-phase <phase-number> [--wave N] [--gaps-only] [--tdd]`**
Execute all plans in a phase, or run a specific wave.
- `--wave N` — execute only wave N (see *Plans within each wave* below)
- `--gaps-only` — re-run only plans flagged as gaps by a prior verifier
- `--tdd` — enforce test-driven order during execution
- Groups plans by wave (from frontmatter), executes waves sequentially
- Plans within each wave run in parallel via Task tool
- Optional `--wave N` flag executes only Wave `N` and stops unless the phase is now fully complete
- Verifies phase goal after all plans complete
- Updates REQUIREMENTS.md, ROADMAP.md, STATE.md
Usage: `/gsd:execute-phase 5`
Usage: `/gsd:execute-phase 5 --wave 2`
### Smart Router
**`/gsd:progress --do "<description>"`**
Route freeform text to the right GSD command automatically.
- Analyzes natural language input to find the best matching GSD command
- Acts as a dispatcher — never does the work itself
- Resolves ambiguity by asking you to pick between top matches
- Use when you know what you want but don't know which `/gsd-*` command to run
Usage: `/gsd:progress --do "fix the login button"`
Usage: `/gsd:progress --do "refactor the auth system"`
Usage: `/gsd:progress --do "I want to start a new milestone"`
### Quick Mode
**`/gsd:quick [--full] [--validate] [--discuss] [--research]`**
Execute small, ad-hoc tasks with GSD guarantees but skip optional agents.
Quick mode uses the same system with a shorter path:
- Spawns planner + executor (skips researcher, checker, verifier by default)
- Quick tasks live in `.planning/quick/` separate from planned phases
- Updates STATE.md tracking (not ROADMAP.md)
Flags enable additional quality steps:
- `--full` — Complete quality pipeline: discussion + research + plan-checking + verification
- `--validate` — Plan-checking (max 2 iterations) and post-execution verification only
- `--discuss` — Lightweight discussion to surface gray areas before planning
- `--research` — Focused research agent investigates approaches before planning
Granular flags are composable: `--discuss --research --validate` gives the same as `--full`.
Usage: `/gsd:quick`
Usage: `/gsd:quick --full`
Usage: `/gsd:quick --research --validate`
Result: Creates `.planning/quick/NNN-slug/PLAN.md`, `.planning/quick/NNN-slug/NNN-slug-SUMMARY.md`
---
**`/gsd:fast [description]`**
Execute a trivial task inline — no subagents, no planning files, no overhead.
For tasks too small to justify planning: typo fixes, config changes, forgotten commits, simple additions. Runs in the current context, makes the change, commits, and logs to STATE.md.
- No PLAN.md or SUMMARY.md created
- No subagent spawned (runs inline)
- ≤ 3 file edits — redirects to `/gsd:quick` if task is non-trivial
- Atomic commit with conventional message
Usage: `/gsd:fast "fix the typo in README"`
Usage: `/gsd:fast "add .env to gitignore"`
### Roadmap Management
**`/gsd:phase <description>`**
Add new phase to end of current milestone.
- Appends to ROADMAP.md
- Uses next sequential number
- Updates phase directory structure
Usage: `/gsd:phase "Add admin dashboard"`
**`/gsd:phase --insert <after> <description>`**
Insert urgent work as decimal phase between existing phases.
- Creates intermediate phase (e.g., 7.1 between 7 and 8)
- Useful for discovered work that must happen mid-milestone
- Maintains phase ordering
Usage: `/gsd:phase --insert 7 "Fix critical auth bug"`
Result: Creates Phase 7.1
**`/gsd:phase --remove <number>`**
Remove a future phase and renumber subsequent phases.
- Deletes phase directory and all references
- Renumbers all subsequent phases to close the gap
- Only works on future (unstarted) phases
- Git commit preserves historical record
Usage: `/gsd:phase --remove 17`
Result: Phase 17 deleted, phases 18-20 become 17-19
**`/gsd:phase --edit <number> [--force]`**
Edit any field of an existing roadmap phase in place, preserving number and position.
- Updates title, description, requirements, dependencies in `ROADMAP.md`
- `--force` allows editing already-started phases (use with caution)
### Milestone Management
**`/gsd:new-milestone <name>`**
Start a new milestone through unified flow.
- Deep questioning to understand what you're building next
- Optional domain research (spawns 4 parallel researcher agents)
- Requirements definition with scoping
- Roadmap creation with phase breakdown
- Optional `--reset-phase-numbers` flag restarts numbering at Phase 1 and archives old phase dirs first for safety
Mirrors `/gsd:new-project` flow for brownfield projects (existing PROJECT.md).
Usage: `/gsd:new-milestone "v2.0 Features"`
Usage: `/gsd:new-milestone --reset-phase-numbers "v2.0 Features"`
**`/gsd:complete-milestone <version>`**
Archive completed milestone and prepare for next version.
- Creates MILESTONES.md entry with stats
- Archives full details to milestones/ directory
- Creates git tag for the release
- Prepares workspace for next version
Usage: `/gsd:complete-milestone 1.0.0`
### Progress Tracking
**`/gsd:progress [--next | --forensic | --do "<description>"]`**
Check project status and intelligently route to next action.
- Shows visual progress bar and completion percentage
- Summarizes recent work from SUMMARY files
- Displays current position and what's next
- Lists key decisions and open issues
- Offers to execute next plan or create it if missing
- Detects 100% milestone completion
Modes:
- **default** — progress report + intelligent routing
- **`--next`** — auto-advance to the next logical step (use `--next --force` to bypass safety gates)
- **`--forensic`** — append a 6-check integrity audit after the progress report
- **`--do "<text>"`** — smart router: dispatch freeform intent to the matching `/gsd-*` command (see *Smart Router* above)
Usage: `/gsd:progress`
Usage: `/gsd:progress --next`
Usage: `/gsd:progress --forensic`
### Session Management
**`/gsd:resume-work`**
Resume work from previous session with full context restoration.
- Reads STATE.md for project context
- Shows current position and recent progress
- Offers next actions based on project state
Usage: `/gsd:resume-work`
**`/gsd:pause-work [--report]`**
Create context handoff when pausing work mid-phase.
- `--report` — generate a post-session summary in `.planning/reports/` capturing commits, file changes, and phase progress
- Creates .continue-here file with current state
- Updates STATE.md session continuity section
- Captures in-progress work context
Usage: `/gsd:pause-work`
### Debugging
**`/gsd:debug [issue description] [--diagnose]`**
Systematic debugging with persistent state across context resets.
- `--diagnose` — run a one-shot diagnostic pass without opening a persistent debug session
- Gathers symptoms through adaptive questioning
- Creates `.planning/debug/[slug].md` to track investigation
- Investigates using scientific method (evidence → hypothesis → test)
- Survives `/clear` — run `/gsd:debug` with no args to resume
- Archives resolved issues to `.planning/debug/resolved/`
Usage: `/gsd:debug "login button doesn't work"`
Usage: `/gsd:debug` (resume active session)
### Spiking & Sketching
**`/gsd:spike [idea] [--quick]`**
Rapidly spike an idea with throwaway experiments to validate feasibility.
- Decomposes idea into 2-5 focused experiments (risk-ordered)
- Each spike answers one specific Given/When/Then question
- Builds minimum code, runs it, captures verdict (VALIDATED/INVALIDATED/PARTIAL)
- Saves to `.planning/spikes/` with MANIFEST.md tracking
- Does not require `/gsd:new-project` — works in any repo
- `--quick` skips decomposition, builds immediately
Usage: `/gsd:spike "can we stream LLM output over WebSockets?"`
Usage: `/gsd:spike --quick "test if pdfjs extracts tables"`
**`/gsd:sketch [idea] [--quick]`**
Rapidly sketch UI/design ideas using throwaway HTML mockups with multi-variant exploration.
- Conversational mood/direction intake before building
- Each sketch produces 2-3 variants as tabbed HTML pages
- User compares variants, cherry-picks elements, iterates
- Shared CSS theme system compounds across sketches
- Saves to `.planning/sketches/` with MANIFEST.md tracking
- Does not require `/gsd:new-project` — works in any repo
- `--quick` skips mood intake, jumps to building
Usage: `/gsd:sketch "dashboard layout for the admin panel"`
Usage: `/gsd:sketch --quick "form card grouping"`
**`/gsd:spike --wrap-up`**
Package spike findings into a persistent project skill.
- Curates each spike one-at-a-time (include/exclude/partial/UAT)
- Groups findings by feature area
- Generates `./.claude/skills/spike-findings-[project]/` with references and sources
- Writes summary to `.planning/spikes/WRAP-UP-SUMMARY.md`
- Adds auto-load routing line to project CLAUDE.md
Usage: `/gsd:spike --wrap-up`
**`/gsd:sketch --wrap-up`**
Package sketch design findings into a persistent project skill.
- Curates each sketch one-at-a-time (include/exclude/partial/revisit)
- Groups findings by design area
- Generates `./.claude/skills/sketch-findings-[project]/` with design decisions, CSS patterns, HTML structures
- Writes summary to `.planning/sketches/WRAP-UP-SUMMARY.md`
- Adds auto-load routing line to project CLAUDE.md
Usage: `/gsd:sketch --wrap-up`
### Capturing Ideas, Notes, and Todos
**`/gsd:capture [description]`**
Capture an idea or task as a structured todo from current conversation.
- Extracts context from conversation (or uses provided description)
- Creates structured todo file in `.planning/todos/pending/`
- Infers area from file paths for grouping
- Checks for duplicates before creating
- Updates STATE.md todo count
Usage: `/gsd:capture` (infers from conversation)
Usage: `/gsd:capture Add auth token refresh`
**`/gsd:capture --note <text>`**
Zero-friction note capture — one command, instant save, no questions.
- Saves timestamped note to `.planning/notes/` (or `~/.claude/notes/` globally)
- Three subcommands: append (default), list, promote
- Promote converts a note into a structured todo
- Works without a project (falls back to global scope)
Usage: `/gsd:capture --note refactor the hook system`
Usage: `/gsd:capture --note list`
Usage: `/gsd:capture --note promote 3`
Usage: `/gsd:capture --note --global cross-project idea`
**`/gsd:capture --list [area]`**
List pending todos and select one to work on.
- Lists all pending todos with title, area, age
- Optional area filter (e.g., `/gsd:capture --list api`)
- Loads full context for selected todo
- Routes to appropriate action (work now, add to phase, brainstorm)
- Moves todo to done/ when work begins
Usage: `/gsd:capture --list`
Usage: `/gsd:capture --list api`
### User Acceptance Testing
**`/gsd:verify-work [phase]`**
Validate built features through conversational UAT.
- Extracts testable deliverables from SUMMARY.md files
- Presents tests one at a time (yes/no responses)
- Automatically diagnoses failures and creates fix plans
- Ready for re-execution if issues found
Usage: `/gsd:verify-work 3`
### Ship Work
**`/gsd:ship [phase]`**
Create a PR from completed phase work with an auto-generated body.
- Pushes branch to remote
- Creates PR with summary from SUMMARY.md, VERIFICATION.md, REQUIREMENTS.md
- Optionally requests code review
- Updates STATE.md with shipping status
Prerequisites: Phase verified, `gh` CLI installed and authenticated.
Usage: `/gsd:ship 4` or `/gsd:ship 4 --draft`
---
**`/gsd:review --phase N [--gemini] [--claude] [--codex] [--coderabbit] [--opencode] [--qwen] [--cursor] [--agy] [--all]`**
Cross-AI peer review — invoke external AI CLIs to independently review phase plans.
- Detects available CLIs (gemini, claude, codex, coderabbit, agy)
- Each CLI reviews plans independently with the same structured prompt
- CodeRabbit reviews the current git diff (not a prompt) — may take up to 5 minutes
- Produces REVIEWS.md with per-reviewer feedback and consensus summary
- Feed reviews back into planning: `/gsd:plan-phase N --reviews`
Usage: `/gsd:review --phase 3 --all`
---
**`/gsd:pr-branch [target]`**
Create a clean branch for pull requests by filtering out .planning/ commits.
- Classifies commits: code-only (include), planning-only (exclude), mixed (include sans .planning/)
- Cherry-picks code commits onto a clean branch
- Reviewers see only code changes, no GSD artifacts
Usage: `/gsd:pr-branch` or `/gsd:pr-branch main`
---
**`/gsd:capture --seed [idea]`**
Capture a forward-looking idea with trigger conditions for automatic surfacing.
- Seeds preserve WHY, WHEN to surface, and breadcrumbs to related code
- Auto-surfaces during `/gsd:new-milestone` when trigger conditions match
- Better than deferred items — triggers are checked, not forgotten
Usage: `/gsd:capture --seed "add real-time notifications when we build the events system"`
**`/gsd:capture --backlog [description]`**
Add an idea to the backlog parking lot for future milestones.
- Creates a backlog item under 999.x numbering in ROADMAP.md
- Reserves ideas without committing to the current milestone
- Surface and promote later via `/gsd:review-backlog`
Usage: `/gsd:capture --backlog "real-time notifications when events ship"`
---
**`/gsd:audit-uat`**
Cross-phase audit of all outstanding UAT and verification items.
- Scans every phase for pending, skipped, blocked, and human_needed items
- Cross-references against codebase to detect stale documentation
- Produces prioritized human test plan grouped by testability
- Use before starting a new milestone to clear verification debt
Usage: `/gsd:audit-uat`
### Milestone Auditing
**`/gsd:audit-milestone [version]`**
Audit milestone completion against original intent.
- Reads all phase VERIFICATION.md files
- Checks requirements coverage
- Spawns integration checker for cross-phase wiring
- Creates MILESTONE-AUDIT.md with gaps and tech debt
Usage: `/gsd:audit-milestone`
### Configuration
**`/gsd:settings`**
Configure workflow toggles and model profile interactively.
- Toggle researcher, plan checker, verifier agents
- Select model profile (quality/balanced/budget/inherit)
- Updates `.planning/config.json`
Usage: `/gsd:settings`
**`/gsd:config [--profile <profile> | --advanced | --integrations]`**
Configure GSD beyond the basic settings: model profile, advanced tuning, and third-party integrations.
- `--profile <profile>` — quick switch model profile (`quality | balanced | budget | inherit`)
- `--advanced` — power-user tuning: plan bounce, timeouts, branch templates, cross-AI execution (replaces the former `gsd-settings-advanced`)
- `--integrations` — third-party API keys, code-review CLI routing, agent-skill injection (replaces the former `gsd-settings-integrations`)
- `quality` — Opus everywhere except verification
- `balanced` — Opus for planning, Sonnet for execution (default)
- `budget` — Sonnet for writing, Haiku for research/verification
- `inherit` — Use current session model for all agents (OpenCode `/model`)
Usage: `/gsd:config --profile budget`
**`/gsd:surface [list|status|profile <name>|disable <cluster>|enable <cluster>|reset]`**
Toggle which skills are surfaced — apply a profile, list, or disable a cluster without reinstall.
- `list` / `status` — Show enabled and disabled clusters and skills with token cost
- `profile <name>` — Switch to a named base profile (`core`, `standard`, `full`)
- `disable <cluster>` — Remove a cluster from the active surface
- `enable <cluster>` — Add a cluster back to the active surface
- `reset` — Delete the surface delta and return to the install-time profile
Usage: `/gsd:surface list`
Usage: `/gsd:surface profile standard`
Usage: `/gsd:surface disable utility`
### Utility Commands
**`/gsd:cleanup`**
Archive accumulated phase directories from completed milestones.
- Identifies phases from completed milestones still in `.planning/phases/`
- Shows dry-run summary before moving anything
- Moves phase dirs to `.planning/milestones/v{X.Y}-phases/`
- Use after multiple milestones to reduce `.planning/phases/` clutter
Usage: `/gsd:cleanup`
**`/gsd:help [--brief | --full | <topic> | --brief <topic>]`**
Show GSD command help at the tier you ask for.
- `--brief` — one-liner refresher of the top commands (~10 lines)
- *(no flag)* — one-page newcomer tour (default)
- `--full` — the complete reference you are reading now
- `<topic>` — emit only the matching section (e.g. `/gsd:help debug`, `/gsd:help workflow`)
- `--brief <topic>` — compact scoped lookup: signature + one-line summary of the matched section
Every topic output starts with a `**Topic:** \`<alias>\` → \`<heading>\` *(scope: full | compact)*` preamble so resolved routing is visible. See `gsd-core/workflows/help/modes/topic.md` for the full alias table. Unknown topics print the recognized list.
Usage: `/gsd:help`
Usage: `/gsd:help --brief`
Usage: `/gsd:help --full`
Usage: `/gsd:help debug`
Usage: `/gsd:help --brief debug`
**`/gsd:update [--sync] [--reapply]`**
Update GSD to latest version with changelog preview.
- `--sync` — sync managed GSD skills across runtime roots (replaces the former `gsd-sync-skills`)
- `--reapply` — reapply local modifications after an update (replaces the former `gsd-reapply-patches`)
- Shows installed vs latest version comparison
- Displays changelog entries for versions you've missed
- Highlights breaking changes
- Confirms before running install
- Better than raw `npx @opengsd/gsd-core`
Usage: `/gsd:update`
## Additional Commands
The commands above cover the most common day-to-day flows. Every command listed here is also a live `/gsd-*` slash command and is grouped by purpose.
### Discovery & Specification
- **`/gsd:explore`** — Socratic ideation and idea routing. Think through ideas before committing to plans.
- **`/gsd:spec-phase <phase> [--auto] [--text]`** — Clarify WHAT a phase delivers with ambiguity scoring; produces a SPEC.md before discuss-phase.
- **`/gsd:ai-integration-phase [phase]`** — Generate an AI-SPEC.md design contract for phases that involve building AI systems.
- **`/gsd:ui-phase [phase]`** — Generate UI design contract (UI-SPEC.md) for frontend phases.
- **`/gsd:import --from <filepath> | --from-gsd2`** — Ingest external plans with conflict detection, or reverse-migrate a GSD-2 (`.gsd/`) project back to GSD v1 (`.planning/`) format.
- **`/gsd:ingest-docs [path] [--mode new|merge] [--manifest <file>] [--resolve auto|interactive]`** — Bootstrap or merge a `.planning/` setup from existing ADRs, PRDs, SPECs, and docs in a repo.
### Planning & Execution
- **`/gsd:mvp-phase <phase-number>`** — Plan a phase as a vertical MVP slice (user story + SPIDR splitting) before handing off to plan-phase. Same end-state as `/gsd:plan-phase --mvp`, with a guided MVP-shaping intro.
- **`/gsd:ultraplan-phase [phase]`** — [BETA] Offload plan phase to Claude Code's ultraplan cloud; review in browser and import back.
- **`/gsd:plan-review-convergence <phase> [--codex] [--gemini] [--claude] [--opencode] [--ollama] [--lm-studio] [--llama-cpp] [--all] [--text] [--ws <name>] [--max-cycles N]`** — Cross-AI plan convergence loop — replan with review feedback until no HIGH concerns remain. Supports both cloud reviewers (Codex/Gemini/Claude/OpenCode) and local model runtimes (Ollama, LM Studio, llama.cpp).
- **`/gsd:autonomous [--from N] [--to N] [--only N] [--interactive]`** — Run all remaining phases autonomously: discuss → plan → execute per phase.
### Quality, Review & Verification
- **`/gsd:code-review <phase> [--depth=quick|standard|deep] [--files file1,file2,...] [--fix [--all] [--auto]]`** — Review source files changed during a phase for bugs, security issues, and code quality problems.
- **`/gsd:secure-phase [phase]`** — Retroactively verify threat mitigations for a completed phase.
- **`/gsd:validate-phase [phase]`** — Retroactively audit and fill Nyquist validation gaps for a completed phase.
- **`/gsd:ui-review [phase]`** — Retroactive 6-pillar visual audit of implemented frontend code.
- **`/gsd:eval-review [phase]`** — Audit an executed AI phase's evaluation coverage and produce an EVAL-REVIEW.md remediation plan.
- **`/gsd:audit-fix --source <audit-uat> [--severity medium|high|all] [--max N] [--dry-run]`** — Autonomous audit-to-fix pipeline: find issues, classify, fix, test, commit.
- **`/gsd:add-tests <phase> [additional instructions]`** — Generate tests for a completed phase based on UAT criteria and implementation.
### Diagnostics & Maintenance
- **`/gsd:health [--repair] [--context]`** — Diagnose planning directory health and optionally repair issues.
- **`/gsd:forensics [problem description]`** — Post-mortem investigation for failed GSD workflows; diagnoses what went wrong.
- **`/gsd:undo --last N | --phase NN | --plan NN-MM`** — Safe git revert. Roll back phase or plan commits using the phase manifest with dependency checks.
- **`/gsd:docs-update [--force] [--verify-only]`** — Generate or update project documentation verified against the codebase.
- **`/gsd:extract-learnings <phase>`** — Extract decisions, lessons, patterns, and surprises from completed phase artifacts.
### Knowledge & Context
- **`/gsd:graphify [build|query <term>|status|diff]`** — Build, query, and inspect the project knowledge graph in `.planning/graphs/`.
- **`/gsd:thread [list [--open|--resolved] | close <slug> | status <slug> | name | description]`** — Manage persistent context threads for cross-session work.
- **`/gsd:profile-user [--questionnaire] [--refresh]`** — Generate developer behavioral profile and create Claude-discoverable artifacts.
- **`/gsd:stats`** — Display project statistics: phases, plans, requirements, git metrics, and timeline.
### Workflow & Orchestration
- **`/gsd:manager [--analyze-deps]`** — Interactive command center for managing multiple phases from one terminal. `--analyze-deps` scans ROADMAP phases for dependency relationships before parallel execution.
- **`/gsd:workspace [--new | --list | --remove] [name]`** — Manage GSD workspaces: create, list, or remove isolated workspace environments.
- **`/gsd:workstreams`** — Manage parallel workstreams: list, create, switch, status, progress, complete, and resume.
- **`/gsd:review-backlog`** — Review and promote backlog items to active milestone.
- **`/gsd:milestone-summary [version]`** — Generate a comprehensive project summary from milestone artifacts for team onboarding and review.
### Repository Integration
- **`/gsd:inbox [--issues] [--prs] [--label] [--close-incomplete] [--repo owner/repo]`** — Triage and review open GitHub issues and PRs against project templates and contribution guidelines.
### Namespace Routers (model-facing meta-skills)
These six skills exist primarily for the model to perform two-stage hierarchical routing across 60+ skills. You can invoke them directly when you want to browse a category interactively.
- **`/gsd-context`** — Codebase intelligence routing (map, graphify, docs, learnings).
- **`/gsd-ideate`** — Exploration / capture routing (explore, sketch, spike, spec, capture).
- **`/gsd-manage`** — Configuration and workspace routing (workstreams, thread, update, ship, inbox).
- **`/gsd-project`** — Project-lifecycle routing (milestones, audits, summary).
- **`/gsd-quality`** — Quality-gate routing (code review, debug, audit, security, eval, ui).
- **`/gsd-workflow`** — Phase-pipeline routing (discuss, plan, execute, verify, phase, progress).
## Files & Structure
```text
.planning/
├── PROJECT.md # Project vision
├── ROADMAP.md # Current phase breakdown
├── STATE.md # Project memory & context
├── RETROSPECTIVE.md # Living retrospective (updated per milestone)
├── config.json # Workflow mode & gates
├── todos/ # Captured ideas and tasks
│ ├── pending/ # Todos waiting to be worked on
│ └── done/ # Completed todos
├── spikes/ # Spike experiments (/gsd:spike)
│ ├── MANIFEST.md # Spike inventory and verdicts
│ └── NNN-name/ # Individual spike directories
├── sketches/ # Design sketches (/gsd:sketch)
│ ├── MANIFEST.md # Sketch inventory and winners
│ ├── themes/ # Shared CSS theme files
│ └── NNN-name/ # Individual sketch directories (HTML + README)
├── debug/ # Active debug sessions
│ └── resolved/ # Archived resolved issues
├── milestones/
│ ├── v1.0-ROADMAP.md # Archived roadmap snapshot
│ ├── v1.0-REQUIREMENTS.md # Archived requirements
│ └── v1.0-phases/ # Archived phase dirs (via /gsd:cleanup or --archive-phases)
│ ├── 01-foundation/
│ └── 02-core-features/
├── codebase/ # Codebase map (brownfield projects)
│ ├── STACK.md # Languages, frameworks, dependencies
│ ├── ARCHITECTURE.md # Patterns, layers, data flow
│ ├── STRUCTURE.md # Directory layout, key files
│ ├── CONVENTIONS.md # Coding standards, naming
│ ├── TESTING.md # Test setup, patterns
│ ├── INTEGRATIONS.md # External services, APIs
│ └── CONCERNS.md # Tech debt, known issues
└── phases/
├── 01-foundation/
│ ├── 01-01-PLAN.md
│ └── 01-01-SUMMARY.md
└── 02-core-features/
├── 02-01-PLAN.md
└── 02-01-SUMMARY.md
```
## Workflow Modes
Set during `/gsd:new-project`:
**Interactive Mode**
- Confirms each major decision
- Pauses at checkpoints for approval
- More guidance throughout
**YOLO Mode**
- Auto-approves most decisions
- Executes plans without confirmation
- Only stops for critical checkpoints
Change anytime by editing `.planning/config.json`
## Planning Configuration
Configure how planning artifacts are managed in `.planning/config.json`:
**`planning.commit_docs`** (default: `true`)
- `true`: Planning artifacts committed to git (standard workflow)
- `false`: Planning artifacts kept local-only, not committed
When `commit_docs: false`:
- Add `.planning/` to your `.gitignore`
- Useful for OSS contributions, client projects, or keeping planning private
- All planning files still work normally, just not tracked in git
**`planning.search_gitignored`** (default: `false`)
- `true`: Add `--no-ignore` to broad ripgrep searches
- Only needed when `.planning/` is gitignored and you want project-wide searches to include it
Example config:
```json
{
"planning": {
"commit_docs": false,
"search_gitignored": true
}
}
```
## Common Workflows
**Starting a new project:**
```text
/gsd:new-project # Unified flow: questioning → research → requirements → roadmap
/clear
/gsd:plan-phase 1 # Create plans for first phase
/clear
/gsd:execute-phase 1 # Execute all plans in phase
```
**Resuming work after a break:**
```text
/gsd:progress # See where you left off and continue
```
**Adding urgent mid-milestone work:**
```text
/gsd:phase --insert 5 "Critical security fix"
/gsd:plan-phase 5.1
/gsd:execute-phase 5.1
```
**Completing a milestone:**
```text
/gsd:complete-milestone 1.0.0
/clear
/gsd:new-milestone # Start next milestone (questioning → research → requirements → roadmap)
```
**Capturing ideas during work:**
```text
/gsd:capture # Capture from conversation context
/gsd:capture Fix modal z-index # Capture with explicit description
/gsd:capture --note refactor auth system # Quick friction-free note
/gsd:capture --seed "real-time notifications" # Forward-looking idea with triggers
/gsd:capture --list # Review and work on todos
/gsd:capture --list api # Filter by area
```
**Debugging an issue:**
```text
/gsd:debug "form submission fails silently" # Start debug session
# ... investigation happens, context fills up ...
/clear
/gsd:debug # Resume from where you left off
```
## Getting Help
- Read `.planning/PROJECT.md` for project vision
- Read `.planning/STATE.md` for current context
- Check `.planning/ROADMAP.md` for phase status
- Run `/gsd:progress` to check where you're up to
</reference>

74
gsd-core/workflows/help/modes/topic.md Normal file
View File

@@ -0,0 +1,74 @@
<purpose>
Emit a section from the full reference for the topic in `$ARGUMENTS`. Read `workflows/help/modes/full.md`, resolve the topic alias to a section heading using the table below, and output the resolved-routing preamble plus the section content. Scope is controlled by a `--brief` flag in `$ARGUMENTS`: full scope (default) emits the entire section; compact scope (`--brief <topic>`) emits only the signature line + one-line summary for a compact scoped lookup. No additions, no surrounding chrome.
</purpose>
<reference>
**Topic resolution table.** Match the topic alias case-insensitively. Strip a single leading `--` if present.
| Topic alias(es) | Section heading in `full.md` |
|---|---|
| `workflow`, `core`, `core-workflow` | `## Core Workflow` (entire section through end of `### Quick Mode`) |
| `init`, `new-project` | `### Project Initialization` |
| `map`, `map-codebase` | The `/gsd:map-codebase` block under `### Project Initialization` |
| `discuss`, `discuss-phase` | The `/gsd:discuss-phase` block under `### Phase Planning` |
| `plan`, `planning`, `plan-phase` | `### Phase Planning` |
| `execute`, `exec`, `execute-phase` | `### Execution` |
| `progress`, `route` | `### Progress Tracking` plus `### Smart Router` |
| `quick`, `quick-mode` | `### Quick Mode` |
| `fast` | The `/gsd:fast` block under `### Quick Mode` |
| `phase`, `phases`, `roadmap` | `### Roadmap Management` |
| `milestone`, `milestones` | `### Milestone Management` plus `### Milestone Auditing` |
| `session`, `pause`, `resume` | `### Session Management` |
| `debug`, `debugging` | `### Debugging` |
| `spike` | The `/gsd:spike` and `/gsd:spike --wrap-up` blocks under `### Spiking & Sketching` |
| `sketch` | The `/gsd:sketch` and `/gsd:sketch --wrap-up` blocks under `### Spiking & Sketching` |
| `spike-sketch`, `experiments` | `### Spiking & Sketching` |
| `capture`, `notes`, `todos` | `### Capturing Ideas, Notes, and Todos` |
| `verify`, `verify-work`, `uat` | `### User Acceptance Testing` plus the `/gsd:audit-uat` block |
| `ship`, `pr` | `### Ship Work` plus the `/gsd:pr-branch` block |
| `review`, `peer-review` | The `/gsd:review` block under `### Ship Work` |
| `audit`, `auditing`, `audit-milestone` | `### Milestone Auditing` |
| `config`, `settings`, `configuration` | `### Configuration` |
| `cleanup` | The `/gsd:cleanup` block under `### Utility Commands` |
| `update` | The `/gsd:update` block under `### Utility Commands` |
| `files`, `structure`, `layout` | `## Files & Structure` |
| `modes`, `interactive`, `yolo` | `## Workflow Modes` |
| `planning-config` | `## Planning Configuration` |
| `workflows`, `common-workflows`, `examples` | `## Common Workflows` |
| `help` | `## Getting Help` |
**Output rules:**
1. Parse `$ARGUMENTS`: detect a `--brief` (or `-b`) flag — this selects **compact scope**. Otherwise scope is **full**. Strip the flag, then take the remaining token (with a single leading `--` stripped) as the topic alias.
2. Resolve the alias against the table.
3. If no match: emit a one-line error followed by a comma-separated list of the canonical topic names from the leftmost column (one per row, deduplicated). Suggest `/gsd:help --full` for the complete reference. Stop.
4. If matched: emit a single resolved-routing preamble line so the user sees what was matched:
```text
**Topic:** `<alias>` → `<heading>` *(scope: full | compact)*
```
Use the canonical alias from the leftmost column. Use the literal heading text from the matched cell. State the scope you are about to emit.
5. Read `workflows/help/modes/full.md`. Strip `<reference>` / `</reference>` wrapper tags — never emit them. Apply the extraction rule for the matched table cell, modulated by scope:
5a. **Single section** (cell contains a single `` `## Heading` `` or `` `### Heading` ``):
- *Full scope:* emit from that heading up to (but not including) the next sibling or higher-level heading.
- *Compact scope:* emit the heading, then the first `` **`/gsd:...`** `` bold line within the section (the signature) and the single non-blank line immediately after it (the one-line summary). If the section has no `` **`/gsd:...`** `` bold line, emit the heading and the first paragraph.
5b. **Multiple sections joined by "plus"**: apply rule 5a to each listed section in document order and emit them sequentially with no gap between them.
5c. **Sub-block** (cell says `the /gsd:X block under ### Heading` or `the /gsd:X ... blocks under ### Heading`): within the named heading's section, start at each `` **`/gsd:X ...`** `` bold line.
- *Full scope:* stop immediately before the next `` **`/gsd:...`** `` bold line or the next heading, whichever comes first.
- *Compact scope:* emit the bold line and the single non-blank line immediately after it (the one-line summary).
For cells listing multiple sub-blocks, emit them sequentially.
6. After the section content, emit a single closing line:
```text
More: /gsd:help --full · /gsd:help <topic> · /gsd:help --brief <topic>
```
7. No project-specific commentary, no follow-up questions.
</reference>