# GSD Core Command Reference > Command reference for GSD Core — syntax, flags, options, and examples for every stable command. For feature details see [Feature Reference](FEATURES.md); for workflow walkthroughs see [User Guide](USER-GUIDE.md); for the docs index see [README](README.md). --- ## Command Syntax - **Claude Code / Copilot / OpenCode / Kilo:** `/gsd-command-name [args]` (hyphen form) - **Codex:** `$gsd-command-name [args]` The hyphen and colon forms are *runtime-specific spellings of the same command*. Whichever runtime you're on, the installer writes the correct form into your runtime's command directory. ### Skill Runtime Behavior (Claude Code) Heavy workflow skills (`/gsd-plan-phase`, `/gsd-execute-phase`, `/gsd-autonomous`) declare `effort: max`, signalling maximum token budget to the runtime. These skills are spawning orchestrators — they must run at top level so they retain the `Agent` tool needed to spawn subagents. They do **not** carry `context: fork` (see #921). Quick-status skills (`/gsd-progress`, `/gsd-stats`) declare `effort: low`, directing the runtime to use a minimal token budget for fast reads. These fields are Claude Code–specific frontmatter. On runtimes that do not recognise them (Antigravity, Codex, Cursor, etc.) the fields are silently ignored — existing behaviour is unchanged. --- ## Namespace Meta-Skills Six namespace routers ship as the first-stage entry points in v1.40. They keep the eager skill-listing token cost low (~120 tokens for 6 routers vs ~2,150 for a flat 86-skill listing) while the full surface remains directly invocable. The model selects a namespace, then routes to the concrete sub-skill. See [#2792](https://github.com/open-gsd/gsd-core/issues/2792). | Command | Routes to | |---------|-----------| | `/gsd-workflow` | Phase pipeline — discuss / plan / execute / verify / phase / progress / next | | `/gsd-project` | Project lifecycle — milestones, audits, summary | | `/gsd-quality` | Quality gates — code review, debug, audit, security, eval, ui | | `/gsd-context` | Codebase intelligence — map, graphify, docs, learnings | | `/gsd-manage` | Management — config, workspace, workstreams, thread, update, ship, inbox | | `/gsd-ideate` | Exploration & capture — explore, sketch, spike, spec, capture | The namespace skills are **additive** — every existing concrete command (e.g. `/gsd-plan-phase`, `/gsd-code-review --fix`) is still invocable directly. --- ## Core Workflow Commands ### `/gsd-new-project` Initialize a new project with deep context gathering. | Flag | Description | |------|-------------| | `--auto @file.md` | Auto-extract from document, skip interactive questions | **Prerequisites:** No existing `.planning/PROJECT.md` **Produces:** `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, `config.json`, `research/`, `CLAUDE.md` ```bash /gsd-new-project # Interactive mode /gsd-new-project --auto @prd.md # Auto-extract from PRD ``` --- ### `/gsd-onboard` Guide an existing codebase through first-time GSD onboarding. The command checks repo state, routes you through codebase mapping, optional docs ingest, project initialization, and creates an onboarding summary once planning exists. | Flag | Description | |------|-------------| | `--fast` | Prefer the lightweight `/gsd-map-codebase --fast` mapping handoff; a complete map is still required before `/gsd-new-project` | | `--text` | Use numbered plain-text gates instead of TUI menus | **Prerequisites:** Existing repo or planning docs. For empty greenfield projects, use `/gsd-new-project`. **Produces:** `.planning/codebase/` via map-codebase, `.planning/` via new-project or ingest-docs, and `.planning/onboarding/SUMMARY.md` after project setup. ```bash /gsd-onboard # Guided brownfield onboarding /gsd-onboard --fast # Use lightweight codebase mapping first, then complete the map before project setup ``` --- ### `/gsd-workspace` Manage GSD workspaces — create, list, or remove isolated workspace environments with repo copies and independent `.planning/` directories. | Flag | Description | |------|-------------| | `--new` | Create a new workspace (use with `--name`, `--repos`, etc.) | | `--list` | List active GSD workspaces and their status | | `--remove ` | Remove a workspace and clean up git worktrees | | `--name ` | Workspace name (used with `--new`) | | `--repos repo1,repo2` | Comma-separated repo paths or names (used with `--new`) | | `--path /target` | Target directory (default: `~/gsd-workspaces/`) | | `--strategy worktree\|clone` | Copy strategy (default: `worktree`) | | `--branch ` | Branch to checkout (default: `workspace/`) | | `--auto` | Skip interactive questions | **Use cases:** - Multi-repo: work on a subset of repos with isolated GSD state - Feature isolation: `--repos .` creates a worktree of the current repo **Produces:** `WORKSPACE.md`, `.planning/`, repo copies (worktrees or clones) ```bash /gsd-workspace --new --name feature-b --repos hr-ui,ZeymoAPI /gsd-workspace --new --name feature-b --repos . --strategy worktree # Same-repo isolation /gsd-workspace --list /gsd-workspace --remove feature-b ``` --- ### `/gsd-spec-phase` Clarify WHAT a phase delivers through Socratic questioning with quantitative ambiguity scoring, then probe for omitted edges. Produces `SPEC.md` before discuss-phase. | Argument | Required | Description | |----------|----------|-------------| | `N` | Yes | Phase number | | Flag | Description | |------|-------------| | `--auto` | Skip interactive questions; Claude selects recommended defaults and writes SPEC.md | | `--text` | Use plain-text numbered lists instead of TUI menus (required for `/rc` remote sessions) | **Position in workflow:** `spec-phase → discuss-phase → plan-phase → execute-phase → verify` **Edge Coverage (Step 5.5):** After the ambiguity gate passes, spec-phase runs an edge-completeness probe over each requirement. It raises only applicable categories from a closed 8-category taxonomy (boundary, adjacency, empty, encoding, ordering, precision, idempotency, concurrency), proposes one concrete candidate edge per category, and records each as `covered` / `dismissed` (reason required) / `backstop` / `unresolved` in a `## Edge Coverage` SPEC section. Unresolved applicable edges soft-gate the spec (Resolve / Write-anyway-flagged / Keep-probing); `covered` and `backstop` edges are later lifted into plan-phase `must_haves`. Under `--auto` the probe **never auto-dismisses** — it auto-covers where a defensible acceptance criterion exists, otherwise auto-backstops. **Prohibition Coverage (Step 5.6):** After the edge probe, spec-phase runs a prohibition-completeness probe — a two-stage prose pass (adversarial recall → precision classifier) that surfaces the unwritten *must-NOT* constraints (values/safety/ethics) the spec never forbids. Each is resolved to `resolved` (a NEGATIVE acceptance criterion, carrying a `test` or `judgment` verification tier) / `dismissed` (reason required) / `unresolved`, recorded in a `## Prohibitions (must-NOT)` SPEC section. Resolved prohibitions are lifted into plan-phase `must_haves.prohibitions`; judgment-tier items soft-gate at verify time (never silent, never hard-halt) and unwired test-tier items fail closed. Under `--auto` the probe **never auto-dismisses**; canon-bound concerns (OWASP / GDPR / fairness) are referred to `/gsd-secure-phase`. **Prerequisites:** `.planning/ROADMAP.md` exists **Produces:** `{phase}-SPEC.md` (with a `## Edge Coverage` section) ```bash /gsd-spec-phase 1 # Interactive spec + edge probe for phase 1 /gsd-spec-phase 3 --auto # Auto-select defaults; never auto-dismisses an edge /gsd-spec-phase 2 --text # Plain-text menus for remote sessions ``` --- ### `/gsd-discuss-phase` Gather phase context through adaptive questioning before planning. | Argument | Required | Description | |----------|----------|-------------| | `N` | No | Phase number (defaults to current phase) | | Flag | Description | |------|-------------| | `--all` | Skip area selection — discuss all gray areas interactively (no auto-advance) | | `--auto` | Auto-select recommended defaults for all questions | | `--batch` | Group questions for batch intake instead of one-by-one | | `--analyze` | Add trade-off analysis during discussion | | `--power` | File-based bulk question answering from a prepared answers file | | `--assumptions` | Surface Claude's implementation assumptions about the phase without an interactive session | **Prerequisites:** `.planning/ROADMAP.md` exists **Produces:** `{phase}-CONTEXT.md`, `{phase}-DISCUSSION-LOG.md` (audit trail) ```bash /gsd-discuss-phase 1 # Interactive discussion for phase 1 /gsd-discuss-phase 1 --all # Discuss all gray areas without selection step /gsd-discuss-phase 3 --auto # Auto-select defaults for phase 3 /gsd-discuss-phase --batch # Batch mode for current phase /gsd-discuss-phase 2 --analyze # Discussion with trade-off analysis /gsd-discuss-phase 1 --power # Bulk answers from file /gsd-discuss-phase 3 --assumptions # Surface Claude's assumptions before planning ``` --- ### `/gsd-ui-phase` Generate UI design contract for frontend phases. | Argument | Required | Description | |----------|----------|-------------| | `N` | No | Phase number (defaults to current phase) | **Prerequisites:** `.planning/ROADMAP.md` exists, phase has frontend/UI work **Produces:** `{phase}-UI-SPEC.md` ```bash /gsd-ui-phase 2 # Design contract for phase 2 ``` --- ### `/gsd-plan-phase` Research, plan, and verify a phase. | Argument | Required | Description | |----------|----------|-------------| | `N` | No | Phase number (if omitted, the orchestrating workflow reads ROADMAP.md and targets the next unplanned phase — not a `gsd-tools.cjs` CLI feature) | | Flag | Description | |------|-------------| | `--auto` | Skip interactive confirmations | | `--research` | Force re-research even if RESEARCH.md exists | | `--skip-research` | Skip domain research step | | `--research-phase ` | Research-only mode: spawn researcher for phase ``, write RESEARCH.md, exit before planner. Supersedes the deleted standalone research command (#3042). | | `--view` | Research-only modifier: when used with `--research-phase`, print existing RESEARCH.md to stdout and exit (no spawn). | | `--gaps` | Gap closure mode (reads VERIFICATION.md, skips research) | | `--skip-verify` | Skip plan checker verification loop | | `--prd ` | Use a PRD file instead of discuss-phase for context | | `--ingest ` | Use ADR file(s) instead of discuss-phase for context synthesis | | `--ingest-format ` | Optional ADR parser format override for `--ingest` | | `--reviews` | Replan with cross-AI review feedback from REVIEWS.md | | `--bounce` | Run external plan bounce validation after planning (uses `workflow.plan_bounce_script`) | | `--skip-bounce` | Skip plan bounce even if enabled in config | | `--mvp` | MVP enrichment on top of the default tracer-first ordering — frames the phase goal as a user story and, on Phase 1 of a new project with no prior phase summaries, also emits `SKELETON.md` (Walking Skeleton). Vertical slicing is now the default (see `--no-tracer`); `--mvp` no longer turns it on. Can be persisted on a phase via `**Mode:** mvp` in ROADMAP.md, which applies `--mvp` automatically without the flag. | | `--no-tracer` | Opt out of the default **tracer-first** decomposition and plan horizontal layers (the legacy default). By default every plan leads with one production-quality end-to-end `tracer` slice that the executor verifies before any expansion task. | | `--no-reversibility-gates` | Suppress the human checkpoint that a **one-way-door** decision normally earns, for runs you intend to leave unattended. By default a decision rated `one-way` — undoing it needs a data migration, breaks a published contract, or is impossible — gets a `checkpoint:decision` inserted before the task that implements it. Ratings are still recorded on tasks and `costly` decisions are still flagged, so the flag changes what stops the run, not what the plan remembers. | | `--tdd` | TDD mode — planner applies `type: tdd` to eligible behavior-adding tasks so each begins with a failing test. Composable with `--mvp`: `--mvp --tdd` produces vertical slices where every behavior-adding task starts red-green. The leading `tracer` task also starts red under `--tdd`. | | `--granularity ` | Override the planning granularity for this invocation, ignoring config. Valid values: `coarse`, `standard`, `fine`. Takes precedence over `granularities.planning`, top-level `granularity`, and `planning.granularity` config. | **Smart-zone estimate report (#2631).** Every generated PLAN.md carries an optional `estimate` block (`{tokens, tasks, confidence}`). During the plan-check pass, `gsd-plan-checker` runs each plan's `estimate.tokens` through `estimate-check` against the configurable `workflow.smart_zone_tokens` budget (default `100000`) and reports the result; a plan above budget gets a concrete split recommendation. The report is **advisory and never blocks planning**, and it is skipped with `--skip-verify` since it runs inside the verification pass. `confidence` is derived from how many completed phases carry recorded actuals — `low` means fewer than three, so the figure is not yet calibrated for your project. See [ADR-2629](adr/2629-phase-effort-estimation-calibration.md). **Prerequisites:** `.planning/ROADMAP.md` exists **Produces:** `{phase}-RESEARCH.md`, `{phase}-{N}-PLAN.md`, `{phase}-VALIDATION.md`; `{phase}/SKELETON.md` when Walking Skeleton mode fires **Research-only mode (`--research-phase `):** - No modifier: when RESEARCH.md already exists, auto-uses it — emits a one-line notice and exits, no prompt. - With `--research`: force-refresh — re-spawn researcher unconditionally, no prompt. - With `--view`: print existing RESEARCH.md to stdout, no spawn. Errors if RESEARCH.md missing. **Package Legitimacy Gate (v1.42.1):** When the researcher recommends external packages, it runs `gsd-tools query package-legitimacy check --ecosystem ` on each one and writes a `## Package Legitimacy Audit` table to RESEARCH.md recording Registry, Age, Downloads, Source Repo, and legitimacy verdict. Verdicts are computed from live registry APIs (npm, PyPI, crates.io): - `[SLOP]` — package removed from RESEARCH.md entirely; never reaches the planner - `[SUS]` — package flagged; planner inserts `checkpoint:human-verify` before the install task - `[OK]` — package approved; no checkpoint added Packages sourced from WebSearch are tagged `[ASSUMED]` (not `[VERIFIED]`) and treated the same as `[SUS]` — they get a human checkpoint before install. A failed registry lookup degrades to `[SUS]` rather than throwing, so it is gated, not silently accepted. `slopcheck` is an optional escalate-only adapter that no shipped configuration wires; it is not required for the gate to function. See [Package Legitimacy Gate in the User Guide](USER-GUIDE.md#package-legitimacy-gate-v1421) for the full checkpoint format, verdict table, and troubleshooting. **In-repo value citation:** For any in-repo *discrete value* the researcher reports — an enum, a schema or type union, an error code, a status constant, or a filesystem path — a `[VERIFIED: …]` tag requires that it opened the source-of-truth file with `Read` during the run and cited the path **and line range** (`[VERIFIED: src/types/order.ts:14-22]`). The values are quoted verbatim in RESEARCH.md beside the claim, and any value used in a code example must also appear in that quote; anything else stays `[ASSUMED]`. A codebase `grep`, training memory, or a web search do not earn the tag on their own. This stops a plausible-but-drifted enum from reaching PLAN.md — where the planner lifts it into the plan's `` context block and the executor trusts it as ground truth — and surfacing only as a mid-execution deviation at typecheck. ```bash /gsd-plan-phase 1 # Research + plan + verify phase 1 /gsd-plan-phase 3 --skip-research # Plan without research (familiar domain) /gsd-plan-phase --auto # Non-interactive planning /gsd-plan-phase 1 --bounce # Plan + external bounce validation /gsd-plan-phase 2 --ingest docs/adr/0010.md # ADR express path for context synthesis /gsd-plan-phase 2 --ingest 'docs/adr/00*.md' --ingest-format auto /gsd-plan-phase --research-phase 4 # Research only on phase 4 (auto-uses existing RESEARCH.md, no prompt) /gsd-plan-phase --research-phase 4 --view # Print existing RESEARCH.md, no spawn /gsd-plan-phase --research-phase 4 --research # Force-refresh research, no prompt /gsd-plan-phase 1 --mvp # Vertical-slice plan for phase 1 /gsd-plan-phase 1 --mvp --tdd # Vertical slices + failing test per behavior-adding task ``` --- ### `/gsd-plan-review-convergence` Cross-AI plan convergence loop — replan with review feedback until no HIGH concerns remain and no actionable MEDIUM/LOW findings remain outside `PLAN.md`. Runs `plan-phase → review → replan → re-review` cycles (max 3 cycles by default). Plan-phase runs inline (bare Skill at depth 0 so it can spawn gsd-planner/gsd-plan-checker at depth 1); only gsd-review runs in an isolated Agent. Orchestrator handles loop control, unresolved review counting (HIGH + actionable non-HIGH), stall detection, and escalation. | Argument / Flag | Required | Description | |-----------------|----------|-------------| | `N` | **Yes** | Phase number to plan and review | | Reviewer flags | No | Pass through every reviewer lane flag: `--gemini`, `--claude`, `--codex`, `--coderabbit`, `--opencode`, `--qwen`, `--cursor`, `--agy` / `--antigravity`, `--ollama`, `--lm-studio`, `--llama-cpp`, `--kimi-code` | | `--all` | No | Run every configured reviewer in parallel | | `--max-cycles N` | No | Override cycle cap (default 3) | **Exit behavior:** Loop exits when both `current_high` and `current_actionable` hit zero. Stall detection warns when the total unresolved review count is not decreasing across cycles. Escalation gate asks the user to proceed or review manually when `--max-cycles` is hit with HIGH or actionable non-HIGH concerns still open. ```bash /gsd-plan-review-convergence 3 # Default reviewers, 3 cycles /gsd-plan-review-convergence 3 --codex # Codex-only review /gsd-plan-review-convergence 3 --all --max-cycles 5 ``` --- ### `/gsd-ultraplan-phase` **[BETA]** Offload plan phase to Claude Code's ultraplan cloud; review in browser and import back. The plan drafts remotely so the terminal stays free; review inline comments in a browser, then import the finalized plan back into `.planning/` via `/gsd-import`. | Flag | Required | Description | |------|----------|-------------| | `N` | **Yes** | Phase number to plan remotely | **Isolation:** Intentionally separate from `/gsd-plan-phase` so upstream ultraplan changes cannot affect the core planning pipeline. ```bash /gsd-ultraplan-phase 4 # Offload planning for phase 4 ``` --- ### `/gsd-execute-phase` Execute all plans in a phase with wave-based parallelization, or run a specific wave. | Argument | Required | Description | |----------|----------|-------------| | `N` | **Yes** | Phase number to execute | | `--wave N` | No | Execute only Wave `N` in the phase | | `--cross-ai` | No | Delegate execution to an external AI CLI (uses `workflow.cross_ai_command`) | | `--no-cross-ai` | No | Force local execution even if cross-AI is enabled in config | **Prerequisites:** Phase has PLAN.md files **Produces:** per-plan `{phase}-{N}-SUMMARY.md`, git commits, and `{phase}-VERIFICATION.md` when the phase is fully complete **Package install failures (v1.42.1):** If a plan's install step fails, the executor surfaces a `checkpoint:human-verify` and stops. It does not auto-install a similarly-named alternative. This is intentional — silently substituting package names is how slopsquatting spreads. Respond to the checkpoint after verifying the package on its registry page. ```bash /gsd-execute-phase 1 # Execute phase 1 /gsd-execute-phase 1 --wave 2 # Execute only Wave 2 /gsd-execute-phase 2 --cross-ai # Delegate phase 2 to external AI CLI ``` --- ### `/gsd-verify-work` User acceptance testing with auto-diagnosis. | Argument | Required | Description | |----------|----------|-------------| | `N` | No | Phase number (defaults to last executed phase) | **Prerequisites:** Phase has been executed **Produces:** `{phase}-UAT.md`, fix plans if issues found For browser-backed UAT, use a configured browser MCP server. The current Open GSD companion is `gsd-browser` (`gsd-browser mcp`), which provides deterministic navigation, versioned refs, assertions, screenshots, visual diffs, recordings, and human takeover. Legacy Playwright MCP servers remain usable when already configured. ```bash /gsd-verify-work 1 # UAT for phase 1 ``` **Coverage-aware UAT routing (#1602).** When a SUMMARY.md carries a `coverage:` frontmatter block, `verify-work` classifies each deliverable deterministically instead of prompting for every prose bullet: deliverables proven by passing tests are auto-passed (recorded with `source: automated`, no prompt) and only judgment-dependent deliverables are presented for human sign-off. SUMMARYs without a `coverage:` block fall back to the previous prose-based extraction unchanged. See the [`coverage:` block reference](#summary-coverage-block) below. **Honest verifier — `insufficient_spec` abstention (#1154).** A `must_haves.truths` item carrying the `verification: backstop` marker (a *non-inferable* check the edge-probe surfaced at spec time) is graded specially: if the verifier cannot confirm it with **explicit evidence** (a passing wired held-out/property-based test, or a directly-observed behavior), it **abstains** — the item is reported `unverified — held-out test recommended` and the phase verdict becomes `human_needed` (with reason `insufficient_spec`, distinct from ordinary manual-UAT `human_needed`), **never a silent `passed`**. Autonomous runs complete with "N unverified non-inferable checks" rather than hard-halting; interactive runs route the item to the end-of-phase human checkpoint. Abstention is exogenous (driven by the `backstop` tag, never a self-judged "abstain if unsure") and an inferable truth is never abstained. Reliable on capable verifier tiers (`sonnet`+); the budget `haiku` tier degrades toward current behavior. See [Honest Verifier](../gsd-core/references/honest-verifier.md). #### SUMMARY `coverage:` block A SUMMARY.md may carry an optional `coverage:` frontmatter block — a list of per-deliverable entries that joins requirements → tests → verification status: | Field | Description | |-------|-------------| | `id` | Stable identifier (`D1`, `D2`…), unique within the SUMMARY | | `description` | The deliverable in human-readable form | | `requirement` | Optional REQ-ID linking to REQUIREMENTS.md | | `verification[].kind` | `unit` \| `integration` \| `e2e` \| `automated_ui` \| `manual_procedural` \| `other` | | `verification[].ref` | Test path + descriptor, screenshot ref, or command | | `verification[].status` | `pass` \| `fail` \| `unknown` | | `human_judgment` | Required boolean. `true` always routes to a human | | `rationale` | Required when `human_judgment: true` | A deliverable is auto-passed **only** when `human_judgment: false`, its `verification` list is non-empty, and every entry's `status` is `pass`. Anything else — `human_judgment: true`, an empty `verification`, a non-`pass` status, or a schema error — is presented to a human (fail-safe). Inspect the classification directly with: ```bash node gsd-tools.cjs uat classify-coverage --summary .planning/phases/01-foundation/01-01-SUMMARY.md ``` --- --- ### `/gsd-ship` Create PR from completed phase work with auto-generated body. | Argument | Required | Description | |----------|----------|-------------| | `N` | No | Phase number or milestone version (e.g., `4` or `v1.0`) | | `--draft` | No | Create as draft PR | **Prerequisites:** Phase verified (`/gsd-verify-work` passed), `gh` CLI installed and authenticated **Produces:** GitHub PR with rich body from planning artifacts, STATE.md updated ```bash /gsd-ship 4 # Ship phase 4 /gsd-ship 4 --draft # Ship as draft PR ``` **PR body includes:** - Phase goal from ROADMAP.md - Changes summary from SUMMARY.md files - Requirements addressed (REQ-IDs) - Verification status - Key decisions - Optional configured PRD-style sections from `ship.pr_body_sections` **Ship gates (capability-driven):** `/gsd-ship` runs every active `ship:pre` gate from the capability registry. Two are on by default: - **Security** (`security` capability): blocks while `SECURITY.md` reports `threats_open > 0`. Resolve via `/gsd-secure-phase {n}`. - **Broken-windows ledger** (`broken-windows` capability, issue #1950): when `workflow.windows_enforce=true` is set, blocks while `.planning/WINDOWS.md` reports any `open` entry. The ledger accumulates stubs, TODOs, skipped tests, unrun verifies, and unmet truths across phases. Resolve an entry with `gsd-tools windows fixed ` (defect resolved) or `gsd-tools windows waive ""` (justified deferral — reason is required and recorded). Inspect via `gsd-tools windows status`. Enforcement is **opt-in** (default `workflow.windows_enforce=false`): enable with `gsd config-set workflow.windows_enforce true`; tracking continues regardless. See [Custom PR Body Sections](ship-pr-body-sections.md) for onboarding, examples, and validation rules. --- ### `/gsd-ui-review` Retroactive 6-pillar visual audit of implemented frontend. | Argument | Required | Description | |----------|----------|-------------| | `N` | No | Phase number (defaults to last executed phase) | **Prerequisites:** Project has frontend code (works standalone, no GSD project needed) **Produces:** `{phase}-UI-REVIEW.md`, screenshots in `.planning/ui-reviews/` For richer visual evidence, pair this with `gsd-browser` or another browser MCP server so the audit can capture screenshots, state, console/network context, and reproducible interaction steps. ```bash /gsd-ui-review # Audit current phase /gsd-ui-review 3 # Audit phase 3 ``` --- ### `/gsd-audit-uat` Cross-phase audit of all outstanding UAT and verification items. **Prerequisites:** At least one phase has been executed with UAT or verification **Produces:** Categorized audit report with human test plan ```bash /gsd-audit-uat ``` --- ### `/gsd-audit-milestone` Verify milestone met its definition of done. **Prerequisites:** All phases executed **Produces:** Audit report with gap analysis ```bash /gsd-audit-milestone ``` --- ### `/gsd-complete-milestone` Archive milestone, tag release. **Prerequisites:** Milestone audit complete (recommended) **Produces:** `MILESTONES.md` entry, git tag ```bash /gsd-complete-milestone ``` **Pre-close artifact audit.** Before archiving, the workflow runs `gsd-tools audit-open` and reports every unresolved item across nine categories: | Category | Source | Open when | |----------|--------|-----------| | Debug sessions | `.planning/debug/` | status not `resolved` / `complete` | | Quick tasks | `.planning/quick/` | SUMMARY missing or not `complete` | | Threads | `.planning/threads/` | status not terminal | | Pending todos | `.planning/todos/pending/` | present | | Seeds | `.planning/seeds/` | not yet implemented | | UAT gaps | `*-UAT.md` | scenarios still pending | | Verification gaps | `*-VERIFICATION.md` | verdict `gaps_found` / `human_needed` | | CONTEXT questions | `*-CONTEXT.md` | questions left open | | **Deferred items** | `deferred-items.md` | entry lacks `status: resolved` | The four phase-scoped categories above (UAT gaps, Verification gaps, CONTEXT questions, Deferred items) read phase directories from **both** the active `.planning/phases/` root and every archived `.planning/milestones/vX.Y-phases/` root (#3458) — an item still unresolved when its milestone closed and its phase directory archived stays visible in every later audit instead of silently disappearing. In `--json` output, an item sourced from an archived milestone carries an `archived_milestone` field (e.g. `"v1.0"`); active items omit the field entirely. The human-readable report labels an archived item's line with `(archived vX.Y)` so a phase number that repeats across milestones (numbering restarts at `01` after each archive) is not misread as one duplicate line. If any category is non-empty you are prompted with `[R] Resolve` / `[A] Acknowledge all` / `[C] Cancel`. `[A]` calls `gsd-tools audit-open acknowledge` once per open item — the CLI writer that actually suppresses each item starting at the next `audit-open` scan — then records the same items to `STATE.md` under its own `## Deferred Items` heading (a disclosure record, not the suppression mechanism) and closes as `override_closeout`; an all-clear closes as `verified_closeout`. **`audit-open acknowledge` (#3458 follow-up).** Suppresses one open item by writing (or refreshing) a verdict-preserving `audit_acknowledged` marker in the artifact's own frontmatter: ```bash gsd-tools audit-open acknowledge --category --milestone [--at ] ``` `--category` and `--milestone` are always required; `--at` defaults to today. The identifier flags depend on `--category`: | `--category` | Identifier flags | |---------------|-------------------| | `debug_sessions` | `--slug ` | | `threads` | `--slug ` | | `seeds` | `--seed-id ` | | `todos` | `--filename ` | | `quick_tasks` | `--dir ` (the `.planning/quick//` directory name — note this is the ORIGINAL directory name, not the date-stripped `slug` the audit JSON displays) | | `uat_gaps`, `verification_gaps`, `context_questions` | `--phase --file ` [`--archived-milestone `] | | `deferred_items` | `--phase --file --text ` [`--archived-milestone `] | The marker never overwrites the artifact's own `status:` field for the eight frontmatter-marker categories — only `deferred_items` is the deliberate exception, where the marker IS the entry's `status:` field (there is no other meaning for that field on a `deferred-items.md` bullet). The marker also self-invalidates: it snapshots the artifact's current observed state at acknowledgment time — its `status:` for most categories, a composite of `status:` plus its open-scenario count for `uat_gaps` (a status can stay the same while more scenarios go pending), and a content digest of the full question set (not just a count) for `context_questions` (so replacing every question's text while holding the count steady still invalidates the snapshot) — and the item resurfaces on its own the moment that snapshot no longer matches — an edited, reopened, or otherwise-changed artifact is never silently suppressed forever. `--json` output on `audit-open` (the `run` subcommand, default) now reports an `acknowledged` count per category alongside `counts`, plus an `acknowledged.total`, so a clean audit (`counts.total === 0`) can be told apart from one that is clean only because earlier items are still being suppressed (`acknowledged.total > 0`). > **Note:** the `deferred-items.md` category is the per-phase SCOPE BOUNDARY log a phase agent writes when it finds a defect it should not fix. It is a different artifact from the `## Deferred Items` section `[A]` writes into `STATE.md`, which records what you acknowledged at close. > **Truncated-window guard.** Archiving also refuses when the milestone's ROADMAP window is truncated — `Cannot mark milestone complete: the ROADMAP window for "" is truncated`. This is the case where the milestone's heading is found but its section closes before reaching the roadmap's `### Phase N:` region (typically a closed-milestone heading sitting in between), which previously degraded to an over-inclusive filter and archived *every* phase directory in the project rather than the milestone's own. An unreadable ROADMAP.md or a version with no matching section at all are pre-existing, legitimately-handled states and are not refused here. Same override as below: `gsd-tools milestone complete --force`. A window that is genuinely empty — a freshly-declared milestone with no phases yet — is *not* affected and still completes normally. > **Unstarted-phase guard.** Archiving refuses if the milestone's ROADMAP still lists a phase with no phase directory on disk — `Cannot mark milestone complete: ROADMAP lists N unstarted phase(s)`. If a phase was intentionally deferred or merged without a directory, run `gsd-tools milestone complete --force` (the `/gsd-complete-milestone` workflow runs the underlying command without `--force`, so use the CLI directly to override). A `STATE.md` `milestone:` value that does not match `` prints a WARNING and still runs the guard (#2946). > **Sentinel directories stay put.** Moving phase directories into the archive (the default, unless `--no-archive-phases` is passed) now excludes `999.*` (backlog) and `0-*` (pre-milestone) directories via the same sentinel predicate the unstarted-phase guard already uses. Previously the archive move was scoped only by the milestone window, so a sentinel directory sitting inside that window could be archived along with the milestone's own phases. > **Quick-task archival (opt-in, default OFF, #2142).** Unlike phase archival above, quick-task archival does not run unless you say yes — doing nothing leaves `.planning/quick/` untouched. If `.planning/quick/` contains at least one directory, the workflow asks: `Archive completed quick tasks into this milestone too?` with options `Yes — archive quick tasks into v[X.Y]` / `Skip`. Choosing "Yes" passes `--archive-quick` to the underlying `gsd-tools milestone complete` call, which moves every directory under `.planning/quick/` into `.planning/milestones/v[X.Y]-quick/`, (re)writes that directory's `README.md` index (built by scanning the archive directory, not STATE.md), and clears the data rows of STATE.md's `### Quick Tasks Completed` table while preserving its header and column variant. **Known limit:** there is no on-disk record of which milestone a quick task belongs to, so archival buckets **all** remaining `.planning/quick/*` into the one milestone being completed — a task predating an earlier, unarchived milestone lands in the current bucket regardless. See [Archiving quick tasks](how-to/handle-quick-and-fast-tasks.md#archiving-quick-tasks) for the full walkthrough, including the retroactive path. --- ### `/gsd-milestone-summary` Generate comprehensive project summary from milestone artifacts for team onboarding and review. | Argument | Required | Description | |----------|----------|-------------| | `version` | No | Milestone version (defaults to current/latest milestone) | **Prerequisites:** At least one completed or in-progress milestone **Produces:** `.planning/reports/MILESTONE_SUMMARY-v{version}.md` **Summary includes:** - Overview, architecture decisions, phase-by-phase breakdown - Key decisions and trade-offs - Requirements coverage - Tech debt and deferred items - Getting started guide for new team members - Interactive Q&A offered after generation ```bash /gsd-milestone-summary # Summarize current milestone /gsd-milestone-summary v1.0 # Summarize specific milestone ``` --- ### `/gsd-new-milestone` Start next version cycle. | Argument | Required | Description | |----------|----------|-------------| | `name` | No | Milestone name | | `--reset-phase-numbers` | No | Restart the new milestone at Phase 1 and archive old phase dirs before roadmapping | | `--ws ` | No | Scope the milestone to a workstream; skips the shared `PROJECT.md` write | **Prerequisites:** Previous milestone completed **Produces:** Updated `PROJECT.md`, new `REQUIREMENTS.md`, new `ROADMAP.md` ```bash /gsd-new-milestone # Interactive /gsd-new-milestone "v2.0 Mobile" # Named milestone /gsd-new-milestone --reset-phase-numbers "v2.0 Mobile" # Restart milestone numbering at 1 /gsd-new-milestone --ws search "v2.0 Search" # Scope to a workstream ``` --- ## Phase Management Commands ### `/gsd-phase` CRUD for phases in ROADMAP.md — add, insert, remove, or edit phases with a single consolidated command. | Flag | Description | |------|-------------| | (none) | Append a new integer phase to the end of the current milestone | | `--insert ` | Insert urgent work as a decimal phase (e.g., 3.1) after phase N | | `--remove ` | Remove a future phase and renumber subsequent phases | | `--edit ` | Edit any field of an existing phase in place | | `--force` | Allow editing in-progress or completed phases (used with `--edit`) | **Prerequisites:** `.planning/ROADMAP.md` exists **Produces:** Updated ROADMAP.md ```bash /gsd-phase "Add authentication system" # Append new phase with description /gsd-phase --insert 3 "Fix auth race condition" # Insert between phase 3 and 4 → creates 3.1 /gsd-phase --remove 7 # Remove phase 7, renumber 8→7, 9→8, etc. /gsd-phase --edit 5 # Edit any field of phase 5 /gsd-phase --edit 5 --force # Edit phase 5 even if in-progress or completed ``` --- ### `/gsd-mvp-phase` Guided MVP planning for a phase — prompts for a user story, runs SPIDR splitting check, writes `**Mode:** mvp` to ROADMAP.md, then delegates to `/gsd-plan-phase` (which auto-detects MVP mode via the roadmap field). | Argument | Required | Description | |----------|----------|-------------| | `N` | **Yes** | Phase number to convert to MVP mode (integer or decimal like `2.1`) | | Flag | Description | |------|-------------| | `--force` | Allow converting an `in_progress` or `completed` phase | **Prerequisites:** Phase must already exist in ROADMAP.md (created via `/gsd-new-project`, `/gsd-phase`, or `/gsd-phase --insert`). The command does not create new phases — it converts an existing phase. **Behaviour:** Collects a structured user story, validates format, runs a SPIDR splitting check, writes `**Goal:**` and `**Mode:** mvp` to the phase's ROADMAP.md section, then delegates to `/gsd-plan-phase `. See [How to plan an MVP phase](USER-GUIDE.md#mvp-phase-planning) for a walkthrough. **Walking Skeleton:** Auto-triggered when `--mvp` (or `mode: mvp`) is used on Phase 1 of a new project with no prior phase summaries. The planner produces `SKELETON.md` alongside `PLAN.md`. **Produces:** Updated ROADMAP.md, then all artifacts from `/gsd-plan-phase`; `SKELETON.md` when Walking Skeleton mode fires. ```bash /gsd-mvp-phase 1 # MVP planning for phase 1 /gsd-mvp-phase 2.1 # MVP planning for a decimal phase /gsd-mvp-phase 3 --force # Convert phase 3 even if in-progress ``` --- ### `/gsd-validate-phase` Retroactively audit and fill Nyquist validation gaps. | Argument | Required | Description | |----------|----------|-------------| | `N` | No | Phase number | ```bash /gsd-validate-phase 2 # Audit test coverage for phase 2 ``` --- ### `phase uat-passed [--require-verification]` Runtime-neutral predicate that evaluates HUMAN-UAT results for a phase and reports whether all required checks passed. Uses markdown-aware parsing that ignores false-positive contexts (YAML frontmatter, fenced code blocks, HTML comments, and blockquotes), so incomplete checkbox fragments in prose sections never trigger a false pass. | Argument | Required | Description | |----------|----------|-------------| | `N` | **Yes** | Phase number to evaluate | | `--require-verification` | No | Require at least one `*-VERIFICATION.md` file alongside UAT results; fails if none are found | **Output fields (JSON):** | Field | Type | Description | |-------|------|-------------| | `passed` | `boolean` | `true` only when at least one check exists AND all checks pass AND no blockers — fail-closed (no vacuous pass) | | `uat_files` | `string[]` | Filenames of `*-UAT.md` files evaluated | | `verification_files` | `string[]` | Filenames of `*-VERIFICATION.md` files evaluated | | `checks[]` | `{ file, test, name, result, passing }[]` | Per-item evaluation results parsed from heading blocks | | `blockers[]` | `string[]` | Human-readable reasons for failure (frontmatter issues, failing/missing test items, policy violations, malformed markdown) — NOT a subset of `checks[]` | | `no_uat_artifacts` | `boolean` | `true` when no real UAT test items were parsed (no `*-UAT.md` files, unreadable dir, or files with no test blocks); when `true`, `passed` is always `false` | | `policy.require_verification` | `boolean` | Whether `--require-verification` was active | **Programmatic access:** `node gsd-tools.cjs phase uat-passed [--require-verification] [--raw]` — see [CLI Tools Reference](CLI-TOOLS.md) ```bash node gsd-tools.cjs phase uat-passed 3 # Evaluate UAT for phase 3 node gsd-tools.cjs phase uat-passed 3 --require-verification # Also require VERIFICATION.md node gsd-tools.cjs phase uat-passed 3 --raw # Machine-readable JSON output ``` --- ## Navigation Commands ### `/gsd-next` Open the state-aware smart-entry launcher. It reads `.planning/STATE.md`, `ROADMAP.md`, verification artifacts, and git status, classifies the current situation, shows a short menu, then dispatches exactly one existing GSD command. This is a launcher/router only — it never performs project work directly. Detection is handled by `gsd-tools smart-entry --json`; the markdown workflow presents the menu with `AskUserQuestion` or a numbered `--text` fallback. **Situations detected:** no project, paused work, blockers, failed verification, first-phase setup, planning, executing, pending verification, idle stranded work, complete milestone, or unknown state. ```bash /gsd-next # Detect state and route to the best next action ``` ### `/gsd-progress` Show status, next steps, and automatically advance to the next logical workflow step. Reads project state and determines the appropriate action. Use `/gsd-next` when you want an interactive smart-entry menu before dispatch; use `/gsd-progress --next` when you want GSD to advance directly. | Flag | Description | |------|-------------| | `--next` | Automatically advance to the next logical workflow step without manual route selection | | `--next --auto` | Like `--next`, but chains steps automatically until milestone completion or a blocking decision | | `--next --converge` | When the next action is planning, route it through `/gsd-plan-review-convergence`; requires `workflow.plan_review_convergence=true` | | `--cross-ai` | Alias for `--converge` | | Reviewer flags | With `--converge`, pass through every reviewer lane flag: `--gemini`, `--claude`, `--codex`, `--coderabbit`, `--opencode`, `--qwen`, `--cursor`, `--agy` / `--antigravity`, `--ollama`, `--lm-studio`, `--llama-cpp`, `--kimi-code`, `--all`, and `--max-cycles N` | | `--do "task description"` | Analyze freeform intent and dispatch to the most appropriate GSD command | | `--forensic` | Append a 6-check integrity audit after the standard report (STATE consistency, orphaned handoffs, deferred scope drift, memory-flagged pending work, blocking todos, uncommitted code) | > **Milestone name and version.** The milestone this report shows comes from one > implementation shared with `/gsd-stats`, `/gsd-manager` and `roadmap analyze`. > A name is no longer cut short at a parenthesis (`v3.3 — Portability (Windows)` > keeps its full name), a `### Phase N:` heading that mentions a version is never > mistaken for the milestone heading, and a milestone that cannot be identified is > shown as absent rather than as a plausible-looking `v1.0`/`milestone`. See > [CLI-TOOLS.md → Milestone identity](CLI-TOOLS.md#milestone-identity-which-milestone-and-what-it-is-called). **Auto-routing behavior (`--next`):** - No project → suggests `/gsd-new-project` - Phase needs discussion → runs `/gsd-discuss-phase` - Phase needs planning → runs `/gsd-plan-phase` (or `/gsd-plan-review-convergence` when `--converge` is set) - Phase needs execution → runs `/gsd-execute-phase` - Phase needs verification → runs `/gsd-verify-work` - All phases complete → suggests `/gsd-complete-milestone` Status reporting is scoped to the current milestone's `ROADMAP.md` window and sentinel-filtered: `999.*` backlog directories and `0-*` pre-milestone directories are not counted as current-milestone phases, so the reported progress percentage no longer holds at `100` while phases in the active window are still outstanding. > **Nullable percentage.** The reported completion percentage is `null` — never a fabricated `0`, `100`, or stale value — when the current milestone's phase set is not fully readable/scoped. See [CLI-TOOLS.md → A non-COMPLETE scope withholds the percentage entirely](CLI-TOOLS.md#a-non-complete-scope-withholds-the-percentage-entirely-3217). ```bash /gsd-progress # "Where am I? What's next?" with auto-routing /gsd-progress --next # Advance to next step automatically /gsd-progress --next --auto # Chain steps automatically until completion /gsd-progress --next --auto --converge # Hands-free run with plan-review convergence /gsd-progress --do "fix the auth bug" # Dispatch freeform intent to best GSD command /gsd-progress --forensic # Standard report + integrity audit ``` ### `/gsd-resume-work` Restore full context from last session. ```bash /gsd-resume-work # After context reset or new session ``` ### `/gsd-pause-work` Save context handoff when stopping mid-phase. | Flag | Description | |------|-------------| | `--report` | Generate a post-session summary in `.planning/reports/` capturing commits, file changes, and phase progress | ```bash /gsd-pause-work # Creates continue-here.md /gsd-pause-work --report # Creates continue-here.md + session report ``` ### `/gsd-manager` Interactive command center for managing multiple phases from one terminal. **Prerequisites:** `.planning/ROADMAP.md` exists **Behavior:** - Dashboard of all phases with visual status indicators - Recommends optimal next actions based on dependencies and progress - Dispatches work: discuss runs inline; plan/execute run as background agents on runtimes that support nested background dispatch, or inline on Claude Code - Designed for power users parallelizing work across phases from one terminal - Supports per-step passthrough flags via `manager.flags` config (see [Configuration](CONFIGURATION.md#manager-passthrough-flags)) ```bash /gsd-manager # Open command center dashboard /gsd-manager --analyze-deps # Scan ROADMAP phases for dependency relationships before parallel execution ``` **Phase completion is disk-strict (ADR-3180 §7.4, issue #3186).** A phase's status here — and in `roadmap analyze`, `roadmap update-plan-progress`, and `phase complete` — is decided by one rule: a passing `*-VERIFICATION.md` on disk, checked unconditionally (plan count is never a precondition, so a zero-plan phase with a passing verification reports complete). A ticked `- [x]` checkbox in `ROADMAP.md` is a human annotation only; it carries no machine authority and is never consulted for these commands' completion verdicts. `roadmap update-plan-progress` additionally withholds writing the checkbox/completion date while any plan in the phase has no matching `*-SUMMARY.md`, mirroring `phase complete`'s own coverage gate. **Checkpoint Heartbeats (#2410):** Background `execute-phase` runs emit `[checkpoint]` markers at every wave and plan boundary so the Claude API SSE stream never idles long enough to trigger `Stream idle timeout - partial response received` on multi-plan phases. The format is: ``` [checkpoint] phase {N} wave {W}/{M} starting, {count} plan(s), {P}/{Q} plans done [checkpoint] phase {N} wave {W}/{M} plan {plan_id} starting ({P}/{Q} plans done) [checkpoint] phase {N} wave {W}/{M} plan {plan_id} complete ({P}/{Q} plans done) [checkpoint] phase {N} wave {W}/{M} complete, {P}/{Q} plans done ({ok}/{count} ok) ``` If a background phase fails partway through, grep the transcript for `[checkpoint]` to see the last confirmed boundary. The manager's background-completion handler uses these markers to report partial progress when an agent errors out. **Manager Passthrough Flags:** Configure per-step flags in `.planning/config.json` under `manager.flags`. These flags are appended to each dispatched command: ```json { "manager": { "flags": { "discuss": "--auto", "plan": "--skip-research", "execute": "--cross-ai" } } } ``` --- ### `/gsd-help` Show GSD commands at the tier you ask for. Default fits one screen; `--full` is the complete reference; `` jumps directly to one section. ```bash /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 # One section only (e.g. /gsd-help debug) /gsd-help --brief # Compact scoped lookup — signature + one-line summary ``` See `gsd-core/workflows/help/modes/topic.md` for the full alias table. Unknown topics print the recognized list. --- ## Utility Commands ### `/gsd-explore` Socratic ideation session — guide an idea through probing questions, optionally spawn research, then route output to the right GSD artifact (notes, todos, seeds, research questions, requirements, or a new phase). | Argument | Required | Description | |----------|----------|-------------| | `topic` | No | Topic to explore (e.g., `/gsd-explore authentication strategy`) | ```bash /gsd-explore # Open-ended ideation session /gsd-explore authentication strategy # Explore a specific topic ``` When the optional research pass runs, each surfaced claim is dispositioned three ways — **admit** (survives a prompted-to-refute pass and is grounded in a source, shown with the source), **refute** (a source *authoritative for that claim* contradicts it, dropped or corrected), or **abstain** (unverifiable, non-authoritative disagreement, or a source-vs-prior conflict). Abstained claims are listed in a separate **Unresolved** ledger rather than smoothed into the narrative. (Claims-side analogue of the honest verifier, #1154.) --- ### `/gsd-undo` Safe git revert — roll back GSD phase or plan commits using the phase manifest with dependency checks and a confirmation gate. | Flag | Required | Description | |------|----------|-------------| | `--last N` | (one of three required) | Show recent GSD commits for interactive selection | | `--phase NN` | (one of three required) | Revert all commits for a phase | | `--plan NN-MM` | (one of three required) | Revert all commits for a specific plan | **Safety:** Checks dependent phases/plans before reverting; always shows a confirmation gate. ```bash /gsd-undo --last 5 # Pick from the 5 most recent GSD commits /gsd-undo --phase 03 # Revert all commits for phase 3 /gsd-undo --plan 03-02 # Revert commits for plan 02 of phase 3 ``` --- ### `/gsd-import` Ingest an external plan file into the GSD planning system with conflict detection against `PROJECT.md` decisions before writing anything. | Flag | Required | Description | |------|----------|--------------| | `--from ` | Yes (or `--from-gsd2`) | Path to the external plan file to import | | `--from-gsd2` | Yes (or `--from`) | Reverse-migrate a GSD-2 (`.gsd/`) project back to GSD v1 (`.planning/`) format | | `--path ` | No | With `--from-gsd2`: path to the GSD-2 project directory (defaults to current directory) | **Process:** Detects conflicts → prompts for resolution → writes as GSD PLAN.md → validates via `gsd-plan-checker` ```bash /gsd-import --from /tmp/team-plan.md # Import and validate an external plan /gsd-import --from-gsd2 # Migrate from GSD-2 back to v1 (current dir) /gsd-import --from-gsd2 --path ~/old-project # Migrate from a different path ``` --- ### `/gsd-ingest-docs` Bootstrap or merge a .planning/ setup from existing ADRs, PRDs, SPECs, and docs in a repo. Runs parallel classification (`gsd-doc-classifier`) plus synthesis with precedence rules and cycle detection (`gsd-doc-synthesizer`). Produces a three-bucket conflicts report (`INGEST-CONFLICTS.md`: auto-resolved, competing-variants, unresolved-blockers) and hard-blocks on LOCKED-vs-LOCKED ADR contradictions. | Argument / Flag | Required | Description | |-----------------|----------|-------------| | `path` | No | Target directory to scan (defaults to repo root) | | `--mode new\|merge` | No | Override auto-detect (defaults: `new` if `.planning/` absent, `merge` if present) | | `--manifest ` | No | YAML file listing `{path, type, precedence?}` per doc; overrides heuristic classification | | `--resolve auto` | No | Conflict resolution mode (v1: only `auto`; `interactive` is reserved) | **Limits:** v1 caps at 50 docs per invocation. Extracts the shared conflict-detection contract into `references/doc-conflict-engine.md`, which `/gsd-import` also consumes. ```bash /gsd-ingest-docs # Scan repo root, auto-detect mode /gsd-ingest-docs docs/ # Only ingest under docs/ /gsd-ingest-docs --manifest ingest.yaml # Explicit precedence manifest ``` --- ### `/gsd-quick` Execute ad-hoc task with GSD guarantees. | Flag | Description | |------|-------------| | `--full` | Enable the complete quality pipeline — discussion + research + plan-checking + verification | | `--validate` | Plan-checking (max 2 iterations) + post-execution verification only; no discussion or research | | `--discuss` | Lightweight pre-planning discussion | | `--research` | Spawn focused researcher before planning | Granular flags are composable: `--discuss --research --validate` is equivalent to `--full`. | Subcommand | Description | |------------|-------------| | `list` | List all quick tasks with status | | `status ` | Show status of a specific quick task | | `resume ` | Resume a specific quick task by slug | ```bash /gsd-quick # Basic quick task /gsd-quick --discuss --research # Discussion + research + planning /gsd-quick --validate # Plan-checking + verification only /gsd-quick --full # Complete quality pipeline /gsd-quick list # List all quick tasks /gsd-quick status my-task-slug # Show status of a quick task /gsd-quick resume my-task-slug # Resume a quick task ``` ### `/gsd-autonomous` Run all remaining phases autonomously. | Flag | Description | |------|-------------| | `--from N` | Start from a specific phase number | | `--to N` | Stop after completing a specific phase number | | `--only N` | Restrict execution to phase N; lifecycle step is skipped | | `--interactive` | Lean context with user input | | `--converge` | Route each planning step through `/gsd-plan-review-convergence`; requires `workflow.plan_review_convergence=true` | | `--cross-ai` | Alias for `--converge` | | Reviewer flags | With `--converge`, pass through every reviewer lane flag: `--gemini`, `--claude`, `--codex`, `--coderabbit`, `--opencode`, `--qwen`, `--cursor`, `--agy` / `--antigravity`, `--ollama`, `--lm-studio`, `--llama-cpp`, `--kimi-code`, `--all`, and `--max-cycles N` | | `--text` | Replace `AskUserQuestion` prompts with plain numbered lists | ```bash /gsd-autonomous # Run all remaining phases /gsd-autonomous --from 3 # Start from phase 3 /gsd-autonomous --to 5 # Run up to and including phase 5 /gsd-autonomous --from 3 --to 5 # Run phases 3 through 5 /gsd-autonomous --only 4 # Run only phase 4 /gsd-autonomous --only 4 --converge # Run one phase with plan convergence /gsd-autonomous --converge --all --max-cycles 5 /gsd-autonomous --text # Run with text-mode prompts ``` ### `/gsd-debug` Systematic debugging with persistent state. | Argument | Required | Description | |----------|----------|-------------| | `description` | No | Description of the bug | | Flag | Description | |------|-------------| | `--diagnose` | Diagnosis-only mode — investigate without attempting fixes | **Subcommands:** - `/gsd-debug list` — List all active debug sessions with status, hypothesis, and next action - `/gsd-debug status ` — Print full summary of a session (Evidence count, Eliminated count, Resolution, TDD checkpoint) without spawning an agent - `/gsd-debug continue ` — Resume a specific session by slug (surfaces Current Focus then spawns continuation agent) - `/gsd-debug [--diagnose] ` — Start new debug session (existing behavior; `--diagnose` stops at root cause without applying fix) **TDD mode:** When `tdd_mode: true` in `.planning/config.json`, debug sessions require a failing test to be written and verified before any fix is applied (red → green → done). ```bash /gsd-debug "Login button not responding on mobile Safari" /gsd-debug --diagnose "Intermittent 500 errors on /api/users" /gsd-debug list /gsd-debug status auth-token-null /gsd-debug continue form-submit-500 ``` ### `/gsd-add-tests` Generate tests for a completed phase. | Argument | Required | Description | |----------|----------|-------------| | `N` | No | Phase number | ```bash /gsd-add-tests 2 # Generate tests for phase 2 ``` ### `/gsd-stats` Display project statistics. ```bash /gsd-stats # Project metrics dashboard ``` Scoped to the current milestone's `ROADMAP.md` window and sentinel-filtered: `999.*` backlog directories and `0-*` pre-milestone directories are not counted as current-milestone phases. > **Nullable percentage.** The reported completion percentage is `null` — never a fabricated `0`, `100`, or stale value — when the current milestone's phase set is not fully readable/scoped (e.g. a truncated or unresolvable milestone window, or an unreadable `.planning/phases` directory). See [CLI-TOOLS.md → A non-COMPLETE scope withholds the percentage entirely](CLI-TOOLS.md#a-non-complete-scope-withholds-the-percentage-entirely-3217). ### `/gsd-profile-user` Generate a developer behavioral profile from Claude Code session analysis across 8 dimensions (communication style, decision patterns, debugging approach, UX preferences, vendor choices, frustration triggers, learning style, explanation depth). Produces artifacts that personalize Claude's responses. | Flag | Description | |------|-------------| | `--questionnaire` | Use interactive questionnaire instead of session analysis | | `--refresh` | Re-analyze sessions and regenerate profile | **Generated artifacts:** - `USER-PROFILE.md` — Full behavioral profile - `CLAUDE.md` profile section — Auto-discovered by Claude Code ```bash /gsd-profile-user # Analyze sessions and build profile /gsd-profile-user --questionnaire # Interactive questionnaire fallback /gsd-profile-user --refresh # Re-generate from fresh analysis ``` ### `/gsd-health` Validate `.planning/` directory integrity. With `--context`, probes the context-window utilization guard against the 60 % / 70 % thresholds (added v1.40.0, [#2792](https://github.com/open-gsd/gsd-core/issues/2792)). | Flag | Description | |------|-------------| | `--repair` | Auto-fix recoverable issues | | `--backfill` | Synthesize missing MILESTONES.md entries from `.planning/milestones/vX.Y-ROADMAP.md` snapshots | | `--context` | Probe context-window utilization; warns at 60 %, critical at 70 % | ```bash /gsd-health # Check integrity /gsd-health --repair # Check and fix /gsd-health --backfill # Backfill missing MILESTONES.md entries /gsd-health --context # Context-utilization triage ``` **STATE.md freshness (`W024`).** STATE.md records the commit it was last written against (`state_head` in its frontmatter). When the codebase has moved a long way since — 20 commits or more — health adds an advisory noting that STATE.md's contents should be treated as approximate. This is a *freshness proxy, not a drift measurement*: the count includes commits that never touched anything STATE.md describes, and the stamp is refreshed by any command that writes STATE.md, so a low count means STATE.md was written recently rather than that its contents are correct. The advisory never changes health's pass/fail status, and stays silent when the stamp is absent or the project isn't a git repo — "unknown" is reported as unknown, not as fresh. **Cross-scope install shadowing (`W028`).** When a runtime is installed at both `global` and `local` scope and the host's trigger-resolution rules make one scope's `/gsd-*` surface unreachable — the Claude Code case: personal skill always beats project command — health adds a WARNING-severity advisory naming the shadowed triggers, the winning scope, and the losing scope. It never changes health's pass/fail status and is never auto-fixable (there is no single correct scope to remove), so `--repair` never touches it. Identical to the same advisory GSD Core prints at install time. See [Interpret install-shadow warnings](how-to/interpret-install-shadow-warnings.md). **`--repair` does not apply destructive fixes.** Resetting config.json (`resetConfig`) and regenerating STATE.md (`regenerateState`) are destructive — the former loses custom settings, the latter loses session history — so `--repair` reports these fixes as available but never applies them automatically; the suggested command must be run by hand (ADR-3180, [#3309](https://github.com/open-gsd/gsd-core/issues/3309)). The same migration split two previously-conflated diagnostic codes: `W021` now covers only the phase-id-convention mismatch, with the STATE-vs-ROADMAP milestone-complete mismatch it used to also report moving to the new `W026`; likewise `W017` now covers only orphan worktrees, with the stale-worktree case moving to the new `W027`. ### `/gsd-cleanup` Archive accumulated phase directories from completed milestones, prune local branches whose upstream has been deleted, and — when applicable — retroactively archive quick tasks (#2142). **Behaviour:** Presents a dry-run summary of phase directories to archive (moved from `.planning/phases/` into `.planning/milestones/v{X.Y}-phases/`) and local branches whose upstream is gone (pruned via `git fetch --prune`). Requires confirmation before writing any changes. The currently checked-out branch is never pruned. **Retroactive quick-task archival (opt-in, #2142).** When `.planning/quick/` contains at least one directory, `/gsd-cleanup` additionally offers to sweep it: `Archive ALL {N} quick-task directories into v{X.Y} — {Milestone Name}? This buckets every remaining quick task into this ONE milestone; there is no way to split them per-milestone.` with options `Yes — archive quick tasks into v{X.Y}` / `Skip`. The target is the single most recent completed milestone (from `MILESTONES.md`) that does not yet have a `v{X.Y}-quick` archive directory. If `.planning/quick/` is empty, this step is not offered at all. Confirming calls the narrower `gsd-tools milestone archive-quick ` command — the same move/README-index/table-reset logic `/gsd-complete-milestone`'s `--archive-quick` uses, but without touching `ROADMAP.md`, `REQUIREMENTS.md`, `MILESTONES.md`, or milestone-completion guards, since `/gsd-cleanup` typically targets a milestone that is already closed. See [Archiving quick tasks](how-to/handle-quick-and-fast-tasks.md#archiving-quick-tasks) for the full walkthrough and the silent/failure cases. ```bash /gsd-cleanup ``` --- ## Spiking & Sketching Commands ### `/gsd-spike` Run 2–5 focused feasibility experiments before committing to an implementation approach. Each experiment uses Given/When/Then framing, produces executable code, and returns a VALIDATED / INVALIDATED / PARTIAL verdict. | Argument | Required | Description | |----------|----------|-------------| | `idea` | No | The technical question or approach to investigate | | `--quick` | No | Skip intake conversation; use `idea` text directly | | `--wrap-up` | No | Package completed spike findings into a reusable project-local skill | **Produces:** `.planning/spikes/NNN-experiment-name/` with code, results, and README; `.planning/spikes/MANIFEST.md` **`--wrap-up` produces:** `.claude/skills/spike-findings-[project]/` skill file ```bash /gsd-spike # Interactive intake /gsd-spike "can we stream LLM tokens through SSE" /gsd-spike --quick websocket-vs-polling /gsd-spike --wrap-up # Package findings into a reusable skill ``` --- ### `/gsd-sketch` Explore design directions through throwaway HTML mockups before committing to implementation. Produces 2–3 variants per design question for direct browser comparison. | Argument | Required | Description | |----------|----------|-------------| | `idea` | No | The UI design question or direction to explore | | `--quick` | No | Skip mood intake; use `idea` text directly | | `--text` | No | Text-mode fallback — replace interactive prompts with numbered lists (for non-Claude runtimes) | | `--wrap-up` | No | Package winning sketch decisions into a reusable project-local skill | **Produces:** `.planning/sketches/NNN-descriptive-name/index.html` (2–3 interactive variants), `README.md`, shared `themes/default.css`; `.planning/sketches/MANIFEST.md` **`--wrap-up` produces:** `.claude/skills/sketch-findings-[project]/` skill file ```bash /gsd-sketch # Interactive mood intake /gsd-sketch "dashboard layout" /gsd-sketch --quick "sidebar navigation" /gsd-sketch --text "onboarding flow" # Non-Claude runtime /gsd-sketch --wrap-up # Package winning sketch into a skill ``` --- ## Diagnostics Commands ### `/gsd-forensics` Post-mortem investigation for failed GSD workflows — diagnoses what went wrong. | Argument | Required | Description | |----------|----------|-------------| | `description` | No | Problem description (prompted if omitted) | **Prerequisites:** `.planning/` directory exists **Produces:** `.planning/forensics/report-{timestamp}.md` **Investigation covers:** - Git history analysis (recent commits, stuck patterns, time gaps) - Artifact integrity (expected files for completed phases) - STATE.md anomalies and session history - Uncommitted work, conflicts, abandoned changes - At least 4 anomaly types checked (stuck loop, missing artifacts, abandoned work, crash/interruption) - GitHub issue creation offered if actionable findings exist ```bash /gsd-forensics # Interactive — prompted for problem /gsd-forensics "Phase 3 execution stalled" # With problem description ``` --- ### `/gsd-extract-learnings` Extract reusable patterns, anti-patterns, and architectural decisions from completed phase work. | Argument | Required | Description | |----------|----------|-------------| | `N` | **Yes** | Phase number to extract learnings from | | Flag | Description | |------|-------------| | `--all` | Extract learnings from all completed phases | | `--format` | Output format: `markdown` (default), `json` | **Prerequisites:** Phase has been executed (SUMMARY.md files exist) **Produces:** `.planning/learnings/{phase}-LEARNINGS.md` **Extracts:** - Architectural decisions and their rationale - Patterns that worked well (reusable in future phases) - Anti-patterns encountered and how they were resolved - Technology-specific insights - Performance and testing observations ```bash /gsd-extract-learnings 3 # Extract learnings from phase 3 /gsd-extract-learnings --all # Extract from all completed phases ``` --- ### `gsd-tools check verify-command-paths` Deterministic resolvability probe over a phase's `` verify commands (#2401). Run automatically by `/gsd-plan-phase` before the plan-check pass and handed to `gsd-plan-checker`; runnable by hand to see what the checker saw. | Argument | Required | Description | |----------|----------|-------------| | `N` | **Yes** | Phase number whose `-PLAN.md` files are probed | | Flag | Description | |------|-------------| | `--raw` | Emit the JSON payload with no surrounding prose | **Prerequisites:** none — an unresolvable phase degrades to a JSON payload with `readError` set rather than failing. **Produces:** JSON on stdout. Nothing is written to disk. **It never executes command text.** PLAN.md is LLM-authored, so the probe only resolves paths and stats directories; a `package.json` it finds is read for script *names* only. It grounds exactly two forms — a leading `cd ` chain and `npm --prefix ` — and refuses to guess at anything else. `pushd`, `make -C`, `yarn --cwd`, `pnpm -C`, and `cargo --manifest-path` are not recognized today and report `unresolvable`. Each row of `commands` carries `command`, `plan`, `task`, `status`, `severity`, `reason`, `form`, `rawTarget`, `target`, `manifest`, `script`, `sentinel`, and `base`. There is deliberately **no** `suggestion` field — the probe reports what failed to resolve and leaves the replacement to the planner. | `status` | Meaning | |---|---| | `ok` | Target resolved (a `reason` may still carry an advisory — see below) | | `broken` | Target does not resolve, or holds no required manifest — **blocker** | | `unresolvable` | The path could not be grounded (variable, glob, substitution, `~`) — warning | | `pending_creation` | An earlier task in this phase creates the target — not a finding | | `not_applicable` | No `cd`/`--prefix` to resolve, or a Nyquist `MISSING …` sentinel | | `reason` | `severity` | What it means | |---|---|---| | `missing_dir` | `blocker` | The resolved directory does not exist, or is not a directory | | `no_manifest` | `blocker` | The directory exists but holds no `package.json` / `Makefile` the command needs | | `dynamic_path` | `warning` | The path contains `$`, a backtick, `*`, `?`, or `~` — refused, not guessed | | `outside_root` | `warning` | A bare ancestor climb (`cd ../..`); the base differs under worktree execution | | `script_missing` | `warning` | `npm run