golem15/msd-core
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: comprehensive v1.26 release documentation update (#1187)

Browse Source 
Updates all docs to reflect v1.26.0 features and changes:

README.md:
- Add /gsd:ship and /gsd:next to command tables
- Add /gsd:session-report to Session section
- Update workflow to show ship step and auto-advance
- Update inherit profile description for non-Anthropic providers

docs/COMMANDS.md:
- Add /gsd:next command reference with full state detection logic
- Add /gsd:session-report command reference with report contents

docs/FEATURES.md:
- Add Auto-Advance (Next) feature (#14)
- Add Cross-Phase Regression Gate feature (#20)
- Add Requirements Coverage Gate feature (#21)
- Add Session Reporting feature (#24)
- Fix all section numbering (was broken with duplicates)
- Update inherit profile to mention non-Anthropic providers
- Renumber all 39 features consistently

docs/USER-GUIDE.md:
- Add /gsd:ship to workflow diagram
- Add /gsd:next and /gsd:session-report to command tables
- Add HANDOFF.json and reports/ to file structure
- Add troubleshooting for non-Anthropic model providers
- Add recovery entries for session-report and next
- Update example workflow to include ship and session-report

docs/CONFIGURATION.md:
- Update inherit profile to mention non-Anthropic providers
This commit is contained in:
Tom Boucher
2026-03-18 14:54:02 -04:00
committed by GitHub
parent fc468adb42
commit a9be67f504
5 changed files with 201 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
README.md
View File

@@ -342,19 +342,26 @@ If everything passes, you move on. If something's broken, you don't manually deb
---
### 6. Repeat → Complete → Next Milestone
### 6. Repeat → Ship → Complete → Next Milestone
```
/gsd:discuss-phase 2
/gsd:plan-phase 2
/gsd:execute-phase 2
/gsd:verify-work 2
/gsd:ship 2 # Create PR from verified work
...
/gsd:complete-milestone
/gsd:new-milestone
```
Loop **discuss → plan → execute → verify** until milestone complete.
Or let GSD figure out the next step automatically:
```
/gsd:next # Auto-detect and run next step
```
Loop **discuss → plan → execute → verify → ship** until milestone complete.
If you want faster intake during discussion, use `/gsd:discuss-phase <n> --batch` to answer a small grouped set of questions at once instead of one-by-one.
@@ -491,6 +498,8 @@ You're never locked in. The system adapts.
| `/gsd:plan-phase [N] [--auto]` | Research + plan + verify for a phase |
| `/gsd:execute-phase <N>` | Execute all plans in parallel waves, verify when complete |
| `/gsd:verify-work [N]` | Manual user acceptance testing ¹ |
| `/gsd:ship [N] [--draft]` | Create PR from verified phase work with auto-generated body |
| `/gsd:next` | Automatically advance to the next logical workflow step |
| `/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 |
@@ -507,6 +516,7 @@ You're never locked in. The system adapts.
| Command | What it does |
|---------|--------------|
| `/gsd:progress` | Where am I? What's next? |
| `/gsd:next` | Auto-detect state and run the next step |
| `/gsd:help` | Show all commands and usage guide |
| `/gsd:update` | Update GSD with changelog preview |
| `/gsd:join-discord` | Join the GSD Discord community |
@@ -531,8 +541,9 @@ You're never locked in. The system adapts.
| Command | What it does |
|---------|--------------|
| `/gsd:pause-work` | Create handoff when stopping mid-phase |
| `/gsd:pause-work` | Create handoff when stopping mid-phase (writes HANDOFF.json) |
| `/gsd:resume-work` | Restore from last session |
| `/gsd:session-report` | Generate session summary with work performed and outcomes |
### Utilities
@@ -581,7 +592,7 @@ Switch profiles:
/gsd:set-profile budget
```
Use `inherit` to follow the current runtime model selection (for example OpenCode `/model`).
Use `inherit` when using non-Anthropic providers (OpenRouter, local models) or to follow the current runtime model selection (e.g. OpenCode `/model`).
Or configure via `/gsd:settings`.

39
docs/COMMANDS.md
View File

@@ -132,6 +132,45 @@ User acceptance testing with auto-diagnosis.
---
### `/gsd:next`
Automatically advance to the next logical workflow step. Reads project state and runs the appropriate command.
**Prerequisites:** `.planning/` directory exists
**Behavior:**
- No project → suggests `/gsd:new-project`
- Phase needs discussion → runs `/gsd:discuss-phase`
- Phase needs planning → runs `/gsd:plan-phase`
- Phase needs execution → runs `/gsd:execute-phase`
- Phase needs verification → runs `/gsd:verify-work`
- All phases complete → suggests `/gsd:complete-milestone`
```bash
/gsd:next # Auto-detect and run next step
```
---
### `/gsd:session-report`
Generate a session report with work summary, outcomes, and estimated resource usage.
**Prerequisites:** Active project with recent work
**Produces:** `.planning/reports/SESSION_REPORT.md`
```bash
/gsd:session-report # Generate post-session summary
```
**Report includes:**
- Work performed (commits, plans executed, phases progressed)
- Outcomes and deliverables
- Blockers and decisions made
- Estimated token/cost usage
- Next steps recommendation
---
### `/gsd:ship`
Create PR from completed phase work with auto-generated body.

2
docs/CONFIGURATION.md
View File

@@ -246,7 +246,7 @@ Valid override values: `opus`, `sonnet`, `haiku`, `inherit`
| `quality` | Opus for all decision-making, Sonnet for verification | Quota available, critical architecture work |
| `balanced` | Opus for planning only, Sonnet for everything else | Normal development (default) |
| `budget` | Sonnet for code-writing, Haiku for research/verification | High-volume work, less critical phases |
| `inherit` | All agents use current session model | Dynamic model switching (OpenCode `/model`) |
| `inherit` | All agents use current session model | Dynamic model switching, **non-Anthropic providers** (OpenRouter, local models) |
---

172
docs/FEATURES.md
View File

@@ -20,33 +20,38 @@
- [Quick Mode](#10-quick-mode)
- [Autonomous Mode](#11-autonomous-mode)
- [Freeform Routing](#12-freeform-routing)
- [Note Capture](#13-note-capture)
- [Auto-Advance (Next)](#14-auto-advance-next)
- [Quality Assurance Features](#quality-assurance-features)
- [Nyquist Validation](#13-nyquist-validation)
- [Plan Checking](#14-plan-checking)
- [Post-Execution Verification](#15-post-execution-verification)
- [Node Repair](#16-node-repair)
- [Health Validation](#17-health-validation)
- [Nyquist Validation](#15-nyquist-validation)
- [Plan Checking](#16-plan-checking)
- [Post-Execution Verification](#17-post-execution-verification)
- [Node Repair](#18-node-repair)
- [Health Validation](#19-health-validation)
- [Cross-Phase Regression Gate](#20-cross-phase-regression-gate)
- [Requirements Coverage Gate](#21-requirements-coverage-gate)
- [Context Engineering Features](#context-engineering-features)
- [Context Window Monitoring](#18-context-window-monitoring)
- [Session Management](#19-session-management)
- [Multi-Agent Orchestration](#20-multi-agent-orchestration)
- [Model Profiles](#21-model-profiles)
- [Context Window Monitoring](#22-context-window-monitoring)
- [Session Management](#23-session-management)
- [Session Reporting](#24-session-reporting)
- [Multi-Agent Orchestration](#25-multi-agent-orchestration)
- [Model Profiles](#26-model-profiles)
- [Brownfield Features](#brownfield-features)
- [Codebase Mapping](#22-codebase-mapping)
- [Codebase Mapping](#27-codebase-mapping)
- [Utility Features](#utility-features)
- [Debug System](#23-debug-system)
- [Todo Management](#24-todo-management)
- [Statistics Dashboard](#25-statistics-dashboard)
- [Update System](#26-update-system)
- [Settings Management](#27-settings-management)
- [Test Generation](#28-test-generation)
- [Debug System](#28-debug-system)
- [Todo Management](#29-todo-management)
- [Statistics Dashboard](#30-statistics-dashboard)
- [Update System](#31-update-system)
- [Settings Management](#32-settings-management)
- [Test Generation](#33-test-generation)
- [Infrastructure Features](#infrastructure-features)
- [Git Integration](#29-git-integration)
- [CLI Tools](#30-cli-tools)
- [Multi-Runtime Support](#31-multi-runtime-support)
- [Hook System](#32-hook-system)
- [Developer Profiling](#33-developer-profiling)
- [Execution Hardening](#34-execution-hardening)
- [Git Integration](#34-git-integration)
- [CLI Tools](#35-cli-tools)
- [Multi-Runtime Support](#36-multi-runtime-support)
- [Hook System](#37-hook-system)
- [Developer Profiling](#38-developer-profiling)
- [Execution Hardening](#39-execution-hardening)
---
@@ -408,9 +413,34 @@
---
### 14. Auto-Advance (Next)
**Command:** `/gsd:next`
**Purpose:** Automatically detect current project state and advance to the next logical workflow step, eliminating the need to remember which phase/step you're on.
**Requirements:**
- REQ-NEXT-01: System MUST read STATE.md, ROADMAP.md, and phase directories to determine current position
- REQ-NEXT-02: System MUST detect whether discuss, plan, execute, or verify is needed
- REQ-NEXT-03: System MUST invoke the correct command automatically
- REQ-NEXT-04: System MUST suggest `/gsd:new-project` if no project exists
- REQ-NEXT-05: System MUST suggest `/gsd:complete-milestone` when all phases are complete
**State Detection Logic:**
| State | Action |
|-------|--------|
| No `.planning/` directory | Suggest `/gsd:new-project` |
| Phase has no CONTEXT.md | Run `/gsd:discuss-phase` |
| Phase has no PLAN.md files | Run `/gsd:plan-phase` |
| Phase has plans but no SUMMARY.md | Run `/gsd:execute-phase` |
| Phase executed but no VERIFICATION.md | Run `/gsd:verify-work` |
| All phases complete | Suggest `/gsd:complete-milestone` |
---
## Quality Assurance Features
### 14. Nyquist Validation
### 15. Nyquist Validation
**Purpose:** Map automated test coverage to phase requirements before any code is written. Named after the Nyquist sampling theorem — ensures a feedback signal exists for every requirement.
@@ -433,7 +463,7 @@
---
### 15. Plan Checking
### 16. Plan Checking
**Purpose:** Goal-backward verification that plans will achieve phase objectives before execution.
@@ -445,7 +475,7 @@
---
### 16. Post-Execution Verification
### 17. Post-Execution Verification
**Purpose:** Automated check that the codebase delivers what the phase promised.
@@ -457,7 +487,7 @@
---
### 17. Node Repair
### 18. Node Repair
**Purpose:** Autonomous recovery when task verification fails during execution.
@@ -471,7 +501,7 @@
---
### 18. Health Validation
### 19. Health Validation
**Command:** `/gsd:health [--repair]`
@@ -486,9 +516,37 @@
---
### 20. Cross-Phase Regression Gate
**Purpose:** Prevent regressions from compounding across phases by running prior phases' test suites after execution.
**Requirements:**
- REQ-REGR-01: System MUST run test suites from all completed prior phases after phase execution
- REQ-REGR-02: System MUST report any test failures as cross-phase regressions
- REQ-REGR-03: Regressions MUST be surfaced before post-execution verification
- REQ-REGR-04: System MUST identify which prior phase's tests were broken
**When:** Runs automatically during `/gsd:execute-phase` before the verifier step.
---
### 21. Requirements Coverage Gate
**Purpose:** Ensure all phase requirements are covered by at least one plan before planning completes.
**Requirements:**
- REQ-COVGATE-01: System MUST extract all requirement IDs assigned to the phase from ROADMAP.md
- REQ-COVGATE-02: System MUST verify each requirement appears in at least one PLAN.md
- REQ-COVGATE-03: Uncovered requirements MUST block planning completion
- REQ-COVGATE-04: System MUST report which specific requirements lack plan coverage
**When:** Runs automatically at the end of `/gsd:plan-phase` after the plan checker loop.
---
## Context Engineering Features
### 19. Context Window Monitoring
### 22. Context Window Monitoring
**Purpose:** Prevent context rot by alerting both user and agent when context is running low.
@@ -508,7 +566,7 @@
---
### 20. Session Management
### 23. Session Management
**Commands:** `/gsd:pause-work`, `/gsd:resume-work`, `/gsd:progress`
@@ -525,7 +583,32 @@
---
### 21. Multi-Agent Orchestration
### 24. Session Reporting
**Command:** `/gsd:session-report`
**Purpose:** Generate a structured post-session summary document capturing work performed, outcomes achieved, and estimated resource usage.
**Requirements:**
- REQ-REPORT-01: System MUST gather data from STATE.md, git log, and plan/summary files
- REQ-REPORT-02: System MUST include commits made, plans executed, and phases progressed
- REQ-REPORT-03: System MUST estimate token usage and cost based on session activity
- REQ-REPORT-04: System MUST include active blockers and decisions made
- REQ-REPORT-05: System MUST recommend next steps
**Produces:** `.planning/reports/SESSION_REPORT.md`
**Report Sections:**
- Session overview (duration, milestone, phase)
- Work performed (commits, plans, phases)
- Outcomes and deliverables
- Blockers and decisions
- Resource estimates (tokens, cost)
- Next steps recommendation
---
### 25. Multi-Agent Orchestration
**Purpose:** Coordinate specialized agents with fresh context windows for each task.
@@ -539,7 +622,7 @@
---
### 22. Model Profiles
### 26. Model Profiles
**Command:** `/gsd:set-profile <quality|balanced|budget|inherit>`
@@ -550,6 +633,7 @@
- REQ-MODEL-02: Each profile MUST define model tier per agent (see profile table)
- REQ-MODEL-03: Per-agent overrides MUST take precedence over profile
- REQ-MODEL-04: `inherit` profile MUST defer to runtime's current model selection
- REQ-MODEL-04a: `inherit` profile MUST be used when running non-Anthropic providers (OpenRouter, local models) to avoid unexpected API costs
- REQ-MODEL-05: Profile switch MUST be programmatic (script, not LLM-driven)
- REQ-MODEL-06: Model resolution MUST happen once per orchestration, not per spawn
@@ -574,7 +658,7 @@
## Brownfield Features
### 23. Codebase Mapping
### 27. Codebase Mapping
**Command:** `/gsd:map-codebase [area]`
@@ -602,7 +686,7 @@
## Utility Features
### 24. Debug System
### 28. Debug System
**Command:** `/gsd:debug [description]`
@@ -620,7 +704,7 @@
---
### 25. Todo Management
### 29. Todo Management
**Commands:** `/gsd:add-todo [desc]`, `/gsd:check-todos`
@@ -634,7 +718,7 @@
---
### 26. Statistics Dashboard
### 30. Statistics Dashboard
**Command:** `/gsd:stats`
@@ -648,7 +732,7 @@
---
### 27. Update System
### 31. Update System
**Command:** `/gsd:update`
@@ -663,7 +747,7 @@
---
### 28. Settings Management
### 32. Settings Management
**Command:** `/gsd:settings`
@@ -696,7 +780,7 @@
---
### 29. Test Generation
### 33. Test Generation
**Command:** `/gsd:add-tests [N]`
@@ -711,7 +795,7 @@
## Infrastructure Features
### 30. Git Integration
### 34. Git Integration
**Purpose:** Atomic commits, branching strategies, and clean history management.
@@ -737,7 +821,7 @@ fix(03-01): correct auth token expiry
---
### 31. CLI Tools
### 35. CLI Tools
**Purpose:** Programmatic utilities for workflows and agents, replacing repetitive inline bash patterns.
@@ -752,7 +836,7 @@ fix(03-01): correct auth token expiry
---
### 32. Multi-Runtime Support
### 36. Multi-Runtime Support
**Purpose:** Run GSD across 6 different AI coding agent runtimes.
@@ -775,7 +859,7 @@ fix(03-01): correct auth token expiry
---
### 33. Hook System
### 37. Hook System
**Purpose:** Runtime event hooks for context monitoring, status display, and update checking.
@@ -795,7 +879,7 @@ fix(03-01): correct auth token expiry
Color coding: <50% green, <65% yellow, <80% orange, ≥80% red with skull emoji
### 33. Developer Profiling
### 38. Developer Profiling
**Command:** `/gsd:profile-user [--questionnaire] [--refresh]`
@@ -831,7 +915,7 @@ Color coding: <50% green, <65% yellow, <80% orange, ≥80% red with skull emoji
- REQ-PROF-03: Questionnaire MUST be available as fallback when no session history exists
- REQ-PROF-04: Generated artifacts MUST be discoverable by Claude Code (CLAUDE.md integration)
### 34. Execution Hardening
### 39. Execution Hardening
**Purpose:** Three additive quality improvements to the execution pipeline that catch cross-plan failures before they cascade.

20
docs/USER-GUIDE.md
View File

@@ -50,6 +50,10 @@ A detailed reference for workflows, troubleshooting, and configuration. For quic
│ │ /gsd:verify-work │ │ <- Manual UAT
│ └──────────┬─────────┘ │
│ │ │
│ ┌──────────▼─────────┐ │
│ │ /gsd:ship │ │ <- Create PR (optional)
│ └──────────┬─────────┘ │
│ │ │
│ Next Phase?────────────┘
│ │ No
└─────────────┼──────────────┘
@@ -285,6 +289,7 @@ Controlled by `workflow.ui_safety_gate` config toggle.
| `/gsd:execute-phase <N>` | Execute all plans in parallel waves | After planning is complete |
| `/gsd:verify-work [N]` | Manual UAT with auto-diagnosis | After execution completes |
| `/gsd:ship [N]` | Create PR from verified work | After verification passes |
| `/gsd:next` | Auto-detect state and run next step | Anytime — "what should I do next?" |
| `/gsd:ui-review [N]` | Retroactive 6-pillar visual audit | After execution or verify-work (frontend projects) |
| `/gsd:audit-milestone` | Verify milestone met its definition of done | Before completing milestone |
| `/gsd:complete-milestone` | Archive milestone, tag release | All phases verified |
@@ -297,6 +302,7 @@ Controlled by `workflow.ui_safety_gate` config toggle.
| `/gsd:progress` | Show status and next steps | Anytime -- "where am I?" |
| `/gsd:resume-work` | Restore full context from last session | Starting a new session |
| `/gsd:pause-work` | Save structured handoff (HANDOFF.json + continue-here.md) | Stopping mid-phase |
| `/gsd:session-report` | Generate session summary with work and outcomes | End of session, stakeholder sharing |
| `/gsd:help` | Show all commands | Quick reference |
| `/gsd:update` | Update GSD with changelog preview | Check for new versions |
| `/gsd:join-discord` | Open Discord community invite | Questions or community |
@@ -426,7 +432,7 @@ Disable these to speed up phases in familiar domains or when conserving tokens.
- **quality** -- Opus for all decision-making agents, Sonnet for read-only verification. Use when quota is available and the work is critical.
- **balanced** -- Opus only for planning (where architecture decisions happen), Sonnet for everything else. The default for good reason.
- **budget** -- Sonnet for anything that writes code, Haiku for research and verification. Use for high-volume work or less critical phases.
- **inherit** -- All agents use the current session model. Best when switching models dynamically (for example OpenCode `/model`).
- **inherit** -- All agents use the current session model. Best when switching models dynamically (e.g. OpenCode `/model`), or **required** when using non-Anthropic providers (OpenRouter, local models) to avoid unexpected API costs.
---
@@ -443,12 +449,14 @@ claude --dangerously-skip-permissions
/gsd:plan-phase 1 # Research + plan + verify
/gsd:execute-phase 1 # Parallel execution
/gsd:verify-work 1 # Manual UAT
/gsd:ship 1 # Create PR from verified work
/gsd:ui-review 1 # Visual audit (frontend phases)
/clear
/gsd:discuss-phase 2 # Repeat for each phase
/gsd:next # Auto-detect and run next step
...
/gsd:audit-milestone # Check everything shipped
/gsd:complete-milestone # Archive, tag, done
/gsd:session-report # Generate session summary
```
### New Project from Existing Document
@@ -540,6 +548,10 @@ Do not re-run `/gsd:execute-phase`. Use `/gsd:quick` for targeted fixes, or `/gs
Switch to budget profile: `/gsd:set-profile budget`. Disable research and plan-check agents via `/gsd:settings` if the domain is familiar to you (or to Claude).
### Using Non-Anthropic Models (OpenRouter, Local)
If GSD subagents call Anthropic models and you're paying through OpenRouter or a local provider, switch to the `inherit` profile: `/gsd:set-profile inherit`. This makes all agents use your current session model instead of specific Anthropic models. See also `/gsd:settings` → Model Profile → Inherit.
### Working on a Sensitive/Private Project
Set `commit_docs: false` during `/gsd:new-project` or via `/gsd:settings`. Add `.planning/` to your `.gitignore`. Planning artifacts stay local and never touch git.
@@ -567,6 +579,8 @@ A known workaround exists for a Claude Code classification bug. GSD's orchestrat
| 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 |
| Update broke local changes | `/gsd:reapply-patches` |
| Want session summary for stakeholder | `/gsd:session-report` |
| Don't know what step is next | `/gsd:next` |
---
@@ -582,7 +596,9 @@ For reference, here is what GSD creates in your project:
STATE.md # Decisions, blockers, session memory
config.json # Workflow configuration
MILESTONES.md # Completed milestone archive
HANDOFF.json # Structured session handoff (from /gsd:pause-work)
research/ # Domain research from /gsd:new-project
reports/ # Session reports (from /gsd:session-report)
todos/
pending/ # Captured ideas awaiting work
done/ # Completed todos