diff --git a/docs/CLI-TOOLS.md b/docs/CLI-TOOLS.md index 2e1dcfb0f..9910a5784 100644 --- a/docs/CLI-TOOLS.md +++ b/docs/CLI-TOOLS.md @@ -21,6 +21,7 @@ node gsd-tools.cjs [args] [--raw] [--cwd ] |------|-------------| | `--raw` | Machine-readable output (JSON or plain text, no formatting) | | `--cwd ` | Override working directory (for sandboxed subagents) | +| `--ws ` | Target a specific workstream context (SDK only) | --- @@ -275,6 +276,10 @@ node gsd-tools.cjs init todos [area] node gsd-tools.cjs init milestone-op node gsd-tools.cjs init map-codebase node gsd-tools.cjs init progress + +# Workstream-scoped init (SDK --ws flag) +node gsd-tools.cjs init execute-phase --ws +node gsd-tools.cjs init plan-phase --ws ``` **Large payload handling:** When output exceeds ~50KB, the CLI writes to a temp file and returns `@file:/tmp/gsd-init-XXXXX.json`. Workflows check for the `@file:` prefix and read from disk: @@ -299,6 +304,22 @@ node gsd-tools.cjs requirements mark-complete --- +## Skill Manifest + +Pre-compute and cache skill discovery for faster command loading. + +```bash +# Generate skill manifest (writes to .claude/skill-manifest.json) +node gsd-tools.cjs skill-manifest + +# Generate with custom output path +node gsd-tools.cjs skill-manifest --output +``` + +Returns JSON mapping of all available GSD skills with their metadata (name, description, file path, argument hints). Used by the installer and session-start hooks to avoid repeated filesystem scans. + +--- + ## Utility Commands ```bash diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md index ad7f19f49..0e57387cd 100644 --- a/docs/COMMANDS.md +++ b/docs/COMMANDS.md @@ -151,6 +151,8 @@ Research, plan, and verify a phase. | `--prd ` | Use a PRD file instead of discuss-phase for context | | `--reviews` | Replan with cross-AI review feedback from REVIEWS.md | | `--validate` | Run state validation before planning begins | +| `--bounce` | Run external plan bounce validation after planning (uses `workflow.plan_bounce_script`) | +| `--skip-bounce` | Skip plan bounce even if enabled in config | **Prerequisites:** `.planning/ROADMAP.md` exists **Produces:** `{phase}-RESEARCH.md`, `{phase}-{N}-PLAN.md`, `{phase}-VALIDATION.md` @@ -160,6 +162,7 @@ Research, plan, and verify a phase. /gsd-plan-phase 3 --skip-research # Plan without research (familiar domain) /gsd-plan-phase --auto # Non-interactive planning /gsd-plan-phase 2 --validate # Validate state before planning +/gsd-plan-phase 1 --bounce # Plan + external bounce validation ``` --- @@ -173,6 +176,8 @@ Execute all plans in a phase with wave-based parallelization, or run a specific | `N` | **Yes** | Phase number to execute | | `--wave N` | No | Execute only Wave `N` in the phase | | `--validate` | No | Run state validation before execution begins | +| `--cross-ai` | No | Delegate execution to an external AI CLI (uses `workflow.cross_ai_command`) | +| `--no-cross-ai` | No | Force local execution even if cross-AI is enabled in config | **Prerequisites:** Phase has PLAN.md files **Produces:** per-plan `{phase}-{N}-SUMMARY.md`, git commits, and `{phase}-VERIFICATION.md` when the phase is fully complete @@ -181,6 +186,7 @@ Execute all plans in a phase with wave-based parallelization, or run a specific /gsd-execute-phase 1 # Execute phase 1 /gsd-execute-phase 1 --wave 2 # Execute only Wave 2 /gsd-execute-phase 1 --validate # Validate state before execution +/gsd-execute-phase 2 --cross-ai # Delegate phase 2 to external AI CLI ``` --- @@ -810,6 +816,36 @@ Post-mortem investigation of failed or stuck GSD workflows. --- +### `/gsd-extract-learnings` + +Extract reusable patterns, anti-patterns, and architectural decisions from completed phase work. + +| Argument | Required | Description | +|----------|----------|-------------| +| `N` | **Yes** | Phase number to extract learnings from | + +| Flag | Description | +|------|-------------| +| `--all` | Extract learnings from all completed phases | +| `--format` | Output format: `markdown` (default), `json` | + +**Prerequisites:** Phase has been executed (SUMMARY.md files exist) +**Produces:** `.planning/learnings/{phase}-LEARNINGS.md` + +**Extracts:** +- Architectural decisions and their rationale +- Patterns that worked well (reusable in future phases) +- Anti-patterns encountered and how they were resolved +- Technology-specific insights +- Performance and testing observations + +```bash +/gsd-extract-learnings 3 # Extract learnings from phase 3 +/gsd-extract-learnings --all # Extract from all completed phases +``` + +--- + ## Workstream Management ### `/gsd-workstreams` diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index eaae862c6..12d36792a 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -37,7 +37,14 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd-new "text_mode": false, "use_worktrees": true, "code_review": true, - "code_review_depth": "standard" + "code_review_depth": "standard", + "plan_bounce": false, + "plan_bounce_script": null, + "plan_bounce_passes": 1, + "code_review_command": null, + "cross_ai_execution": false, + "cross_ai_command": null, + "cross_ai_timeout": 300 }, "hooks": { "context_warnings": true, @@ -86,7 +93,8 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd-new }, "intel": { "enabled": false - } + }, + "claude_md_path": null } ``` @@ -102,6 +110,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 | > **Note:** `granularity` was renamed from `depth` in v1.22.3. Existing configs are auto-migrated. @@ -129,6 +138,13 @@ All workflow toggles follow the **absent = enabled** pattern. If a key is missin | `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 | +| `workflow.plan_bounce` | boolean | `false` | Run external validation script against generated plans. When enabled, the plan-phase orchestrator pipes each PLAN.md through the script specified by `plan_bounce_script` and blocks on non-zero exit. Added in v1.36 | +| `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 | `1` | 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.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 | ### Recommended Presets diff --git a/docs/FEATURES.md b/docs/FEATURES.md index 48ba6fc99..347a1624f 100644 --- a/docs/FEATURES.md +++ b/docs/FEATURES.md @@ -107,6 +107,15 @@ - [GSD-2 Reverse Migration](#105-gsd-2-reverse-migration) - [AI Integration Phase Wizard](#106-ai-integration-phase-wizard) - [AI Eval Review](#107-ai-eval-review) +- [v1.36.0 Features](#v1360-features) + - [Plan Bounce](#108-plan-bounce) + - [External Code Review Command](#109-external-code-review-command) + - [Cross-AI Execution Delegation](#110-cross-ai-execution-delegation) + - [Architectural Responsibility Mapping](#111-architectural-responsibility-mapping) + - [Extract Learnings](#112-extract-learnings) + - [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) - [v1.32 Features](#v132-features) - [STATE.md Consistency Gates](#69-statemd-consistency-gates) - [Autonomous `--to N` Flag](#70-autonomous---to-n-flag) @@ -2269,3 +2278,129 @@ Test suite that scans all agent, workflow, and command files for embedded inject - REQ-EVALREVIEW-04: `EVAL-REVIEW.md` MUST be written to the phase directory **Produces:** `{phase}-EVAL-REVIEW.md` with scored eval dimensions, gap analysis, and remediation steps + +--- + +## v1.36.0 Features + +### 108. Plan Bounce + +**Command:** `/gsd-plan-phase N --bounce` + +**Purpose:** After plans pass the checker, optionally refine them through an external script (a second AI, a linter, a custom validator). The bounce step backs up each plan, runs the script, validates YAML frontmatter integrity on the result, re-runs the plan checker, and restores the original if anything fails. + +**Requirements:** +- REQ-BOUNCE-01: `--bounce` flag or `workflow.plan_bounce: true` activates the step; `--skip-bounce` always disables it +- REQ-BOUNCE-02: `workflow.plan_bounce_script` must point to a valid executable; missing script produces a warning and skips +- REQ-BOUNCE-03: Each plan is backed up to `*-PLAN.pre-bounce.md` before the script runs +- REQ-BOUNCE-04: Bounced plans with broken YAML frontmatter or that fail the plan checker are restored from backup +- REQ-BOUNCE-05: `workflow.plan_bounce_passes` (default: 2) controls how many refinement passes the script receives + +**Configuration:** `workflow.plan_bounce`, `workflow.plan_bounce_script`, `workflow.plan_bounce_passes` + +--- + +### 109. External Code Review Command + +**Command:** `/gsd-ship` (enhanced) + +**Purpose:** Before the manual review step in `/gsd-ship`, automatically run an external code review command if configured. The command receives the diff and phase context via stdin and returns a JSON verdict (`APPROVED` or `REVISE`). Falls through to the existing manual review flow regardless of outcome. + +**Requirements:** +- REQ-EXTREVIEW-01: `workflow.code_review_command` must be set to a command string; null means skip +- REQ-EXTREVIEW-02: Diff is generated against `BASE_BRANCH` with `--stat` summary included +- REQ-EXTREVIEW-03: Review prompt is piped via stdin (never shell-interpolated) +- REQ-EXTREVIEW-04: 120-second timeout; stderr captured on failure +- REQ-EXTREVIEW-05: JSON output parsed for `verdict`, `confidence`, `summary`, `issues` fields + +**Configuration:** `workflow.code_review_command` + +--- + +### 110. Cross-AI Execution Delegation + +**Command:** `/gsd-execute-phase N --cross-ai` + +**Purpose:** Delegate individual plans to an external AI runtime for execution. Plans with `cross_ai: true` in their frontmatter (or all plans when `--cross-ai` is used) are sent to the configured command via stdin. Successfully handled plans are removed from the normal executor queue. + +**Requirements:** +- REQ-CROSSAI-01: `--cross-ai` forces all plans through cross-AI; `--no-cross-ai` disables it +- REQ-CROSSAI-02: `workflow.cross_ai_execution: true` and plan frontmatter `cross_ai: true` required for per-plan activation +- REQ-CROSSAI-03: Task prompt is piped via stdin to prevent injection +- REQ-CROSSAI-04: Dirty working tree produces a warning before execution +- REQ-CROSSAI-05: On failure, user chooses: retry, skip (fall back to normal executor), or abort + +**Configuration:** `workflow.cross_ai_execution`, `workflow.cross_ai_command`, `workflow.cross_ai_timeout` + +--- + +### 111. Architectural Responsibility Mapping + +**Command:** `/gsd-plan-phase` (enhanced research step) + +**Purpose:** During phase research, the phase-researcher now maps each capability to its architectural tier owner (browser, frontend server, API, CDN/static, database). The planner cross-references tasks against this map, and the plan-checker enforces tier compliance as Dimension 7c. + +**Requirements:** +- REQ-ARM-01: Phase researcher produces an Architectural Responsibility Map table in RESEARCH.md (Step 1.5) +- REQ-ARM-02: Planner sanity-checks task-to-tier assignments against the map +- REQ-ARM-03: Plan checker validates tier compliance as Dimension 7c (WARNING for general mismatches, BLOCKER for security-sensitive ones) + +**Produces:** `## Architectural Responsibility Map` section in `{phase}-RESEARCH.md` + +--- + +### 112. Extract Learnings + +**Command:** `/gsd-extract-learnings N` + +**Purpose:** Extract structured knowledge from completed phase artifacts. Reads PLAN.md and SUMMARY.md (required) plus VERIFICATION.md, UAT.md, and STATE.md (optional) to produce four categories of learnings: decisions, lessons, patterns, and surprises. Optionally captures each item to an external knowledge base via `capture_thought` tool. + +**Requirements:** +- REQ-LEARN-01: Requires PLAN.md and SUMMARY.md; exits with clear error if missing +- REQ-LEARN-02: Each extracted item includes source attribution (artifact and section) +- REQ-LEARN-03: If `capture_thought` tool is available, captures items with `source`, `project`, and `phase` metadata +- REQ-LEARN-04: If `capture_thought` is unavailable, completes successfully and logs that external capture was skipped +- REQ-LEARN-05: Running twice overwrites the previous `LEARNINGS.md` + +**Produces:** `{phase}-LEARNINGS.md` with YAML frontmatter (phase, project, counts per category, missing_artifacts) + +--- + +### 113. SDK Workstream Support + +**Command:** `gsd-sdk init @prd.md --ws my-workstream` + +**Purpose:** Route all SDK `.planning/` paths to `.planning/workstreams//`, enabling multi-workstream projects without "Project already exists" errors. The `--ws` flag validates the workstream name and propagates to all subsystems (tools, config, context engine). + +**Requirements:** +- REQ-WS-01: `--ws ` routes all `.planning/` paths to `.planning/workstreams//` +- REQ-WS-02: Without `--ws`, behavior is unchanged (flat mode) +- REQ-WS-03: Name validated to alphanumeric, hyphens, underscores, and dots only +- REQ-WS-04: Config resolves from workstream path first, falls back to root `.planning/config.json` + +--- + +### 114. Context-Window-Aware Prompt Thinning + +**Purpose:** Reduce static prompt overhead by ~40% for models with context windows under 200K tokens. Extended examples and anti-pattern lists are extracted from agent definitions into reference files loaded on demand via `@` required_reading. + +**Requirements:** +- REQ-THIN-01: When `CONTEXT_WINDOW < 200000`, executor and planner agent prompts omit inline examples +- REQ-THIN-02: Extracted content lives in `references/executor-examples.md` and `references/planner-antipatterns.md` +- REQ-THIN-03: Standard (200K-500K) and enriched (500K+) tiers are unaffected +- REQ-THIN-04: Core rules and decision logic remain inline; only verbose examples are extracted + +**Reference files:** `executor-examples.md`, `planner-antipatterns.md` + +--- + +### 115. Configurable CLAUDE.md Path + +**Purpose:** Allow projects to store their CLAUDE.md in a non-root location. The `claude_md_path` config key controls where `/gsd-profile-user` and related commands write the generated CLAUDE.md file. + +**Requirements:** +- REQ-CMDPATH-01: `claude_md_path` defaults to `./CLAUDE.md` +- REQ-CMDPATH-02: Profile generation commands read the path from config and write to the specified location +- REQ-CMDPATH-03: Relative paths are resolved from the project root + +**Configuration:** `claude_md_path`