From ccd49d88b2154b978e92818168a125db4f431522 Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Fri, 16 Jan 2026 12:22:18 -0600 Subject: [PATCH] =?UTF-8?q?docs(readme):=20simplify=20workflow=20to=20new-?= =?UTF-8?q?project=20=E2=86=92=20plan=20=E2=86=92=20execute=20loop?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Collapse 5-step flow into 4 clear phases - Show /gsd:new-project as single ~10min initialization flow - Document research → plan → verify loop in plan-phase - Document parallel waves + verification in execute-phase - Remove deprecated commands: execute-plan, research-project, define-requirements, create-roadmap, research-phase, list-phase-assumptions - Reorganize commands table with Core Workflow at top - Simplify brownfield section Co-Authored-By: Claude Opus 4.5 --- README.md | 136 ++++++++++++++++++++++-------------------------------- 1 file changed, 56 insertions(+), 80 deletions(-) diff --git a/README.md b/README.md index b17b43297..f45e58ec2 100644 --- a/README.md +++ b/README.md @@ -166,67 +166,59 @@ If you prefer not to use that flag, add this to your project's `.claude/settings ## How It Works -### 1. Start with an idea +### 1. Initialize Project (~10 minutes) ``` /gsd:new-project ``` -The system asks questions. Keeps asking until it has everything — your goals, constraints, tech preferences, edge cases. You go back and forth until the idea is fully captured. Creates **PROJECT.md**. +One command, one flow. The system: -### 1.5. Research the domain (optional) +1. **Questions** — Asks until it understands your idea completely (goals, constraints, tech preferences, edge cases) +2. **Research** — Spawns parallel agents to investigate the domain (optional but recommended) +3. **Requirements** — Extracts what's v1, v2, and out of scope +4. **Roadmap** — Creates phases mapped to requirements + +You approve the roadmap. Now you're ready to build. + +**Creates:** `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, `.planning/research/` + +### 2. Plan Phase ``` -/gsd:research-project +/gsd:plan-phase 1 ``` -Spawns parallel agents to investigate the domain — what's the standard stack, what features users expect, common architectural patterns, and pitfalls to avoid. Creates `.planning/research/` with ecosystem knowledge. +The system: -> Recommended for best results. Skip only if you need speed over thoroughness. +1. **Researches** — Investigates how to implement this specific phase +2. **Plans** — Creates 2-3 atomic task plans with XML structure +3. **Verifies** — Checks plans against requirements, loops if needed -### 2. Define requirements +Ready when plans pass verification. + +### 3. Execute Phase ``` -/gsd:define-requirements +/gsd:execute-phase 1 ``` -Scope what's v1, what's v2, and what's out of scope. Creates **REQUIREMENTS.md** with checkable requirements and traceability. Works with or without prior research. +The system: -### 3. Create roadmap +1. **Runs plans in waves** — Parallel where possible, sequential when dependent +2. **Fresh context per plan** — 200k tokens purely for implementation, zero degradation +3. **Verifies code** — Checks against phase goals when complete + +### 4. Repeat ``` -/gsd:create-roadmap +/gsd:plan-phase 2 +/gsd:execute-phase 2 +... +/gsd:complete-milestone # When all phases done ``` -Produces: -- **ROADMAP.md** — Phases from start to finish, mapped to requirements -- **STATE.md** — Living memory that persists across sessions - -### 4. Plan and execute phases - -``` -/gsd:plan-phase 1 # System creates atomic task plans -/gsd:execute-phase 1 # Parallel agents execute all plans -``` - -Each phase breaks into 2-3 task plans. Each plan runs in a fresh subagent context — 200k tokens purely for implementation, zero degradation. Plans without dependencies run in parallel. - -**For single-plan or interactive execution:** -``` -/gsd:execute-plan # Run one plan at a time with checkpoints -``` - -Use `/gsd:execute-phase` for parallel "walk away" automation (recommended). Use `/gsd:execute-plan` when you need interactive single-plan execution with manual checkpoints. - -### 5. Ship and iterate - -``` -/gsd:complete-milestone # Archive v1, prep for v2 -/gsd:add-phase # Append new work -/gsd:insert-phase 2 # Slip urgent work between phases -``` - -Ship your MVP in a day. Add features. Insert hotfixes. The system stays modular — you're never stuck. +Loop plan → execute until milestone complete. Ship your MVP. Start next milestone. --- @@ -240,30 +232,15 @@ Already have code? Start here instead. /gsd:map-codebase ``` -Spawns parallel agents to analyze your code. Creates `.planning/codebase/` with 7 documents: +Spawns parallel agents to analyze your code. Creates `.planning/codebase/` with structured analysis of your stack, architecture, conventions, and concerns. -| Document | Purpose | -|----------|---------| -| `STACK.md` | Languages, frameworks, dependencies | -| `ARCHITECTURE.md` | Patterns, layers, data flow | -| `STRUCTURE.md` | Directory layout, where things live | -| `CONVENTIONS.md` | Code style, naming patterns | -| `TESTING.md` | Test framework, patterns | -| `INTEGRATIONS.md` | External services, APIs | -| `CONCERNS.md` | Tech debt, known issues, fragile areas | - -### 2. Initialize project +### 2. Initialize and build ``` /gsd:new-project ``` -Same as greenfield, but the system knows your codebase. Questions focus on what you're adding/changing, not starting from scratch. - -### 3. Continue as normal - -From here, it's the same flow: -- `/gsd:research-project` (optional) → `/gsd:define-requirements` → `/gsd:create-roadmap` → `/gsd:plan-phase` → `/gsd:execute-phase` +Same flow as greenfield, but the system knows your codebase. Questions focus on what you're adding/changing. Then plan → execute as normal. The codebase docs load automatically during planning. Claude knows your patterns, conventions, and where to put things. @@ -353,38 +330,33 @@ You're never locked in. The system adapts. ## Commands -### Setup +### Core Workflow | Command | What it does | |---------|--------------| -| `/gsd:new-project` | Extract your idea through questions, create PROJECT.md | -| `/gsd:research-project` | Research domain ecosystem (stacks, features, pitfalls) | -| `/gsd:define-requirements` | Scope v1/v2/out-of-scope requirements | -| `/gsd:create-roadmap` | Create roadmap with phases mapped to requirements | -| `/gsd:map-codebase` | Map existing codebase for brownfield projects | +| `/gsd:new-project` | Full initialization: questions → research → requirements → roadmap | +| `/gsd:plan-phase [N]` | Research + plan + verify for a phase | +| `/gsd:execute-phase ` | Execute all plans in parallel waves, verify when complete | +| `/gsd:complete-milestone` | Ship it, prep next version | -### Execution +### Navigation | Command | What it does | |---------|--------------| -| `/gsd:plan-phase [N]` | Generate task plans for phase | -| `/gsd:execute-phase ` | Execute all plans in phase with parallel agents | -| `/gsd:execute-plan` | Run single plan via subagent | | `/gsd:progress` | Where am I? What's next? | +| `/gsd:help` | Show all commands and usage guide | ### Verification | Command | What it does | |---------|--------------| -| `/gsd:verify-work [N]` | User acceptance test of phase or plan ¹ | +| `/gsd:verify-work [N]` | Manual user acceptance testing ¹ | -### Milestones +### Brownfield | Command | What it does | |---------|--------------| -| `/gsd:complete-milestone` | Ship it, prep next version | -| `/gsd:discuss-milestone` | Gather context for next milestone | -| `/gsd:new-milestone [name]` | Create new milestone with phases | +| `/gsd:map-codebase` | Analyze existing codebase before new-project | ### Phase Management @@ -392,26 +364,30 @@ You're never locked in. The system adapts. |---------|--------------| | `/gsd:add-phase` | Append phase to roadmap | | `/gsd:insert-phase [N]` | Insert urgent work between phases | -| `/gsd:remove-phase [N]` | Remove future phase, renumber subsequent | +| `/gsd:remove-phase [N]` | Remove future phase, renumber | | `/gsd:discuss-phase [N]` | Gather context before planning | -| `/gsd:research-phase [N]` | Deep research for unfamiliar domains | -| `/gsd:list-phase-assumptions [N]` | See what Claude assumes before correcting | + +### Milestones + +| Command | What it does | +|---------|--------------| +| `/gsd:new-milestone [name]` | Start next milestone | +| `/gsd:discuss-milestone` | Gather context for next milestone | ### Session | Command | What it does | |---------|--------------| -| `/gsd:pause-work` | Create handoff file when stopping mid-phase | +| `/gsd:pause-work` | Create handoff when stopping mid-phase | | `/gsd:resume-work` | Restore from last session | ### Utilities | Command | What it does | |---------|--------------| -| `/gsd:add-todo [desc]` | Capture idea or task for later | -| `/gsd:check-todos [area]` | List pending todos, select one to work on | +| `/gsd:add-todo [desc]` | Capture idea for later | +| `/gsd:check-todos` | List pending todos | | `/gsd:debug [desc]` | Systematic debugging with persistent state | -| `/gsd:help` | Show all commands and usage guide | ¹ Contributed by reddit user OracleGreyBeard