From 7457e332631fd5cb5d59b129de1a7ecd37114596 Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Sun, 22 Mar 2026 12:10:06 -0400 Subject: [PATCH] docs: v1.28 release documentation update MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add documentation for all new features merged since v1.27: - Forensics command (/gsd:forensics) — post-mortem workflow investigation - Milestone Summary (/gsd:milestone-summary) — project summary for onboarding - Workstream Namespacing (/gsd:workstreams) — parallel milestone work - Manager Dashboard (/gsd:manager) — interactive phase command center - Assumptions Discussion Mode (workflow.discuss_mode) — codebase-first context - UI Phase Auto-Detection — surface /gsd:ui-phase for UI-heavy projects - Multi-Runtime Installer Selection — select multiple runtimes interactively Updated files: - README.md: new commands, config keys, assumptions mode callout - docs/COMMANDS.md: 4 new command entries with full syntax - docs/FEATURES.md: 7 new feature entries (#49-#55) with requirements - docs/CONFIGURATION.md: 3 new workflow config keys - docs/AGENTS.md: 2 new agents, count 15→18 - docs/USER-GUIDE.md: assumptions mode, forensics, workstreams, non-Claude runtimes - docs/README.md: updated index with discuss-mode doc link Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 20 ++++-- docs/AGENTS.md | 50 ++++++++++++- docs/COMMANDS.md | 104 +++++++++++++++++++++++++++ docs/CONFIGURATION.md | 8 ++- docs/FEATURES.md | 164 ++++++++++++++++++++++++++++++++++++++++++ docs/README.md | 2 + docs/USER-GUIDE.md | 72 ++++++++++++++++++- 7 files changed, 410 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 949a23a4c..13d8baf83 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,7 @@ npx get-shit-done-cc@latest ``` The installer prompts you to choose: -1. **Runtime** — Claude Code, OpenCode, Gemini, Codex, Copilot, Cursor, Antigravity, or all +1. **Runtime** — Claude Code, OpenCode, Gemini, Codex, Copilot, Cursor, Antigravity, or all (interactive multi-select — pick multiple runtimes in a single install session) 2. **Location** — Global (all projects) or local (current project only) Verify with: @@ -254,6 +254,8 @@ The deeper you go here, the more the system builds what you actually want. Skip **Creates:** `{phase_num}-CONTEXT.md` +> **Assumptions Mode:** Prefer codebase analysis over questions? Set `workflow.discuss_mode` to `assumptions` in `/gsd:settings`. The system reads your code, surfaces what it would do and why, and only asks you to correct what's wrong. See [Discuss Mode](docs/workflow-discuss-mode.md). + --- ### 3. Plan Phase @@ -512,8 +514,8 @@ You're never locked in. The system adapts. | `/gsd:audit-milestone` | Verify milestone achieved its definition of done | | `/gsd:complete-milestone` | Archive milestone, tag release | | `/gsd:new-milestone [name]` | Start next version: questions → research → requirements → roadmap | -| `/gsd:milestone-summary` | Generate onboarding summary from completed milestone artifacts | -| `/gsd:forensics` | Post-mortem investigation of failed or stuck workflows | +| `/gsd:forensics [desc]` | Post-mortem investigation of failed workflow runs (diagnoses stuck loops, missing artifacts, git anomalies) | +| `/gsd:milestone-summary [version]` | Generate comprehensive project summary for team onboarding and review | ### Workstreams @@ -548,6 +550,7 @@ You're never locked in. The system adapts. | `/gsd:help` | Show all commands and usage guide | | `/gsd:update` | Update GSD with changelog preview | | `/gsd:join-discord` | Join the GSD Discord community | +| `/gsd:manager` | Interactive command center for managing multiple phases | ### Brownfield @@ -573,6 +576,12 @@ You're never locked in. The system adapts. | `/gsd:resume-work` | Restore from last session | | `/gsd:session-report` | Generate session summary with work performed and outcomes | +### Workstreams + +| Command | What it does | +|---------|--------------| +| `/gsd:workstreams` | Manage parallel workstreams (list, create, switch, status, progress, complete) | + ### Code Quality | Command | What it does | @@ -652,8 +661,9 @@ These spawn additional agents during planning/execution. They improve quality bu | `workflow.verifier` | `true` | Confirms must-haves were delivered after execution | | `workflow.auto_advance` | `false` | Auto-chain discuss → plan → execute without stopping | | `workflow.research_before_questions` | `false` | Run research before discussion questions instead of after | -| `workflow.skip_discuss` | `false` | Skip discuss-phase entirely in autonomous mode | -| `workflow.discuss_mode` | `null` | Control discuss-phase behavior (`assumptions` uses inferred defaults) | +| `workflow.discuss_mode` | `'discuss'` | Discussion mode: `discuss` (interview), `assumptions` (codebase-first) | +| `workflow.skip_discuss` | `false` | Skip discuss-phase in autonomous mode | +| `workflow.text_mode` | `false` | Text-only mode for remote sessions (no TUI menus) | Use `/gsd:settings` to toggle these, or override per-invocation: - `/gsd:plan-phase --skip-research` diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 07e5834b8..1816f7554 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -1,6 +1,6 @@ # GSD Agent Reference -> All 15 specialized agents — roles, tools, spawn patterns, and relationships. For architecture context, see [Architecture](ARCHITECTURE.md). +> All 18 specialized agents — roles, tools, spawn patterns, and relationships. For architecture context, see [Architecture](ARCHITECTURE.md). --- @@ -13,6 +13,7 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp | Category | Count | Agents | |----------|-------|--------| | Researchers | 3 | project-researcher, phase-researcher, ui-researcher | +| Analyzers | 2 | assumptions-analyzer, advisor-researcher | | Synthesizers | 1 | research-synthesizer | | Planners | 1 | planner | | Roadmappers | 1 | roadmapper | @@ -86,6 +87,51 @@ GSD uses a multi-agent architecture where thin orchestrators (workflow files) sp --- +### gsd-assumptions-analyzer + +**Role:** Deeply analyzes codebase for a phase and returns structured assumptions with evidence, confidence levels, and consequences if wrong. + +| Property | Value | +|----------|-------| +| **Spawned by** | `discuss-phase-assumptions` workflow (when `workflow.discuss_mode = 'assumptions'`) | +| **Parallelism** | Single instance | +| **Tools** | Read, Bash, Grep, Glob | +| **Model (balanced)** | Sonnet | +| **Color** | Cyan | +| **Produces** | Structured assumptions with decision statements, evidence file paths, confidence levels | + +**Key behaviors:** +- Reads ROADMAP.md phase description and prior CONTEXT.md files +- Searches codebase for files related to the phase (components, patterns, similar features) +- Reads 5-15 most relevant source files to form evidence-based assumptions +- Classifies confidence: Confident (clear from code), Likely (reasonable inference), Unclear (could go multiple ways) +- Flags topics that need external research (library compatibility, ecosystem best practices) +- Output calibrated by tier: full_maturity (3-5 areas), standard (3-4), minimal_decisive (2-3) + +--- + +### gsd-advisor-researcher + +**Role:** Researches a single gray area decision during discuss-phase advisor mode and returns a structured comparison table. + +| Property | Value | +|----------|-------| +| **Spawned by** | `discuss-phase` workflow (when ADVISOR_MODE = true) | +| **Parallelism** | Multiple instances (one per gray area) | +| **Tools** | Read, Bash, Grep, Glob, WebSearch, WebFetch, mcp (context7) | +| **Model (balanced)** | Sonnet | +| **Color** | Cyan | +| **Produces** | 5-column comparison table (Option / Pros / Cons / Complexity / Recommendation) with rationale paragraph | + +**Key behaviors:** +- Researches a single assigned gray area using Claude's knowledge, Context7, and web search +- Produces genuinely viable options — no padding with filler alternatives +- Complexity column uses impact surface + risk (never time estimates) +- Recommendations are conditional ("Rec if X", "Rec if Y") — never single-winner ranking +- Output calibrated by tier: full_maturity (3-5 options with maturity signals), standard (2-4), minimal_decisive (2 options, decisive recommendation) + +--- + ### gsd-research-synthesizer **Role:** Combines outputs from parallel researchers into a unified summary. @@ -359,6 +405,8 @@ Communication style, decision patterns, debugging approach, UX preferences, vend | project-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | phase-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | ui-researcher | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| assumptions-analyzer | ✓ | | | ✓ | ✓ | ✓ | | | | +| advisor-researcher | ✓ | | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | research-synthesizer | ✓ | ✓ | | ✓ | | | | | | | planner | ✓ | ✓ | | ✓ | ✓ | ✓ | | ✓ | ✓ | | roadmapper | ✓ | ✓ | | ✓ | ✓ | ✓ | | | | diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md index 2ced3cb90..c5659f1c3 100644 --- a/docs/COMMANDS.md +++ b/docs/COMMANDS.md @@ -318,6 +318,32 @@ Archive milestone, tag release. --- +### `/gsd:milestone-summary` + +Generate comprehensive project summary from milestone artifacts for team onboarding and review. + +| Argument | Required | Description | +|----------|----------|-------------| +| `version` | No | Milestone version (defaults to current/latest milestone) | + +**Prerequisites:** At least one completed or in-progress milestone +**Produces:** `.planning/reports/MILESTONE_SUMMARY-v{version}.md` + +**Summary includes:** +- Overview, architecture decisions, phase-by-phase breakdown +- Key decisions and trade-offs +- Requirements coverage +- Tech debt and deferred items +- Getting started guide for new team members +- Interactive Q&A offered after generation + +```bash +/gsd:milestone-summary # Summarize current milestone +/gsd:milestone-summary v1.0 # Summarize specific milestone +``` + +--- + ### `/gsd:new-milestone` Start next version cycle. @@ -444,6 +470,23 @@ Save context handoff when stopping mid-phase. /gsd:pause-work # Creates continue-here.md ``` +### `/gsd:manager` + +Interactive command center for managing multiple phases from one terminal. + +**Prerequisites:** `.planning/ROADMAP.md` exists +**Behavior:** +- Dashboard of all phases with visual status indicators +- Recommends optimal next actions based on dependencies and progress +- Dispatches work: discuss runs inline, plan/execute run as background agents +- Designed for power users parallelizing work across phases from one terminal + +```bash +/gsd:manager # Open command center dashboard +``` + +--- + ### `/gsd:help` Show all commands and usage guide. @@ -611,6 +654,67 @@ Archive accumulated phase directories from completed milestones. --- +## Diagnostics Commands + +### `/gsd:forensics` + +Post-mortem investigation of failed or stuck GSD workflows. + +| Argument | Required | Description | +|----------|----------|-------------| +| `description` | No | Problem description (prompted if omitted) | + +**Prerequisites:** `.planning/` directory exists +**Produces:** `.planning/forensics/report-{timestamp}.md` + +**Investigation covers:** +- Git history analysis (recent commits, stuck patterns, time gaps) +- Artifact integrity (expected files for completed phases) +- STATE.md anomalies and session history +- Uncommitted work, conflicts, abandoned changes +- At least 4 anomaly types checked (stuck loop, missing artifacts, abandoned work, crash/interruption) +- GitHub issue creation offered if actionable findings exist + +```bash +/gsd:forensics # Interactive — prompted for problem +/gsd:forensics "Phase 3 execution stalled" # With problem description +``` + +--- + +## Workstream Management + +### `/gsd:workstreams` + +Manage parallel workstreams for concurrent work on different milestone areas. + +**Subcommands:** + +| Subcommand | Description | +|------------|-------------| +| `list` | List all workstreams with status (default if no subcommand) | +| `create ` | Create a new workstream | +| `status ` | Detailed status for one workstream | +| `switch ` | Set active workstream | +| `progress` | Progress summary across all workstreams | +| `complete ` | Archive a completed workstream | +| `resume ` | Resume work in a workstream | + +**Prerequisites:** Active GSD project +**Produces:** Workstream directories under `.planning/`, state tracking per workstream + +```bash +/gsd:workstreams # List all workstreams +/gsd:workstreams create backend-api # Create new workstream +/gsd:workstreams switch backend-api # Set active workstream +/gsd:workstreams status backend-api # Detailed status +/gsd:workstreams progress # Cross-workstream progress overview +/gsd:workstreams complete backend-api # Archive completed workstream +/gsd:workstreams resume backend-api # Resume work in workstream +``` + +--- + ## Configuration Commands ### `/gsd:settings` diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index 4a590479b..ad5d5ca0a 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -30,7 +30,10 @@ GSD stores project settings in `.planning/config.json`. Created during `/gsd:new "ui_safety_gate": true, "node_repair": true, "node_repair_budget": 2, - "research_before_questions": false + "research_before_questions": false, + "discuss_mode": "discuss", + "skip_discuss": false, + "text_mode": false }, "hooks": { "context_warnings": true, @@ -97,6 +100,9 @@ All workflow toggles follow the **absent = enabled** pattern. If a key is missin | `workflow.node_repair` | boolean | `true` | Autonomous task repair on verification failure | | `workflow.node_repair_budget` | number | `2` | Max repair attempts per failed task | | `workflow.research_before_questions` | boolean | `false` | Run research before discussion questions instead of after | +| `workflow.discuss_mode` | string | `'discuss'` | Controls how `/gsd:discuss-phase` gathers context. `'discuss'` (default) asks questions one-by-one. `'assumptions'` reads the codebase first, generates structured assumptions with confidence levels, and only asks you to correct what's wrong. Added in v1.28 | +| `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 | ### Recommended Presets diff --git a/docs/FEATURES.md b/docs/FEATURES.md index c9f818ebb..4f2e6d692 100644 --- a/docs/FEATURES.md +++ b/docs/FEATURES.md @@ -62,6 +62,14 @@ - [Security Hardening](#46-security-hardening) - [Multi-Repo Workspace Support](#47-multi-repo-workspace-support) - [Discussion Audit Trail](#48-discussion-audit-trail) +- [v1.28 Features](#v128-features) + - [Forensics](#49-forensics) + - [Milestone Summary](#50-milestone-summary) + - [Workstream Namespacing](#51-workstream-namespacing) + - [Manager Dashboard](#52-manager-dashboard) + - [Assumptions Discussion Mode](#53-assumptions-discussion-mode) + - [UI Phase Auto-Detection](#54-ui-phase-auto-detection) + - [Multi-Runtime Installer Selection](#55-multi-runtime-installer-selection) --- @@ -1124,3 +1132,159 @@ Test suite that scans all agent, workflow, and command files for embedded inject - REQ-DISCLOG-01: System MUST auto-generate DISCUSSION-LOG.md during discuss-phase - REQ-DISCLOG-02: Log MUST capture questions asked, options presented, and decisions made - REQ-DISCLOG-03: Decision IDs MUST enable traceability from discuss-phase to plan-phase + +--- + +## v1.28 Features + +### 49. Forensics + +**Command:** `/gsd:forensics [description]` + +**Purpose:** Post-mortem investigation of failed or stuck GSD workflows. + +**Requirements:** +- REQ-FORENSICS-01: System MUST analyze git history for anomalies (stuck loops, long gaps, repeated commits) +- REQ-FORENSICS-02: System MUST check artifact integrity (completed phases have expected files) +- REQ-FORENSICS-03: System MUST generate a markdown report saved to `.planning/forensics/` +- REQ-FORENSICS-04: System MUST offer to create a GitHub issue with findings +- REQ-FORENSICS-05: System MUST NOT modify project files (read-only investigation) + +**Produces:** +| Artifact | Description | +|----------|-------------| +| `.planning/forensics/report-{timestamp}.md` | Post-mortem investigation report | + +**Process:** +1. **Scan** — Analyze git history for anomalies: stuck loops, long gaps between commits, repeated identical commits +2. **Integrity Check** — Verify completed phases have expected artifact files +3. **Report** — Generate markdown report with findings, saved to `.planning/forensics/` +4. **Issue** — Offer to create a GitHub issue with findings for team visibility + +--- + +### 50. Milestone Summary + +**Command:** `/gsd:milestone-summary [version]` + +**Purpose:** Generate comprehensive project summary from milestone artifacts for team onboarding. + +**Requirements:** +- REQ-SUMMARY-01: System MUST aggregate phase plans, summaries, and verification results +- REQ-SUMMARY-02: System MUST work for both current and archived milestones +- REQ-SUMMARY-03: System MUST produce a single navigable document + +**Produces:** +| Artifact | Description | +|----------|-------------| +| `MILESTONE-SUMMARY.md` | Comprehensive navigable summary of milestone artifacts | + +**Process:** +1. **Collect** — Aggregate phase plans, summaries, and verification results from the target milestone +2. **Synthesize** — Combine artifacts into a single navigable document with cross-references +3. **Output** — Write `MILESTONE-SUMMARY.md` suitable for team onboarding and stakeholder review + +--- + +### 51. Workstream Namespacing + +**Command:** `/gsd:workstreams` + +**Purpose:** Parallel workstreams for concurrent work on different milestone areas. + +**Requirements:** +- REQ-WS-01: System MUST isolate workstream state in separate `.planning/workstreams/{name}/` directories +- REQ-WS-02: System MUST validate workstream names (alphanumeric + hyphens only, no path traversal) +- REQ-WS-03: System MUST support list, create, switch, status, progress, complete, resume subcommands + +**Produces:** +| Artifact | Description | +|----------|-------------| +| `.planning/workstreams/{name}/` | Isolated workstream directory structure | + +**Process:** +1. **Create** — Initialize a named workstream with isolated `.planning/workstreams/{name}/` directory +2. **Switch** — Change active workstream context for subsequent GSD commands +3. **Manage** — List, check status, track progress, complete, or resume workstreams + +--- + +### 52. Manager Dashboard + +**Command:** `/gsd:manager` + +**Purpose:** Interactive command center for managing multiple phases from one terminal. + +**Requirements:** +- REQ-MGR-01: System MUST show overview of all phases with status +- REQ-MGR-02: System MUST filter to current milestone scope +- REQ-MGR-03: System MUST show phase dependencies and conflicts + +**Produces:** Interactive terminal output + +**Process:** +1. **Scan** — Load all phases in the current milestone with their statuses +2. **Display** — Render overview showing phase dependencies, conflicts, and progress +3. **Interact** — Accept commands to navigate, inspect, or act on individual phases + +--- + +### 53. Assumptions Discussion Mode + +**Command:** `/gsd:discuss-phase` with `workflow.discuss_mode: 'assumptions'` + +**Purpose:** Replace interview-style questioning with codebase-first assumption analysis. + +**Requirements:** +- REQ-ASSUME-01: System MUST analyze codebase to generate structured assumptions before asking questions +- REQ-ASSUME-02: System MUST classify assumptions by confidence level (Confident/Likely/Unclear) +- REQ-ASSUME-03: System MUST produce identical CONTEXT.md format as default discuss mode +- REQ-ASSUME-04: System MUST support confidence-based skip gate (all HIGH = no questions) + +**Produces:** +| Artifact | Description | +|----------|-------------| +| `{phase}-CONTEXT.md` | Same format as default discuss mode | + +**Process:** +1. **Analyze** — Scan codebase to generate structured assumptions about implementation approach +2. **Classify** — Categorize assumptions by confidence level: Confident, Likely, Unclear +3. **Gate** — If all assumptions are HIGH confidence, skip questioning entirely +4. **Confirm** — Present unclear assumptions as targeted questions to the user +5. **Output** — Produce `{phase}-CONTEXT.md` in identical format to default discuss mode + +--- + +### 54. UI Phase Auto-Detection + +**Part of:** `/gsd:new-project` and `/gsd:progress` + +**Purpose:** Automatically detect UI-heavy projects and surface `/gsd:ui-phase` recommendation. + +**Requirements:** +- REQ-UI-DETECT-01: System MUST detect UI signals in project description (keywords, framework references) +- REQ-UI-DETECT-02: System MUST annotate ROADMAP.md phases with `ui_hint` when applicable +- REQ-UI-DETECT-03: System MUST suggest `/gsd:ui-phase` in next steps for UI-heavy phases +- REQ-UI-DETECT-04: System MUST NOT make `/gsd:ui-phase` mandatory + +**Process:** +1. **Detect** — Scan project description and tech stack for UI signals (keywords, framework references) +2. **Annotate** — Add `ui_hint` markers to applicable phases in ROADMAP.md +3. **Surface** — Include `/gsd:ui-phase` recommendation in next steps for UI-heavy phases + +--- + +### 55. Multi-Runtime Installer Selection + +**Part of:** `npx get-shit-done-cc` + +**Purpose:** Select multiple runtimes in a single interactive install session. + +**Requirements:** +- REQ-MULTI-RT-01: Interactive prompt MUST support multi-select (e.g., Claude Code + Gemini) +- REQ-MULTI-RT-02: CLI flags MUST continue to work for non-interactive installs + +**Process:** +1. **Detect** — Identify available AI CLI runtimes on the system +2. **Prompt** — Present multi-select interface for runtime selection +3. **Install** — Configure GSD for all selected runtimes in a single session diff --git a/docs/README.md b/docs/README.md index 821778766..53303927a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -14,9 +14,11 @@ Comprehensive documentation for the Get Shit Done (GSD) framework — a meta-pro | [Agent Reference](AGENTS.md) | Contributors, advanced users | All 15 specialized agents — roles, tools, spawn patterns | | [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.28:** Forensics, milestone summary, workstreams, assumptions mode, UI auto-detect, manager dashboard - **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 50f833ca1..08cc697c5 100644 --- a/docs/USER-GUIDE.md +++ b/docs/USER-GUIDE.md @@ -9,6 +9,7 @@ A detailed reference for workflows, troubleshooting, and configuration. For quic - [Workflow Diagrams](#workflow-diagrams) - [UI Design Contract](#ui-design-contract) - [Backlog & Threads](#backlog--threads) +- [Workstreams](#workstreams) - [Security](#security) - [Command Reference](#command-reference) - [Configuration Reference](#configuration-reference) @@ -157,6 +158,25 @@ escalation for you to address. **When to use:** After executing phases that were planned before Nyquist was enabled, or after `/gsd:audit-milestone` surfaces Nyquist compliance gaps. +### Assumptions Discussion Mode + +By default, `/gsd:discuss-phase` asks open-ended questions about your implementation preferences. Assumptions mode inverts this: GSD reads your codebase first, surfaces structured assumptions about how it would build the phase, and asks only for corrections. + +**Enable:** Set `workflow.discuss_mode` to `'assumptions'` via `/gsd:settings`. + +**How it works:** +1. Reads PROJECT.md, codebase mapping, and existing conventions +2. Generates a structured list of assumptions (tech choices, patterns, file locations) +3. Presents assumptions for you to confirm, correct, or expand +4. Writes CONTEXT.md from confirmed assumptions + +**When to use:** +- Experienced developers who already know their codebase well +- Rapid iteration where open-ended questions slow you down +- Projects where patterns are well-established and predictable + +See [docs/workflow-discuss-mode.md](workflow-discuss-mode.md) for the full discuss-mode reference. + --- ## UI Design Contract @@ -284,6 +304,29 @@ Threads can be promoted to phases (`/gsd:add-phase`) or backlog items (`/gsd:add --- +## Workstreams + +Workstreams let you work on multiple milestone areas concurrently without state collisions. Each workstream gets its own isolated `.planning/` state, so switching between them doesn't clobber progress. + +**When to use:** You're working on milestone features that span different concern areas (e.g., backend API and frontend dashboard) and want to plan, execute, or discuss them independently without context bleed. + +### Commands + +| Command | Purpose | +|---------|---------| +| `/gsd:workstreams create ` | Create a new workstream with isolated planning state | +| `/gsd:workstreams switch ` | Switch active context to a different workstream | +| `/gsd:workstreams list` | Show all workstreams and which is active | +| `/gsd:workstreams complete ` | Mark a workstream as done and archive its state | + +### How It Works + +Each workstream maintains its own `.planning/` directory subtree. When you switch workstreams, GSD swaps the active planning context so that `/gsd:progress`, `/gsd:discuss-phase`, `/gsd:plan-phase`, and other commands operate on that workstream's state. + +This is lighter weight than `/gsd:new-workspace` (which creates separate repo worktrees). Workstreams share the same codebase and git history but isolate planning artifacts. + +--- + ## Security ### Defense-in-Depth (v1.27) @@ -394,6 +437,7 @@ The `security.cjs` module scans for known injection patterns (role overrides, in | `/gsd:map-codebase` | Analyze existing codebase | Before `/gsd:new-project` on existing code | | `/gsd:quick` | Ad-hoc task with GSD guarantees | Bug fixes, small features, config changes | | `/gsd:debug [desc]` | Systematic debugging with persistent state | 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 | @@ -441,8 +485,11 @@ GSD stores project settings in `.planning/config.json`. Configure during `/gsd:n "nyquist_validation": true, "ui_phase": true, "ui_safety_gate": true, - "research_before_questions": false + "research_before_questions": false, + "discuss_mode": "standard", + "skip_discuss": false }, + "resolve_model_ids": "anthropic", "hooks": { "context_warnings": true, "workflow_guard": false @@ -484,6 +531,8 @@ GSD stores project settings in `.planning/config.json`. Configure during `/gsd:n | `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 | ### Hook Settings @@ -615,6 +664,8 @@ claude --dangerously-skip-permissions | Normal dev | `interactive` | `standard` | `balanced` | on | on | on | | Production | `interactive` | `fine` | `quality` | on | on | on | +**Skipping discuss-phase in autonomous mode:** When running in `yolo` mode with well-established preferences already captured in PROJECT.md, set `workflow.skip_discuss: true` via `/gsd:settings`. This bypasses the discuss-phase entirely and writes a minimal CONTEXT.md derived from the ROADMAP phase goal. Useful when your PROJECT.md and conventions are comprehensive enough that discussion adds no new information. + ### Mid-Milestone Scope Changes ```bash @@ -684,12 +735,13 @@ Switch to budget profile: `/gsd:set-profile budget`. Disable research and plan-c ### Using Non-Claude Runtimes (Codex, OpenCode, Gemini CLI) -If you installed GSD for a non-Claude runtime, the installer already configured model resolution so all agents use the runtime's default model. No manual setup is needed. +If you installed GSD for a non-Claude runtime, the installer already configured model resolution so all agents use the runtime's default model. No manual setup is needed. Specifically, the installer sets `resolve_model_ids: "omit"` in your config, which tells GSD to skip Anthropic model ID resolution and let the runtime choose its own default model. -To assign different models to different agents on a non-Claude runtime, add `model_overrides` to `.planning/config.json` with model IDs your runtime recognizes: +To assign different models to different agents on a non-Claude runtime, add `model_overrides` to `.planning/config.json` with fully-qualified model IDs that your runtime recognizes: ```json { + "resolve_model_ids": "omit", "model_overrides": { "gsd-planner": "o3", "gsd-executor": "o4-mini", @@ -698,6 +750,8 @@ To assign different models to different agents on a non-Claude runtime, add `mod } ``` +The installer auto-configures `resolve_model_ids: "omit"` for Gemini CLI, OpenCode, and Codex. If you're manually setting up a non-Claude runtime, add it to `.planning/config.json` yourself. + See the [Configuration Reference](CONFIGURATION.md#non-claude-runtimes-codex-opencode-gemini-cli) for the full explanation. ### Using Claude Code with Non-Anthropic Providers (OpenRouter, Local) @@ -712,6 +766,17 @@ Set `commit_docs: false` during `/gsd:new-project` or via `/gsd:settings`. Add ` Since v1.17, the installer backs up locally modified files to `gsd-local-patches/`. Run `/gsd:reapply-patches` to merge your changes back. +### Workflow Diagnostics (`/gsd:forensics`) + +When a workflow fails in a way that isn't obvious -- plans reference nonexistent files, execution produces unexpected results, or state seems corrupted -- run `/gsd:forensics` to generate a diagnostic report. + +**What it checks:** +- Git history anomalies (orphaned commits, unexpected branch state, rebase artifacts) +- Artifact integrity (missing or malformed planning files, broken cross-references) +- State inconsistencies (ROADMAP status vs. actual file presence, config drift) + +**Output:** A diagnostic report written to `.planning/forensics/` with findings and suggested remediation steps. + ### Subagent Appears to Fail but Work Was Done A known workaround exists for a Claude Code classification bug. GSD's orchestrators (execute-phase, quick) spot-check actual output before reporting failure. If you see a failure message but commits were made, check `git log` -- the work may have succeeded. @@ -742,6 +807,7 @@ If the installer crashes with `EPERM: operation not permitted, scandir` on Windo | Need to change scope | `/gsd:add-phase`, `/gsd:insert-phase`, or `/gsd:remove-phase` | | Milestone audit found gaps | `/gsd:plan-milestone-gaps` | | Something broke | `/gsd:debug "description"` | +| Workflow state seems corrupted | `/gsd:forensics` | | Quick targeted fix | `/gsd:quick` | | Plan doesn't match your vision | `/gsd:discuss-phase [N]` then re-plan | | Costs running high | `/gsd:set-profile budget` and `/gsd:settings` to toggle agents off |