get-shit-done-cc 1.6.1 → 1.6.2

package/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   # Optional: clarify UI/UX/behavior decisions first
-/gsd:plan-phase 1
+/gsd:discuss-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.
+**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`
+
+---
 
-**plan-phase** — The system:
+### 3. Plan Phase
 
-1. **Researches** — Investigates how to implement this specific phase
+```
+/gsd:plan-phase 1
+```
+
+The system:
+
+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
+
+Walk away, come back to completed work with clean git history.
+
+**Creates:** `{phase}-{N}-SUMMARY.md`, `{phase}-VERIFICATION.md`
+
+---
 
-### 4. Repeat
+### 5. Verify Work
 
 ```
-/gsd:plan-phase 2
-/gsd:execute-phase 2
-...
-/gsd:complete-milestone   # When all phases done
+/gsd:verify-work 1
 ```
 
-Loop plan → execute until milestone complete. Ship your MVP. Start next milestone.
+**This is where you confirm it actually works.**
 
----
+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.
 
-## Existing Projects (Brownfield)
+The system:
 
-Already have code? Start here instead.
+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
 
-### 1. Map the codebase
+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.
 
-```
-/gsd:map-codebase
-```
+**Creates:** `{phase}-UAT.md`, fix plans if issues found
 
-Spawns parallel agents to analyze your code. Creates `.planning/codebase/` with structured analysis of your stack, architecture, conventions, and concerns.
+---
 
-### 2. Initialize and build
+### 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 <N>` | 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
 

package/agents/gsd-roadmapper.md

@@ -414,22 +414,11 @@ If gaps found, include in draft for user decision.
 
 **Write files first, then return.** This ensures artifacts persist even if context is lost.
 
-1. **Create phase directories (zero-padded):**
-   ```bash
-   # Always zero-pad phase numbers: 01, 02, ... 09, 10, 11
-   for i in 1 2 3; do
-     PADDED=$(printf "%02d" $i)
-     mkdir -p ".planning/phases/${PADDED}-{phase-name}"
-   done
-   ```
+1. **Write ROADMAP.md** using output format
 
-   Examples: `01-foundation`, `02-core-features`, `10-polish`
+2. **Write STATE.md** using output format
 
-2. **Write ROADMAP.md** using output format
-
-3. **Write STATE.md** using output format
-
-4. **Update REQUIREMENTS.md traceability section**
+3. **Update REQUIREMENTS.md traceability section**
 
 Files on disk = context preserved. User can review actual files.
 
@@ -459,9 +448,6 @@ When files are written and returning to orchestrator:
 **Files written:**
 - .planning/ROADMAP.md
 - .planning/STATE.md
-- .planning/phases/01-{phase-name}/
-- .planning/phases/02-{phase-name}/
-- ... (all phases zero-padded)
 
 **Updated:**
 - .planning/REQUIREMENTS.md (traceability section)
@@ -602,7 +588,6 @@ Roadmap is complete when:
 - [ ] 100% requirement coverage validated (no orphans)
 - [ ] ROADMAP.md structure complete
 - [ ] STATE.md structure complete
-- [ ] Phase directories identified
 - [ ] REQUIREMENTS.md traceability update prepared
 - [ ] Draft presented for user approval
 - [ ] User feedback incorporated (if any)

package/commands/gsd/new-milestone.md

@@ -23,7 +23,6 @@ This is the brownfield equivalent of new-project. The project exists, PROJECT.md
 - `.planning/REQUIREMENTS.md` — scoped requirements
 - `.planning/ROADMAP.md` — phase structure
 - `.planning/STATE.md` — updated project memory
-- `.planning/phases/` — phase directories
 
 **After this command:** Run `/gsd:plan-phase [N]` to start execution.
 
@@ -591,7 +590,7 @@ Create roadmap:
 2. Map every v1 requirement to exactly one phase
 3. Derive 2-5 success criteria per phase (observable user behaviors)
 4. Validate 100% coverage
-5. Write files immediately (ROADMAP.md, STATE.md, phase directories, update REQUIREMENTS.md traceability)
+5. Write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability)
 6. Return ROADMAP CREATED with summary
 
 Write files first, then return.
@@ -630,7 +629,7 @@ Use AskUserQuestion:
 **Commit roadmap:**
 
 ```bash
-git add .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md .planning/phases/
+git add .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
 git commit -m "$(cat <<'EOF'
 docs: create v[X.Y] roadmap ([N] phases)
 
@@ -696,7 +695,6 @@ Present completion with next steps:
 - `.planning/REQUIREMENTS.md`
 - `.planning/ROADMAP.md`
 - `.planning/STATE.md`
-- `.planning/phases/XX-name/` directories
 
 </output>
 
@@ -713,7 +711,7 @@ Present completion with next steps:
 - [ ] gsd-roadmapper spawned with context
 - [ ] Roadmap files written immediately
 - [ ] User feedback incorporated (if any)
-- [ ] ROADMAP.md, STATE.md, phase directories → **committed**
+- [ ] ROADMAP.md, STATE.md → **committed**
 - [ ] User knows next step is `/gsd:plan-phase [N]`
 
 </success_criteria>

package/commands/gsd/new-project.md

@@ -22,7 +22,6 @@ This is the most leveraged moment in any project. Deep questioning here means be
 - `.planning/REQUIREMENTS.md` — scoped requirements
 - `.planning/ROADMAP.md` — phase structure
 - `.planning/STATE.md` — project memory
-- `.planning/phases/` — phase directories
 
 **After this command:** Run `/gsd:plan-phase 1` to start execution.
 
@@ -710,7 +709,7 @@ Create roadmap:
 2. Map every v1 requirement to exactly one phase
 3. Derive 2-5 success criteria per phase (observable user behaviors)
 4. Validate 100% coverage
-5. Write files immediately (ROADMAP.md, STATE.md, phase directories, update REQUIREMENTS.md traceability)
+5. Write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability)
 6. Return ROADMAP CREATED with summary
 
 Write files first, then return. This ensures artifacts persist even if context is lost.
@@ -801,7 +800,7 @@ Use AskUserQuestion:
 **Commit roadmap (after approval):**
 
 ```bash
-git add .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md .planning/phases/
+git add .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
 git commit -m "$(cat <<'EOF'
 docs: create roadmap ([N] phases)
 
@@ -869,7 +868,6 @@ Present completion with next steps:
 - `.planning/REQUIREMENTS.md`
 - `.planning/ROADMAP.md`
 - `.planning/STATE.md`
-- `.planning/phases/XX-name/` directories
 
 </output>
 
@@ -891,7 +889,6 @@ Present completion with next steps:
 - [ ] ROADMAP.md created with phases, requirement mappings, success criteria
 - [ ] STATE.md initialized
 - [ ] REQUIREMENTS.md traceability updated
-- [ ] Phase directories created → **committed**
 - [ ] User knows next step is `/gsd:discuss-phase 1`
 
 **Atomic commits:** Each phase commits its artifacts immediately. If context is lost, artifacts persist.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "get-shit-done-cc",
-  "version": "1.6.1",
+  "version": "1.6.2",
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.",
   "bin": {
     "get-shit-done-cc": "bin/install.js"