get-shit-done-cc 1.6.0 → 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/bin/install.js

@@ -123,8 +123,13 @@ function writeSettings(settingsPath, settings) {
 
 /**
  * Recursively copy directory, replacing paths in .md files
+ * Deletes existing destDir first to remove orphaned files from previous versions
  */
 function copyWithPathReplacement(srcDir, destDir, pathPrefix) {
+  // Clean install: remove existing destination to prevent orphaned files
+  if (fs.existsSync(destDir)) {
+    fs.rmSync(destDir, { recursive: true });
+  }
   fs.mkdirSync(destDir, { recursive: true });
 
   const entries = fs.readdirSync(srcDir, { withFileTypes: true });
@@ -187,10 +192,30 @@ function install(isGlobal) {
   console.log(`  ${green}✓${reset} Installed get-shit-done`);
 
   // Copy agents to ~/.claude/agents (subagents must be at root level)
+  // Only delete gsd-*.md files to preserve user's custom agents
   const agentsSrc = path.join(src, 'agents');
   if (fs.existsSync(agentsSrc)) {
     const agentsDest = path.join(claudeDir, 'agents');
-    copyWithPathReplacement(agentsSrc, agentsDest, pathPrefix);
+    fs.mkdirSync(agentsDest, { recursive: true });
+
+    // Remove old GSD agents (gsd-*.md) before copying new ones
+    if (fs.existsSync(agentsDest)) {
+      for (const file of fs.readdirSync(agentsDest)) {
+        if (file.startsWith('gsd-') && file.endsWith('.md')) {
+          fs.unlinkSync(path.join(agentsDest, file));
+        }
+      }
+    }
+
+    // Copy new agents (don't use copyWithPathReplacement which would wipe the folder)
+    const agentEntries = fs.readdirSync(agentsSrc, { withFileTypes: true });
+    for (const entry of agentEntries) {
+      if (entry.isFile() && entry.name.endsWith('.md')) {
+        let content = fs.readFileSync(path.join(agentsSrc, entry.name), 'utf8');
+        content = content.replace(/~\/\.claude\//g, pathPrefix);
+        fs.writeFileSync(path.join(agentsDest, entry.name), content);
+      }
+    }
     console.log(`  ${green}✓${reset} Installed agents`);
   }
 

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/commands/gsd/update.md

@@ -77,6 +77,57 @@ You're ahead of the latest release (development version?).
 STOP here if ahead.
 </step>
 
+<step name="show_changes_and_confirm">
+**If update available**, fetch and show what's new BEFORE updating:
+
+1. Fetch changelog (same as fetch_changelog step)
+2. Extract entries between installed and latest versions
+3. Display preview and ask for confirmation:
+
+```
+## GSD Update Available
+
+**Installed:** 1.5.10
+**Latest:** 1.5.15
+
+### What's New
+────────────────────────────────────────────────────────────
+
+## [1.5.15] - 2026-01-20
+
+### Added
+- Feature X
+
+## [1.5.14] - 2026-01-18
+
+### Fixed
+- Bug fix Y
+
+────────────────────────────────────────────────────────────
+
+⚠️  **Note:** The installer performs a clean install of GSD folders:
+- `~/.claude/commands/gsd/` will be wiped and replaced
+- `~/.claude/get-shit-done/` will be wiped and replaced
+- `~/.claude/agents/gsd-*` files will be replaced
+
+Your custom files in other locations are preserved:
+- Custom commands in `~/.claude/commands/your-stuff/` ✓
+- Custom agents not prefixed with `gsd-` ✓
+- Custom hooks ✓
+- Your CLAUDE.md files ✓
+
+If you've modified any GSD files directly, back them up first.
+```
+
+Use AskUserQuestion:
+- Question: "Proceed with update?"
+- Options:
+  - "Yes, update now"
+  - "No, cancel"
+
+**If user cancels:** STOP here.
+</step>
+
 <step name="run_update">
 Run the update:
 
@@ -93,63 +144,18 @@ rm -f ~/.claude/cache/gsd-update-check.json
 ```
 </step>
 
-<step name="fetch_changelog">
-Fetch changelog from GitHub:
-
-Use WebFetch tool with:
-- URL: `https://raw.githubusercontent.com/glittercowboy/get-shit-done/main/CHANGELOG.md`
-- Prompt: "Extract all version entries with their dates and changes. Return the raw markdown for each version section."
-
-**If fetch fails:**
-Fall back to local:
-```bash
-cat ~/.claude/get-shit-done/CHANGELOG.md 2>/dev/null
-```
-</step>
-
-<step name="extract_changes">
-From the changelog, extract entries between:
-- **From:** installed version (exclusive)
-- **To:** latest version (inclusive)
-
-Parse each `## [X.Y.Z]` section and collect all versions in the range.
-</step>
-
 <step name="display_result">
-Format beautiful output:
+Format completion message (changelog was already shown in confirmation step):
 
 ```
 ╔═══════════════════════════════════════════════════════════╗
 ║  GSD Updated: v1.5.10 → v1.5.15                           ║
 ╚═══════════════════════════════════════════════════════════╝
 
-✨ What's New
-────────────────────────────────────────────────────────────
-
-## [1.5.15] - 2026-01-20
-
-### Added
-- Feature X
-- Feature Y
-
-## [1.5.14] - 2026-01-18
-
-### Fixed
-- Bug in feature A
-
-────────────────────────────────────────────────────────────
-
 ⚠️  Restart Claude Code to pick up the new commands.
 
 [View full changelog](https://github.com/glittercowboy/get-shit-done/blob/main/CHANGELOG.md)
 ```
-
-**Key elements:**
-- Box header with version transition
-- All changelog entries in the range
-- **BREAKING:** changes surfaced prominently
-- Restart reminder (critical for picking up new commands)
-- Link to full changelog
 </step>
 
 </process>
@@ -158,8 +164,9 @@ Format beautiful output:
 - [ ] Installed version read correctly
 - [ ] Latest version checked via npm
 - [ ] Update skipped if already current
+- [ ] Changelog fetched and displayed BEFORE update
+- [ ] Clean install warning shown
+- [ ] User confirmation obtained
 - [ ] Update executed successfully
-- [ ] Changelog fetched (remote or local fallback)
-- [ ] Changes between versions displayed
 - [ ] Restart reminder shown
 </success_criteria>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "get-shit-done-cc",
-  "version": "1.6.0",
+  "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"