From 641ea8ad42bc3083e9ea8dfd8392667e5268e6d9 Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Mon, 6 Apr 2026 16:25:41 -0400 Subject: [PATCH] docs: update documentation for v1.34.0 release (#1868) --- docs/ARCHITECTURE.md | 30 +++-- docs/COMMANDS.md | 162 +++++++++++++++++++++++- docs/CONFIGURATION.md | 22 +++- docs/FEATURES.md | 285 ++++++++++++++++++++++++++++++++++++++++++ docs/USER-GUIDE.md | 91 +++++++++++++- 5 files changed, 577 insertions(+), 13 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 91b969a7a..acfd20828 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:** 60 +**Total commands:** 69 ### 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:** 60 +**Total workflows:** 68 ### Agents (`agents/*.md`) @@ -134,23 +134,26 @@ Specialized agent definitions with frontmatter specifying: - `tools` — Allowed tool access (Read, Write, Edit, Bash, Grep, Glob, WebSearch, etc.) - `color` — Terminal output color for visual distinction -**Total agents:** 21 +**Total agents:** 24 ### References (`get-shit-done/references/*.md`) -Shared knowledge documents that workflows and agents `@-reference` (25 total): +Shared knowledge documents that workflows and agents `@-reference` (35 total): **Core references:** - `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 **Workflow references:** - `agent-contracts.md` — Formal interface between orchestrators and agents @@ -165,6 +168,17 @@ Shared knowledge documents that workflows and agents `@-reference` (25 total): - `decimal-phase-calculation.md` — Decimal sub-phase numbering rules - `workstream-flag.md` — Workstream active pointer conventions - `user-profiling.md` — User behavioral profiling methodology +- `thinking-partner.md` — Conditional thinking partner activation at decision points + +**Thinking model references:** + +References for integrating thinking-class models (o3, o4-mini, Gemini 2.5 Pro) into GSD workflows: + +- `thinking-models-debug.md` — Thinking model patterns for debugging 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:** @@ -395,14 +409,14 @@ UI-SPEC.md (per phase) ─────────────────── ``` ~/.claude/ # Claude Code (global install) -├── commands/gsd/*.md # 60 slash commands +├── commands/gsd/*.md # 69 slash commands ├── get-shit-done/ │ ├── bin/gsd-tools.cjs # CLI utility │ ├── bin/lib/*.cjs # 19 domain modules -│ ├── workflows/*.md # 60 workflow definitions -│ ├── references/*.md # 25 shared reference docs +│ ├── workflows/*.md # 68 workflow definitions +│ ├── references/*.md # 35 shared reference docs │ └── templates/ # Planning artifact templates -├── agents/*.md # 21 agent definitions +├── agents/*.md # 24 agent definitions ├── hooks/ │ ├── gsd-statusline.js # Statusline hook │ ├── gsd-context-monitor.js # Context warning hook diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md index 178948461..976be62c4 100644 --- a/docs/COMMANDS.md +++ b/docs/COMMANDS.md @@ -542,6 +542,57 @@ Show all commands and usage guide. ## Utility Commands +### `/gsd-explore` + +Socratic ideation session — guide an idea through probing questions, optionally spawn research, then route output to the right GSD artifact (notes, todos, seeds, research questions, requirements, or a new phase). + +| Argument | Required | Description | +|----------|----------|-------------| +| `topic` | No | Topic to explore (e.g., `/gsd-explore authentication strategy`) | + +```bash +/gsd-explore # Open-ended ideation session +/gsd-explore authentication strategy # Explore a specific topic +``` + +--- + +### `/gsd-undo` + +Safe git revert — roll back GSD phase or plan commits using the phase manifest with dependency checks and a confirmation gate. + +| Flag | Required | Description | +|------|----------|-------------| +| `--last N` | (one of three required) | Show recent GSD commits for interactive selection | +| `--phase NN` | (one of three required) | Revert all commits for a phase | +| `--plan NN-MM` | (one of three required) | Revert all commits for a specific plan | + +**Safety:** Checks dependent phases/plans before reverting; always shows a confirmation gate. + +```bash +/gsd-undo --last 5 # Pick from the 5 most recent GSD commits +/gsd-undo --phase 03 # Revert all commits for phase 3 +/gsd-undo --plan 03-02 # Revert commits for plan 02 of phase 3 +``` + +--- + +### `/gsd-import` + +Ingest an external plan file into the GSD planning system with conflict detection against `PROJECT.md` decisions before writing anything. + +| Flag | Required | Description | +|------|----------|-------------| +| `--from ` | **Yes** | Path to the external plan file to import | + +**Process:** Detects conflicts → prompts for resolution → writes as GSD PLAN.md → validates via `gsd-plan-checker` + +```bash +/gsd-import --from /tmp/team-plan.md # Import and validate an external plan +``` + +--- + ### `/gsd-quick` Execute ad-hoc task with GSD guarantees. @@ -809,6 +860,46 @@ Analyze existing codebase with parallel mapper agents. --- +### `/gsd-scan` + +Rapid single-focus codebase assessment — lightweight alternative to `/gsd-map-codebase` that spawns one mapper agent instead of four parallel ones. + +| Flag | Description | +|------|-------------| +| `--focus tech\|arch\|quality\|concerns\|tech+arch` | Focus area (default: `tech+arch`) | + +**Produces:** Targeted document(s) in `.planning/codebase/` + +```bash +/gsd-scan # Quick tech + arch overview +/gsd-scan --focus quality # Quality and code health only +/gsd-scan --focus concerns # Surface concerns and risk areas +``` + +--- + +### `/gsd-intel` + +Query, inspect, or refresh queryable codebase intelligence files stored in `.planning/intel/`. Requires `intel.enabled: true` in `config.json`. + +| Argument | Description | +|----------|-------------| +| `query ` | Search intel files for a term | +| `status` | Show intel file freshness (FRESH/STALE) | +| `diff` | Show changes since last snapshot | +| `refresh` | Rebuild all intel files from codebase analysis | + +**Produces:** `.planning/intel/` JSON files (stack, api-map, dependency-graph, file-roles, arch-decisions) + +```bash +/gsd-intel status # Check freshness of intel files +/gsd-intel query authentication # Search intel for a term +/gsd-intel diff # What changed since last snapshot +/gsd-intel refresh # Rebuild intel index +``` + +--- + ## Update Commands ### `/gsd-update` @@ -829,6 +920,75 @@ Restore local modifications after a GSD update. --- +## Code Quality Commands + +### `/gsd-code-review` + +Review source files changed during a phase for bugs, security vulnerabilities, and code quality problems. + +| Argument | Required | Description | +|----------|----------|-------------| +| `N` | **Yes** | Phase number whose changes to review (e.g., `2` or `02`) | +| `--depth=quick\|standard\|deep` | No | Review depth level (overrides `workflow.code_review_depth` config). `quick`: pattern-matching only (~2 min). `standard`: per-file analysis with language-specific checks (~5–15 min, default). `deep`: cross-file analysis including import graphs and call chains (~15–30 min) | +| `--files file1,file2,...` | No | Explicit comma-separated file list; skips SUMMARY/git scoping entirely | + +**Prerequisites:** Phase has been executed and has SUMMARY.md or git history +**Produces:** `{phase}-REVIEW.md` in phase directory with severity-classified findings +**Spawns:** `gsd-code-reviewer` agent + +```bash +/gsd-code-review 3 # Standard review for phase 3 +/gsd-code-review 2 --depth=deep # Deep cross-file review +/gsd-code-review 4 --files src/auth.ts,src/token.ts # Explicit file list +``` + +--- + +### `/gsd-code-review-fix` + +Auto-fix issues found by `/gsd-code-review`. Reads `REVIEW.md`, spawns a fixer agent, commits each fix atomically, and produces a `REVIEW-FIX.md` summary. + +| Argument | Required | Description | +|----------|----------|-------------| +| `N` | **Yes** | Phase number whose REVIEW.md to fix | +| `--all` | No | Include Info findings in fix scope (default: Critical + Warning only) | +| `--auto` | No | Enable fix + re-review iteration loop, capped at 3 iterations | + +**Prerequisites:** Phase has a `{phase}-REVIEW.md` file (run `/gsd-code-review` first) +**Produces:** `{phase}-REVIEW-FIX.md` with applied fixes summary +**Spawns:** `gsd-code-fixer` agent + +```bash +/gsd-code-review-fix 3 # Fix Critical + Warning findings for phase 3 +/gsd-code-review-fix 3 --all # Include Info findings +/gsd-code-review-fix 3 --auto # Fix and re-review until clean (max 3 iterations) +``` + +--- + +### `/gsd-audit-fix` + +Autonomous audit-to-fix pipeline — runs an audit, classifies findings, fixes auto-fixable issues with test verification, and commits each fix atomically. + +| Flag | Description | +|------|-------------| +| `--source ` | Which audit to run (default: `audit-uat`) | +| `--severity high\|medium\|all` | Minimum severity to process (default: `medium`) | +| `--max N` | Maximum findings to fix (default: 5) | +| `--dry-run` | Classify findings without fixing (shows classification table) | + +**Prerequisites:** At least one phase has been executed with UAT or verification +**Produces:** Fix commits with test verification; classification report + +```bash +/gsd-audit-fix # Run audit-uat, fix medium+ issues (max 5) +/gsd-audit-fix --severity high # Only fix high-severity issues +/gsd-audit-fix --dry-run # Preview classification without fixing +/gsd-audit-fix --max 10 --severity all # Fix up to 10 issues of any severity +``` + +--- + ## Fast & Inline Commands ### `/gsd-fast` @@ -848,8 +1008,6 @@ Execute a trivial task inline — no subagents, no planning overhead. For typo f --- -## Code Quality Commands - ### `/gsd-review` Cross-AI peer review of phase plans from external AI CLIs. diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index 45400b72b..d8afb080c 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -20,6 +20,7 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd-new "commit_docs": true, "search_gitignored": false }, + "context_profile": null, "workflow": { "research": true, "plan_check": true, @@ -34,7 +35,9 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd-new "discuss_mode": "discuss", "skip_discuss": false, "text_mode": false, - "use_worktrees": true + "use_worktrees": true, + "code_review": true, + "code_review_depth": "standard" }, "hooks": { "context_warnings": true, @@ -73,7 +76,18 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd-new "security_asvs_level": 1, "security_block_on": "high", "agent_skills": {}, - "response_language": null + "response_language": null, + "context_profile": null, + "features": { + "thinking_partner": false, + "global_learnings": false + }, + "learnings": { + "max_inject": 10 + }, + "intel": { + "enabled": false + } } ``` @@ -88,6 +102,7 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd-new | `model_profile` | enum | `quality`, `balanced`, `budget`, `inherit` | `balanced` | Model tier for each agent (see [Model Profiles](#model-profiles)) | | `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 | > **Note:** `granularity` was renamed from `depth` in v1.22.3. Existing configs are auto-migrated. @@ -113,6 +128,8 @@ All workflow toggles follow the **absent = enabled** pattern. If a key is missin | `workflow.skip_discuss` | boolean | `false` | When `true`, `/gsd-autonomous` bypasses the discuss-phase entirely, writing minimal CONTEXT.md from the ROADMAP phase goal. Useful for projects where developer preferences are fully captured in PROJECT.md/REQUIREMENTS.md. Added in v1.28 | | `workflow.text_mode` | boolean | `false` | Replaces AskUserQuestion TUI menus with plain-text numbered lists. Required for Claude Code remote sessions (`/rc` mode) where TUI menus don't render. Can also be set per-session with `--text` flag on discuss-phase. Added in v1.28 | | `workflow.use_worktrees` | boolean | `true` | When `false`, disables git worktree isolation for parallel execution. Users who prefer sequential execution or whose environment does not support worktrees can disable this. Added in v1.31 | +| `workflow.code_review` | boolean | `true` | Enable `/gsd-code-review` and `/gsd-code-review-fix` commands. When `false`, the commands exit with a configuration gate message. Added in v1.34 | +| `workflow.code_review_depth` | string | `standard` | Default review depth for `/gsd-code-review`: `quick` (pattern-matching only), `standard` (per-file analysis), or `deep` (cross-file with import graphs). Can be overridden per-run with `--depth=`. Added in v1.34 | ### Recommended Presets @@ -230,6 +247,7 @@ Toggle optional capabilities via the `features.*` config namespace. Feature flag |---------|------|---------|-------------| | `features.thinking_partner` | boolean | `false` | Enable thinking partner analysis at workflow decision points | | `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 | ### Usage diff --git a/docs/FEATURES.md b/docs/FEATURES.md index d3824873d..142353ace 100644 --- a/docs/FEATURES.md +++ b/docs/FEATURES.md @@ -86,6 +86,22 @@ - [Worktree Toggle](#66-worktree-toggle) - [Project Code Prefixing](#67-project-code-prefixing) - [Claude Code Skills Migration](#68-claude-code-skills-migration) +- [v1.34.0 Features](#v1340-features) + - [Global Learnings Store](#89-global-learnings-store) + - [Queryable Codebase Intelligence](#90-queryable-codebase-intelligence) + - [Execution Context Profiles](#91-execution-context-profiles) + - [Gates Taxonomy](#92-gates-taxonomy) + - [Code Review Pipeline](#93-code-review-pipeline) + - [Socratic Exploration](#94-socratic-exploration) + - [Safe Undo](#95-safe-undo) + - [Plan Import](#96-plan-import) + - [Rapid Codebase Scan](#97-rapid-codebase-scan) + - [Autonomous Audit-to-Fix](#98-autonomous-audit-to-fix) + - [Improved Prompt Injection Scanner](#99-improved-prompt-injection-scanner) + - [Stall Detection in Plan-Phase](#100-stall-detection-in-plan-phase) + - [Hard Stop Safety Gates in /gsd-next](#101-hard-stop-safety-gates-in-gsd-next) + - [Adaptive Model Preset](#102-adaptive-model-preset) + - [Post-Merge Hunk Verification](#103-post-merge-hunk-verification) - [v1.32 Features](#v132-features) - [STATE.md Consistency Gates](#69-statemd-consistency-gates) - [Autonomous `--to N` Flag](#70-autonomous---to-n-flag) @@ -1894,3 +1910,272 @@ Test suite that scans all agent, workflow, and command files for embedded inject | Setting | Type | Default | Description | |---------|------|---------|-------------| | `hooks.community` | boolean | `false` | Enable optional community hooks for commit validation, session state, and phase boundaries | + +--- + +## v1.34.0 Features + + - [Global Learnings Store](#89-global-learnings-store) + - [Queryable Codebase Intelligence](#90-queryable-codebase-intelligence) + - [Execution Context Profiles](#91-execution-context-profiles) + - [Gates Taxonomy](#92-gates-taxonomy) + - [Code Review Pipeline](#93-code-review-pipeline) + - [Socratic Exploration](#94-socratic-exploration) + - [Safe Undo](#95-safe-undo) + - [Plan Import](#96-plan-import) + - [Rapid Codebase Scan](#97-rapid-codebase-scan) + - [Autonomous Audit-to-Fix](#98-autonomous-audit-to-fix) + - [Improved Prompt Injection Scanner](#99-improved-prompt-injection-scanner) + - [Stall Detection in Plan-Phase](#100-stall-detection-in-plan-phase) + - [Hard Stop Safety Gates in /gsd-next](#101-hard-stop-safety-gates-in-gsd-next) + - [Adaptive Model Preset](#102-adaptive-model-preset) + - [Post-Merge Hunk Verification](#103-post-merge-hunk-verification) + +--- + +### 89. Global Learnings Store + +**Commands:** Auto-triggered at phase completion; consumed by planner +**Config:** `features.global_learnings` + +**Purpose:** Persist cross-session, cross-project learnings in a global store so the planner agent can learn from patterns across the entire project history — not just the current session. + +**Requirements:** +- REQ-LEARN-01: Learnings MUST be auto-copied from `.planning/` to the global store at phase completion +- REQ-LEARN-02: The planner agent MUST receive relevant learnings at spawn time via injection +- REQ-LEARN-03: Injection MUST be capped by `learnings.max_inject` to avoid context bloat +- REQ-LEARN-04: Feature MUST be opt-in via `features.global_learnings: true` + +**Config:** +| Setting | Type | Default | Description | +|---------|------|---------|-------------| +| `features.global_learnings` | boolean | `false` | Enable cross-project learnings pipeline | +| `learnings.max_inject` | number | (system default) | Maximum learnings entries injected into planner | + +--- + +### 90. Queryable Codebase Intelligence + +**Command:** `/gsd-intel [query |status|diff|refresh]` +**Config:** `intel.enabled` + +**Purpose:** Maintain a queryable JSON index of codebase structure, API surface, dependency graph, file roles, and architecture decisions in `.planning/intel/`. Enables targeted lookups without reading the entire codebase. + +**Requirements:** +- REQ-INTEL-01: Intel files MUST be stored as JSON in `.planning/intel/` +- REQ-INTEL-02: `query` mode MUST search across all intel files for a term and group results by file +- REQ-INTEL-03: `status` mode MUST report freshness (FRESH/STALE, stale threshold: 24 hours) +- REQ-INTEL-04: `diff` mode MUST compare current intel state to the last snapshot +- REQ-INTEL-05: `refresh` mode MUST spawn the intel-updater agent to rebuild all files +- REQ-INTEL-06: Feature MUST be opt-in via `intel.enabled: true` + +**Intel files produced:** +| File | Contents | +|------|----------| +| `stack.json` | Technology stack and dependencies | +| `api-map.json` | Exported functions and API surface | +| `dependency-graph.json` | Inter-module dependency relationships | +| `file-roles.json` | Role classification for each source file | +| `arch-decisions.json` | Detected architecture decisions | + +--- + +### 91. Execution Context Profiles + +**Config:** `context_profile` + +**Purpose:** Select a pre-configured execution context (mode, model, workflow settings) tuned for a specific type of work without manually adjusting individual settings. + +**Requirements:** +- REQ-CTX-01: `dev` profile MUST optimize for iterative development (balanced model, plan_check enabled) +- REQ-CTX-02: `research` profile MUST optimize for research-heavy work (higher model tier, research enabled) +- REQ-CTX-03: `review` profile MUST optimize for code review work (verifier and code_review enabled) + +**Available profiles:** `dev`, `research`, `review` + +**Config:** +| Setting | Type | Default | Description | +|---------|------|---------|-------------| +| `context_profile` | string | (none) | Execution context preset: `dev`, `research`, or `review` | + +--- + +### 92. Gates Taxonomy + +**References:** `get-shit-done/references/gates.md` +**Agents:** plan-checker, verifier + +**Purpose:** Define 4 canonical gate types that structure all workflow decision points, enabling plan-checker and verifier agents to apply consistent gate logic. + +**Gate types:** +| Type | Description | +|------|-------------| +| **Confirm** | User approves before proceeding (e.g., roadmap review) | +| **Quality** | Automated quality check must pass (e.g., plan verification loop) | +| **Safety** | Hard stop on detected risk or policy violation | +| **Transition** | Phase or milestone boundary acknowledgment | + +**Requirements:** +- REQ-GATES-01: plan-checker MUST classify each checkpoint as one of the 4 gate types +- REQ-GATES-02: verifier MUST apply gate logic appropriate to the gate type +- REQ-GATES-03: Hard stop safety gates MUST never be bypassed by `--auto` flags + +--- + +### 93. Code Review Pipeline + +**Commands:** `/gsd-code-review`, `/gsd-code-review-fix` + +**Purpose:** Structured review of source files changed during a phase, with a separate auto-fix pass that commits each fix atomically. + +**Requirements:** +- REQ-REVIEW-01: `gsd-code-review` MUST scope files to the phase using SUMMARY.md and git diff fallback +- REQ-REVIEW-02: Review MUST support three depth levels: `quick`, `standard`, `deep` +- REQ-REVIEW-03: Findings MUST be severity-classified: Critical, Warning, Info +- REQ-REVIEW-04: `gsd-code-review-fix` MUST read REVIEW.md and fix Critical + Warning findings by default +- REQ-REVIEW-05: Each fix MUST be committed atomically with a descriptive message +- REQ-REVIEW-06: `--auto` flag MUST enable fix + re-review iteration loop, capped at 3 iterations +- REQ-REVIEW-07: Feature MUST be gated by `workflow.code_review` config flag + +**Config:** +| Setting | Type | Default | Description | +|---------|------|---------|-------------| +| `workflow.code_review` | boolean | `true` | Enable code review commands | +| `workflow.code_review_depth` | string | `standard` | Default review depth: `quick`, `standard`, or `deep` | + +--- + +### 94. Socratic Exploration + +**Command:** `/gsd-explore [topic]` + +**Purpose:** Guide a developer through exploring an idea via Socratic probing questions before committing to a plan. Routes outputs to the appropriate GSD artifact: notes, todos, seeds, research questions, requirements updates, or a new phase. + +**Requirements:** +- REQ-EXPLORE-01: Exploration MUST use Socratic probing — ask questions before proposing solutions +- REQ-EXPLORE-02: Session MUST offer to route outputs to the appropriate GSD artifact +- REQ-EXPLORE-03: An optional topic argument MUST prime the first question +- REQ-EXPLORE-04: Exploration MUST optionally spawn a research agent for technical feasibility + +--- + +### 95. Safe Undo + +**Command:** `/gsd-undo --last N | --phase NN | --plan NN-MM` + +**Purpose:** Roll back GSD phase or plan commits safely using the phase manifest and git log, with dependency checks and a hard confirmation gate before any revert is applied. + +**Requirements:** +- REQ-UNDO-01: `--phase` mode MUST identify all commits for the phase via manifest and git log fallback +- REQ-UNDO-02: `--plan` mode MUST identify all commits for a specific plan +- REQ-UNDO-03: `--last N` mode MUST display recent GSD commits for interactive selection +- REQ-UNDO-04: System MUST check for dependent phases/plans before reverting +- REQ-UNDO-05: A confirmation gate MUST be shown before any git revert is executed + +--- + +### 96. Plan Import + +**Command:** `/gsd-import --from ` + +**Purpose:** Ingest an external plan file into the GSD planning system with conflict detection against `PROJECT.md` decisions, converting it to a valid GSD PLAN.md and validating it through the plan-checker. + +**Requirements:** +- REQ-IMPORT-01: Importer MUST detect conflicts between the external plan and existing PROJECT.md decisions +- REQ-IMPORT-02: All detected conflicts MUST be presented to the user for resolution before writing +- REQ-IMPORT-03: Imported plan MUST be written as a valid GSD PLAN.md format +- REQ-IMPORT-04: Written plan MUST pass `gsd-plan-checker` validation + +--- + +### 97. Rapid Codebase Scan + +**Command:** `/gsd-scan [--focus tech|arch|quality|concerns|tech+arch]` + +**Purpose:** Lightweight alternative to `/gsd-map-codebase` that spawns a single mapper agent for a specific focus area, producing targeted output in `.planning/codebase/` without the overhead of 4 parallel agents. + +**Requirements:** +- REQ-SCAN-01: Scan MUST spawn exactly one mapper agent (not four parallel agents) +- REQ-SCAN-02: Focus area MUST be one of: `tech`, `arch`, `quality`, `concerns`, `tech+arch` (default) +- REQ-SCAN-03: Output MUST be written to `.planning/codebase/` in the same format as `/gsd-map-codebase` + +--- + +### 98. Autonomous Audit-to-Fix + +**Command:** `/gsd-audit-fix [--source ] [--severity high|medium|all] [--max N] [--dry-run]` + +**Purpose:** End-to-end pipeline that runs an audit, classifies findings as auto-fixable vs. manual-only, then autonomously fixes auto-fixable issues with test verification and atomic commits. + +**Requirements:** +- REQ-AUDITFIX-01: Findings MUST be classified as auto-fixable or manual-only before any changes +- REQ-AUDITFIX-02: Each fix MUST be verified with tests before committing +- REQ-AUDITFIX-03: Each fix MUST be committed atomically +- REQ-AUDITFIX-04: `--dry-run` MUST show classification table without applying any fixes +- REQ-AUDITFIX-05: `--max N` MUST limit the number of fixes applied in one run (default: 5) + +--- + +### 99. Improved Prompt Injection Scanner + +**Hook:** `gsd-prompt-guard.js` +**Script:** `scripts/prompt-injection-scan.sh` + +**Purpose:** Enhanced detection of prompt injection attempts in planning artifacts, adding invisible Unicode character detection, encoding obfuscation patterns, and entropy-based analysis. + +**Requirements:** +- REQ-SCAN-INJ-01: Scanner MUST detect invisible Unicode characters (zero-width spaces, soft hyphens, etc.) +- REQ-SCAN-INJ-02: Scanner MUST detect encoding obfuscation patterns (base64-encoded instructions, homoglyphs) +- REQ-SCAN-INJ-03: Scanner MUST apply entropy analysis to flag high-entropy strings in unexpected positions +- REQ-SCAN-INJ-04: Scanner MUST remain advisory-only — detection is logged, not blocking + +--- + +### 100. Stall Detection in Plan-Phase + +**Command:** `/gsd-plan-phase` + +**Purpose:** Detect when the planner revision loop has stalled — producing the same output across multiple iterations — and break the cycle by escalating to a different strategy or exiting with a clear diagnostic. + +**Requirements:** +- REQ-STALL-01: Revision loop MUST detect identical plan output across consecutive iterations +- REQ-STALL-02: On stall detection, system MUST escalate strategy before retrying +- REQ-STALL-03: Maximum stall retries MUST be bounded (capped at the existing max 3 iterations) + +--- + +### 101. Hard Stop Safety Gates in /gsd-next + +**Command:** `/gsd-next` + +**Purpose:** Prevent `/gsd-next` from entering runaway loops by adding hard stop safety gates and a consecutive-call guard that interrupts autonomous chaining when repeated identical steps are detected. + +**Requirements:** +- REQ-NEXT-GATE-01: `/gsd-next` MUST track consecutive same-step calls +- REQ-NEXT-GATE-02: On repeated same-step, system MUST present a hard stop gate to the user +- REQ-NEXT-GATE-03: User MUST explicitly confirm to continue past a hard stop gate + +--- + +### 102. Adaptive Model Preset + +**Config:** `model_profile: "adaptive"` + +**Purpose:** Role-based model assignment that automatically selects the appropriate model tier based on the current agent's role, rather than applying a single tier to all agents. + +**Requirements:** +- REQ-ADAPTIVE-01: `adaptive` preset MUST assign model tiers based on agent role (planner → quality tier, executor → balanced tier, etc.) +- REQ-ADAPTIVE-02: `adaptive` MUST be selectable via `/gsd-set-profile adaptive` + +--- + +### 103. Post-Merge Hunk Verification + +**Command:** `/gsd-reapply-patches` + +**Purpose:** After applying local patches post-update, verify that all hunks were actually applied by comparing the expected patch content against the live filesystem. Surface any dropped or partial hunks immediately rather than silently accepting incomplete merges. + +**Requirements:** +- REQ-PATCH-VERIFY-01: Reapply-patches MUST verify each hunk was applied after the merge +- REQ-PATCH-VERIFY-02: Dropped or partial hunks MUST be reported to the user with file and line context +- REQ-PATCH-VERIFY-03: Verification MUST run after all patches are applied, not per-patch diff --git a/docs/USER-GUIDE.md b/docs/USER-GUIDE.md index 7f82f2b08..7e98ae047 100644 --- a/docs/USER-GUIDE.md +++ b/docs/USER-GUIDE.md @@ -387,6 +387,87 @@ The `security.cjs` module scans for known injection patterns (role overrides, in --- +## Code Review Workflow + +### Phase Code Review + +After executing a phase, run a structured code review before UAT: + +```bash +/gsd-code-review 3 # Review all changed files in phase 3 +/gsd-code-review 3 --depth=deep # Deep cross-file review (import graphs, call chains) +``` + +The reviewer scopes files automatically using SUMMARY.md (preferred) or git diff fallback. Findings are classified as Critical, Warning, or Info in `{phase}-REVIEW.md`. + +```bash +/gsd-code-review-fix 3 # Fix Critical + Warning findings atomically +/gsd-code-review-fix 3 --auto # Fix and re-review until clean (max 3 iterations) +``` + +### Autonomous Audit-to-Fix + +To run an audit and fix all auto-fixable issues in one pass: + +```bash +/gsd-audit-fix # Audit + classify + fix (medium+ severity, max 5) +/gsd-audit-fix --dry-run # Preview classification without fixing +``` + +### Code Review in the Full Phase Lifecycle + +The review step slots in after execution and before UAT: + +``` +/gsd-execute-phase N -> /gsd-code-review N -> /gsd-code-review-fix N -> /gsd-verify-work N +``` + +--- + +## Exploration & Discovery + +### Socratic Exploration + +Before committing to a new phase or plan, use `/gsd-explore` to think through the idea: + +```bash +/gsd-explore # Open-ended ideation +/gsd-explore "caching strategy" # Explore a specific topic +``` + +The exploration session guides you through probing questions, optionally spawns a research agent, and routes output to the appropriate GSD artifact: note, todo, seed, research question, requirements update, or new phase. + +### Codebase Intelligence + +For queryable codebase insights without reading the entire codebase, enable the intel system: + +```json +{ "intel": { "enabled": true } } +``` + +Then build the index: + +```bash +/gsd-intel refresh # Analyze codebase and write .planning/intel/ files +/gsd-intel query auth # Search for a term across all intel files +/gsd-intel status # Check freshness of intel files +/gsd-intel diff # See what changed since last snapshot +``` + +Intel files cover stack, API surface, dependency graph, file roles, and architecture decisions. + +### Quick Scan + +For a focused assessment without full `/gsd-map-codebase` overhead: + +```bash +/gsd-scan # Quick tech + arch overview +/gsd-scan --focus quality # Quality and code health only +/gsd-scan --focus concerns # Risk areas and concerns +``` + +--- + ## Command Reference ### Core Workflow @@ -436,9 +517,14 @@ The `security.cjs` module scans for known injection patterns (role overrides, in | Command | Purpose | When to Use | |---------|---------|-------------| -| `/gsd-map-codebase` | Analyze existing codebase | Before `/gsd-new-project` on existing code | +| `/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 | @@ -452,6 +538,9 @@ The `security.cjs` module scans for known injection patterns (role overrides, in | 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 |