Replace the single 747-line /gsd-help reference with a progressive-disclosure dispatcher (#2551 pattern). Newcomers get a one-page tour; returning users get a 10-line refresher with --brief; the complete reference stays available behind --full; /gsd-help <topic> emits one section; and /gsd-help --brief <topic> is a compact scoped lookup (signature + one-line summary). - workflows/help.md becomes a small dispatcher routing on $ARGUMENTS - workflows/help/modes/{brief,default,full,topic}.md hold the tier bodies - commands/gsd/help.md passes $ARGUMENTS through, advertises composable form - docs/COMMANDS.md documents the new flags and topic form - existing tests that read help.md repointed at help/modes/full.md (bug-2836, bug-2950, bug-2954, cursor-reviewer, execute-phase-wave) - new feat-3039-help-tiered test enforces structure, size budgets, dispatcher routing, shim arg passthrough, topic→section coverage, orphan-heading detection, conflict-resolution rules, routing preamble, and compact-scope rule Trek-e review fixes (PR #3040): - topic.md output rules split into 5a/5b/5c — explicit handling for single sections, multi-section "plus" joins, and bold-line sub-block anchors; each rule also takes scope (full vs compact) into account - explicit resolved-routing preamble line emitted by topic.md before content ("**Topic:** `<alias>` → `<heading>` *(scope: full | compact)*") so the user sees which alias matched at which scope (review finding #3) - composable `--brief <topic>` invokes topic.md in compact scope: heading + first `**/gsd:*`** signature line + one-line summary. Dispatcher and topic.md cooperate via $ARGUMENTS pass-through (review finding #4) - full.md capped at LARGE-tier budget (FULL_BUDGET = 1500); the non-recursive workflow-size-budget test does not reach modes/ subdirs - structural <progressive_disclosure> table parse (5-row assertion) replaces substring-soup regex matching — 5 rows = 4 base tiers + composable scope - forward /gsd:* sub-block token coverage + reverse orphan-heading allowlist catch alias-table drift in both directions - four conflict-resolution tests guard dispatcher promises (--brief+--full without topic → --full; --brief <topic> → compact; --full <topic> or bare → full; dispatcher retains --brief when delegating to topic.md) - hardcoded topic lists removed from docs/COMMANDS.md and full.md (drift surfaces reduced from 5 to 2) - topic.md alias bloat trimmed (~75 → ~25 rows); cleanup/update split into distinct sub-block rows under ### Utility Commands - comment-rot ("~750 lines") removed from default.md and full.md - dispatcher size guard tightened from < 100 to <= 40 lines - commands/gsd/help.md <process> block trimmed to one line - MD040 fence languages added to all plain code blocks across mode files Main-merge conflict resolution: - workflows/help.md kept as dispatcher (body lives in help/modes/full.md) - /gsd-<cmd> → /gsd:<cmd> rename from #3452 reapplied to the mode files (full.md, default.md, brief.md, topic.md) — the six namespace routers (/gsd-context, /gsd-ideate, /gsd-manage, /gsd-project, /gsd-quality, /gsd-workflow) and wildcards (/gsd-*) preserved in hyphen form per main's convention - bug-2950 test combines branch's path repointing with main's namespaced replacement strings
This commit is contained in:
Andreas Brauchli
5
.changeset/sturdy-moles-bark.md
Normal file
5
.changeset/sturdy-moles-bark.md
Normal file
@@ -0,0 +1,5 @@
|
||||
---
|
||||
type: Changed
|
||||
pr: 3039
|
||||
---
|
||||
**`/gsd-help` is now tiered** — default output fits one screen, `--brief` gives a 10-line refresher, `--full` keeps the complete reference, `/gsd-help <topic>` jumps straight to one section (e.g. `/gsd-help debug`), and `/gsd-help --brief <topic>` is a compact scoped lookup (signature + one-line summary). Every topic output starts with a resolved-routing preamble so the matched alias and scope are visible. Closes #3039.
|
||||
@@ -1,13 +1,14 @@
|
||||
---
|
||||
name: gsd:help
|
||||
description: Show available GSD commands and usage guide
|
||||
argument-hint: "[--brief | --full | <topic> | --brief <topic>]"
|
||||
allowed-tools:
|
||||
- Read
|
||||
---
|
||||
<objective>
|
||||
Display the complete GSD command reference.
|
||||
Display GSD help at the tier the user asked for: brief (one-line refresher), default (one-page tour), full (complete reference), a single topic section, or a compact scoped lookup of one topic (`--brief <topic>`: signature + one-line summary).
|
||||
|
||||
Output ONLY the reference content below. Do NOT add:
|
||||
Output ONLY the reference content of the chosen tier. Do NOT add:
|
||||
- Project-specific analysis
|
||||
- Git status or file context
|
||||
- Next-step suggestions
|
||||
@@ -18,7 +19,10 @@ Output ONLY the reference content below. Do NOT add:
|
||||
@~/.claude/get-shit-done/workflows/help.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
Arguments: $ARGUMENTS
|
||||
</context>
|
||||
|
||||
<process>
|
||||
Execute end-to-end.
|
||||
Display the reference content directly — no additions or modifications.
|
||||
Follow ~/.claude/get-shit-done/workflows/help.md with $ARGUMENTS.
|
||||
</process>
|
||||
|
||||
@@ -548,12 +548,18 @@ Configure per-step flags in `.planning/config.json` under `manager.flags`. These
|
||||
|
||||
### `/gsd-help`
|
||||
|
||||
Show all commands and usage guide.
|
||||
Show GSD commands at the tier you ask for. Default fits one screen; `--full` is the complete reference; `<topic>` jumps directly to one section.
|
||||
|
||||
```bash
|
||||
/gsd-help # Quick reference
|
||||
/gsd-help # One-page tour (default)
|
||||
/gsd-help --brief # ~10-line one-liner refresher of top commands
|
||||
/gsd-help --full # Complete reference (every command, every flag)
|
||||
/gsd-help <topic> # One section only (e.g. /gsd-help debug)
|
||||
/gsd-help --brief <topic> # Compact scoped lookup — signature + one-line summary
|
||||
```
|
||||
|
||||
See `get-shit-done/workflows/help/modes/topic.md` for the full alias table. Unknown topics print the recognized list.
|
||||
|
||||
---
|
||||
|
||||
## Utility Commands
|
||||
|
||||
@@ -1,783 +1,24 @@
|
||||
<purpose>
|
||||
Display the complete GSD command reference. Output ONLY the reference content. Do NOT add project-specific analysis, git status, next-step suggestions, or any commentary beyond the reference.
|
||||
Display GSD command help at the tier the user asked for. Output ONLY the reference content of the chosen mode. Do NOT add project-specific analysis, git status, next-step suggestions, or any commentary beyond the reference.
|
||||
</purpose>
|
||||
|
||||
<reference>
|
||||
# GSD Command Reference
|
||||
|
||||
**GSD** (Get Shit 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 get-shit-done-cc@latest
|
||||
```
|
||||
|
||||
## Core Workflow
|
||||
|
||||
```
|
||||
/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:mvp-phase <number> [--force]`**
|
||||
Plan a phase as a vertical MVP slice — three structured user-story prompts (`As a / I want to / So that`), SPIDR splitting if the story is too large, then delegates to `/gsd:plan-phase` with MVP mode active.
|
||||
|
||||
- Mutates the phase's ROADMAP entry: writes `**Mode:** mvp` + replaces `**Goal:**` with the assembled user story
|
||||
- Validates the story via `gsd-sdk query user-story.validate` (canonical regex `/^As a .+, I want to .+, so that .+\.$/`)
|
||||
- `--force` overrides the status guard (required if the phase is already `in_progress` or `completed`)
|
||||
- Pairs with the new-project mode prompt (Vertical MVP vs Horizontal Layers)
|
||||
|
||||
Usage: `/gsd:mvp-phase 1`
|
||||
Usage: `/gsd:mvp-phase 2 --force`
|
||||
|
||||
**`/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>] [--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
|
||||
- `--prd <file>` — use a PRD file as planning context and skip discuss-phase (mutually exclusive with `--ingest`)
|
||||
- `--ingest <path-or-glob>` — use ADR file(s) as planning context and skip discuss-phase (mutually exclusive with `--prd`)
|
||||
- `--ingest-format <auto|nygard|madr|narrative>` — optional ADR parser format override
|
||||
- `--tdd` — plan in test-driven order (tests before code)
|
||||
- `--mvp` — vertical-slice MVP planning mode
|
||||
|
||||
- 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. Cannot be combined with `--ingest`.
|
||||
|
||||
**ADR Ingest Express Path:** Pass `--ingest path/to/adr.md` (or a glob) to skip discuss-phase and synthesize CONTEXT.md from approved ADR decisions and scope fences. Cannot be combined with `--prd`.
|
||||
|
||||
### 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] [--all]`**
|
||||
Cross-AI peer review — invoke external AI CLIs to independently review phase plans.
|
||||
|
||||
- Detects available CLIs (gemini, claude, codex, coderabbit)
|
||||
- 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`**
|
||||
Show this command reference.
|
||||
|
||||
**`/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 get-shit-done-cc`
|
||||
|
||||
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: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
|
||||
|
||||
```
|
||||
.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:**
|
||||
|
||||
```
|
||||
/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:**
|
||||
|
||||
```
|
||||
/gsd:progress # See where you left off and continue
|
||||
```
|
||||
|
||||
**Adding urgent mid-milestone work:**
|
||||
|
||||
```
|
||||
/gsd:phase --insert 5 "Critical security fix"
|
||||
/gsd:plan-phase 5.1
|
||||
/gsd:execute-phase 5.1
|
||||
```
|
||||
|
||||
**Completing a milestone:**
|
||||
|
||||
```
|
||||
/gsd:complete-milestone 1.0.0
|
||||
/clear
|
||||
/gsd:new-milestone # Start next milestone (questioning → research → requirements → roadmap)
|
||||
```
|
||||
|
||||
**Capturing ideas during work:**
|
||||
|
||||
```
|
||||
/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:**
|
||||
|
||||
```
|
||||
/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>
|
||||
<progressive_disclosure>
|
||||
**Mode files are lazy-loaded.** Read only the one mode file that matches `$ARGUMENTS`, then output its `<reference>` body verbatim.
|
||||
|
||||
| When `$ARGUMENTS` is | Read |
|
||||
|---|---|
|
||||
| `--brief` (or `-b`) alone | `workflows/help/modes/brief.md` |
|
||||
| `--full` (or `-f`, `--all`) alone | `workflows/help/modes/full.md` |
|
||||
| empty / unset | `workflows/help/modes/default.md` |
|
||||
| `--brief <topic>` (or `-b <topic>`) | `workflows/help/modes/topic.md` in compact scope (signature + one-line summary of the matched section) |
|
||||
| anything else — bare topic, `--full <topic>`, or topic with leading `--` | `workflows/help/modes/topic.md` in full scope (entire matched section) |
|
||||
|
||||
Argument parsing rules:
|
||||
- Trim and lowercase `$ARGUMENTS`.
|
||||
- Recognize the long form, short form, and obvious aliases listed above.
|
||||
- A bare token like `debug`, `--debug`, `capture`, `workflow`, `config` is a topic — route to `topic.md`.
|
||||
- Multiple flags: `--brief` and `--full` are mutually exclusive — if both appear *without* a topic, prefer `--full`.
|
||||
- `--brief` combined with a topic invokes `topic.md` in compact scope; `--full` combined with a topic invokes `topic.md` in full scope (the default topic behavior). When passing arguments through to `topic.md`, retain the `--brief` flag so the mode can pick the right scope.
|
||||
|
||||
After loading the chosen mode, emit its `<reference>` block content directly. No additions, no project context, no suggestions.
|
||||
</progressive_disclosure>
|
||||
|
||||
22
get-shit-done/workflows/help/modes/brief.md
Normal file
22
get-shit-done/workflows/help/modes/brief.md
Normal 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
get-shit-done/workflows/help/modes/default.md
Normal file
50
get-shit-done/workflows/help/modes/default.md
Normal file
@@ -0,0 +1,50 @@
|
||||
<purpose>
|
||||
One-page newcomer-oriented tour of GSD. Output ONLY the `<reference>` content below. No additions.
|
||||
</purpose>
|
||||
|
||||
<reference>
|
||||
# GSD — Get Shit Done
|
||||
|
||||
Plan-driven development for solo agentic work with Claude Code. GSD 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 get-shit-done-cc@latest
|
||||
```
|
||||
</reference>
|
||||
784
get-shit-done/workflows/help/modes/full.md
Normal file
784
get-shit-done/workflows/help/modes/full.md
Normal file
@@ -0,0 +1,784 @@
|
||||
<purpose>
|
||||
Display the complete GSD 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 Command Reference
|
||||
|
||||
**GSD** (Get Shit 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 get-shit-done-cc@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] [--all]`**
|
||||
Cross-AI peer review — invoke external AI CLIs to independently review phase plans.
|
||||
|
||||
- Detects available CLIs (gemini, claude, codex, coderabbit)
|
||||
- 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 `get-shit-done/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 get-shit-done-cc`
|
||||
|
||||
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
get-shit-done/workflows/help/modes/topic.md
Normal file
74
get-shit-done/workflows/help/modes/topic.md
Normal 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>
|
||||
@@ -160,8 +160,9 @@ describe('bug #2836: audit-open quick-task summary filename + UAT terminal statu
|
||||
|
||||
describe('bug #2836: workflows/help.md one-liner reconciliation', () => {
|
||||
test('help.md quick-task one-liner uses ${quick_id}-SUMMARY.md pattern', () => {
|
||||
// After #3039, help content moved into help/modes/full.md.
|
||||
const helpPath = path.resolve(
|
||||
__dirname, '..', 'get-shit-done', 'workflows', 'help.md'
|
||||
__dirname, '..', 'get-shit-done', 'workflows', 'help', 'modes', 'full.md'
|
||||
);
|
||||
const content = fs.readFileSync(helpPath, 'utf-8');
|
||||
|
||||
|
||||
@@ -44,14 +44,14 @@ const DELETED_COMMANDS = [
|
||||
|
||||
// Per-file assertions: [file, deletedCmd, newForm]
|
||||
const FILE_ASSERTIONS = [
|
||||
// help.md
|
||||
['help.md', '/gsd-add-phase', '/gsd:phase "Add admin dashboard"'],
|
||||
['help.md', '/gsd-insert-phase', '/gsd:phase --insert 7 "Fix critical auth bug"'],
|
||||
['help.md', '/gsd-remove-phase', '/gsd:phase --remove 17'],
|
||||
['help.md', '/gsd-spike-wrap-up', '/gsd:spike --wrap-up'],
|
||||
['help.md', '/gsd-sketch-wrap-up', '/gsd:sketch --wrap-up'],
|
||||
['help.md', '/gsd-add-todo', '/gsd:capture'],
|
||||
['help.md', '/gsd-set-profile', '/gsd:config --profile budget'],
|
||||
// help.md → moved to help/modes/full.md in #3039 tiered-help refactor
|
||||
['help/modes/full.md', '/gsd-add-phase', '/gsd:phase "Add admin dashboard"'],
|
||||
['help/modes/full.md', '/gsd-insert-phase', '/gsd:phase --insert 7 "Fix critical auth bug"'],
|
||||
['help/modes/full.md', '/gsd-remove-phase', '/gsd:phase --remove 17'],
|
||||
['help/modes/full.md', '/gsd-spike-wrap-up', '/gsd:spike --wrap-up'],
|
||||
['help/modes/full.md', '/gsd-sketch-wrap-up', '/gsd:sketch --wrap-up'],
|
||||
['help/modes/full.md', '/gsd-add-todo', '/gsd:capture'],
|
||||
['help/modes/full.md', '/gsd-set-profile', '/gsd:config --profile budget'],
|
||||
|
||||
// do.md
|
||||
['do.md', '/gsd-spike-wrap-up', '/gsd:spike --wrap-up'],
|
||||
@@ -117,6 +117,10 @@ describe('bug #2950: stale deleted-command references removed from workflow file
|
||||
// (catches any we might have missed in per-file assertions above)
|
||||
const affectedFiles = [
|
||||
'help.md',
|
||||
'help/modes/full.md',
|
||||
'help/modes/default.md',
|
||||
'help/modes/brief.md',
|
||||
'help/modes/topic.md',
|
||||
'do.md',
|
||||
'settings.md',
|
||||
'discuss-phase.md',
|
||||
|
||||
@@ -35,7 +35,10 @@ const path = require('node:path');
|
||||
|
||||
const ROOT = path.join(__dirname, '..');
|
||||
const COMMANDS_DIR = path.join(ROOT, 'commands', 'gsd');
|
||||
const HELP_MD = path.join(ROOT, 'get-shit-done', 'workflows', 'help.md');
|
||||
// After #3039, the canonical command reference is the `--full` mode file.
|
||||
// `workflows/help.md` is now a small dispatcher; the bidirectional parity
|
||||
// invariant lives with the comprehensive reference body.
|
||||
const HELP_MD = path.join(ROOT, 'get-shit-done', 'workflows', 'help', 'modes', 'full.md');
|
||||
const DO_MD = path.join(ROOT, 'get-shit-done', 'workflows', 'do.md');
|
||||
|
||||
function parseFrontmatter(content) {
|
||||
|
||||
@@ -110,7 +110,8 @@ describe('Cursor CLI reviewer in /gsd-review (#1960)', () => {
|
||||
// --- help.md ---
|
||||
|
||||
describe('help.md', () => {
|
||||
const helpPath = path.join(ROOT, 'get-shit-done', 'workflows', 'help.md');
|
||||
// After #3039, help content moved into help/modes/full.md.
|
||||
const helpPath = path.join(ROOT, 'get-shit-done', 'workflows', 'help', 'modes', 'full.md');
|
||||
|
||||
test('lists --cursor in /gsd-review signature', () => {
|
||||
const c = fs.readFileSync(helpPath, 'utf-8');
|
||||
|
||||
@@ -17,7 +17,8 @@ const { runGsdTools, createTempProject, cleanup } = require('./helpers.cjs');
|
||||
const COMMAND_PATH = path.join(__dirname, '..', 'commands', 'gsd', 'execute-phase.md');
|
||||
const WORKFLOW_PATH = path.join(__dirname, '..', 'get-shit-done', 'workflows', 'execute-phase.md');
|
||||
const COMMANDS_DOC_PATH = path.join(__dirname, '..', 'docs', 'COMMANDS.md');
|
||||
const HELP_PATH = path.join(__dirname, '..', 'get-shit-done', 'workflows', 'help.md');
|
||||
// After #3039, the comprehensive command reference moved to help/modes/full.md.
|
||||
const HELP_PATH = path.join(__dirname, '..', 'get-shit-done', 'workflows', 'help', 'modes', 'full.md');
|
||||
|
||||
// allow-test-rule: source-text-is-the-product
|
||||
// The workflow and command .md files are the installed AI instructions — their text content
|
||||
|
||||
329
tests/feat-3039-help-tiered.test.cjs
Normal file
329
tests/feat-3039-help-tiered.test.cjs
Normal file
@@ -0,0 +1,329 @@
|
||||
'use strict';
|
||||
|
||||
// allow-test-rule: source-text-is-the-product
|
||||
// `workflows/help/modes/*.md` files ARE the help output — their text is what
|
||||
// the runtime emits when the user runs `/gsd:help [--brief|--full|<topic>]`.
|
||||
// Asserting on their structure tests the deployed contract directly.
|
||||
|
||||
/**
|
||||
* Feature #3039: tiered /gsd:help output.
|
||||
*
|
||||
* The legacy single-file 747-line help is replaced by:
|
||||
* - workflows/help.md — small dispatcher (progressive disclosure)
|
||||
* - workflows/help/modes/brief.md — ~one-liner refresher
|
||||
* - workflows/help/modes/default.md — one-page newcomer tour
|
||||
* - workflows/help/modes/full.md — complete reference (former help.md body)
|
||||
* - workflows/help/modes/topic.md — section-extraction logic + alias table
|
||||
*
|
||||
* This test enforces the contract:
|
||||
* 1. All four mode files exist with a single `<reference>` block.
|
||||
* 2. brief and default fit a "one screen" budget; full stays under LARGE tier cap.
|
||||
* 3. The dispatcher routes on $ARGUMENTS to all four mode files (structural parse).
|
||||
* 4. Dispatcher conflict-resolution rules are documented:
|
||||
* - `--brief` + `--full` without a topic → prefer `--full`
|
||||
* - `--brief <topic>` → topic.md in compact scope (composable)
|
||||
* - bare or `--full <topic>` → topic.md in full scope
|
||||
* 5. topic.md documents an explicit routing preamble + compact-scope rule.
|
||||
* 6. Every topic alias in topic.md resolves to a heading that exists in full.md.
|
||||
* 7. Every /gsd:* sub-block token in topic.md's alias table appears in full.md.
|
||||
* 8. Every full.md heading is either aliased or in the intentional-orphan allowlist.
|
||||
* 9. The `commands/gsd/help.md` shim passes `$ARGUMENTS` through and advertises
|
||||
* the composable `--brief <topic>` form.
|
||||
*/
|
||||
|
||||
const { test, describe } = require('node:test');
|
||||
const assert = require('node:assert/strict');
|
||||
const fs = require('node:fs');
|
||||
const path = require('node:path');
|
||||
|
||||
const ROOT = path.join(__dirname, '..');
|
||||
const WORKFLOWS = path.join(ROOT, 'get-shit-done', 'workflows');
|
||||
const MODES = path.join(WORKFLOWS, 'help', 'modes');
|
||||
const DISPATCHER = path.join(WORKFLOWS, 'help.md');
|
||||
const COMMAND_SHIM = path.join(ROOT, 'commands', 'gsd', 'help.md');
|
||||
|
||||
const MODE_FILES = ['brief.md', 'default.md', 'full.md', 'topic.md'];
|
||||
|
||||
// "One screen" budgets, including frontmatter/<purpose>/<reference> tags.
|
||||
// These are conservative (one-page conceptual size of ~25 lines of usable
|
||||
// content) but allow for the wrapping tags. Tighten as content stabilizes.
|
||||
const BRIEF_BUDGET = 30;
|
||||
const DEFAULT_BUDGET = 70;
|
||||
// full.md is the LARGE tier (see workflow-size-budget.test.cjs — LARGE_BUDGET = 1500).
|
||||
// The size-budget test is non-recursive so full.md is not covered there; cap it here.
|
||||
const FULL_BUDGET = 1500;
|
||||
|
||||
function read(file) {
|
||||
return fs.readFileSync(file, 'utf8');
|
||||
}
|
||||
|
||||
function lineCount(file) {
|
||||
const c = read(file);
|
||||
if (c.length === 0) return 0;
|
||||
const trail = c.endsWith('\n') ? 1 : 0;
|
||||
return c.split('\n').length - trail;
|
||||
}
|
||||
|
||||
describe('feature #3039: tiered help — file structure', () => {
|
||||
for (const f of MODE_FILES) {
|
||||
test(`mode file exists: ${f}`, () => {
|
||||
assert.ok(fs.existsSync(path.join(MODES, f)), `missing ${path.join(MODES, f)}`);
|
||||
});
|
||||
}
|
||||
|
||||
test('dispatcher exists and is small (≤ 40 lines)', () => {
|
||||
assert.ok(fs.existsSync(DISPATCHER));
|
||||
const n = lineCount(DISPATCHER);
|
||||
assert.ok(n <= 40, `dispatcher should be small; got ${n} lines`);
|
||||
});
|
||||
|
||||
for (const f of MODE_FILES) {
|
||||
test(`${f} has exactly one <reference> block (line-anchored)`, () => {
|
||||
const content = read(path.join(MODES, f));
|
||||
// Anchor on start-of-line so prose mentions of `<reference>` inside
|
||||
// <purpose> blocks aren't counted.
|
||||
const opens = (content.match(/^<reference>$/gm) || []).length;
|
||||
const closes = (content.match(/^<\/reference>$/gm) || []).length;
|
||||
assert.equal(opens, 1, `${f}: expected 1 <reference> opening line, got ${opens}`);
|
||||
assert.equal(closes, 1, `${f}: expected 1 </reference> closing line, got ${closes}`);
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
describe('feature #3039: tiered help — size budgets', () => {
|
||||
test(`brief.md fits one screen (≤ ${BRIEF_BUDGET} lines)`, () => {
|
||||
const n = lineCount(path.join(MODES, 'brief.md'));
|
||||
assert.ok(n <= BRIEF_BUDGET, `brief.md is ${n} lines, budget ${BRIEF_BUDGET}`);
|
||||
});
|
||||
|
||||
test(`default.md fits one screen (≤ ${DEFAULT_BUDGET} lines)`, () => {
|
||||
const n = lineCount(path.join(MODES, 'default.md'));
|
||||
assert.ok(n <= DEFAULT_BUDGET, `default.md is ${n} lines, budget ${DEFAULT_BUDGET}`);
|
||||
});
|
||||
|
||||
test('full.md preserves the complete reference (≥ 600 lines)', () => {
|
||||
// The pre-#3039 reference was 747 lines. Guard against accidental shrinkage
|
||||
// that would amount to silently removing content from --full.
|
||||
const n = lineCount(path.join(MODES, 'full.md'));
|
||||
assert.ok(n >= 600, `full.md is ${n} lines — too small, content may have been lost`);
|
||||
});
|
||||
|
||||
test(`full.md stays under LARGE workflow budget (≤ ${FULL_BUDGET} lines)`, () => {
|
||||
// full.md lives in a subdirectory and is not enumerated by the non-recursive
|
||||
// workflow-size-budget.test.cjs. Cap it here at the LARGE tier limit.
|
||||
const n = lineCount(path.join(MODES, 'full.md'));
|
||||
assert.ok(n <= FULL_BUDGET, `full.md grew to ${n} lines (LARGE budget: ${FULL_BUDGET})`);
|
||||
});
|
||||
});
|
||||
|
||||
describe('feature #3039: tiered help — dispatcher routing (structural)', () => {
|
||||
const dispatcher = read(DISPATCHER);
|
||||
|
||||
function extractDisclosureBlock(src) {
|
||||
const m = src.match(/<progressive_disclosure>([\s\S]*?)<\/progressive_disclosure>/);
|
||||
assert.ok(m, 'dispatcher must contain a <progressive_disclosure> block');
|
||||
return m[1];
|
||||
}
|
||||
|
||||
test('dispatcher <progressive_disclosure> block has exactly 5 routing rows', () => {
|
||||
// 4 base tiers (brief, full, default, topic) + 1 composable row (--brief <topic>).
|
||||
const block = extractDisclosureBlock(dispatcher);
|
||||
// Table rows are lines starting with `|`, excluding the header and separator rows.
|
||||
const rows = block.split('\n')
|
||||
.filter(l => /^\|/.test(l))
|
||||
.filter(l => !/^\|\s*[-:]+\s*\|/.test(l)) // strip separator rows
|
||||
.filter(l => !/when.*arguments/i.test(l)); // strip header row
|
||||
assert.equal(rows.length, 5,
|
||||
`dispatcher routing table must have exactly 5 rows; got ${rows.length}:\n${rows.join('\n')}`);
|
||||
});
|
||||
|
||||
test('dispatcher routes --brief to brief.md', () => {
|
||||
const block = extractDisclosureBlock(dispatcher);
|
||||
assert.match(block, /`--brief`[\s\S]*?brief\.md/);
|
||||
});
|
||||
|
||||
test('dispatcher routes --full to full.md', () => {
|
||||
const block = extractDisclosureBlock(dispatcher);
|
||||
assert.match(block, /`--full`[\s\S]*?full\.md/);
|
||||
});
|
||||
|
||||
test('dispatcher routes empty/no-flag args to default.md', () => {
|
||||
const block = extractDisclosureBlock(dispatcher);
|
||||
assert.match(block, /(empty|unset)[\s\S]*?default\.md/i);
|
||||
});
|
||||
|
||||
test('dispatcher routes topic args to topic.md', () => {
|
||||
const block = extractDisclosureBlock(dispatcher);
|
||||
assert.match(block, /topic[\s\S]*?topic\.md/i);
|
||||
});
|
||||
});
|
||||
|
||||
describe('feature #3039: tiered help — dispatcher conflict-resolution rules', () => {
|
||||
const dispatcher = read(DISPATCHER);
|
||||
|
||||
test('dispatcher documents --brief + --full (without topic) conflict resolution (prefer --full)', () => {
|
||||
// help.md argument parsing rules: "if both appear *without* a topic, prefer `--full`"
|
||||
assert.match(dispatcher, /prefer.*--full/);
|
||||
});
|
||||
|
||||
test('dispatcher routes --brief <topic> to topic.md in compact scope (composable)', () => {
|
||||
// help.md argument parsing rules: "--brief combined with a topic invokes topic.md
|
||||
// in compact scope" — the composable scoped-lookup form (trek-e review finding #4).
|
||||
assert.match(dispatcher, /--brief[^|]*<topic>[\s\S]*?topic\.md[\s\S]*?compact/i);
|
||||
});
|
||||
|
||||
test('dispatcher routes --full <topic> (or bare topic) to topic.md in full scope', () => {
|
||||
// Bare topic, `--full <topic>`, or topic with leading `--` → full scope.
|
||||
assert.match(dispatcher, /(bare topic|--full <topic>)[\s\S]*?full scope/i);
|
||||
});
|
||||
|
||||
test('dispatcher tells topic.md to retain --brief when delegating', () => {
|
||||
// The dispatcher passes $ARGUMENTS through; topic.md needs to see --brief to
|
||||
// choose compact scope. Guard against accidental flag-stripping.
|
||||
assert.match(dispatcher, /retain.*--brief|pass.*--brief/i);
|
||||
});
|
||||
});
|
||||
|
||||
describe('feature #3039: tiered help — command shim passes $ARGUMENTS', () => {
|
||||
const shim = read(COMMAND_SHIM);
|
||||
|
||||
test('shim references $ARGUMENTS', () => {
|
||||
assert.match(shim, /\$ARGUMENTS/);
|
||||
});
|
||||
|
||||
test('shim declares argument-hint frontmatter', () => {
|
||||
assert.match(shim, /argument-hint:/);
|
||||
});
|
||||
|
||||
test('shim argument-hint advertises composable --brief <topic>', () => {
|
||||
// Discoverability: users need to know the composable form is supported
|
||||
// (trek-e review finding #4).
|
||||
assert.match(shim, /argument-hint:[^\n]*--brief[^\n]*<topic>/);
|
||||
});
|
||||
|
||||
test('shim references the help workflow', () => {
|
||||
assert.match(shim, /workflows\/help\.md/);
|
||||
});
|
||||
});
|
||||
|
||||
describe('feature #3039: tiered help — topic.md routing visibility + compact scope', () => {
|
||||
const topicSrc = read(path.join(MODES, 'topic.md'));
|
||||
|
||||
test('topic.md documents an explicit resolved-routing preamble', () => {
|
||||
// Trek-e review finding #3: routing must be explicit in output so the user
|
||||
// can see which alias matched which heading and at what scope.
|
||||
assert.match(topicSrc, /\*\*Topic:\*\*[\s\S]*<alias>[\s\S]*<heading>/);
|
||||
assert.match(topicSrc, /scope:.*full.*\|.*compact/i);
|
||||
});
|
||||
|
||||
test('topic.md documents a compact scope distinct from full scope', () => {
|
||||
// Trek-e review finding #4: --brief <topic> must produce a compact
|
||||
// scoped lookup (signature + one-line summary), not the full section.
|
||||
assert.match(topicSrc, /compact scope/i);
|
||||
assert.match(topicSrc, /signature.*one-line summary|signature \+ one-line/i);
|
||||
});
|
||||
|
||||
test('topic.md parses --brief flag and strips it before resolving the alias', () => {
|
||||
// Compact scope must trigger off the --brief flag in $ARGUMENTS; the
|
||||
// remaining token is the alias.
|
||||
assert.match(topicSrc, /--brief.*-b.*compact scope|compact scope[\s\S]*--brief/i);
|
||||
});
|
||||
|
||||
test('topic.md closing "More:" line advertises the composable form', () => {
|
||||
assert.match(topicSrc, /More:[\s\S]*--brief <topic>/);
|
||||
});
|
||||
});
|
||||
|
||||
describe('feature #3039: tiered help — topic alias coverage', () => {
|
||||
const topicSrc = read(path.join(MODES, 'topic.md'));
|
||||
const fullSrc = read(path.join(MODES, 'full.md'));
|
||||
|
||||
// Extract the alias table portion of topic.md (before "**Output rules:**")
|
||||
function aliasTableSection(src) {
|
||||
return src.split('**Output rules:**')[0];
|
||||
}
|
||||
|
||||
// Extract the canonical heading text referenced from each row of the
|
||||
// alias table. Rows look like: `| aliases | \`## Heading\` ... |`.
|
||||
// We accept either ## or ### and pull the literal heading text.
|
||||
function extractReferencedHeadings(src) {
|
||||
const headings = new Set();
|
||||
const re = /`(#{2,3} [^`]+?)`/g;
|
||||
let m;
|
||||
while ((m = re.exec(src)) !== null) {
|
||||
headings.add(m[1].trim());
|
||||
}
|
||||
return headings;
|
||||
}
|
||||
|
||||
function fullHeadings(src) {
|
||||
const set = new Set();
|
||||
for (const line of src.split('\n')) {
|
||||
const m = line.match(/^(#{2,3}) (.+?)\s*$/);
|
||||
if (m) set.add(`${m[1]} ${m[2]}`);
|
||||
}
|
||||
return set;
|
||||
}
|
||||
|
||||
test('every heading referenced in topic.md exists in full.md', () => {
|
||||
const referenced = extractReferencedHeadings(aliasTableSection(topicSrc));
|
||||
const present = fullHeadings(fullSrc);
|
||||
const missing = [...referenced].filter((h) => !present.has(h)).sort();
|
||||
assert.deepEqual(missing, [],
|
||||
`topic.md references headings not present in full.md: ${missing.join(' | ')}`);
|
||||
});
|
||||
|
||||
test('every /gsd:* sub-block token in topic.md alias table exists in full.md', () => {
|
||||
// Validates fix for review finding #2: sub-block aliases reference bold-line
|
||||
// anchors (**`/gsd:X`**) — assert each token actually appears in full.md.
|
||||
const tableSection = aliasTableSection(topicSrc);
|
||||
const tokens = [...tableSection.matchAll(/`(\/gsd:[a-z-]+(?:\s+--[a-z-]+)?)`/g)].map(m => m[1]);
|
||||
assert.ok(tokens.length > 0, 'expected at least one /gsd:* token in alias table');
|
||||
const missing = tokens.filter(t => !fullSrc.includes(t));
|
||||
assert.deepEqual(missing, [],
|
||||
`topic.md references /gsd:* tokens not present in full.md: ${missing.join(' | ')}`);
|
||||
});
|
||||
|
||||
test('every full.md heading is either aliased or in the intentional-orphan allowlist', () => {
|
||||
// Catches newly added headings that have no alias (contributor must either
|
||||
// alias the section or explicitly add it to INTENTIONAL_ORPHANS below).
|
||||
const INTENTIONAL_ORPHANS = new Set([
|
||||
'## Quick Start',
|
||||
'## Staying Updated',
|
||||
'### Utility Commands', // covered by cleanup/update sub-block aliases
|
||||
'## Additional Commands',
|
||||
'### Discovery & Specification',
|
||||
'### Planning & Execution',
|
||||
'### Quality, Review & Verification',
|
||||
'### Diagnostics & Maintenance',
|
||||
'### Knowledge & Context',
|
||||
'### Workflow & Orchestration',
|
||||
'### Repository Integration',
|
||||
'### Namespace Routers (model-facing meta-skills)',
|
||||
]);
|
||||
|
||||
const allHeadings = fullSrc.split('\n')
|
||||
.filter(l => /^#{2,3} /.test(l))
|
||||
.map(l => l.trim());
|
||||
|
||||
const aliased = extractReferencedHeadings(aliasTableSection(topicSrc));
|
||||
|
||||
const orphans = allHeadings.filter(h => !aliased.has(h) && !INTENTIONAL_ORPHANS.has(h));
|
||||
assert.deepEqual(orphans, [],
|
||||
`full.md headings not aliased in topic.md (add to INTENTIONAL_ORPHANS if intentional): ${orphans.join(' | ')}`);
|
||||
});
|
||||
|
||||
test('topic.md covers the core topics promised in default.md', () => {
|
||||
// Surface contract: default.md advertises a "Topics:" line. Each alias
|
||||
// there must appear as a recognized topic in topic.md's alias table.
|
||||
const def = read(path.join(MODES, 'default.md'));
|
||||
const topicsLine = def.split('\n').find((l) => /^Topics:/i.test(l));
|
||||
assert.ok(topicsLine, 'default.md must advertise a "Topics:" line for users');
|
||||
// Strip the leading "Topics:" prefix, then pull every backticked token.
|
||||
const aliases = [...topicsLine.matchAll(/`([a-z][a-z0-9-]*)`/g)].map((m) => m[1]);
|
||||
assert.ok(aliases.length >= 5, `expected at least 5 promoted topic aliases; got ${aliases.length}`);
|
||||
const missing = aliases.filter((a) => !new RegExp(`\`${a}\``).test(topicSrc));
|
||||
assert.deepEqual(missing, [],
|
||||
`default.md promotes topic aliases that topic.md does not recognize: ${missing.join(', ')}`);
|
||||
});
|
||||
});
|
||||
@@ -56,7 +56,6 @@ const LARGE_WORKFLOWS = new Set([
|
||||
'complete-milestone', // 847
|
||||
'verify-work', // 740
|
||||
'transition', // 693
|
||||
'help', // 667
|
||||
'discuss-phase-assumptions', // 670
|
||||
'progress', // 619
|
||||
'new-milestone', // 611
|
||||
|
||||
Reference in New Issue
Block a user