From bc047f46ee3f251ea4d7735402dbf80d202c70fd Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Sat, 17 Jan 2026 01:10:41 -0600 Subject: [PATCH] docs: restructure README with improved workflow clarity MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rewrite "How It Works" with 6 clear steps: init → discuss → plan → execute → verify → complete - Emphasize discuss-phase as where users shape implementation (feeds research + planning) - Emphasize verify-work as where users confirm features actually work (auto-diagnoses failures) - Add brownfield callout at top of How It Works instead of separate section - Move discuss-phase, verify-work, new-milestone into Core Workflow commands - Replace "Subagent Execution" with "Multi-Agent Orchestration" explaining thin orchestrator pattern - Highlight 30-40% context usage even after thousands of lines of code --- README.md | 149 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 94 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index 5bb443881..5bc6b93ea 100644 --- a/README.md +++ b/README.md @@ -166,7 +166,9 @@ If you prefer not to use that flag, add this to your project's `.claude/settings ## How It Works -### 1. Initialize Project (~10 minutes) +> **Already have code?** Run `/gsd:map-codebase` first. It spawns parallel agents to analyze your stack, architecture, conventions, and concerns. Then `/gsd:new-project` knows your codebase — questions focus on what you're adding, and planning automatically loads your patterns. + +### 1. Initialize Project ``` /gsd:new-project @@ -183,24 +185,55 @@ You approve the roadmap. Now you're ready to build. **Creates:** `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, `.planning/research/` -### 2. Plan Phase +--- + +### 2. Discuss Phase + +``` +/gsd:discuss-phase 1 +``` + +**This is where you shape the implementation.** + +Your roadmap has a sentence or two per phase. That's not enough context to build something the way *you* imagine it. This step captures your preferences before anything gets researched or planned. + +The system analyzes the phase and identifies gray areas based on what's being built: + +- **Visual features** → Layout, density, interactions, empty states +- **APIs/CLIs** → Response format, flags, error handling, verbosity +- **Content systems** → Structure, tone, depth, flow +- **Organization tasks** → Grouping criteria, naming, duplicates, exceptions + +For each area you select, it asks until you're satisfied. The output — `CONTEXT.md` — feeds directly into the next two steps: + +1. **Researcher reads it** — Knows what patterns to investigate ("user wants card layout" → research card component libraries) +2. **Planner reads it** — Knows what decisions are locked ("infinite scroll decided" → plan includes scroll handling) + +The deeper you go here, the more the system builds what you actually want. Skip it and you get reasonable defaults. Use it and you get *your* vision. + +**Creates:** `{phase}-CONTEXT.md` + +--- + +### 3. Plan Phase ``` -/gsd:discuss-phase 1 # Optional: clarify UI/UX/behavior decisions first /gsd:plan-phase 1 ``` -**discuss-phase** (optional) — If the phase has gray areas (UI choices, UX flows, behavior decisions), discuss them first. Creates `CONTEXT.md` that guides planning. Skip if you trust the system's defaults. +The system: -**plan-phase** — The system: - -1. **Researches** — Investigates how to implement this specific phase +1. **Researches** — Investigates how to implement this phase, guided by your CONTEXT.md decisions 2. **Plans** — Creates 2-3 atomic task plans with XML structure -3. **Verifies** — Checks plans against requirements, loops if needed +3. **Verifies** — Checks plans against requirements, loops until they pass -Ready when plans pass verification. +Each plan is small enough to execute in a fresh context window. No degradation, no "I'll be more concise now." -### 3. Execute Phase +**Creates:** `{phase}-RESEARCH.md`, `{phase}-{N}-PLAN.md` + +--- + +### 4. Execute Phase ``` /gsd:execute-phase 1 @@ -209,43 +242,58 @@ Ready when plans pass verification. The system: 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 +2. **Fresh context per plan** — 200k tokens purely for implementation, zero accumulated garbage +3. **Commits per task** — Every task gets its own atomic commit +4. **Verifies against goals** — Checks the codebase delivers what the phase promised -### 4. Repeat +Walk away, come back to completed work with clean git history. -``` -/gsd:plan-phase 2 -/gsd:execute-phase 2 -... -/gsd:complete-milestone # When all phases done -``` - -Loop plan → execute until milestone complete. Ship your MVP. Start next milestone. +**Creates:** `{phase}-{N}-SUMMARY.md`, `{phase}-VERIFICATION.md` --- -## Existing Projects (Brownfield) - -Already have code? Start here instead. - -### 1. Map the codebase +### 5. Verify Work ``` -/gsd:map-codebase +/gsd:verify-work 1 ``` -Spawns parallel agents to analyze your code. Creates `.planning/codebase/` with structured analysis of your stack, architecture, conventions, and concerns. +**This is where you confirm it actually works.** -### 2. Initialize and build +Automated verification checks that code exists and tests pass. But does the feature *work* the way you expected? This is your chance to use it. + +The system: + +1. **Extracts testable deliverables** — What you should be able to do now +2. **Walks you through one at a time** — "Can you log in with email?" Yes/no, or describe what's wrong +3. **Diagnoses failures automatically** — Spawns debug agents to find root causes +4. **Creates verified fix plans** — Ready for immediate re-execution + +If everything passes, you move on. If something's broken, you don't manually debug — you just run `/gsd:execute-phase` again with the fix plans it created. + +**Creates:** `{phase}-UAT.md`, fix plans if issues found + +--- + +### 6. Repeat → Complete → Next Milestone ``` -/gsd:new-project +/gsd:discuss-phase 2 +/gsd:plan-phase 2 +/gsd:execute-phase 2 +/gsd:verify-work 2 +... +/gsd:complete-milestone +/gsd:new-milestone ``` -Same flow as greenfield, but the system knows your codebase. Questions focus on what you're adding/changing. Then plan → execute as normal. +Loop **discuss → plan → execute → verify** until milestone complete. -The codebase docs load automatically during planning. Claude knows your patterns, conventions, and where to put things. +Each phase gets your input (discuss), proper research (plan), clean execution (execute), and human verification (verify). Context stays fresh. Quality stays high. + +When all phases are done, `/gsd:complete-milestone` archives the milestone and tags the release. + +Then `/gsd:new-milestone` starts the next version — same flow as `new-project` but for your existing codebase. You describe what you want to build next, the system researches the domain, you scope requirements, and it creates a fresh roadmap. Each milestone is a clean cycle: define → build → ship. --- @@ -290,19 +338,20 @@ Every plan is structured XML optimized for Claude: Precise instructions. No guessing. Verification built in. -### Subagent Execution +### Multi-Agent Orchestration -As Claude fills its context window, quality degrades. You've seen it: *"Due to context limits, I'll be more concise now."* That "concision" is code for cutting corners. +Every stage uses the same pattern: a thin orchestrator spawns specialized agents, collects results, and routes to the next step. -GSD prevents this. Each plan is maximum 3 tasks. Each plan runs in a fresh subagent — 200k tokens purely for implementation, zero accumulated garbage. +| Stage | Orchestrator does | Agents do | +|-------|------------------|-----------| +| Research | Coordinates, presents findings | 4 parallel researchers investigate stack, features, architecture, pitfalls | +| Planning | Validates, manages iteration | Planner creates plans, checker verifies, loop until pass | +| Execution | Groups into waves, tracks progress | Executors implement in parallel, each with fresh 200k context | +| Verification | Presents results, routes next | Verifier checks codebase against goals, debuggers diagnose failures | -| Task | Context | Quality | -|------|---------|---------| -| Task 1 | Fresh | ✅ Full | -| Task 2 | Fresh | ✅ Full | -| Task 3 | Fresh | ✅ Full | +The orchestrator never does heavy lifting. It spawns agents, waits, integrates results. -No degradation. Walk away, come back to completed work. +**The result:** You can run an entire phase — deep research, multiple plans created and verified, thousands of lines of code written across parallel executors, automated verification against goals — and your main context window stays at 30-40%. The work happens in fresh subagent contexts. Your session stays fast and responsive. ### Atomic Git Commits @@ -338,9 +387,12 @@ You're never locked in. The system adapts. | Command | What it does | |---------|--------------| | `/gsd:new-project` | Full initialization: questions → research → requirements → roadmap | +| `/gsd:discuss-phase [N]` | Capture implementation decisions before planning | | `/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 | +| `/gsd:verify-work [N]` | Manual user acceptance testing ¹ | +| `/gsd:complete-milestone` | Archive milestone, tag release | +| `/gsd:new-milestone [name]` | Start next version: questions → research → requirements → roadmap | ### Navigation @@ -349,12 +401,6 @@ You're never locked in. The system adapts. | `/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]` | Manual user acceptance testing ¹ | - ### Brownfield | Command | What it does | @@ -368,13 +414,6 @@ 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 | -| `/gsd:discuss-phase [N]` | Gather context before planning | - -### Milestones - -| Command | What it does | -|---------|--------------| -| `/gsd:new-milestone [name]` | Start next milestone (questioning → research → requirements → roadmap) | ### Session