diff --git a/CHANGELOG.md b/CHANGELOG.md index dd784c684..3bed2b3c0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ### Added - **`/gsd-ingest-docs` command** — Scan a repo containing mixed ADRs, PRDs, SPECs, and DOCs and bootstrap or merge the full `.planning/` setup from them in a single pass. Parallel classification (`gsd-doc-classifier`), synthesis with precedence rules and cycle detection (`gsd-doc-synthesizer`), three-bucket conflicts report (`INGEST-CONFLICTS.md`: auto-resolved, competing-variants, unresolved-blockers), and hard-block on LOCKED-vs-LOCKED ADR contradictions in both new and merge modes. Supports directory-convention discovery and `--manifest ` YAML override with per-doc precedence. v1 caps at 50 docs per invocation; `--resolve interactive` is reserved. Extracts shared conflict-detection contract into `references/doc-conflict-engine.md` which `/gsd-import` now also consumes (#2387) +- **`/gsd-plan-review-convergence` command** — Cross-AI plan convergence loop that automates `plan-phase → review → replan → re-review` cycles. Spawns isolated agents for `gsd-plan-phase` and `gsd-review`; orchestrator only does loop control, HIGH concern counting, stall detection, and escalation. Supports `--codex`, `--gemini`, `--claude`, `--opencode`, `--all` reviewers and `--max-cycles N` (default 3). Loop exits when no HIGH concerns remain; stall detection warns when count isn't decreasing; escalation gate asks user to proceed or review manually when max cycles reached (#2306) ### Fixed - **`gsd-read-injection-scanner` hook now ships to users** — the scanner was added in 1.37.0 (#2201) but was never added to `scripts/build-hooks.js`' `HOOKS_TO_COPY` allowlist, so it never landed in `hooks/dist/` and `install.js` skipped it with "Skipped read injection scanner hook — gsd-read-injection-scanner.js not found at target". Effectively disabled the read-time prompt-injection scanner for every user on 1.37.0/1.37.1. Added to the build allowlist and regression test. Also dropped a redundant non-absolute `.claude/hooks/` path check that was bypassing the installer's runtime-path templating and leaking `.claude/` references into non-Claude installs (#2406) diff --git a/commands/gsd/plan-review-convergence.md b/commands/gsd/plan-review-convergence.md new file mode 100644 index 000000000..aeba824e7 --- /dev/null +++ b/commands/gsd/plan-review-convergence.md @@ -0,0 +1,52 @@ +--- +name: gsd:plan-review-convergence +description: "Cross-AI plan convergence loop — replan with review feedback until no HIGH concerns remain (max 3 cycles)" +argument-hint: " [--codex] [--gemini] [--claude] [--opencode] [--text] [--ws ] [--all] [--max-cycles N]" +allowed-tools: + - Read + - Write + - Bash + - Glob + - Grep + - Agent + - AskUserQuestion +--- + + +Cross-AI plan convergence loop — an outer revision gate around gsd-review and gsd-planner. +Repeatedly: review plans with external AI CLIs → if HIGH concerns found → replan with --reviews feedback → re-review. Stops when no HIGH concerns remain or max cycles reached. + +**Flow:** Agent→Skill("gsd-plan-phase") → Agent→Skill("gsd-review") → check HIGHs → Agent→Skill("gsd-plan-phase --reviews") → Agent→Skill("gsd-review") → ... → Converge or escalate + +Replaces gsd-plan-phase's internal gsd-plan-checker with external AI reviewers (codex, gemini, etc.). Each step runs inside an isolated Agent that calls the corresponding existing Skill — orchestrator only does loop control. + +**Orchestrator role:** Parse arguments, validate phase, spawn Agents for existing Skills, check HIGHs, stall detection, escalation gate. + + + +@$HOME/.claude/get-shit-done/workflows/plan-review-convergence.md +@$HOME/.claude/get-shit-done/references/revision-loop.md +@$HOME/.claude/get-shit-done/references/gates.md +@$HOME/.claude/get-shit-done/references/agent-contracts.md + + + +**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`. They are equivalent — `vscode_askquestions` is the VS Code Copilot implementation of the same interactive question API. Do not skip questioning steps because `AskUserQuestion` appears unavailable; use `vscode_askquestions` instead. + + + +Phase number: extracted from $ARGUMENTS (required) + +**Flags:** +- `--codex` — Use Codex CLI as reviewer (default if no reviewer specified) +- `--gemini` — Use Gemini CLI as reviewer +- `--claude` — Use Claude CLI as reviewer (separate session) +- `--opencode` — Use OpenCode as reviewer +- `--all` — Use all available CLIs +- `--max-cycles N` — Maximum replan→review cycles (default: 3) + + + +Execute the plan-review-convergence workflow from @$HOME/.claude/get-shit-done/workflows/plan-review-convergence.md end-to-end. +Preserve all workflow gates (pre-flight, revision loop, stall detection, escalation). + diff --git a/docs/AGENTS.md b/docs/AGENTS.md index e8b945347..585235841 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -1,6 +1,6 @@ # GSD Agent Reference -> All 21 specialized agents — roles, tools, spawn patterns, and relationships. For architecture context, see [Architecture](ARCHITECTURE.md). +> Full role cards for 21 primary agents plus concise stubs for 10 advanced/specialized agents (31 shipped agents total). The `agents/` directory and [`docs/INVENTORY.md`](INVENTORY.md) are the authoritative roster; see [Architecture](ARCHITECTURE.md) for context. --- @@ -10,6 +10,8 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp ### Agent Categories +> The table below covers the **21 primary agents** detailed in this section. Ten additional shipped agents (pattern-mapper, debug-session-manager, code-reviewer, code-fixer, ai-researcher, domain-researcher, eval-planner, eval-auditor, framework-selector, intel-updater) have concise stubs in the [Advanced and Specialized Agents](#advanced-and-specialized-agents) section below. For the authoritative 31-agent roster, see [`docs/INVENTORY.md`](INVENTORY.md) and the `agents/` directory. + | Category | Count | Agents | |----------|-------|--------| | Researchers | 3 | project-researcher, phase-researcher, ui-researcher | @@ -468,8 +470,252 @@ Communication style, decision patterns, debugging approach, UX preferences, vend --- +## Advanced and Specialized Agents + +Ten additional agents ship under `agents/gsd-*.md` and are used by specialty workflows (`/gsd-ai-integration-phase`, `/gsd-eval-review`, `/gsd-code-review`, `/gsd-code-review-fix`, `/gsd-debug`, `/gsd-intel`, `/gsd-select-framework`) and by the planner pipeline. Each carries full frontmatter in its agent file; the stubs below are concise by design. The authoritative roster (with spawner and primary-doc status per agent) lives in [`docs/INVENTORY.md`](INVENTORY.md). + +### gsd-pattern-mapper + +**Role:** Read-only codebase analysis that maps files-to-be-created or modified to their closest existing analogs, producing `PATTERNS.md` for the planner to consume. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd-plan-phase` (between research and planning) | +| **Parallelism** | Single instance | +| **Tools** | Read, Bash, Glob, Grep, Write | +| **Model (balanced)** | Sonnet | +| **Color** | Magenta | +| **Produces** | `PATTERNS.md` in the phase directory | + +**Key behaviors:** +- Extracts file list from CONTEXT.md and RESEARCH.md; classifies each by role (controller, component, service, model, middleware, utility, config, test) and data flow (CRUD, streaming, file I/O, event-driven, request-response) +- Searches for the closest existing analog per file and extracts concrete code excerpts (imports, auth patterns, core pattern, error handling) +- Strictly read-only against source; only writes `PATTERNS.md` + +--- + +### gsd-debug-session-manager + +**Role:** Runs the full `/gsd-debug` checkpoint-and-continuation loop in an isolated context so the orchestrator's main context stays lean; spawns `gsd-debugger` agents, dispatches specialist skills, and handles user checkpoints via AskUserQuestion. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd-debug` | +| **Parallelism** | Single instance (interactive, stateful) | +| **Tools** | Read, Write, Bash, Grep, Glob, Task, AskUserQuestion | +| **Model (balanced)** | Sonnet | +| **Color** | Orange | +| **Produces** | Compact summary returned to main context; evolves the `.planning/debug/{slug}.md` session file | + +**Key behaviors:** +- Reads the debug session file first; passes file paths (not inlined contents) to spawned agents to respect context budget +- Treats all user-supplied AskUserQuestion content as data-only, wrapped in DATA_START/DATA_END markers +- Coordinates TDD gates and reasoning checkpoints introduced in v1.36.0 + +--- + +### gsd-code-reviewer + +**Role:** Reviews source files for bugs, security vulnerabilities, and code-quality problems; produces a structured `REVIEW.md` with severity-classified findings. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd-code-review` | +| **Parallelism** | Typically single instance per review scope | +| **Tools** | Read, Write, Bash, Grep, Glob | +| **Model (balanced)** | Sonnet | +| **Color** | `#F59E0B` (amber) | +| **Produces** | `REVIEW.md` in the phase directory | + +**Key behaviors:** +- Detects bugs (logic errors, null/undefined checks, off-by-one, type mismatches, unreachable code), security issues (injection, XSS, hardcoded secrets, insecure crypto), and quality issues +- Honors `CLAUDE.md` project conventions and `.claude/skills/` / `.agents/skills/` rules when present +- Read-only against implementation source — never modifies code under review + +--- + +### gsd-code-fixer + +**Role:** Applies fixes to findings from `REVIEW.md` with intelligent (non-blind) patching and atomic per-fix commits; produces `REVIEW-FIX.md`. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd-code-review-fix` | +| **Parallelism** | Single instance | +| **Tools** | Read, Edit, Write, Bash, Grep, Glob | +| **Model (balanced)** | Sonnet | +| **Color** | `#10B981` (emerald) | +| **Produces** | `REVIEW-FIX.md`; one atomic git commit per applied fix | + +**Key behaviors:** +- Treats `REVIEW.md` suggestions as guidance, not a patch to apply literally +- Commits each fix atomically so review and rollback stay granular +- Honors `CLAUDE.md` and project-skill rules during fixes + +--- + +### gsd-ai-researcher + +**Role:** Researches a chosen AI/LLM framework's official documentation and distills it into implementation-ready guidance — framework quick reference, patterns, and pitfalls — for the Section 3–4b body of `AI-SPEC.md`. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd-ai-integration-phase` | +| **Parallelism** | Single instance (sequential with domain-researcher / eval-planner) | +| **Tools** | Read, Write, Bash, Grep, Glob, WebFetch, WebSearch, mcp (context7) | +| **Model (balanced)** | Sonnet | +| **Color** | `#34D399` (green) | +| **Produces** | Sections 3–4b of `AI-SPEC.md` (framework quick reference + implementation guidance) | + +**Key behaviors:** +- Uses Context7 MCP when available; falls back to the `ctx7` CLI via Bash when MCP tools are stripped from the agent +- Anchors guidance to the specific use case, not generic framework overviews + +--- + +### gsd-domain-researcher + +**Role:** Surfaces the business-domain and real-world evaluation context for an AI system — expert rubric ingredients, failure modes, regulatory context — before the eval-planner turns it into measurable rubrics. Writes Section 1b of `AI-SPEC.md`. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd-ai-integration-phase` | +| **Parallelism** | Single instance | +| **Tools** | Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) | +| **Model (balanced)** | Sonnet | +| **Color** | `#A78BFA` (violet) | +| **Produces** | Section 1b of `AI-SPEC.md` | + +**Key behaviors:** +- Researches the domain, not the technical framework — its output feeds the eval-planner downstream +- Produces rubric ingredients that downstream evaluators can turn into measurable criteria + +--- + +### gsd-eval-planner + +**Role:** Designs the structured evaluation strategy for an AI phase — failure modes, eval dimensions with rubrics, tooling, reference dataset, guardrails, production monitoring. Writes Sections 5–7 of `AI-SPEC.md`. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd-ai-integration-phase` | +| **Parallelism** | Single instance (sequential after domain-researcher) | +| **Tools** | Read, Write, Bash, Grep, Glob, AskUserQuestion | +| **Model (balanced)** | Sonnet | +| **Color** | `#F59E0B` (amber) | +| **Produces** | Sections 5–7 of `AI-SPEC.md` (Evaluation Strategy, Guardrails, Production Monitoring) | + +**Required reading:** `get-shit-done/references/ai-evals.md` (evaluation framework). + +**Key behaviors:** +- Turns domain-researcher rubric ingredients into measurable, tooled evaluation criteria +- Does not re-derive domain context — reads Section 1 and 1b of `AI-SPEC.md` as established input + +--- + +### gsd-eval-auditor + +**Role:** Retroactive audit of an implemented AI phase's evaluation coverage against its planned `AI-SPEC.md` eval strategy. Scores each eval dimension `COVERED` / `PARTIAL` / `MISSING` and produces `EVAL-REVIEW.md`. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd-eval-review` | +| **Parallelism** | Single instance | +| **Tools** | Read, Write, Bash, Grep, Glob | +| **Model (balanced)** | Sonnet | +| **Color** | `#EF4444` (red) | +| **Produces** | `EVAL-REVIEW.md` with dimension scores, findings, and remediation guidance | + +**Required reading:** `get-shit-done/references/ai-evals.md`. + +**Key behaviors:** +- Compares the implemented codebase against the planned eval strategy — never re-plans +- Reads implementation files incrementally to respect context budget + +--- + +### gsd-framework-selector + +**Role:** Interactive decision-matrix agent that runs a ≤6-question interview, scores candidate AI/LLM frameworks, and returns a ranked recommendation with rationale. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd-ai-integration-phase`, `/gsd-select-framework` | +| **Parallelism** | Single instance (interactive) | +| **Tools** | Read, Bash, Grep, Glob, WebSearch, AskUserQuestion | +| **Model (balanced)** | Sonnet | +| **Color** | `#38BDF8` (sky blue) | +| **Produces** | Scored ranked recommendation (structured return to orchestrator) | + +**Required reading:** `get-shit-done/references/ai-frameworks.md` (decision matrix). + +**Key behaviors:** +- Scans `package.json`, `pyproject.toml`, `requirements*.txt` for existing AI libraries before the interview to avoid recommending a rejected framework +- Asks only what the codebase scan and CONTEXT.md have not already answered + +--- + +### gsd-intel-updater + +**Role:** Reads project source and writes structured intel (JSON + Markdown) into `.planning/intel/`, building a queryable codebase knowledge base that other agents use instead of performing expensive fresh exploration. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd-intel` (refresh / update flows) | +| **Parallelism** | Single instance | +| **Tools** | Read, Write, Bash, Glob, Grep | +| **Model (balanced)** | Sonnet | +| **Color** | Cyan | +| **Produces** | `.planning/intel/*.json` (and companion Markdown) consumed by `gsd-sdk query intel` | + +**Key behaviors:** +- Writes current state only — no temporal language, every claim references an actual file path +- Uses Glob / Read / Grep for cross-platform correctness; Bash is reserved for `gsd-sdk query intel` CLI calls + +--- + +### gsd-doc-classifier + +**Role:** Classifies a single planning document as ADR, PRD, SPEC, DOC, or UNKNOWN. Extracts title, scope summary, and cross-references. Writes a JSON classification file used by `gsd-doc-synthesizer` to build a consolidated context. + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd-ingest-docs` (parallel fan-out over the doc corpus) | +| **Parallelism** | One instance per input document | +| **Tools** | Read, Write, Grep, Glob | +| **Model (balanced)** | Haiku | +| **Color** | Yellow | +| **Produces** | One JSON classification file per input doc (type, title, scope, refs) | + +**Key behaviors:** +- Single-doc scope — never synthesizes or resolves conflicts (that is the synthesizer's job) +- Heuristic-first classification; returns UNKNOWN when the doc lacks type signals rather than guessing + +--- + +### gsd-doc-synthesizer + +**Role:** Synthesizes classified planning docs into a single consolidated context. Applies precedence rules, detects cross-reference cycles, enforces LOCKED-vs-LOCKED hard-blocks, and writes `INGEST-CONFLICTS.md` with three buckets (auto-resolved, competing-variants, unresolved-blockers). + +| Property | Value | +|----------|-------| +| **Spawned by** | `/gsd-ingest-docs` (after classifier fan-in) | +| **Parallelism** | Single instance | +| **Tools** | Read, Write, Grep, Glob, Bash | +| **Model (balanced)** | Sonnet | +| **Color** | Orange | +| **Produces** | Consolidated context for `.planning/` plus `INGEST-CONFLICTS.md` report | + +**Key behaviors:** +- Hard-blocks on LOCKED-vs-LOCKED ADR contradictions instead of silently picking a winner +- Follows the `references/doc-conflict-engine.md` contract so `/gsd-import` and `/gsd-ingest-docs` produce consistent conflict reports + +--- + ## Agent Tool Permissions Summary +> **Scope:** this table covers the 21 primary agents only. The 12 advanced/specialized agents listed above carry their own tool surfaces in their `agents/gsd-*.md` frontmatter (summarized in the per-agent stubs above and in [`docs/INVENTORY.md`](INVENTORY.md)). + | Agent | Read | Write | Edit | Bash | Grep | Glob | WebSearch | WebFetch | MCP | |-------|------|-------|------|------|------|------|-----------|----------|-----| | project-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 91131d2f9..f2b8fa72e 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -113,7 +113,7 @@ User-facing entry points. Each file contains YAML frontmatter (name, description - **Copilot:** Slash commands (`/gsd-command-name`) - **Antigravity:** Skills -**Total commands:** 81 +**Total commands:** see [`docs/INVENTORY.md`](INVENTORY.md#commands) for the authoritative count and full roster. ### Workflows (`get-shit-done/workflows/*.md`) @@ -124,7 +124,7 @@ Orchestration logic that commands reference. Contains the step-by-step process i - State update patterns - Error handling and recovery -**Total workflows:** 78 +**Total workflows:** see [`docs/INVENTORY.md`](INVENTORY.md#workflows) for the authoritative count and full roster. ### Agents (`agents/*.md`) @@ -138,7 +138,7 @@ Specialized agent definitions with frontmatter specifying: ### References (`get-shit-done/references/*.md`) -Shared knowledge documents that workflows and agents `@-reference` (35 total): +Shared knowledge documents that workflows and agents `@-reference` (see [`docs/INVENTORY.md`](INVENTORY.md#references-41-shipped) for the authoritative count and full roster): **Core references:** - `checkpoints.md` — Checkpoint type definitions and interaction patterns @@ -208,17 +208,21 @@ Runtime hooks that integrate with the host AI agent: |------|-------|---------| | `gsd-statusline.js` | `statusLine` | Displays model, task, directory, and context usage bar | | `gsd-context-monitor.js` | `PostToolUse` / `AfterTool` | Injects agent-facing context warnings at 35%/25% remaining | -| `gsd-check-update.js` | `SessionStart` | Background check for new GSD versions | +| `gsd-check-update.js` | `SessionStart` | Foreground trigger for the background update check | +| `gsd-check-update-worker.js` | (helper) | Background worker spawned by `gsd-check-update.js`; no direct event registration | | `gsd-prompt-guard.js` | `PreToolUse` | Scans `.planning/` writes for prompt injection patterns (advisory) | +| `gsd-read-injection-scanner.js` | `PostToolUse` | Scans Read tool output for injected instructions in untrusted content | | `gsd-workflow-guard.js` | `PreToolUse` | Detects file edits outside GSD workflow context (advisory, opt-in via `hooks.workflow_guard`) | | `gsd-read-guard.js` | `PreToolUse` | Advisory guard preventing Edit/Write on files not yet read in the session | | `gsd-session-state.sh` | `PostToolUse` | Session state tracking for shell-based runtimes | | `gsd-validate-commit.sh` | `PostToolUse` | Commit validation for conventional commit enforcement | | `gsd-phase-boundary.sh` | `PostToolUse` | Phase boundary detection for workflow transitions | +See [`docs/INVENTORY.md`](INVENTORY.md#hooks-11-shipped) for the authoritative 11-hook roster. + ### CLI Tools (`get-shit-done/bin/`) -Node.js CLI utility (`gsd-tools.cjs`) with 19 domain modules: +Node.js CLI utility (`gsd-tools.cjs`) with domain modules split across `get-shit-done/bin/lib/` (see [`docs/INVENTORY.md`](INVENTORY.md#cli-modules-24-shipped) for the authoritative roster): | Module | Responsibility | |--------|---------------| @@ -268,7 +272,9 @@ Orchestrator (workflow .md) └── Update state: gsd-tools.cjs state update/patch/advance-plan ``` -### Agent Spawn Categories +### Primary Agent Spawn Categories + +Conceptual spawn-pattern taxonomy for the 21 primary agents. For the authoritative 31-agent roster (including the 10 advanced/specialized agents such as `gsd-pattern-mapper`, `gsd-code-reviewer`, `gsd-code-fixer`, `gsd-ai-researcher`, `gsd-domain-researcher`, `gsd-eval-planner`, `gsd-eval-auditor`, `gsd-framework-selector`, `gsd-debug-session-manager`, `gsd-intel-updater`), see [`docs/INVENTORY.md`](INVENTORY.md#agents-31-shipped). | Category | Agents | Parallelism | |----------|--------|-------------| @@ -409,18 +415,16 @@ UI-SPEC.md (per phase) ─────────────────── ``` ~/.claude/ # Claude Code (global install) -├── commands/gsd/*.md # 81 slash commands +├── commands/gsd/*.md # Slash commands (authoritative roster: docs/INVENTORY.md) ├── get-shit-done/ │ ├── bin/gsd-tools.cjs # CLI utility -│ ├── bin/lib/*.cjs # 19 domain modules -│ ├── workflows/*.md # 78 workflow definitions -│ ├── references/*.md # 35 shared reference docs +│ ├── bin/lib/*.cjs # Domain modules (authoritative roster: docs/INVENTORY.md) +│ ├── workflows/*.md # Workflow definitions (authoritative roster: docs/INVENTORY.md) +│ ├── references/*.md # Shared reference docs (authoritative roster: docs/INVENTORY.md) │ └── templates/ # Planning artifact templates -├── agents/*.md # 33 agent definitions -├── hooks/ -│ ├── gsd-statusline.js # Statusline hook -│ ├── gsd-context-monitor.js # Context warning hook -│ └── gsd-check-update.js # Update check hook +├── agents/*.md # Agent definitions (authoritative roster: docs/INVENTORY.md) +├── hooks/*.js # Node.js hooks (statusline, guards, monitors, update check) +├── hooks/*.sh # Shell hooks (session state, commit validation, phase boundary) ├── settings.json # Hook registrations └── VERSION # Installed version number ``` diff --git a/docs/CLI-TOOLS.md b/docs/CLI-TOOLS.md index e76b71e8f..69cb71fc1 100644 --- a/docs/CLI-TOOLS.md +++ b/docs/CLI-TOOLS.md @@ -11,7 +11,7 @@ **Preferred for new orchestration:** Many of the same operations are available as `gsd-sdk query ` (see `sdk/src/query/index.ts` and `docs/QUERY-HANDLERS.md`). Use that in workflows and examples where the handler exists; keep `node … gsd-tools.cjs` for commands not yet in the registry (for example graphify) or when you need CJS-only flags. **Location:** `get-shit-done/bin/gsd-tools.cjs` -**Modules:** 15 domain modules in `get-shit-done/bin/lib/` +**Modules:** see the [Module Architecture](#module-architecture) table; the `get-shit-done/bin/lib/` directory is authoritative. **Usage:** ```bash @@ -67,6 +67,13 @@ node gsd-tools.cjs state resolve-blocker --text "..." # Record session continuity node gsd-tools.cjs state record-session --stopped-at "..." [--resume-file path] + +# Phase start — update STATE.md Status/Last activity for a new phase +node gsd-tools.cjs state begin-phase --phase N --name SLUG --plans COUNT + +# Agent-discoverable blocker signalling (used by discuss-phase / UI flows) +node gsd-tools.cjs state signal-waiting --type TYPE --question "..." --options "A|B" --phase P +node gsd-tools.cjs state signal-resume ``` ### State Snapshot @@ -356,6 +363,12 @@ node gsd-tools.cjs todo complete # UAT audit — scan all phases for unresolved items node gsd-tools.cjs audit-uat +# Cross-artifact audit queue — scan `.planning/` for unresolved audit items +node gsd-tools.cjs audit-open [--json] + +# Reverse-migrate a GSD-2 project into the current structure (backs `/gsd-from-gsd2`) +node gsd-tools.cjs from-gsd2 [--path ] [--force] [--dry-run] + # Git commit with config checks node gsd-tools.cjs commit [--files f1 f2] [--amend] [--no-verify] ``` @@ -368,6 +381,31 @@ node gsd-tools.cjs websearch [--limit N] [--freshness day|week|month] --- +## Graphify + +Build, query, and inspect the project knowledge graph in `.planning/graphs/`. Requires `graphify.enabled: true` in `config.json` (see [Configuration Reference](CONFIGURATION.md#graphify-settings)). Graphify is **CJS-only**: `gsd-sdk query` does not yet register graphify handlers — always use `node gsd-tools.cjs graphify …`. + +```bash +# Build or rebuild the knowledge graph +node gsd-tools.cjs graphify build + +# Search the graph for a term +node gsd-tools.cjs graphify query + +# Show graph freshness and statistics +node gsd-tools.cjs graphify status + +# Show changes since the last build +node gsd-tools.cjs graphify diff + +# Write a named snapshot of the current graph +node gsd-tools.cjs graphify snapshot [name] +``` + +User-facing entry point: `/gsd-graphify` (see [Command Reference](COMMANDS.md#gsd-graphify)). + +--- + ## Module Architecture | Module | File | Exports | @@ -387,3 +425,8 @@ node gsd-tools.cjs websearch [--limit N] [--freshness day|week|month] | UAT | `lib/uat.cjs` | Cross-phase UAT/verification audit | | Profile Output | `lib/profile-output.cjs` | Developer profile formatting | | Profile Pipeline | `lib/profile-pipeline.cjs` | Session analysis pipeline | +| Graphify | `lib/graphify.cjs` | Knowledge graph build/query/status/diff/snapshot (backs `/gsd-graphify`) | +| Learnings | `lib/learnings.cjs` | Extract learnings from phases/SUMMARY artifacts (backs `/gsd-extract-learnings`) | +| Audit | `lib/audit.cjs` | Phase/milestone audit queue handlers; `audit-open` helper | +| GSD2 Import | `lib/gsd2-import.cjs` | Reverse-migration importer from GSD-2 projects (backs `/gsd-from-gsd2`) | +| Intel | `lib/intel.cjs` | Queryable codebase intelligence index (backs `/gsd-intel`) | diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md index d3f0bd8d4..5e107933c 100644 --- a/docs/COMMANDS.md +++ b/docs/COMMANDS.md @@ -1,6 +1,6 @@ # GSD Command Reference -> Complete command syntax, flags, options, and examples. For feature details, see [Feature Reference](FEATURES.md). For workflow walkthroughs, see [User Guide](USER-GUIDE.md). +> Command syntax, flags, options, and examples for stable commands. For feature details, see [Feature Reference](FEATURES.md). For workflow walkthroughs, see [User Guide](USER-GUIDE.md). --- @@ -169,6 +169,43 @@ Research, plan, and verify a phase. --- +### `/gsd-plan-review-convergence` + +Cross-AI plan convergence loop. Runs `plan-phase → review → replan → re-review` cycles until no HIGH concerns remain (max 3 cycles by default). Spawns isolated agents for planning and review; orchestrator handles loop control, HIGH-concern counting, stall detection, and escalation. + +| Argument / Flag | Required | Description | +|-----------------|----------|-------------| +| `N` | **Yes** | Phase number to plan and review | +| `--codex` / `--gemini` / `--claude` / `--opencode` | No | Single-reviewer selection | +| `--all` | No | Run every configured reviewer in parallel | +| `--max-cycles N` | No | Override cycle cap (default 3) | + +**Exit behavior:** Loop exits when HIGH count hits zero. Stall detection warns when HIGH count is not decreasing across cycles. Escalation gate asks the user to proceed or review manually when `--max-cycles` is hit with 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 — Claude Code only.]** Offload plan-phase work to Claude Code's ultraplan cloud. 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. @@ -606,6 +643,27 @@ Ingest an external plan file into the GSD planning system with conflict detectio --- +### `/gsd-ingest-docs` + +Scan a repo containing mixed ADRs, PRDs, SPECs, and DOCs and bootstrap or merge the full `.planning/` setup from them in a single pass. 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-from-gsd2` Reverse migration from GSD-2 format (`.gsd/` with Milestone→Slice→Task hierarchy) back to v1 `.planning/` format. @@ -637,17 +695,27 @@ Execute ad-hoc task with GSD guarantees. | Flag | Description | |------|-------------| -| `--full` | Enable plan checking (2 iterations) + post-execution verification | +| `--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 | -Flags are composable. +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 --full # With plan checking and verification -/gsd-quick --discuss --research --full # All optional stages +/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` @@ -1045,6 +1113,28 @@ Query, inspect, or refresh queryable codebase intelligence files stored in `.pla /gsd-intel refresh # Rebuild intel index ``` +### `/gsd-graphify` + +Build, query, and inspect the project knowledge graph stored in `.planning/graphs/`. Opt-in via `graphify.enabled: true` in `config.json` (see [Configuration Reference](CONFIGURATION.md#graphify-settings)); when disabled, the command prints an activation hint and stops. + +| Subcommand | Description | +|------------|-------------| +| `build` | Build or rebuild the knowledge graph (spawns the graphify-builder agent) | +| `query ` | Search the graph for a term | +| `status` | Show graph freshness and statistics | +| `diff` | Show changes since the last build | + +**Produces:** `.planning/graphs/` graph artifacts (nodes, edges, snapshots) + +```bash +/gsd-graphify build # Build or rebuild the knowledge graph +/gsd-graphify query authentication # Search the graph for a term +/gsd-graphify status # Show freshness and statistics +/gsd-graphify diff # Show changes since last build +``` + +**Programmatic access:** `node gsd-tools.cjs graphify ` — see [CLI Tools Reference](CLI-TOOLS.md). + --- ## AI Integration Commands @@ -1346,7 +1436,11 @@ Manage persistent context threads for cross-session work. | Argument | Required | Description | |----------|----------|-------------| -| (none) | — | List all threads | +| (none) / `list` | — | List all threads | +| `list --open` | — | List threads with status `open` or `in_progress` only | +| `list --resolved` | — | List threads with status `resolved` only | +| `status ` | — | Show status of a specific thread | +| `close ` | — | Mark a thread as resolved | | `name` | — | Resume existing thread by name | | `description` | — | Create new thread | @@ -1354,6 +1448,10 @@ Threads are lightweight cross-session knowledge stores for work that spans multi ```bash /gsd-thread # List all threads +/gsd-thread list --open # List only open/in-progress threads +/gsd-thread list --resolved # List only resolved threads +/gsd-thread status fix-deploy-key # Show thread status +/gsd-thread close fix-deploy-key # Mark thread as resolved /gsd-thread fix-deploy-key-auth # Resume thread /gsd-thread "Investigate TCP timeout in pasta service" # Create new ``` diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index 947170c6a..418b921d2 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -18,7 +18,8 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd-new "model_overrides": {}, "planning": { "commit_docs": true, - "search_gitignored": false + "search_gitignored": false, + "sub_repos": [] }, "context_profile": null, "workflow": { @@ -45,7 +46,10 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd-new "code_review_command": null, "cross_ai_execution": false, "cross_ai_command": null, - "cross_ai_timeout": 300 + "cross_ai_timeout": 300, + "security_enforcement": true, + "security_asvs_level": 1, + "security_block_on": "high" }, "hooks": { "context_warnings": true, @@ -80,9 +84,6 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd-new "always_confirm_external_services": true }, "project_code": null, - "security_enforcement": true, - "security_asvs_level": 1, - "security_block_on": "high", "agent_skills": {}, "response_language": null, "features": { @@ -95,7 +96,7 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd-new "intel": { "enabled": false }, - "claude_md_path": null + "claude_md_path": "./CLAUDE.md" } ``` @@ -111,7 +112,7 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd-new | `project_code` | string | any short string | (none) | Prefix for phase directory names (e.g., `"ABC"` produces `ABC-01-setup/`). Added in v1.31 | | `response_language` | string | language code | (none) | Language for agent responses (e.g., `"pt"`, `"ko"`, `"ja"`). Propagates to all spawned agents for cross-phase language consistency. Added in v1.32 | | `context_profile` | string | `dev`, `research`, `review` | (none) | Execution context preset that applies a pre-configured bundle of mode, model, and workflow settings for the current type of work. Added in v1.34 | -| `claude_md_path` | string | any file path | (none) | Custom output path for the generated CLAUDE.md file. Useful for monorepos or projects that need CLAUDE.md in a non-root location. When set, GSD writes its CLAUDE.md content to this path instead of the project root. Added in v1.36 | +| `claude_md_path` | string | any file path | `./CLAUDE.md` | Custom output path for the generated CLAUDE.md file. Useful for monorepos or projects that need CLAUDE.md in a non-root location. Defaults to `./CLAUDE.md` at the project root. Added in v1.36 | > **Note:** `granularity` was renamed from `depth` in v1.22.3. Existing configs are auto-migrated. @@ -143,7 +144,7 @@ All workflow toggles follow the **absent = enabled** pattern. If a key is missin | `workflow.plan_bounce_script` | string | (none) | Path to the external script invoked for plan bounce validation. Receives the PLAN.md path as its first argument. Required when `plan_bounce` is `true`. Added in v1.36 | | `workflow.plan_bounce_passes` | number | `2` | Number of sequential bounce passes to run. Each pass feeds the previous pass's output back into the validator. Higher values increase rigor at the cost of latency. Added in v1.36 | | `workflow.code_review_command` | string | (none) | Shell command for external code review integration in `/gsd-ship`. Receives changed file paths via stdin. Non-zero exit blocks the ship workflow. Added in v1.36 | -| `workflow.tdd_mode` | boolean | `false` | Enable TDD pipeline as a first-class execution mode. When `true`, the planner aggressively applies `type: tdd` to eligible tasks (business logic, APIs, validations, algorithms) and the executor enforces RED/GREEN/REFACTOR gate sequence. An end-of-phase collaborative review checkpoint verifies gate compliance. Added in v1.37 | +| `workflow.tdd_mode` | boolean | `false` | Enable TDD pipeline as a first-class execution mode. When `true`, the planner aggressively applies `type: tdd` to eligible tasks (business logic, APIs, validations, algorithms) and the executor enforces RED/GREEN/REFACTOR gate sequence. An end-of-phase collaborative review checkpoint verifies gate compliance. Added in v1.36 | | `workflow.cross_ai_execution` | boolean | `false` | Delegate phase execution to an external AI CLI instead of spawning local executor agents. Useful for leveraging a different model's strengths for specific phases. Added in v1.36 | | `workflow.cross_ai_command` | string | (none) | Shell command template for cross-AI execution. Receives the phase prompt via stdin. Must produce SUMMARY.md-compatible output. Required when `cross_ai_execution` is `true`. Added in v1.36 | | `workflow.cross_ai_timeout` | number | `300` | Timeout in seconds for cross-AI execution commands. Prevents runaway external processes. Added in v1.36 | @@ -164,6 +165,7 @@ All workflow toggles follow the **absent = enabled** pattern. If a key is missin |---------|------|---------|-------------| | `planning.commit_docs` | boolean | `true` | Whether `.planning/` files are committed to git | | `planning.search_gitignored` | boolean | `false` | Add `--no-ignore` to broad searches to include `.planning/` | +| `planning.sub_repos` | array of strings | `[]` | Paths of nested sub-repos relative to the project root. When set, GSD-aware tooling scopes phase-lookup, path-resolution, and commit operations per sub-repo instead of treating the outer repo as a monorepo | ### Auto-Detection @@ -266,6 +268,14 @@ Toggle optional capabilities via the `features.*` config namespace. Feature flag | `features.global_learnings` | boolean | `false` | Enable cross-project learnings pipeline (auto-copy at phase completion, planner injection) | | `intel.enabled` | boolean | `false` | Enable queryable codebase intelligence system. When `true`, `/gsd-intel` commands build and query a JSON index in `.planning/intel/`. Added in v1.34 | + +### Graphify Settings + +| Setting | Type | Default | Description | +|---------|------|---------|-------------| +| `graphify.enabled` | boolean | `false` | Enable the project knowledge graph. When `true`, `/gsd-graphify` builds and queries a graph in `.planning/graphs/`. Added in v1.36 | +| `graphify.build_timeout` | number (seconds) | `300` | Maximum seconds allowed for a `/gsd-graphify build` run before it aborts. Added in v1.36 | + ### Usage ```bash @@ -368,13 +378,13 @@ Control confirmation prompts during workflows. ## Security Settings -Settings for the security enforcement feature (v1.31). All follow the **absent = enabled** pattern. +Settings for the security enforcement feature (v1.31). All follow the **absent = enabled** pattern. These keys live under `workflow.*` in `.planning/config.json` — matching the shipped template and the runtime reads in `workflows/plan-phase.md`, `workflows/execute-phase.md`, `workflows/secure-phase.md`, and `workflows/verify-work.md`. | Setting | Type | Default | Description | |---------|------|---------|-------------| -| `security_enforcement` | boolean | `true` | Enable threat-model-anchored security verification via `/gsd-secure-phase`. When `false`, security checks are skipped entirely | -| `security_asvs_level` | number (1-3) | `1` | OWASP ASVS verification level. Level 1 = opportunistic, Level 2 = standard, Level 3 = comprehensive | -| `security_block_on` | string | `"high"` | Minimum severity that blocks phase advancement. Options: `"high"`, `"medium"`, `"low"` | +| `workflow.security_enforcement` | boolean | `true` | Enable threat-model-anchored security verification via `/gsd-secure-phase`. When `false`, security checks are skipped entirely | +| `workflow.security_asvs_level` | number (1-3) | `1` | OWASP ASVS verification level. Level 1 = opportunistic, Level 2 = standard, Level 3 = comprehensive | +| `workflow.security_block_on` | string | `"high"` | Minimum severity that blocks phase advancement. Options: `"high"`, `"medium"`, `"low"` | --- @@ -454,6 +464,14 @@ Invalid flag tokens are sanitized and logged as warnings. Only recognized GSD fl | gsd-plan-checker | Sonnet | Sonnet | Haiku | Inherit | | gsd-integration-checker | Sonnet | Sonnet | Haiku | Inherit | | gsd-nyquist-auditor | Sonnet | Sonnet | Haiku | Inherit | +| gsd-pattern-mapper | Sonnet | Sonnet | Haiku | Inherit | +| gsd-ui-researcher | Opus | Sonnet | Haiku | Inherit | +| gsd-ui-checker | Sonnet | Sonnet | Haiku | Inherit | +| gsd-ui-auditor | Sonnet | Sonnet | Haiku | Inherit | +| gsd-doc-writer | Opus | Sonnet | Haiku | Inherit | +| gsd-doc-verifier | Sonnet | Sonnet | Haiku | Inherit | + +> **Fallback semantics for unlisted agents.** The profiles table above covers 18 of 31 shipped agents. Agents without an explicit profile row (`gsd-advisor-researcher`, `gsd-assumptions-analyzer`, `gsd-security-auditor`, `gsd-user-profiler`, and the nine advanced agents — `gsd-ai-researcher`, `gsd-domain-researcher`, `gsd-eval-planner`, `gsd-eval-auditor`, `gsd-framework-selector`, `gsd-code-reviewer`, `gsd-code-fixer`, `gsd-debug-session-manager`, `gsd-intel-updater`) inherit the runtime default model for the selected profile. To pin a specific model for any of these agents, use `model_overrides` (next section) — `model_overrides` accepts any shipped agent name regardless of whether it has a profile row here. The authoritative profile table lives in `get-shit-done/bin/lib/model-profiles.cjs`; the authoritative 31-agent roster lives in [`docs/INVENTORY.md`](INVENTORY.md). ### Per-Agent Overrides diff --git a/docs/FEATURES.md b/docs/FEATURES.md index 497488f76..88a56c431 100644 --- a/docs/FEATURES.md +++ b/docs/FEATURES.md @@ -86,6 +86,27 @@ - [Worktree Toggle](#66-worktree-toggle) - [Project Code Prefixing](#67-project-code-prefixing) - [Claude Code Skills Migration](#68-claude-code-skills-migration) +- [v1.32 Features](#v132-features) + - [STATE.md Consistency Gates](#69-statemd-consistency-gates) + - [Autonomous `--to N` Flag](#70-autonomous---to-n-flag) + - [Research Gate](#71-research-gate) + - [Verifier Milestone Scope Filtering](#72-verifier-milestone-scope-filtering) + - [Read-Before-Edit Guard Hook](#73-read-before-edit-guard-hook) + - [Context Reduction](#74-context-reduction) + - [Discuss-Phase `--power` Flag](#75-discuss-phase---power-flag) + - [Debug `--diagnose` Flag](#76-debug---diagnose-flag) + - [Phase Dependency Analysis](#77-phase-dependency-analysis) + - [Anti-Pattern Severity Levels](#78-anti-pattern-severity-levels) + - [Methodology Artifact Type](#79-methodology-artifact-type) + - [Planner Reachability Check](#80-planner-reachability-check) + - [Playwright-MCP UI Verification](#81-playwright-mcp-ui-verification) + - [Pause-Work Expansion](#82-pause-work-expansion) + - [Response Language Config](#83-response-language-config) + - [Manual Update Procedure](#84-manual-update-procedure) + - [New Runtime Support (Trae, Cline, Augment Code)](#85-new-runtime-support-trae-cline-augment-code) + - [Autonomous `--interactive` Flag](#86-autonomous---interactive-flag) + - [Commit-Docs Guard Hook](#87-commit-docs-guard-hook) + - [Community Hooks Opt-In](#88-community-hooks-opt-in) - [v1.34.0 Features](#v1340-features) - [Global Learnings Store](#89-global-learnings-store) - [Queryable Codebase Intelligence](#90-queryable-codebase-intelligence) @@ -116,11 +137,13 @@ - [SDK Workstream Support](#113-sdk-workstream-support) - [Context-Window-Aware Prompt Thinning](#114-context-window-aware-prompt-thinning) - [Configurable CLAUDE.md Path](#115-configurable-claudemd-path) + - [TDD Pipeline Mode](#116-tdd-pipeline-mode) - [v1.37.0 Features](#v1370-features) - [Spike Command](#117-spike-command) - [Sketch Command](#118-sketch-command) - [Agent Size-Budget Enforcement](#119-agent-size-budget-enforcement) - [Shared Boilerplate Extraction](#120-shared-boilerplate-extraction) + - [Knowledge Graph Integration](#121-knowledge-graph-integration) - [v1.32 Features](#v132-features) - [STATE.md Consistency Gates](#69-statemd-consistency-gates) - [Autonomous `--to N` Flag](#70-autonomous---to-n-flag) @@ -2521,3 +2544,19 @@ Users who run a memory / knowledge-base MCP server (for example, ExoCortex-style - REQ-BOILER-03: Agents that previously inlined these blocks MUST now reference them via `@` required_reading **Reference files:** `references/mandatory-initial-read.md`, `references/project-skills-discovery.md` + +--- + +### 121. Knowledge Graph Integration + +**Purpose:** Build, query, and inspect a lightweight knowledge graph of the project in `.planning/graphs/`. Opt-in per project. Exposed as the `/gsd-graphify` user-facing command and the `gsd-tools.cjs graphify …` programmatic verb family. Complements `/gsd-intel` (snapshot-oriented) with a graph-oriented view of nodes and edges across commands, agents, workflows, and phases. + +**Requirements:** +- REQ-GRAPH-01: Opt-in via `graphify.enabled: true` in `.planning/config.json`. When disabled, `/gsd-graphify` prints an activation hint and stops without writing. +- REQ-GRAPH-02: Slash-command `/gsd-graphify` exposes subcommands `build`, `query `, `status`, `diff`. The programmatic CLI `node gsd-tools.cjs graphify …` additionally exposes `snapshot`, which is also invoked automatically as the final step of `graphify build`. +- REQ-GRAPH-03: Build runs within the configurable `graphify.build_timeout` (seconds); exceeding the timeout aborts cleanly without leaving a partial graph. +- REQ-GRAPH-04: `graphify.cjs` falls back to `graph.links` when `graph.edges` is absent so older graph artifacts keep rendering. +- REQ-GRAPH-05: CJS-only surface; `gsd-sdk query` does not yet register graphify handlers. + +**Configuration:** `graphify.enabled`, `graphify.build_timeout` +**Reference files:** `commands/gsd/graphify.md`, `bin/lib/graphify.cjs` diff --git a/docs/INVENTORY.md b/docs/INVENTORY.md new file mode 100644 index 000000000..5ae187f72 --- /dev/null +++ b/docs/INVENTORY.md @@ -0,0 +1,412 @@ +# GSD Shipped Surface Inventory + +> Authoritative roster of every shipped GSD surface: commands, agents, workflows, references, CLI modules, and hooks. Where the broad docs (AGENTS.md, COMMANDS.md, ARCHITECTURE.md, CLI-TOOLS.md) diverge from the filesystem, treat this file and the repository tree itself as the source of truth. + +## How To Use This File + +- Counts here are derived from the filesystem at the v1.36.0 pin and may drift between releases. For live counts, run `ls commands/gsd/*.md | wc -l`, `ls agents/gsd-*.md | wc -l`, etc. against the checkout. +- This file enumerates every shipped surface across all six families (agents, commands, workflows, references, CLI modules, hooks). Broad docs may render narrative or curated subsets; when they disagree with the filesystem, this file and the directory listings are authoritative. +- New surfaces added after v1.36.0 should land here first, then propagate to the broad docs. The drift-control tests in `tests/inventory-counts.test.cjs`, `tests/commands-doc-parity.test.cjs`, `tests/agents-doc-parity.test.cjs`, `tests/cli-modules-doc-parity.test.cjs`, `tests/hooks-doc-parity.test.cjs`, `tests/architecture-counts.test.cjs`, and `tests/command-count-sync.test.cjs` anchor the counts and roster contents against the filesystem. + +--- + +## Agents (33 shipped) + +Full roster at `agents/gsd-*.md`. The "Primary doc" column flags whether [`docs/AGENTS.md`](AGENTS.md) carries a full role card (*primary*), a short stub in the "Advanced and Specialized Agents" section (*advanced stub*), or no coverage (*inventory only*). + +| Agent | Role (one line) | Spawned by | Primary doc | +|-------|-----------------|------------|-------------| +| gsd-project-researcher | Researches domain ecosystem before roadmap creation (stack, features, architecture, pitfalls). | `/gsd-new-project`, `/gsd-new-milestone` | primary | +| gsd-phase-researcher | Researches implementation approach for a specific phase before planning. | `/gsd-plan-phase` | primary | +| gsd-ui-researcher | Produces UI design contracts for frontend phases. | `/gsd-ui-phase` | primary | +| gsd-assumptions-analyzer | Produces evidence-backed assumptions for discuss-phase (assumptions mode). | `discuss-phase-assumptions` workflow | primary | +| gsd-advisor-researcher | Researches a single gray-area decision during discuss-phase advisor mode. | `discuss-phase` workflow (advisor mode) | primary | +| gsd-research-synthesizer | Combines parallel researcher outputs into a unified SUMMARY.md. | `/gsd-new-project` | primary | +| gsd-planner | Creates executable phase plans with task breakdown and goal-backward verification. | `/gsd-plan-phase`, `/gsd-quick` | primary | +| gsd-roadmapper | Creates project roadmaps with phase breakdown and requirement mapping. | `/gsd-new-project` | primary | +| gsd-executor | Executes GSD plans with atomic commits and deviation handling. | `/gsd-execute-phase`, `/gsd-quick` | primary | +| gsd-plan-checker | Verifies plans will achieve phase goals (8 verification dimensions). | `/gsd-plan-phase` (verification loop) | primary | +| gsd-integration-checker | Verifies cross-phase integration and end-to-end flows. | `/gsd-audit-milestone` | primary | +| gsd-ui-checker | Validates UI-SPEC.md design contracts against quality dimensions. | `/gsd-ui-phase` (validation loop) | primary | +| gsd-verifier | Verifies phase goal achievement through goal-backward analysis. | `/gsd-execute-phase` | primary | +| gsd-nyquist-auditor | Fills Nyquist validation gaps by generating tests. | `/gsd-validate-phase` | primary | +| gsd-ui-auditor | Retroactive 6-pillar visual audit of implemented frontend code. | `/gsd-ui-review` | primary | +| gsd-codebase-mapper | Explores codebase and writes structured analysis documents. | `/gsd-map-codebase` | primary | +| gsd-debugger | Investigates bugs using scientific method with persistent state. | `/gsd-debug`, `/gsd-verify-work` | primary | +| gsd-user-profiler | Scores developer behavior across 8 dimensions. | `/gsd-profile-user` | primary | +| gsd-doc-writer | Writes and updates project documentation. | `/gsd-docs-update` | primary | +| gsd-doc-verifier | Verifies factual claims in generated documentation. | `/gsd-docs-update` | primary | +| gsd-security-auditor | Verifies threat mitigations from PLAN.md threat model. | `/gsd-secure-phase` | primary | +| gsd-pattern-mapper | Maps new files to closest existing analogs; writes PATTERNS.md for the planner. | `/gsd-plan-phase` (between research and planning) | advanced stub | +| gsd-debug-session-manager | Runs the full `/gsd-debug` checkpoint-and-continuation loop in isolated context so main stays lean. | `/gsd-debug` | advanced stub | +| gsd-code-reviewer | Reviews source files for bugs, security issues, and code-quality problems; produces REVIEW.md. | `/gsd-code-review` | advanced stub | +| gsd-code-fixer | Applies fixes to REVIEW.md findings with atomic per-fix commits; produces REVIEW-FIX.md. | `/gsd-code-review-fix` | advanced stub | +| gsd-ai-researcher | Researches a chosen AI framework's official docs into implementation-ready guidance (AI-SPEC.md §3–§4b). | `/gsd-ai-integration-phase` | advanced stub | +| gsd-domain-researcher | Surfaces domain-expert evaluation criteria and failure modes for an AI system (AI-SPEC.md §1b). | `/gsd-ai-integration-phase` | advanced stub | +| gsd-eval-planner | Designs structured evaluation strategy for an AI phase (AI-SPEC.md §5–§7). | `/gsd-ai-integration-phase` | advanced stub | +| gsd-eval-auditor | Retroactive audit of an AI phase's evaluation coverage; produces EVAL-REVIEW.md (COVERED/PARTIAL/MISSING). | `/gsd-eval-review` | advanced stub | +| gsd-framework-selector | ≤6-question interactive decision matrix that scores and recommends an AI/LLM framework. | `/gsd-ai-integration-phase`, `/gsd-select-framework` | advanced stub | +| gsd-intel-updater | Writes structured intel files (`.planning/intel/*.json`) used as a queryable codebase knowledge base. | `/gsd-intel` | advanced stub | +| gsd-doc-classifier | Classifies a single planning document as ADR, PRD, SPEC, DOC, or UNKNOWN; spawned in parallel to process the doc corpus. | `/gsd-ingest-docs` | advanced stub | +| gsd-doc-synthesizer | Synthesizes classified planning docs into a single consolidated context with precedence rules, cycle detection, and three-bucket conflicts report. | `/gsd-ingest-docs` | advanced stub | + +**Coverage note.** `docs/AGENTS.md` gives full role cards for 21 primary agents plus concise stubs for the 12 advanced agents. The Agent Tool Permissions Summary in that file covers only the primary 21 agents; the advanced agents' tool lists are captured in their per-agent frontmatter in `agents/gsd-*.md`. + +--- + +## Commands (82 shipped) + +Full roster at `commands/gsd/*.md`. The groupings below mirror `docs/COMMANDS.md` section order; each row carries the command name, a one-line role derived from the command's frontmatter `description:`, and a link to the source file. `tests/command-count-sync.test.cjs` locks the count against the filesystem. + +### Core Workflow + +| Command | Role | Source | +|---------|------|--------| +| `/gsd-new-project` | Initialize a new project with deep context gathering and PROJECT.md. | [commands/gsd/new-project.md](../commands/gsd/new-project.md) | +| `/gsd-new-workspace` | Create an isolated workspace with repo copies and independent `.planning/`. | [commands/gsd/new-workspace.md](../commands/gsd/new-workspace.md) | +| `/gsd-list-workspaces` | List active GSD workspaces and their status. | [commands/gsd/list-workspaces.md](../commands/gsd/list-workspaces.md) | +| `/gsd-remove-workspace` | Remove a GSD workspace and clean up worktrees. | [commands/gsd/remove-workspace.md](../commands/gsd/remove-workspace.md) | +| `/gsd-discuss-phase` | Gather phase context through adaptive questioning before planning. | [commands/gsd/discuss-phase.md](../commands/gsd/discuss-phase.md) | +| `/gsd-spec-phase` | Socratic spec refinement producing a SPEC.md with falsifiable requirements. | [commands/gsd/spec-phase.md](../commands/gsd/spec-phase.md) | +| `/gsd-ui-phase` | Generate UI design contract (UI-SPEC.md) for frontend phases. | [commands/gsd/ui-phase.md](../commands/gsd/ui-phase.md) | +| `/gsd-ai-integration-phase` | Generate AI design contract (AI-SPEC.md) via framework selection, research, and eval planning. | [commands/gsd/ai-integration-phase.md](../commands/gsd/ai-integration-phase.md) | +| `/gsd-plan-phase` | Create detailed phase plan (PLAN.md) with verification loop. | [commands/gsd/plan-phase.md](../commands/gsd/plan-phase.md) | +| `/gsd-plan-review-convergence` | Cross-AI plan convergence loop — replan with review feedback until no HIGH concerns remain (max 3 cycles). | [commands/gsd/plan-review-convergence.md](../commands/gsd/plan-review-convergence.md) | +| `/gsd-ultraplan-phase` | [BETA] Offload plan phase to Claude Code's ultraplan cloud — drafts remotely, review in browser, import back via `/gsd-import`. Claude Code only. | [commands/gsd/ultraplan-phase.md](../commands/gsd/ultraplan-phase.md) | +| `/gsd-spike` | Rapidly spike an idea with throwaway experiments to validate feasibility before planning. | [commands/gsd/spike.md](../commands/gsd/spike.md) | +| `/gsd-sketch` | Rapidly sketch UI/design ideas using throwaway HTML mockups with multi-variant exploration. | [commands/gsd/sketch.md](../commands/gsd/sketch.md) | +| `/gsd-research-phase` | Research how to implement a phase (standalone). | [commands/gsd/research-phase.md](../commands/gsd/research-phase.md) | +| `/gsd-execute-phase` | Execute all plans in a phase with wave-based parallelization. | [commands/gsd/execute-phase.md](../commands/gsd/execute-phase.md) | +| `/gsd-verify-work` | Validate built features through conversational UAT with auto-diagnosis. | [commands/gsd/verify-work.md](../commands/gsd/verify-work.md) | +| `/gsd-ship` | Create PR, run review, and prepare for merge after verification. | [commands/gsd/ship.md](../commands/gsd/ship.md) | +| `/gsd-next` | Automatically advance to the next logical step in the GSD workflow. | [commands/gsd/next.md](../commands/gsd/next.md) | +| `/gsd-fast` | Execute a trivial task inline — no subagents, no planning overhead. | [commands/gsd/fast.md](../commands/gsd/fast.md) | +| `/gsd-quick` | Execute a quick task with GSD guarantees (atomic commits, state tracking) but skip optional agents. | [commands/gsd/quick.md](../commands/gsd/quick.md) | +| `/gsd-ui-review` | Retroactive 6-pillar visual audit of implemented frontend code. | [commands/gsd/ui-review.md](../commands/gsd/ui-review.md) | +| `/gsd-code-review` | Review source files changed during a phase for bugs, security, and code-quality problems. | [commands/gsd/code-review.md](../commands/gsd/code-review.md) | +| `/gsd-code-review-fix` | Auto-fix issues found by `/gsd-code-review`, committing each fix atomically. | [commands/gsd/code-review-fix.md](../commands/gsd/code-review-fix.md) | +| `/gsd-eval-review` | Retroactively audit an executed AI phase's evaluation coverage; produces EVAL-REVIEW.md. | [commands/gsd/eval-review.md](../commands/gsd/eval-review.md) | + +### Phase & Milestone Management + +| Command | Role | Source | +|---------|------|--------| +| `/gsd-add-phase` | Add phase to end of current milestone in roadmap. | [commands/gsd/add-phase.md](../commands/gsd/add-phase.md) | +| `/gsd-insert-phase` | Insert urgent work as decimal phase (e.g., 72.1) between existing phases. | [commands/gsd/insert-phase.md](../commands/gsd/insert-phase.md) | +| `/gsd-remove-phase` | Remove a future phase from roadmap and renumber subsequent phases. | [commands/gsd/remove-phase.md](../commands/gsd/remove-phase.md) | +| `/gsd-add-tests` | Generate tests for a completed phase based on UAT criteria and implementation. | [commands/gsd/add-tests.md](../commands/gsd/add-tests.md) | +| `/gsd-list-phase-assumptions` | Surface Claude's assumptions about a phase approach before planning. | [commands/gsd/list-phase-assumptions.md](../commands/gsd/list-phase-assumptions.md) | +| `/gsd-analyze-dependencies` | Analyze phase dependencies and suggest `Depends on` entries for ROADMAP.md. | [commands/gsd/analyze-dependencies.md](../commands/gsd/analyze-dependencies.md) | +| `/gsd-validate-phase` | Retroactively audit and fill Nyquist validation gaps for a completed phase. | [commands/gsd/validate-phase.md](../commands/gsd/validate-phase.md) | +| `/gsd-secure-phase` | Retroactively verify threat mitigations for a completed phase. | [commands/gsd/secure-phase.md](../commands/gsd/secure-phase.md) | +| `/gsd-audit-milestone` | Audit milestone completion against original intent before archiving. | [commands/gsd/audit-milestone.md](../commands/gsd/audit-milestone.md) | +| `/gsd-audit-uat` | Cross-phase audit of all outstanding UAT and verification items. | [commands/gsd/audit-uat.md](../commands/gsd/audit-uat.md) | +| `/gsd-audit-fix` | Autonomous audit-to-fix pipeline — find issues, classify, fix, test, commit. | [commands/gsd/audit-fix.md](../commands/gsd/audit-fix.md) | +| `/gsd-plan-milestone-gaps` | Create phases to close all gaps identified by milestone audit. | [commands/gsd/plan-milestone-gaps.md](../commands/gsd/plan-milestone-gaps.md) | +| `/gsd-complete-milestone` | Archive completed milestone and prepare for next version. | [commands/gsd/complete-milestone.md](../commands/gsd/complete-milestone.md) | +| `/gsd-new-milestone` | Start a new milestone cycle — update PROJECT.md and route to requirements. | [commands/gsd/new-milestone.md](../commands/gsd/new-milestone.md) | +| `/gsd-milestone-summary` | Generate a comprehensive project summary from milestone artifacts. | [commands/gsd/milestone-summary.md](../commands/gsd/milestone-summary.md) | +| `/gsd-cleanup` | Archive accumulated phase directories from completed milestones. | [commands/gsd/cleanup.md](../commands/gsd/cleanup.md) | +| `/gsd-manager` | Interactive command center for managing multiple phases from one terminal. | [commands/gsd/manager.md](../commands/gsd/manager.md) | +| `/gsd-workstreams` | Manage parallel workstreams — list, create, switch, status, progress, complete, resume. | [commands/gsd/workstreams.md](../commands/gsd/workstreams.md) | +| `/gsd-autonomous` | Run all remaining phases autonomously — discuss → plan → execute per phase. | [commands/gsd/autonomous.md](../commands/gsd/autonomous.md) | +| `/gsd-undo` | Safe git revert — roll back phase or plan commits using the phase manifest. | [commands/gsd/undo.md](../commands/gsd/undo.md) | + +### Session & Navigation + +| Command | Role | Source | +|---------|------|--------| +| `/gsd-progress` | Check project progress, show context, and route to next action. | [commands/gsd/progress.md](../commands/gsd/progress.md) | +| `/gsd-stats` | Display project statistics — phases, plans, requirements, git metrics, timeline. | [commands/gsd/stats.md](../commands/gsd/stats.md) | +| `/gsd-session-report` | Generate a session report with token usage estimates, work summary, outcomes. | [commands/gsd/session-report.md](../commands/gsd/session-report.md) | +| `/gsd-pause-work` | Create context handoff when pausing work mid-phase. | [commands/gsd/pause-work.md](../commands/gsd/pause-work.md) | +| `/gsd-resume-work` | Resume work from previous session with full context restoration. | [commands/gsd/resume-work.md](../commands/gsd/resume-work.md) | +| `/gsd-explore` | Socratic ideation and idea routing — think through ideas before committing. | [commands/gsd/explore.md](../commands/gsd/explore.md) | +| `/gsd-do` | Route freeform text to the right GSD command automatically. | [commands/gsd/do.md](../commands/gsd/do.md) | +| `/gsd-note` | Zero-friction idea capture — append, list, or promote notes to todos. | [commands/gsd/note.md](../commands/gsd/note.md) | +| `/gsd-add-todo` | Capture idea or task as todo from current conversation context. | [commands/gsd/add-todo.md](../commands/gsd/add-todo.md) | +| `/gsd-check-todos` | List pending todos and select one to work on. | [commands/gsd/check-todos.md](../commands/gsd/check-todos.md) | +| `/gsd-add-backlog` | Add an idea to the backlog parking lot (999.x numbering). | [commands/gsd/add-backlog.md](../commands/gsd/add-backlog.md) | +| `/gsd-review-backlog` | Review and promote backlog items to active milestone. | [commands/gsd/review-backlog.md](../commands/gsd/review-backlog.md) | +| `/gsd-plant-seed` | Capture a forward-looking idea with trigger conditions. | [commands/gsd/plant-seed.md](../commands/gsd/plant-seed.md) | +| `/gsd-thread` | Manage persistent context threads for cross-session work. | [commands/gsd/thread.md](../commands/gsd/thread.md) | + +### Codebase Intelligence + +| Command | Role | Source | +|---------|------|--------| +| `/gsd-map-codebase` | Analyze codebase with parallel mapper agents; produces `.planning/codebase/` documents. | [commands/gsd/map-codebase.md](../commands/gsd/map-codebase.md) | +| `/gsd-scan` | Rapid codebase assessment — lightweight alternative to `/gsd-map-codebase`. | [commands/gsd/scan.md](../commands/gsd/scan.md) | +| `/gsd-intel` | Query, inspect, or refresh codebase intelligence files in `.planning/intel/`. | [commands/gsd/intel.md](../commands/gsd/intel.md) | +| `/gsd-graphify` | Build, query, and inspect the project knowledge graph in `.planning/graphs/`. | [commands/gsd/graphify.md](../commands/gsd/graphify.md) | +| `/gsd-extract-learnings` | Extract decisions, lessons, patterns, and surprises from completed phase artifacts. | [commands/gsd/extract_learnings.md](../commands/gsd/extract_learnings.md) | + +### Review, Debug & Recovery + +| Command | Role | Source | +|---------|------|--------| +| `/gsd-review` | Request cross-AI peer review of phase plans from external AI CLIs. | [commands/gsd/review.md](../commands/gsd/review.md) | +| `/gsd-debug` | Systematic debugging with persistent state across context resets. | [commands/gsd/debug.md](../commands/gsd/debug.md) | +| `/gsd-forensics` | Post-mortem investigation for failed GSD workflows — analyzes git, artifacts, state. | [commands/gsd/forensics.md](../commands/gsd/forensics.md) | +| `/gsd-health` | Diagnose planning directory health and optionally repair issues. | [commands/gsd/health.md](../commands/gsd/health.md) | +| `/gsd-import` | Ingest external plans with conflict detection against project decisions. | [commands/gsd/import.md](../commands/gsd/import.md) | +| `/gsd-from-gsd2` | Import a GSD-2 (`.gsd/`) project back to GSD v1 (`.planning/`) format. | [commands/gsd/from-gsd2.md](../commands/gsd/from-gsd2.md) | +| `/gsd-inbox` | Triage and review all open GitHub issues and PRs against project templates. | [commands/gsd/inbox.md](../commands/gsd/inbox.md) | + +### Docs, Profile & Utilities + +| Command | Role | Source | +|---------|------|--------| +| `/gsd-docs-update` | Generate or update project documentation verified against the codebase. | [commands/gsd/docs-update.md](../commands/gsd/docs-update.md) | +| `/gsd-ingest-docs` | Scan a repo for mixed ADRs/PRDs/SPECs/DOCs and bootstrap or merge the full `.planning/` setup with classification, synthesis, and conflicts report. | [commands/gsd/ingest-docs.md](../commands/gsd/ingest-docs.md) | +| `/gsd-spike-wrap-up` | Package spike findings into a persistent project skill for future build conversations. | [commands/gsd/spike-wrap-up.md](../commands/gsd/spike-wrap-up.md) | +| `/gsd-sketch-wrap-up` | Package sketch design findings into a persistent project skill for future build conversations. | [commands/gsd/sketch-wrap-up.md](../commands/gsd/sketch-wrap-up.md) | +| `/gsd-profile-user` | Generate developer behavioral profile and Claude-discoverable artifacts. | [commands/gsd/profile-user.md](../commands/gsd/profile-user.md) | +| `/gsd-settings` | Configure GSD workflow toggles and model profile. | [commands/gsd/settings.md](../commands/gsd/settings.md) | +| `/gsd-set-profile` | Switch model profile for GSD agents (quality/balanced/budget/inherit). | [commands/gsd/set-profile.md](../commands/gsd/set-profile.md) | +| `/gsd-pr-branch` | Create a clean PR branch by filtering out `.planning/` commits. | [commands/gsd/pr-branch.md](../commands/gsd/pr-branch.md) | +| `/gsd-update` | Update GSD to latest version with changelog display. | [commands/gsd/update.md](../commands/gsd/update.md) | +| `/gsd-reapply-patches` | Reapply local modifications after a GSD update. | [commands/gsd/reapply-patches.md](../commands/gsd/reapply-patches.md) | +| `/gsd-help` | Show available GSD commands and usage guide. | [commands/gsd/help.md](../commands/gsd/help.md) | +| `/gsd-join-discord` | Join the GSD Discord community. | [commands/gsd/join-discord.md](../commands/gsd/join-discord.md) | + +--- + +## Workflows (79 shipped) + +Full roster at `get-shit-done/workflows/*.md`. Workflows are thin orchestrators that commands reference internally; most are not read directly by end users. Rows below map each workflow file to its role (derived from the `` block) and, where applicable, to the command that invokes it. + +| Workflow | Role | Invoked by | +|----------|------|------------| +| `add-phase.md` | Add a new integer phase to the end of the current milestone in the roadmap. | `/gsd-add-phase` | +| `add-tests.md` | Generate unit and E2E tests for a completed phase based on its artifacts. | `/gsd-add-tests` | +| `add-todo.md` | Capture an idea or task that surfaces during a session as a structured todo. | `/gsd-add-todo`, `/gsd-add-backlog` | +| `ai-integration-phase.md` | Orchestrate framework selection → AI research → domain research → eval planning into AI-SPEC.md. | `/gsd-ai-integration-phase` | +| `analyze-dependencies.md` | Analyze ROADMAP.md phases for file overlap and semantic dependencies; suggest `Depends on` edges. | `/gsd-analyze-dependencies` | +| `audit-fix.md` | Autonomous audit-to-fix pipeline — run audit, parse, classify, fix, test, commit. | `/gsd-audit-fix` | +| `audit-milestone.md` | Verify milestone met its definition of done by aggregating phase verifications. | `/gsd-audit-milestone` | +| `audit-uat.md` | Cross-phase audit of UAT and verification files; produces prioritized outstanding-items list. | `/gsd-audit-uat` | +| `autonomous.md` | Drive milestone phases autonomously — all remaining, a range, or a single phase. | `/gsd-autonomous` | +| `check-todos.md` | List pending todos, allow selection, load context, and route to the appropriate action. | `/gsd-check-todos` | +| `cleanup.md` | Archive accumulated phase directories from completed milestones. | `/gsd-cleanup` | +| `code-review-fix.md` | Auto-fix issues from REVIEW.md via gsd-code-fixer with per-fix atomic commits. | `/gsd-code-review-fix` | +| `code-review.md` | Review phase source changes via gsd-code-reviewer; produces REVIEW.md. | `/gsd-code-review` | +| `complete-milestone.md` | Mark a shipped version as complete — MILESTONES.md entry, PROJECT.md evolution, tag. | `/gsd-complete-milestone` | +| `diagnose-issues.md` | Orchestrate parallel debug agents to investigate UAT gaps and find root causes. | `/gsd-verify-work` (auto-diagnosis) | +| `discovery-phase.md` | Execute discovery at the appropriate depth level. | `/gsd-new-project` (discovery path) | +| `discuss-phase-assumptions.md` | Assumptions-mode discuss — extract implementation decisions via codebase-first analysis. | `/gsd-discuss-phase` (when `discuss_mode=assumptions`) | +| `discuss-phase-power.md` | Power-user discuss — pre-generate all questions into a JSON state file + HTML UI. | `/gsd-discuss-phase --power` | +| `discuss-phase.md` | Extract implementation decisions through iterative gray-area discussion. | `/gsd-discuss-phase` | +| `do.md` | Route freeform text from the user to the best matching GSD command. | `/gsd-do` | +| `docs-update.md` | Generate, update, and verify canonical and hand-written project documentation. | `/gsd-docs-update` | +| `eval-review.md` | Retroactive audit of an implemented AI phase's evaluation coverage. | `/gsd-eval-review` | +| `execute-phase.md` | Execute all plans in a phase using wave-based parallel execution. | `/gsd-execute-phase` | +| `execute-plan.md` | Execute a phase prompt (PLAN.md) and create the outcome summary (SUMMARY.md). | `execute-phase.md` (per-plan subagent) | +| `explore.md` | Socratic ideation — guide the developer through probing questions. | `/gsd-explore` | +| `extract_learnings.md` | Extract decisions, lessons, patterns, and surprises from completed phase artifacts. | `/gsd-extract-learnings` | +| `fast.md` | Execute a trivial task inline without subagent overhead. | `/gsd-fast` | +| `forensics.md` | Forensics investigation of failed workflows — git, artifacts, and state analysis. | `/gsd-forensics` | +| `health.md` | Validate `.planning/` directory integrity and report actionable issues. | `/gsd-health` | +| `help.md` | Display the complete GSD command reference. | `/gsd-help` | +| `import.md` | Ingest external plans with conflict detection against existing project decisions. | `/gsd-import` | +| `inbox.md` | Triage open GitHub issues and PRs against project contribution templates. | `/gsd-inbox` | +| `ingest-docs.md` | Scan a repo for mixed planning docs; classify, synthesize, and bootstrap or merge into `.planning/` with a conflicts report. | `/gsd-ingest-docs` | +| `insert-phase.md` | Insert a decimal phase for urgent work discovered mid-milestone. | `/gsd-insert-phase` | +| `list-phase-assumptions.md` | Surface Claude's assumptions about a phase before planning. | `/gsd-list-phase-assumptions` | +| `list-workspaces.md` | List all GSD workspaces found in `~/gsd-workspaces/` with their status. | `/gsd-list-workspaces` | +| `manager.md` | Interactive milestone command center — dashboard, inline discuss, background plan/execute. | `/gsd-manager` | +| `map-codebase.md` | Orchestrate parallel codebase mapper agents to produce `.planning/codebase/` docs. | `/gsd-map-codebase` | +| `milestone-summary.md` | Milestone summary synthesis — onboarding and review artifact from milestone artifacts. | `/gsd-milestone-summary` | +| `new-milestone.md` | Start a new milestone cycle — load project context, gather goals, update PROJECT.md/STATE.md. | `/gsd-new-milestone` | +| `new-project.md` | Unified new-project flow — questioning, research (optional), requirements, roadmap. | `/gsd-new-project` | +| `new-workspace.md` | Create an isolated workspace with repo worktrees/clones and an independent `.planning/`. | `/gsd-new-workspace` | +| `next.md` | Detect current project state and automatically advance to the next logical step. | `/gsd-next` | +| `node-repair.md` | Autonomous repair operator for failed task verification; invoked by `execute-plan`. | `execute-plan.md` (recovery) | +| `note.md` | Zero-friction idea capture — one Write call, one confirmation line. | `/gsd-note` | +| `pause-work.md` | Create structured `.planning/HANDOFF.json` and `.continue-here.md` handoff files. | `/gsd-pause-work` | +| `plan-milestone-gaps.md` | Create all phases necessary to close gaps identified by `/gsd-audit-milestone`. | `/gsd-plan-milestone-gaps` | +| `plan-phase.md` | Create executable PLAN.md files with integrated research and verification loop. | `/gsd-plan-phase`, `/gsd-quick` | +| `plan-review-convergence.md` | Cross-AI plan convergence loop — replan with review feedback until no HIGH concerns remain. | `/gsd-plan-review-convergence` | +| `plant-seed.md` | Capture a forward-looking idea as a structured seed file with trigger conditions. | `/gsd-plant-seed` | +| `pr-branch.md` | Create a clean branch for pull requests by filtering `.planning/` commits. | `/gsd-pr-branch` | +| `profile-user.md` | Orchestrate the full developer profiling flow — consent, session scan, profile generation. | `/gsd-profile-user` | +| `progress.md` | Progress rendering — project context, position, and next-action routing. | `/gsd-progress` | +| `quick.md` | Quick-task execution with GSD guarantees (atomic commits, state tracking). | `/gsd-quick` | +| `remove-phase.md` | Remove a future phase from the roadmap and renumber subsequent phases. | `/gsd-remove-phase` | +| `remove-workspace.md` | Remove a GSD workspace and clean up worktrees. | `/gsd-remove-workspace` | +| `research-phase.md` | Standalone phase research workflow (usually invoked via `plan-phase`). | `/gsd-research-phase` | +| `resume-project.md` | Resume work — restore full context from STATE.md, HANDOFF.json, and artifacts. | `/gsd-resume-work` | +| `review.md` | Cross-AI plan review via external CLIs; produces REVIEWS.md. | `/gsd-review` | +| `scan.md` | Rapid single-focus codebase scan — lightweight alternative to map-codebase. | `/gsd-scan` | +| `secure-phase.md` | Retroactive threat-mitigation audit for a completed phase. | `/gsd-secure-phase` | +| `session-report.md` | Session report — token usage, work summary, outcomes. | `/gsd-session-report` | +| `settings.md` | Configure GSD workflow toggles and model profile. | `/gsd-settings`, `/gsd-set-profile` | +| `ship.md` | Create PR, run review, and prepare for merge after verification. | `/gsd-ship` | +| `sketch.md` | Explore design directions through throwaway HTML mockups with 2-3 variants per sketch. | `/gsd-sketch` | +| `sketch-wrap-up.md` | Curate sketch findings and package them as a persistent `sketch-findings-[project]` skill. | `/gsd-sketch-wrap-up` | +| `spec-phase.md` | Socratic spec refinement with ambiguity scoring; produces SPEC.md. | `/gsd-spec-phase` | +| `spike.md` | Rapid feasibility validation through focused, throwaway experiments. | `/gsd-spike` | +| `spike-wrap-up.md` | Curate spike findings and package them as a persistent `spike-findings-[project]` skill. | `/gsd-spike-wrap-up` | +| `stats.md` | Project statistics rendering — phases, plans, requirements, git metrics. | `/gsd-stats` | +| `transition.md` | Phase-boundary transition workflow — workstream checks, state advancement. | `execute-phase.md`, `/gsd-next` | +| `ui-phase.md` | Generate UI-SPEC.md design contract via gsd-ui-researcher. | `/gsd-ui-phase` | +| `ui-review.md` | Retroactive 6-pillar visual audit via gsd-ui-auditor. | `/gsd-ui-review` | +| `ultraplan-phase.md` | [BETA] Offload planning to Claude Code's ultraplan cloud; drafts remotely and imports back via `/gsd-import`. | `/gsd-ultraplan-phase` | +| `undo.md` | Safe git revert — phase or plan commits using the phase manifest. | `/gsd-undo` | +| `update.md` | Update GSD to latest version with changelog display. | `/gsd-update` | +| `validate-phase.md` | Retroactively audit and fill Nyquist validation gaps for a completed phase. | `/gsd-validate-phase` | +| `verify-phase.md` | Verify phase goal achievement through goal-backward analysis. | `execute-phase.md` (post-execution) | +| `verify-work.md` | Conversational UAT with auto-diagnosis — produces UAT.md and fix plans. | `/gsd-verify-work` | + +> **Note:** Some workflows have no direct user-facing command (e.g. `execute-plan.md`, `verify-phase.md`, `transition.md`, `node-repair.md`, `diagnose-issues.md`) — they are invoked internally by orchestrator workflows. `discovery-phase.md` is an alternate entry for `/gsd-new-project`. + +--- + +## References (49 shipped) + +Full roster at `get-shit-done/references/*.md`. References are shared knowledge documents that workflows and agents `@-reference`. The groupings below match [`docs/ARCHITECTURE.md`](ARCHITECTURE.md#references-get-shit-donereferencesmd) — core, workflow, thinking-model clusters, and the modular planner decomposition. + +### Core References + +| Reference | Role | +|-----------|------| +| `checkpoints.md` | Checkpoint type definitions and interaction patterns. | +| `gates.md` | 4 canonical gate types (Confirm, Quality, Safety, Transition) wired into plan-checker and verifier. | +| `model-profiles.md` | Per-agent model tier assignments. | +| `model-profile-resolution.md` | Model resolution algorithm documentation. | +| `verification-patterns.md` | How to verify different artifact types. | +| `verification-overrides.md` | Per-artifact verification override rules. | +| `planning-config.md` | Full config schema and behavior. | +| `git-integration.md` | Git commit, branching, and history patterns. | +| `git-planning-commit.md` | Planning directory commit conventions. | +| `questioning.md` | Dream-extraction philosophy for project initialization. | +| `tdd.md` | Test-driven development integration patterns. | +| `ui-brand.md` | Visual output formatting patterns. | +| `common-bug-patterns.md` | Common bug patterns for code review and verification. | +| `debugger-philosophy.md` | Evergreen debugging disciplines loaded by `gsd-debugger`. | +| `mandatory-initial-read.md` | Shared required-reading boilerplate injected into agent prompts. | +| `project-skills-discovery.md` | Shared project-skills-discovery boilerplate injected into agent prompts. | + +### Workflow References + +| Reference | Role | +|-----------|------| +| `agent-contracts.md` | Formal interface between orchestrators and agents. | +| `context-budget.md` | Context window budget allocation rules. | +| `continuation-format.md` | Session continuation/resume format. | +| `domain-probes.md` | Domain-specific probing questions for discuss-phase. | +| `gate-prompts.md` | Gate/checkpoint prompt templates. | +| `revision-loop.md` | Plan revision iteration patterns. | +| `universal-anti-patterns.md` | Universal anti-patterns to detect and avoid. | +| `artifact-types.md` | Planning artifact type definitions. | +| `phase-argument-parsing.md` | Phase argument parsing conventions. | +| `decimal-phase-calculation.md` | Decimal sub-phase numbering rules. | +| `workstream-flag.md` | Workstream active-pointer conventions (`--ws`). | +| `user-profiling.md` | User behavioral profiling detection heuristics. | +| `thinking-partner.md` | Conditional thinking-partner activation at decision points. | +| `autonomous-smart-discuss.md` | Smart-discuss logic for autonomous mode. | +| `ios-scaffold.md` | iOS application scaffolding patterns. | +| `ai-evals.md` | AI evaluation design reference for `/gsd-ai-integration-phase`. | +| `ai-frameworks.md` | AI framework decision-matrix reference for `gsd-framework-selector`. | +| `executor-examples.md` | Worked examples for the gsd-executor agent. | +| `doc-conflict-engine.md` | Shared conflict-detection contract for ingest/import workflows. | + +### Sketch References + +References consumed by the `/gsd-sketch` workflow and its wrap-up companion. + +| Reference | Role | +|-----------|------| +| `sketch-interactivity.md` | Rules for making HTML sketches feel interactive and alive. | +| `sketch-theme-system.md` | Shared CSS theme variable system for cross-sketch consistency. | +| `sketch-tooling.md` | Floating toolbar utilities included in every sketch. | +| `sketch-variant-patterns.md` | Multi-variant HTML patterns (tabs, side-by-side, overlays). | + +### Thinking-Model References + +References for integrating thinking-class models (o3, o4-mini, Gemini 2.5 Pro) into GSD workflows. + +| Reference | Role | +|-----------|------| +| `thinking-models-debug.md` | Thinking-model patterns for debug workflows. | +| `thinking-models-execution.md` | Thinking-model patterns for execution agents. | +| `thinking-models-planning.md` | Thinking-model patterns for planning agents. | +| `thinking-models-research.md` | Thinking-model patterns for research agents. | +| `thinking-models-verification.md` | Thinking-model patterns for verification agents. | + +### Modular Planner Decomposition + +The `gsd-planner` agent is decomposed into a core agent plus reference modules to fit runtime character limits. + +| Reference | Role | +|-----------|------| +| `planner-antipatterns.md` | Planner anti-patterns and specificity examples. | +| `planner-gap-closure.md` | Gap-closure mode behavior (reads VERIFICATION.md, targeted replanning). | +| `planner-reviews.md` | Cross-AI review integration (reads REVIEWS.md from `/gsd-review`). | +| `planner-revision.md` | Plan revision patterns for iterative refinement. | +| `planner-source-audit.md` | Planner source-audit and authority-limit rules. | + +> **Subdirectory:** `get-shit-done/references/few-shot-examples/` contains additional few-shot examples (`plan-checker.md`, `verifier.md`) that are referenced from specific agents. These are not counted in the 49 top-level references. + +--- + +## CLI Modules (24 shipped) + +Full listing: `get-shit-done/bin/lib/*.cjs`. + +| Module | Responsibility | +|--------|----------------| +| `audit.cjs` | Audit dispatch, audit open sessions, audit storage helpers | +| `commands.cjs` | Misc CLI commands (slug, timestamp, todos, scaffolding, stats) | +| `config.cjs` | `config.json` read/write, section initialization, `VALID_CONFIG_KEYS` | +| `core.cjs` | Error handling, output formatting, shared utilities, runtime fallbacks | +| `docs.cjs` | Docs-update workflow init, Markdown scanning, monorepo detection | +| `frontmatter.cjs` | YAML frontmatter CRUD operations | +| `graphify.cjs` | Knowledge-graph build/query/status/diff for `/gsd-graphify` | +| `gsd2-import.cjs` | External-plan ingest for `/gsd-from-gsd2` | +| `init.cjs` | Compound context loading for each workflow type | +| `intel.cjs` | Codebase intel store backing `/gsd-intel` and `gsd-intel-updater` | +| `learnings.cjs` | Cross-phase learnings extraction for `/gsd-extract-learnings` | +| `milestone.cjs` | Milestone archival, requirements marking | +| `model-profiles.cjs` | Model profile resolution table (authoritative profile data) | +| `phase.cjs` | Phase directory operations, decimal numbering, plan indexing | +| `profile-output.cjs` | Profile rendering, USER-PROFILE.md and dev-preferences.md generation | +| `profile-pipeline.cjs` | User behavioral profiling data pipeline, session file scanning | +| `roadmap.cjs` | ROADMAP.md parsing, phase extraction, plan progress | +| `schema-detect.cjs` | Schema-drift detection for ORM patterns (Prisma, Drizzle, etc.) | +| `security.cjs` | Path traversal prevention, prompt injection detection, safe JSON/shell helpers | +| `state.cjs` | STATE.md parsing, updating, progression, metrics | +| `template.cjs` | Template selection and filling with variable substitution | +| `uat.cjs` | UAT file parsing, verification debt tracking, audit-uat support | +| `verify.cjs` | Plan structure, phase completeness, reference, commit validation | +| `workstream.cjs` | Workstream CRUD, migration, session-scoped active pointer | + +[`docs/CLI-TOOLS.md`](CLI-TOOLS.md) may describe a subset of these modules; when it disagrees with the filesystem, this table and the directory listing are authoritative. + +--- + +## Hooks (11 shipped) + +Full listing: `hooks/`. + +| Hook | Event | Purpose | +|------|-------|---------| +| `gsd-statusline.js` | `statusLine` | Displays model, task, directory, context usage | +| `gsd-context-monitor.js` | `PostToolUse` / `AfterTool` | Injects agent-facing context warnings at 35%/25% remaining | +| `gsd-check-update.js` | `SessionStart` | Background check for new GSD versions | +| `gsd-check-update-worker.js` | (worker) | Background worker helper for check-update | +| `gsd-prompt-guard.js` | `PreToolUse` | Scans `.planning/` writes for prompt-injection patterns (advisory) | +| `gsd-workflow-guard.js` | `PreToolUse` | Detects file edits outside GSD workflow context (advisory, opt-in) | +| `gsd-read-guard.js` | `PreToolUse` | Advisory guard preventing Edit/Write on unread files | +| `gsd-read-injection-scanner.js` | `PostToolUse` | Scans tool Read results for prompt-injection patterns (v1.36+, PR #2201) | +| `gsd-session-state.sh` | `PostToolUse` | Session-state tracking for shell-based runtimes | +| `gsd-validate-commit.sh` | `PostToolUse` | Commit validation for conventional-commit enforcement | +| `gsd-phase-boundary.sh` | `PostToolUse` | Phase-boundary detection for workflow transitions | + +--- + +## Maintenance + +- When a new command, agent, workflow, reference, CLI module, or hook ships, update the corresponding section here before the release is cut. +- The drift-guard tests under `tests/` (see "How To Use This File" above) assert that every shipped file is enumerated in this inventory. A new file without a matching row here will fail CI. +- When the filesystem diverges from `docs/ARCHITECTURE.md` counts or from curated-subset docs (e.g. `docs/AGENTS.md`'s primary roster), this file is the source of truth. diff --git a/docs/README.md b/docs/README.md index 609c4240d..1b029cb83 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,18 +9,18 @@ Language versions: [English](README.md) · [Português (pt-BR)](pt-BR/README.md) | Document | Audience | Description | |----------|----------|-------------| | [Architecture](ARCHITECTURE.md) | Contributors, advanced users | System architecture, agent model, data flow, and internal design | -| [Feature Reference](FEATURES.md) | All users | Complete feature and function documentation with requirements | -| [Command Reference](COMMANDS.md) | All users | Every command with syntax, flags, options, and examples | +| [Feature Reference](FEATURES.md) | All users | Feature narratives and requirements for released features (see [CHANGELOG](../CHANGELOG.md) for latest additions) | +| [Command Reference](COMMANDS.md) | All users | Stable commands with syntax, flags, options, and examples | | [Configuration Reference](CONFIGURATION.md) | All users | Full config schema, workflow toggles, model profiles, git branching | | [CLI Tools Reference](CLI-TOOLS.md) | Contributors, agent authors | `gsd-tools.cjs` programmatic API for workflows and agents | -| [Agent Reference](AGENTS.md) | Contributors, advanced users | All 18 specialized agents — roles, tools, spawn patterns | +| [Agent Reference](AGENTS.md) | Contributors, advanced users | Role cards for primary agents — roles, tools, spawn patterns (the `agents/` filesystem is authoritative) | | [User Guide](USER-GUIDE.md) | All users | Workflow walkthroughs, troubleshooting, and recovery | | [Context Monitor](context-monitor.md) | All users | Context window monitoring hook architecture | | [Discuss Mode](workflow-discuss-mode.md) | All users | Assumptions vs interview mode for discuss-phase | ## Quick Links -- **What's new in v1.32:** STATE.md consistency gates, `--to N` autonomous flag, research gate, verifier scope filtering, read-before-edit guard, 4 new runtimes (Trae, Kilo, Augment, Cline), context reduction, response language config — see [CHANGELOG](../CHANGELOG.md) +- **What's new:** see [CHANGELOG](../CHANGELOG.md) for current release notes, and upstream [README](../README.md) for release highlights - **Getting started:** [README](../README.md) → install → `/gsd-new-project` - **Full workflow walkthrough:** [User Guide](USER-GUIDE.md) - **All commands at a glance:** [Command Reference](COMMANDS.md) diff --git a/docs/USER-GUIDE.md b/docs/USER-GUIDE.md index 9a9e1a955..1baee361a 100644 --- a/docs/USER-GUIDE.md +++ b/docs/USER-GUIDE.md @@ -12,8 +12,7 @@ A detailed reference for workflows, troubleshooting, and configuration. For quic - [Backlog & Threads](#backlog--threads) - [Workstreams](#workstreams) - [Security](#security) -- [Command Reference](#command-reference) -- [Configuration Reference](#configuration-reference) +- [Command And Configuration Reference](#command-and-configuration-reference) - [Usage Examples](#usage-examples) - [Troubleshooting](#troubleshooting) - [Recovery Quick Reference](#recovery-quick-reference) @@ -522,222 +521,16 @@ For a focused assessment without full `/gsd-map-codebase` overhead: --- -## Command Reference +## Command And Configuration Reference -### Core Workflow +- **Command Reference:** see [`docs/COMMANDS.md`](COMMANDS.md) for every stable command's flags, subcommands, and examples. The authoritative shipped-command roster lives in [`docs/INVENTORY.md`](INVENTORY.md#commands-75-shipped). +- **Configuration Reference:** see [`docs/CONFIGURATION.md`](CONFIGURATION.md) for the full `config.json` schema, every setting's default and provenance, the per-agent model-profile table (including the `inherit` option for non-Claude runtimes), git branching strategies, and security settings. +- **Discuss Mode:** see [`docs/workflow-discuss-mode.md`](workflow-discuss-mode.md) for interview vs assumptions mode. -| Command | Purpose | When to Use | -|---------|---------|-------------| -| `/gsd-new-project` | Full project init: questions, research, requirements, roadmap | Start of a new project | -| `/gsd-new-project --auto @idea.md` | Automated init from document | Have a PRD or idea doc ready | -| `/gsd-discuss-phase [N]` | Capture implementation decisions | Before planning, to shape how it gets built | -| `/gsd-ui-phase [N]` | Generate UI design contract | After discuss-phase, before plan-phase (frontend phases) | -| `/gsd-plan-phase [N]` | Research + plan + verify | Before executing a phase | -| `/gsd-execute-phase ` | Execute all plans in parallel waves | After planning is complete | -| `/gsd-verify-work [N]` | Manual UAT with auto-diagnosis | After execution completes | -| `/gsd-ship [N]` | Create PR from verified work | After verification passes | -| `/gsd-fast ` | Inline trivial tasks — skips planning entirely | Typo fixes, config changes, small refactors | -| `/gsd-next` | Auto-detect state and run next step | Anytime — "what should I do next?" | -| `/gsd-ui-review [N]` | Retroactive 6-pillar visual audit | After execution or verify-work (frontend projects) | -| `/gsd-audit-milestone` | Verify milestone met its definition of done | Before completing milestone | -| `/gsd-complete-milestone` | Archive milestone, tag release | All phases verified | -| `/gsd-new-milestone [name]` | Start next version cycle | After completing a milestone | +This guide intentionally does not re-document commands or config settings: maintaining two copies previously produced drift (`workflow.discuss_mode`'s default, `claude_md_path`'s default, the model-profile table's agent coverage). The single-source-of-truth rule is enforced mechanically by the drift-guard tests anchored on `docs/INVENTORY.md`. -### Navigation - -| Command | Purpose | When to Use | -|---------|---------|-------------| -| `/gsd-progress` | Show status and next steps | Anytime -- "where am I?" | -| `/gsd-resume-work` | Restore full context from last session | Starting a new session | -| `/gsd-pause-work` | Save structured handoff (HANDOFF.json + continue-here.md) | Stopping mid-phase | -| `/gsd-session-report` | Generate session summary with work and outcomes | End of session, stakeholder sharing | -| `/gsd-help` | Show all commands | Quick reference | -| `/gsd-update` | Update GSD with changelog preview | Check for new versions | -| `/gsd-join-discord` | Open Discord community invite | Questions or community | - -### Phase Management - -| Command | Purpose | When to Use | -|---------|---------|-------------| -| `/gsd-add-phase` | Append new phase to roadmap | Scope grows after initial planning | -| `/gsd-insert-phase [N]` | Insert urgent work (decimal numbering) | Urgent fix mid-milestone | -| `/gsd-remove-phase [N]` | Remove future phase and renumber | Descoping a feature | -| `/gsd-list-phase-assumptions [N]` | Preview Claude's intended approach | Before planning, to validate direction | -| `/gsd-analyze-dependencies` | Detect phase dependencies for ROADMAP.md | Before `/gsd-manager` when phases have empty `Depends on` | -| `/gsd-plan-milestone-gaps` | Create phases for audit gaps | After audit finds missing items | -| `/gsd-research-phase [N]` | Deep ecosystem research only | Complex or unfamiliar domain | - -### Brownfield & Utilities - -| Command | Purpose | When to Use | -|---------|---------|-------------| -| `/gsd-map-codebase` | Analyze existing codebase (4 parallel agents) | Before `/gsd-new-project` on existing code | -| `/gsd-scan [--focus area]` | Rapid single-focus codebase scan (1 agent) | Quick assessment of a specific area | -| `/gsd-intel [query\|status\|diff\|refresh]` | Query codebase intelligence index | Look up APIs, deps, or architecture decisions | -| `/gsd-explore [topic]` | Socratic ideation — think through an idea before committing | Exploring unfamiliar solution space | -| `/gsd-quick` | Ad-hoc task with GSD guarantees | Bug fixes, small features, config changes | -| `/gsd-autonomous` | Run remaining phases autonomously (`--from N`, `--to N`) | Hands-free multi-phase execution | -| `/gsd-undo --last N\|--phase NN\|--plan NN-MM` | Safe git revert using phase manifest | Roll back a bad execution | -| `/gsd-import --from ` | Ingest external plan with conflict detection | Import plans from teammates or other tools | -| `/gsd-debug [desc]` | Systematic debugging with persistent state (`--diagnose` for no-fix mode) | When something breaks | -| `/gsd-forensics` | Diagnostic report for workflow failures | When state, artifacts, or git history seem corrupted | -| `/gsd-add-todo [desc]` | Capture an idea for later | Think of something during a session | -| `/gsd-check-todos` | List pending todos | Review captured ideas | -| `/gsd-settings` | Configure workflow toggles and model profile | Change model, toggle agents | -| `/gsd-set-profile ` | Quick profile switch | Change cost/quality tradeoff | -| `/gsd-reapply-patches` | Restore local modifications after update | After `/gsd-update` if you had local edits | - -### Code Quality & Review - -| Command | Purpose | When to Use | -|---------|---------|-------------| -| `/gsd-review --phase N` | Cross-AI peer review from external CLIs | Before executing, to validate plans | -| `/gsd-code-review ` | Review source files changed in a phase for bugs and security issues | After execution, before verification | -| `/gsd-code-review-fix ` | Auto-fix issues found by `/gsd-code-review` | After code review produces REVIEW.md | -| `/gsd-audit-fix` | Autonomous audit-to-fix pipeline with classification and atomic commits | After UAT surfaces fixable issues | -| `/gsd-pr-branch` | Clean PR branch filtering `.planning/` commits | Before creating PR with planning-free diff | -| `/gsd-audit-uat` | Audit verification debt across all phases | Before milestone completion | - -### Backlog & Threads - -| Command | Purpose | When to Use | -|---------|---------|-------------| -| `/gsd-add-backlog ` | Add idea to backlog parking lot (999.x) | Ideas not ready for active planning | -| `/gsd-review-backlog` | Promote/keep/remove backlog items | Before new milestone, to prioritize | -| `/gsd-plant-seed ` | Forward-looking idea with trigger conditions | Ideas that should surface at a future milestone | -| `/gsd-thread [name]` | Persistent context threads | Cross-session work outside the phase structure | - ---- - -## Configuration Reference - -GSD stores project settings in `.planning/config.json`. Configure during `/gsd-new-project` or update later with `/gsd-settings`. - -### Full config.json Schema - -```json -{ - "mode": "interactive", - "granularity": "standard", - "model_profile": "balanced", - "planning": { - "commit_docs": true, - "search_gitignored": false - }, - "workflow": { - "research": true, - "plan_check": true, - "verifier": true, - "nyquist_validation": true, - "ui_phase": true, - "ui_safety_gate": true, - "research_before_questions": false, - "discuss_mode": "standard", - "skip_discuss": false - }, - "resolve_model_ids": "anthropic", - "hooks": { - "context_warnings": true, - "workflow_guard": false - }, - "git": { - "branching_strategy": "none", - "phase_branch_template": "gsd/phase-{phase}-{slug}", - "milestone_branch_template": "gsd/{milestone}-{slug}", - "quick_branch_template": null - } -} -``` - -### Core Settings - -| Setting | Options | Default | What it Controls | -|---------|---------|---------|------------------| -| `mode` | `interactive`, `yolo` | `interactive` | `yolo` auto-approves decisions; `interactive` confirms at each step | -| `granularity` | `coarse`, `standard`, `fine` | `standard` | Phase granularity: how finely scope is sliced (3-5, 5-8, or 8-12 phases) | -| `model_profile` | `quality`, `balanced`, `budget`, `inherit` | `balanced` | Model tier for each agent (see table below) | - -### Planning Settings - -| Setting | Options | Default | What it Controls | -|---------|---------|---------|------------------| -| `planning.commit_docs` | `true`, `false` | `true` | Whether `.planning/` files are committed to git | -| `planning.search_gitignored` | `true`, `false` | `false` | Add `--no-ignore` to broad searches to include `.planning/` | - -> **Note:** If `.planning/` is in `.gitignore`, `commit_docs` is automatically `false` regardless of the config value. - -### Workflow Toggles - -| Setting | Options | Default | What it Controls | -|---------|---------|---------|------------------| -| `workflow.research` | `true`, `false` | `true` | Domain investigation before planning | -| `workflow.plan_check` | `true`, `false` | `true` | Plan verification loop (up to 3 iterations) | -| `workflow.verifier` | `true`, `false` | `true` | Post-execution verification against phase goals | -| `workflow.nyquist_validation` | `true`, `false` | `true` | Validation architecture research during plan-phase; 8th plan-check dimension | -| `workflow.ui_phase` | `true`, `false` | `true` | Generate UI design contracts for frontend phases | -| `workflow.ui_safety_gate` | `true`, `false` | `true` | plan-phase prompts to run /gsd-ui-phase for frontend phases | -| `workflow.research_before_questions` | `true`, `false` | `false` | Run research before discussion questions instead of after | -| `workflow.discuss_mode` | `standard`, `assumptions` | `standard` | Discussion style: open-ended questions vs. codebase-driven assumptions | -| `workflow.skip_discuss` | `true`, `false` | `false` | Skip discuss-phase entirely in autonomous mode; writes minimal CONTEXT.md from ROADMAP phase goal | -| `response_language` | language code | (none) | Agent response language for cross-phase consistency (e.g., `"pt"`, `"ko"`, `"ja"`) | - -### Hook Settings - -| Setting | Options | Default | What it Controls | -|---------|---------|---------|------------------| -| `hooks.context_warnings` | `true`, `false` | `true` | Context window usage warnings | -| `hooks.workflow_guard` | `true`, `false` | `false` | Warn on file edits outside GSD workflow context | - -Disable workflow toggles to speed up phases in familiar domains or when conserving tokens. - -### Git Branching - -| Setting | Options | Default | What it Controls | -|---------|---------|---------|------------------| -| `git.branching_strategy` | `none`, `phase`, `milestone` | `none` | When and how branches are created | -| `git.phase_branch_template` | Template string | `gsd/phase-{phase}-{slug}` | Branch name for phase strategy | -| `git.milestone_branch_template` | Template string | `gsd/{milestone}-{slug}` | Branch name for milestone strategy | -| `git.quick_branch_template` | Template string or `null` | `null` | Optional branch name for `/gsd-quick` tasks | - -**Branching strategies explained:** - -| Strategy | Creates Branch | Scope | Best For | -|----------|---------------|-------|----------| -| `none` | Never | N/A | Solo development, simple projects | -| `phase` | At each `execute-phase` | One phase per branch | Code review per phase, granular rollback | -| `milestone` | At first `execute-phase` | All phases share one branch | Release branches, PR per version | - -**Template variables:** `{phase}` = zero-padded number (e.g., "03"), `{slug}` = lowercase hyphenated name, `{milestone}` = version (e.g., "v1.0"), `{num}` / `{quick}` = quick task ID (e.g., "260317-abc"). - -Example quick-task branching: - -```json -"git": { - "quick_branch_template": "gsd/quick-{num}-{slug}" -} -``` - -### Model Profiles (Per-Agent Breakdown) - -| Agent | `quality` | `balanced` | `budget` | `inherit` | -|-------|-----------|------------|----------|-----------| -| gsd-planner | Opus | Opus | Sonnet | Inherit | -| gsd-roadmapper | Opus | Sonnet | Sonnet | Inherit | -| gsd-executor | Opus | Sonnet | Sonnet | Inherit | -| gsd-phase-researcher | Opus | Sonnet | Haiku | Inherit | -| gsd-project-researcher | Opus | Sonnet | Haiku | Inherit | -| gsd-research-synthesizer | Sonnet | Sonnet | Haiku | Inherit | -| gsd-debugger | Opus | Sonnet | Sonnet | Inherit | -| gsd-codebase-mapper | Sonnet | Haiku | Haiku | Inherit | -| gsd-verifier | Sonnet | Sonnet | Haiku | Inherit | -| gsd-plan-checker | Sonnet | Sonnet | Haiku | Inherit | -| gsd-integration-checker | Sonnet | Sonnet | Haiku | Inherit | - -**Profile philosophy:** -- **quality** -- Opus for all decision-making agents, Sonnet for read-only verification. Use when quota is available and the work is critical. -- **balanced** -- Opus only for planning (where architecture decisions happen), Sonnet for everything else. The default for good reason. -- **budget** -- Sonnet for anything that writes code, Haiku for research and verification. Use for high-volume work or less critical phases. -- **inherit** -- All agents use the current session model. Best when switching models dynamically (e.g. OpenCode or Kilo `/model`), or when using Claude Code with non-Anthropic providers (OpenRouter, local models) to avoid unexpected API costs. For non-Claude runtimes (Codex, OpenCode, Gemini CLI, Kilo), the installer sets `resolve_model_ids: "omit"` automatically -- see [Non-Claude Runtimes](#using-non-claude-runtimes-codex-opencode-gemini-cli-kilo). + + --- diff --git a/docs/workflow-discuss-mode.md b/docs/workflow-discuss-mode.md index 70aa66056..c6da28b42 100644 --- a/docs/workflow-discuss-mode.md +++ b/docs/workflow-discuss-mode.md @@ -27,10 +27,10 @@ correction. Good for: ```bash # Enable assumptions mode -gsd-tools config-set workflow.discuss_mode assumptions +node gsd-tools.cjs config-set workflow.discuss_mode assumptions # Switch back to interview mode -gsd-tools config-set workflow.discuss_mode discuss +node gsd-tools.cjs config-set workflow.discuss_mode discuss ``` The setting is per-project (stored in `.planning/config.json`). diff --git a/get-shit-done/bin/lib/config.cjs b/get-shit-done/bin/lib/config.cjs index 8f8223e14..6b9d5e3a4 100644 --- a/get-shit-done/bin/lib/config.cjs +++ b/get-shit-done/bin/lib/config.cjs @@ -35,6 +35,9 @@ const VALID_CONFIG_KEYS = new Set([ 'workflow.plan_bounce', 'workflow.plan_bounce_script', 'workflow.plan_bounce_passes', + 'workflow.security_enforcement', + 'workflow.security_asvs_level', + 'workflow.security_block_on', 'git.branching_strategy', 'git.base_branch', 'git.phase_branch_template', 'git.milestone_branch_template', 'git.quick_branch_template', 'planning.commit_docs', 'planning.search_gitignored', 'workflow.cross_ai_execution', 'workflow.cross_ai_command', 'workflow.cross_ai_timeout', @@ -177,6 +180,9 @@ function buildNewProjectConfig(userChoices) { plan_bounce_script: null, plan_bounce_passes: 2, auto_prune_state: false, + security_enforcement: CONFIG_DEFAULTS.security_enforcement, + security_asvs_level: CONFIG_DEFAULTS.security_asvs_level, + security_block_on: CONFIG_DEFAULTS.security_block_on, }, hooks: { context_warnings: true, diff --git a/get-shit-done/bin/lib/core.cjs b/get-shit-done/bin/lib/core.cjs index c140c0af5..3e035f891 100644 --- a/get-shit-done/bin/lib/core.cjs +++ b/get-shit-done/bin/lib/core.cjs @@ -263,6 +263,9 @@ const CONFIG_DEFAULTS = { phase_naming: 'sequential', // 'sequential' (default, auto-increment) or 'custom' (arbitrary string IDs) project_code: null, // optional short prefix for phase dirs (e.g., 'CK' → 'CK-01-foundation') subagent_timeout: 300000, // 5 min default; increase for large codebases or slower models (ms) + security_enforcement: true, // workflow.security_enforcement — threat-model-anchored security verification via /gsd-secure-phase + security_asvs_level: 1, // workflow.security_asvs_level — OWASP ASVS verification level (1=opportunistic, 2=standard, 3=comprehensive) + security_block_on: 'high', // workflow.security_block_on — minimum severity that blocks phase advancement ('high' | 'medium' | 'low') }; function loadConfig(cwd) { diff --git a/get-shit-done/references/planning-config.md b/get-shit-done/references/planning-config.md index 921454ebb..c4eb93c20 100644 --- a/get-shit-done/references/planning-config.md +++ b/get-shit-done/references/planning-config.md @@ -265,6 +265,9 @@ Set via `workflow.*` namespace in config.json (e.g., `"workflow": { "research": | `workflow.code_review` | boolean | `true` | `true`, `false` | Enable built-in code review step in the ship workflow | | `workflow.code_review_depth` | string | `"standard"` | `"light"`, `"standard"`, `"deep"` | Depth level for code review analysis in the ship workflow | | `workflow._auto_chain_active` | boolean | `false` | `true`, `false` | Internal: tracks whether autonomous chaining is active | +| `workflow.security_enforcement` | boolean | `true` | `true`, `false` | Enable threat-model-anchored security verification via `/gsd-secure-phase`. When `false`, security checks are skipped entirely | +| `workflow.security_asvs_level` | number | `1` | `1`, `2`, `3` | OWASP ASVS verification level. Level 1 = opportunistic, Level 2 = standard, Level 3 = comprehensive | +| `workflow.security_block_on` | string | `"high"` | `"high"`, `"medium"`, `"low"` | Minimum severity that blocks phase advancement | ### Git Fields diff --git a/get-shit-done/workflows/plan-review-convergence.md b/get-shit-done/workflows/plan-review-convergence.md new file mode 100644 index 000000000..f02f2cd5f --- /dev/null +++ b/get-shit-done/workflows/plan-review-convergence.md @@ -0,0 +1,254 @@ + +Cross-AI plan convergence loop — automates the manual chain: +gsd-plan-phase N → gsd-review N --codex → gsd-plan-phase N --reviews → gsd-review N --codex → ... +Each step runs inside an isolated Agent that calls the corresponding Skill. +Orchestrator only does: init, loop control, HIGH count check, stall detection, escalation. + + + +Read all files referenced by the invoking prompt's execution_context before starting. + +@$HOME/.claude/get-shit-done/references/revision-loop.md +@$HOME/.claude/get-shit-done/references/gates.md +@$HOME/.claude/get-shit-done/references/agent-contracts.md + + + + +## 1. Parse and Normalize Arguments + +Extract from $ARGUMENTS: phase number, reviewer flags (`--codex`, `--gemini`, `--claude`, `--opencode`, `--all`), `--max-cycles N`, `--text`, `--ws`. + +```bash +PHASE=$(echo "$ARGUMENTS" | grep -oE '[0-9]+\.?[0-9]*' | head -1) + +REVIEWER_FLAGS="" +echo "$ARGUMENTS" | grep -q '\-\-codex' && REVIEWER_FLAGS="$REVIEWER_FLAGS --codex" +echo "$ARGUMENTS" | grep -q '\-\-gemini' && REVIEWER_FLAGS="$REVIEWER_FLAGS --gemini" +echo "$ARGUMENTS" | grep -q '\-\-claude' && REVIEWER_FLAGS="$REVIEWER_FLAGS --claude" +echo "$ARGUMENTS" | grep -q '\-\-opencode' && REVIEWER_FLAGS="$REVIEWER_FLAGS --opencode" +echo "$ARGUMENTS" | grep -q '\-\-all' && REVIEWER_FLAGS="$REVIEWER_FLAGS --all" +if [ -z "$REVIEWER_FLAGS" ]; then REVIEWER_FLAGS="--codex"; fi + +MAX_CYCLES=$(echo "$ARGUMENTS" | grep -oE '\-\-max-cycles\s+[0-9]+' | awk '{print $2}') +if [ -z "$MAX_CYCLES" ]; then MAX_CYCLES=3; fi + +GSD_WS="" +echo "$ARGUMENTS" | grep -qE '\-\-ws\s+\S+' && GSD_WS=$(echo "$ARGUMENTS" | grep -oE '\-\-ws\s+\S+') +``` + +## 2. Initialize + +```bash +INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init plan-phase "$PHASE") +if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi +``` + +Parse JSON for: `phase_dir`, `phase_number`, `padded_phase`, `phase_name`, `has_plans`, `plan_count`, `commit_docs`, `text_mode`, `response_language`. + +**If `response_language` is set:** All user-facing output should be in `{response_language}`. + +Set `TEXT_MODE=true` if `--text` is present in $ARGUMENTS OR `text_mode` from init JSON is `true`. When `TEXT_MODE` is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. + +## 3. Validate Phase + Pre-flight Gate + +```bash +PHASE_INFO=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" roadmap get-phase "${PHASE}") +``` + +**If `found` is false:** Error with available phases. Exit. + +Display startup banner: + +```text +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► PLAN CONVERGENCE — Phase {phase_number} +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + Reviewers: {REVIEWER_FLAGS} + Max cycles: {MAX_CYCLES} +``` + +## 4. Initial Planning (if no plans exist) + +**If `has_plans` is true:** Skip to step 5. Display: `Plans found: {plan_count} PLAN.md files — skipping initial planning.` + +**If `has_plans` is false:** + +Display: `◆ No plans found — spawning initial planning agent...` + +```text +Agent( + description="Initial planning Phase {PHASE}", + prompt="Run /gsd-plan-phase for Phase {PHASE}. + +Execute: Skill(skill='gsd-plan-phase', args='{PHASE} {GSD_WS}') + +Complete the full planning workflow. Do NOT return until planning is complete and PLAN.md files are committed.", + mode="auto" +) +``` + +After agent returns, verify plans were created: +```bash +PLAN_COUNT=$(ls ${phase_dir}/${padded_phase}-*-PLAN.md 2>/dev/null | wc -l) +``` + +If PLAN_COUNT == 0: Error — initial planning failed. Exit. + +Display: `Initial planning complete: ${PLAN_COUNT} PLAN.md files created.` + +## 5. Convergence Loop + +Initialize loop variables: + +```text +cycle = 0 +prev_high_count = Infinity +``` + +### 5a. Review (Spawn Agent) + +Increment `cycle`. + +Display: `◆ Cycle {cycle}/{MAX_CYCLES} — spawning review agent...` + +```text +Agent( + description="Cross-AI review Phase {PHASE} cycle {cycle}", + prompt="Run /gsd-review for Phase {PHASE}. + +Execute: Skill(skill='gsd-review', args='--phase {PHASE} {REVIEWER_FLAGS} {GSD_WS}') + +Complete the full review workflow. Do NOT return until REVIEWS.md is committed.", + mode="auto" +) +``` + +After agent returns, verify REVIEWS.md exists: +```bash +REVIEWS_FILE=$(ls ${phase_dir}/${padded_phase}-REVIEWS.md 2>/dev/null) +``` + +If REVIEWS_FILE is empty: Error — review agent did not produce REVIEWS.md. Exit. + +### 5b. Check for HIGH Concerns + +```bash +HIGH_COUNT=$(grep -c '\*\*HIGH' "${REVIEWS_FILE}" 2>/dev/null || true) +HIGH_COUNT=${HIGH_COUNT:-0} +HIGH_LINES=$(grep -B0 -A1 '\*\*HIGH' "${REVIEWS_FILE}" 2>/dev/null) +``` + +**If HIGH_COUNT == 0 (converged):** + +```bash +node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state planned-phase --phase "${PHASE}" --name "${phase_name}" --plans "${PLAN_COUNT}" +``` + +Display: +```text +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GSD ► CONVERGENCE COMPLETE ✓ +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + Phase {phase_number} converged in {cycle} cycle(s). + No HIGH concerns remaining. + + REVIEWS.md: {REVIEWS_FILE} + Next: /gsd-execute-phase {PHASE} +``` + +Exit — convergence achieved. + +**If HIGH_COUNT > 0:** Continue to 5c. + +### 5c. Stall Detection + Escalation Check + +Display: `◆ Cycle {cycle}/{MAX_CYCLES} — {HIGH_COUNT} HIGH concerns found` + +**Stall detection:** If `HIGH_COUNT >= prev_high_count`: +```text +⚠ Convergence stalled — HIGH concern count not decreasing + ({HIGH_COUNT} HIGH concerns, previous cycle had {prev_high_count}) +``` + +**Max cycles check:** If `cycle >= MAX_CYCLES`: + +If `TEXT_MODE` is true, present as plain-text numbered list: +```text +Plan convergence did not complete after {MAX_CYCLES} cycles. +{HIGH_COUNT} HIGH concerns remain: + +{HIGH_LINES} + +How would you like to proceed? + +1. Proceed anyway — Accept plans with remaining HIGH concerns and move to execution +2. Manual review — Stop here, review REVIEWS.md and address concerns manually + +Enter number: +``` + +Otherwise use AskUserQuestion: +```js +AskUserQuestion([ + { + question: "Plan convergence did not complete after {MAX_CYCLES} cycles. {HIGH_COUNT} HIGH concerns remain:\n\n{HIGH_LINES}\n\nHow would you like to proceed?", + header: "Convergence", + multiSelect: false, + options: [ + { label: "Proceed anyway", description: "Accept plans with remaining HIGH concerns and move to execution" }, + { label: "Manual review", description: "Stop here — review REVIEWS.md and address concerns manually" } + ] + } +]) +``` + +If "Proceed anyway": Display final status and exit. +If "Manual review": +```text +Review the concerns in: {REVIEWS_FILE} + +To replan manually: /gsd-plan-phase {PHASE} --reviews +To restart loop: /gsd-plan-review-convergence {PHASE} {REVIEWER_FLAGS} +``` +Exit workflow. + +### 5d. Replan (Spawn Agent) + +**If under max cycles:** + +Update `prev_high_count = HIGH_COUNT`. + +Display: `◆ Spawning replan agent with review feedback...` + +```text +Agent( + description="Replan Phase {PHASE} with review feedback cycle {cycle}", + prompt="Run /gsd-plan-phase with --reviews for Phase {PHASE}. + +Execute: Skill(skill='gsd-plan-phase', args='{PHASE} --reviews --skip-research {GSD_WS}') + +This will replan incorporating cross-AI review feedback from REVIEWS.md. +Do NOT return until replanning is complete and updated PLAN.md files are committed. + +IMPORTANT: When gsd-plan-phase outputs '## PLANNING COMPLETE', that means replanning is done. Return at that point.", + mode="auto" +) +``` + +After agent returns → go back to **step 5a** (review again). + + + + +- [ ] Initial planning via Agent → Skill("gsd-plan-phase") if no plans exist +- [ ] Review via Agent → Skill("gsd-review") — isolated, not inline +- [ ] Replan via Agent → Skill("gsd-plan-phase --reviews") — isolated, not inline +- [ ] Orchestrator only does: init, loop control, grep HIGHs, stall detection, escalation +- [ ] Each Agent fully completes its Skill before returning +- [ ] Loop exits on: no HIGH concerns (converged) OR max cycles (escalation) +- [ ] Stall detection reported when HIGH count not decreasing +- [ ] STATE.md updated on convergence completion + diff --git a/tests/agents-doc-parity.test.cjs b/tests/agents-doc-parity.test.cjs new file mode 100644 index 000000000..6b8ede03d --- /dev/null +++ b/tests/agents-doc-parity.test.cjs @@ -0,0 +1,42 @@ +'use strict'; + +/** + * For every `agents/gsd-*.md`, assert its agent name appears as a row + * in docs/INVENTORY.md's Agents table. AGENTS.md card presence is NOT + * enforced — that file is allowed to be a curated subset (primary + * cards + advanced stubs). + * + * Related: docs readiness refresh, lane-12 recommendation. + */ + +const { describe, test } = require('node:test'); +const assert = require('node:assert/strict'); +const fs = require('node:fs'); +const path = require('node:path'); + +const ROOT = path.resolve(__dirname, '..'); +const AGENTS_DIR = path.join(ROOT, 'agents'); +const INVENTORY_MD = fs.readFileSync(path.join(ROOT, 'docs', 'INVENTORY.md'), 'utf8'); + +const agentFiles = fs + .readdirSync(AGENTS_DIR) + .filter((f) => /^gsd-.*\.md$/.test(f)); + +function mentionedInInventoryAgents(name) { + // Row form in the Agents table: `| agent-name | role | ... |` + // The Agents table uses the raw name (no code fence) in column 1. + const rowRe = new RegExp(`^\\|\\s*${name.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\$&')}\\s*\\|`, 'm'); + return rowRe.test(INVENTORY_MD); +} + +describe('every shipped agent has a row in INVENTORY.md', () => { + for (const file of agentFiles) { + const name = file.replace(/\.md$/, ''); + test(name, () => { + assert.ok( + mentionedInInventoryAgents(name), + `agents/${file} has no row in docs/INVENTORY.md Agents table — add one`, + ); + }); + } +}); diff --git a/tests/architecture-counts.test.cjs b/tests/architecture-counts.test.cjs deleted file mode 100644 index 9b2ea8b69..000000000 --- a/tests/architecture-counts.test.cjs +++ /dev/null @@ -1,59 +0,0 @@ -'use strict'; - -/** - * Guards ARCHITECTURE.md component counts against drift. - * - * Both sides are computed at test runtime — no hardcoded numbers. - * Parsing ARCHITECTURE.md: regex extracts the documented count. - * Filesystem count: readdirSync filters to *.md files. - * - * To add a new component: append a row to COMPONENTS below and update - * docs/ARCHITECTURE.md with a matching "**Total