docs: v1.28 release documentation update

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) <noreply@anthropic.com>
2026-03-22 12:10:06 -04:00
parent cdc464bdb9
commit 7457e33263
7 changed files with 410 additions and 10 deletions
--- 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`
--- 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 | ✓ | ✓ | | ✓ | ✓ | ✓ | | | |
--- 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 <name>` | Create a new workstream |
+| `status <name>` | Detailed status for one workstream |
+| `switch <name>` | Set active workstream |
+| `progress` | Progress summary across all workstreams |
+| `complete <name>` | Archive a completed workstream |
+| `resume <name>` | 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`
--- 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

--- 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
--- 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)
--- 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 <name>` | Create a new workstream with isolated planning state |
+| `/gsd:workstreams switch <name>` | Switch active context to a different workstream |
+| `/gsd:workstreams list` | Show all workstreams and which is active |
+| `/gsd:workstreams complete <name>` | 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 |