diff --git a/README.md b/README.md index ddcee19a7..13e96875f 100644 --- a/README.md +++ b/README.md @@ -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 --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 ` | 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`. diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md index 9b7947737..1e2870342 100644 --- a/docs/COMMANDS.md +++ b/docs/COMMANDS.md @@ -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. diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index 3d1631752..bc750d3c4 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -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) | --- diff --git a/docs/FEATURES.md b/docs/FEATURES.md index 79e4a83d9..5ece01d3a 100644 --- a/docs/FEATURES.md +++ b/docs/FEATURES.md @@ -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 ` @@ -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. diff --git a/docs/USER-GUIDE.md b/docs/USER-GUIDE.md index 4dcfca52b..36253a1fc 100644 --- a/docs/USER-GUIDE.md +++ b/docs/USER-GUIDE.md @@ -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 ` | 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