get-shit-done-cc 1.3.27 → 1.3.29

package/README.md

@@ -302,11 +302,14 @@ You're never locked in. The system adapts.
 | `/gsd:plan-phase [N]`             | Generate task plans for phase                                 |
 | `/gsd:execute-plan`               | Run plan via subagent                                         |
 | `/gsd:progress`                   | Where am I? What's next?                                      |
+| `/gsd:verify-work [N]`*           | User acceptance test of phase or plan                         |
+| `/gsd:plan-fix [plan]`            | Plan fixes for UAT issues from verify-work                    |
 | `/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:add-phase`                  | Append phase to roadmap                                       |
 | `/gsd:insert-phase [N]`           | Insert urgent work                                            |
+| `/gsd:remove-phase [N]`           | Remove future phase, renumber subsequent                      |
 | `/gsd:discuss-phase [N]`          | Gather context before planning                                |
 | `/gsd:research-phase [N]`         | Deep ecosystem research for niche domains                     |
 | `/gsd:list-phase-assumptions [N]` | See what Claude thinks before you correct it                  |
@@ -315,6 +318,8 @@ You're never locked in. The system adapts.
 | `/gsd:consider-issues`            | Review deferred issues, close resolved, identify urgent       |
 | `/gsd:help`                       | Show all commands and usage guide                             |
 
+*Contributed by reddit user OracleGreyBeard
+
 ---
 
 ## Troubleshooting

package/bin/install.js

@@ -33,8 +33,61 @@ const args = process.argv.slice(2);
 const hasGlobal = args.includes('--global') || args.includes('-g');
 const hasLocal = args.includes('--local') || args.includes('-l');
 
+// Parse --config-dir argument
+function parseConfigDirArg() {
+  const configDirIndex = args.findIndex(arg => arg === '--config-dir' || arg === '-c');
+  if (configDirIndex !== -1) {
+    const nextArg = args[configDirIndex + 1];
+    // Error if --config-dir is provided without a value or next arg is another flag
+    if (!nextArg || nextArg.startsWith('-')) {
+      console.error(`  ${yellow}--config-dir requires a path argument${reset}`);
+      process.exit(1);
+    }
+    return nextArg;
+  }
+  // Also handle --config-dir=value format
+  const configDirArg = args.find(arg => arg.startsWith('--config-dir=') || arg.startsWith('-c='));
+  if (configDirArg) {
+    return configDirArg.split('=')[1];
+  }
+  return null;
+}
+const explicitConfigDir = parseConfigDirArg();
+const hasHelp = args.includes('--help') || args.includes('-h');
+
 console.log(banner);
 
+// Show help if requested
+if (hasHelp) {
+  console.log(`  ${yellow}Usage:${reset} npx get-shit-done-cc [options]
+
+  ${yellow}Options:${reset}
+    ${cyan}-g, --global${reset}              Install globally (to Claude config directory)
+    ${cyan}-l, --local${reset}               Install locally (to ./.claude in current directory)
+    ${cyan}-c, --config-dir <path>${reset}   Specify custom Claude config directory
+    ${cyan}-h, --help${reset}                Show this help message
+
+  ${yellow}Examples:${reset}
+    ${dim}# Install to default ~/.claude directory${reset}
+    npx get-shit-done-cc --global
+
+    ${dim}# Install to custom config directory (for multiple Claude accounts)${reset}
+    npx get-shit-done-cc --global --config-dir ~/.claude-bc
+
+    ${dim}# Using environment variable${reset}
+    CLAUDE_CONFIG_DIR=~/.claude-bc npx get-shit-done-cc --global
+
+    ${dim}# Install to current project only${reset}
+    npx get-shit-done-cc --local
+
+  ${yellow}Notes:${reset}
+    The --config-dir option is useful when you have multiple Claude Code
+    configurations (e.g., for different subscriptions). It takes priority
+    over the CLAUDE_CONFIG_DIR environment variable.
+`);
+  process.exit(0);
+}
+
 /**
  * Expand ~ to home directory (shell doesn't expand in env vars passed to node)
  */
@@ -75,7 +128,8 @@ function copyWithPathReplacement(srcDir, destDir, pathPrefix) {
  */
 function install(isGlobal) {
   const src = path.join(__dirname, '..');
-  const configDir = expandTilde(process.env.CLAUDE_CONFIG_DIR);
+  // Priority: explicit --config-dir arg > CLAUDE_CONFIG_DIR env var > default ~/.claude
+  const configDir = expandTilde(explicitConfigDir) || expandTilde(process.env.CLAUDE_CONFIG_DIR);
   const defaultGlobalDir = configDir || path.join(os.homedir(), '.claude');
   const claudeDir = isGlobal
     ? defaultGlobalDir
@@ -123,7 +177,8 @@ function promptLocation() {
     output: process.stdout
   });
 
-  const globalPath = expandTilde(process.env.CLAUDE_CONFIG_DIR) || path.join(os.homedir(), '.claude');
+  const configDir = expandTilde(explicitConfigDir) || expandTilde(process.env.CLAUDE_CONFIG_DIR);
+  const globalPath = configDir || path.join(os.homedir(), '.claude');
   const globalLabel = globalPath.replace(os.homedir(), '~');
 
   console.log(`  ${yellow}Where would you like to install?${reset}
@@ -144,6 +199,9 @@ function promptLocation() {
 if (hasGlobal && hasLocal) {
   console.error(`  ${yellow}Cannot specify both --global and --local${reset}`);
   process.exit(1);
+} else if (explicitConfigDir && hasLocal) {
+  console.error(`  ${yellow}Cannot use --config-dir with --local${reset}`);
+  process.exit(1);
 } else if (hasGlobal) {
   install(true);
 } else if (hasLocal) {

package/commands/gsd/help.md

@@ -137,6 +137,17 @@ Insert urgent work as decimal phase between existing phases.
 Usage: `/gsd:insert-phase 7 "Fix critical auth bug"`
 Result: Creates Phase 7.1
 
+**`/gsd:remove-phase <number>`**
+Remove a future phase and renumber subsequent phases.
+
+- Deletes phase directory and all references
+- Renumbers all subsequent phases to close the gap
+- Only works on future (unstarted) phases
+- Git commit preserves historical record
+
+Usage: `/gsd:remove-phase 17`
+Result: Phase 17 deleted, phases 18-20 become 17-19
+
 ### Milestone Management
 
 **`/gsd:discuss-milestone`**

package/commands/gsd/plan-fix.md

@@ -0,0 +1,205 @@
+---
+name: gsd:plan-fix
+description: Plan fixes for UAT issues from verify-work
+argument-hint: "[plan, e.g., '04-02']"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+<objective>
+Create FIX.md plan from UAT issues found during verify-work.
+
+Purpose: Plan fixes for issues logged in phase-scoped ISSUES.md files.
+Output: {plan}-FIX.md in the phase directory, ready for execution.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/references/plan-format.md
+@~/.claude/get-shit-done/references/checkpoints.md
+</execution_context>
+
+<context>
+Plan number: $ARGUMENTS (required - e.g., "04-02" or "09-01")
+
+**Load project state:**
+@.planning/STATE.md
+@.planning/ROADMAP.md
+</context>
+
+<process>
+
+<step name="parse">
+**Parse plan argument:**
+
+$ARGUMENTS should be a plan number like "04-02" or "09-01".
+Extract phase number (XX) and plan number (NN).
+
+If no argument provided:
+```
+Error: Plan number required.
+
+Usage: /gsd:plan-fix 04-02
+
+This creates a fix plan from .planning/phases/XX-name/04-02-ISSUES.md
+```
+Exit.
+</step>
+
+<step name="find">
+**Find ISSUES.md file:**
+
+Search for matching ISSUES.md:
+```bash
+ls .planning/phases/*/{plan}-ISSUES.md 2>/dev/null
+```
+
+If not found:
+```
+No ISSUES.md found for plan {plan}.
+
+ISSUES.md files are created by /gsd:verify-work when UAT finds issues.
+If no issues were found during testing, no fix plan is needed.
+```
+Exit.
+</step>
+
+<step name="read">
+**Read issues:**
+
+Read the ISSUES.md file.
+Parse each issue:
+- ID (UAT-XXX)
+- Title
+- Severity (critical/major/minor)
+- Description/steps to reproduce
+- Acceptance criteria
+
+Count total issues by severity.
+</step>
+
+<step name="plan">
+**Create fix tasks:**
+
+For each issue (or logical group):
+- Create one task per issue OR
+- Group related minor issues into single task
+
+Task structure:
+```xml
+<task type="auto">
+  <name>Fix UAT-001: [issue title]</name>
+  <files>[affected files from issue]</files>
+  <action>
+[What to fix based on issue description]
+[Reference original acceptance criteria]
+  </action>
+  <verify>[Test that issue is resolved]</verify>
+  <done>[Issue acceptance criteria met]</done>
+</task>
+```
+
+Prioritize: critical → major → minor
+</step>
+
+<step name="write">
+**Write FIX.md:**
+
+Create `.planning/phases/XX-name/{plan}-FIX.md`:
+
+```markdown
+---
+phase: XX-name
+plan: {plan}-FIX
+type: fix
+---
+
+<objective>
+Fix {N} UAT issues from plan {plan}.
+
+Source: {plan}-ISSUES.md
+Priority: {critical count} critical, {major count} major, {minor count} minor
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/execute-phase.md
+@~/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/STATE.md
+@.planning/ROADMAP.md
+
+**Issues being fixed:**
+@.planning/phases/XX-name/{plan}-ISSUES.md
+
+**Original plan for reference:**
+@.planning/phases/XX-name/{plan}-PLAN.md
+</context>
+
+<tasks>
+[Generated fix tasks]
+</tasks>
+
+<verification>
+Before declaring plan complete:
+- [ ] All critical issues fixed
+- [ ] All major issues fixed
+- [ ] Minor issues fixed or documented as deferred
+- [ ] Original acceptance criteria from issues met
+</verification>
+
+<success_criteria>
+- All UAT issues from {plan}-ISSUES.md addressed
+- Tests pass
+- Ready for re-verification
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/XX-name/{plan}-FIX-SUMMARY.md`
+</output>
+```
+</step>
+
+<step name="offer">
+**Offer execution:**
+
+```
+---
+
+## ✓ Fix Plan Created
+
+**{plan}-FIX.md** — {N} issues to fix
+
+| Severity | Count |
+|----------|-------|
+| Critical | {n}   |
+| Major    | {n}   |
+| Minor    | {n}   |
+
+---
+
+Would you like to:
+1. Execute the fix plan now
+2. Review the plan first
+3. Modify the plan before executing
+
+---
+```
+
+Use AskUserQuestion to get response.
+If execute: `/gsd:execute-plan .planning/phases/XX-name/{plan}-FIX.md`
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] ISSUES.md found and parsed
+- [ ] Fix tasks created for each issue
+- [ ] FIX.md written with proper structure
+- [ ] User offered to execute or review
+</success_criteria>

package/commands/gsd/progress.md

@@ -92,21 +92,35 @@ CONTEXT: [✓ if CONTEXT.md exists | - if not]
 <step name="route">
 **Determine next action based on verified counts.**
 
-**Step 1: Count plans and summaries in current phase**
+**Step 1: Count plans, summaries, and issues in current phase**
 
 List files in the current phase directory:
 
 ```bash
 ls -1 .planning/phases/[current-phase-dir]/*-PLAN.md 2>/dev/null | wc -l
 ls -1 .planning/phases/[current-phase-dir]/*-SUMMARY.md 2>/dev/null | wc -l
+ls -1 .planning/phases/[current-phase-dir]/*-ISSUES.md 2>/dev/null | wc -l
+ls -1 .planning/phases/[current-phase-dir]/*-FIX.md 2>/dev/null | wc -l
+ls -1 .planning/phases/[current-phase-dir]/*-FIX-SUMMARY.md 2>/dev/null | wc -l
 ```
 
-State: "This phase has {X} plans and {Y} summaries."
+State: "This phase has {X} plans, {Y} summaries, {Z} issues files, {W} fix plans."
+
+**Step 1.5: Check for unaddressed UAT issues**
+
+For each *-ISSUES.md file, check if matching *-FIX.md exists.
+For each *-FIX.md file, check if matching *-FIX-SUMMARY.md exists.
+
+Track:
+- `issues_without_fix`: ISSUES.md files without FIX.md
+- `fixes_without_summary`: FIX.md files without FIX-SUMMARY.md
 
 **Step 2: Route based on counts**
 
 | Condition | Meaning | Action |
 |-----------|---------|--------|
+| fixes_without_summary > 0 | Unexecuted fix plans exist | Go to **Route A** (with FIX.md) |
+| issues_without_fix > 0 | UAT issues need fix plans | Go to **Route E** |
 | summaries < plans | Unexecuted plans exist | Go to **Route A** |
 | summaries = plans AND plans > 0 | Phase complete | Go to Step 3 |
 | plans = 0 | Phase not yet planned | Go to **Route B** |
@@ -180,6 +194,32 @@ Check if `{phase}-CONTEXT.md` exists in phase directory.
 
 ---
 
+**Route E: UAT issues need fix plans**
+
+ISSUES.md exists without matching FIX.md. User needs to plan fixes.
+
+```
+---
+
+## ⚠ UAT Issues Found
+
+**{plan}-ISSUES.md** has {N} issues without a fix plan.
+
+`/gsd:plan-fix {plan}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/gsd:execute-plan [path]` — continue with other work first
+- `/gsd:verify-work {phase}` — run more UAT testing
+
+---
+```
+
+---
+
 **Step 3: Check milestone status (only when phase complete)**
 
 Read ROADMAP.md and identify:
@@ -219,6 +259,7 @@ Read ROADMAP.md to get the next phase's name and goal.
 ---
 
 **Also available:**
+- `/gsd:verify-work {Z}` — user acceptance test before continuing
 - `/gsd:discuss-phase {Z+1}` — gather context first
 - `/gsd:research-phase {Z+1}` — investigate unknowns
 
@@ -244,6 +285,11 @@ All {N} phases finished!
 
 <sub>`/clear` first → fresh context window</sub>
 
+---
+
+**Also available:**
+- `/gsd:verify-work` — user acceptance test before completing milestone
+
 ---
 ```
 

package/commands/gsd/remove-phase.md

@@ -0,0 +1,338 @@
+---
+name: gsd:remove-phase
+description: Remove a future phase from roadmap and renumber subsequent phases
+argument-hint: <phase-number>
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+---
+
+<objective>
+Remove an unstarted future phase from the roadmap and renumber all subsequent phases to maintain a clean, linear sequence.
+
+Purpose: Clean removal of work you've decided not to do, without polluting context with cancelled/deferred markers.
+Output: Phase deleted, all subsequent phases renumbered, git commit as historical record.
+</objective>
+
+<execution_context>
+@.planning/ROADMAP.md
+@.planning/STATE.md
+</execution_context>
+
+<process>
+
+<step name="parse_arguments">
+Parse the command arguments:
+- Argument is the phase number to remove (integer or decimal)
+- Example: `/gsd:remove-phase 17` → phase = 17
+- Example: `/gsd:remove-phase 16.1` → phase = 16.1
+
+If no argument provided:
+
+```
+ERROR: Phase number required
+Usage: /gsd:remove-phase <phase-number>
+Example: /gsd:remove-phase 17
+```
+
+Exit.
+</step>
+
+<step name="load_state">
+Load project state:
+
+```bash
+cat .planning/STATE.md 2>/dev/null
+cat .planning/ROADMAP.md 2>/dev/null
+```
+
+Parse current phase number from STATE.md "Current Position" section.
+</step>
+
+<step name="validate_phase_exists">
+Verify the target phase exists in ROADMAP.md:
+
+1. Search for `### Phase {target}:` heading
+2. If not found:
+
+   ```
+   ERROR: Phase {target} not found in roadmap
+   Available phases: [list phase numbers]
+   ```
+
+   Exit.
+</step>
+
+<step name="validate_future_phase">
+Verify the phase is a future phase (not started):
+
+1. Compare target phase to current phase from STATE.md
+2. Target must be > current phase number
+
+If target <= current phase:
+
+```
+ERROR: Cannot remove Phase {target}
+
+Only future phases can be removed:
+- Current phase: {current}
+- Phase {target} is current or completed
+
+To abandon current work, use /gsd:pause-work instead.
+```
+
+Exit.
+
+3. Check for SUMMARY.md files in phase directory:
+
+```bash
+ls .planning/phases/{target}-*/*-SUMMARY.md 2>/dev/null
+```
+
+If any SUMMARY.md files exist:
+
+```
+ERROR: Phase {target} has completed work
+
+Found executed plans:
+- {list of SUMMARY.md files}
+
+Cannot remove phases with completed work.
+```
+
+Exit.
+</step>
+
+<step name="gather_phase_info">
+Collect information about the phase being removed:
+
+1. Extract phase name from ROADMAP.md heading: `### Phase {target}: {Name}`
+2. Find phase directory: `.planning/phases/{target}-{slug}/`
+3. Find all subsequent phases (integer and decimal) that need renumbering
+
+**Subsequent phase detection:**
+
+For integer phase removal (e.g., 17):
+- Find all phases > 17 (integers: 18, 19, 20...)
+- Find all decimal phases >= 17.0 and < 18.0 (17.1, 17.2...) → these become 16.x
+- Find all decimal phases for subsequent integers (18.1, 19.1...) → renumber with their parent
+
+For decimal phase removal (e.g., 17.1):
+- Find all decimal phases > 17.1 and < 18 (17.2, 17.3...) → renumber down
+- Integer phases unchanged
+
+List all phases that will be renumbered.
+</step>
+
+<step name="confirm_removal">
+Present removal summary and confirm:
+
+```
+Removing Phase {target}: {Name}
+
+This will:
+- Delete: .planning/phases/{target}-{slug}/
+- Renumber {N} subsequent phases:
+  - Phase 18 → Phase 17
+  - Phase 18.1 → Phase 17.1
+  - Phase 19 → Phase 18
+  [etc.]
+
+Proceed? (y/n)
+```
+
+Wait for confirmation.
+</step>
+
+<step name="delete_phase_directory">
+Delete the target phase directory if it exists:
+
+```bash
+if [ -d ".planning/phases/{target}-{slug}" ]; then
+  rm -rf ".planning/phases/{target}-{slug}"
+  echo "Deleted: .planning/phases/{target}-{slug}/"
+fi
+```
+
+If directory doesn't exist, note: "No directory to delete (phase not yet created)"
+</step>
+
+<step name="renumber_directories">
+Rename all subsequent phase directories:
+
+For each phase directory that needs renumbering (in reverse order to avoid conflicts):
+
+```bash
+# Example: renaming 18-dashboard to 17-dashboard
+mv ".planning/phases/18-dashboard" ".planning/phases/17-dashboard"
+```
+
+Process in descending order (20→19, then 19→18, then 18→17) to avoid overwriting.
+
+Also rename decimal phase directories:
+- `17.1-fix-bug` → `16.1-fix-bug` (if removing integer 17)
+- `17.2-hotfix` → `17.1-hotfix` (if removing decimal 17.1)
+</step>
+
+<step name="rename_files_in_directories">
+Rename plan files inside renumbered directories:
+
+For each renumbered directory, rename files that contain the phase number:
+
+```bash
+# Inside 17-dashboard (was 18-dashboard):
+mv "18-01-PLAN.md" "17-01-PLAN.md"
+mv "18-02-PLAN.md" "17-02-PLAN.md"
+mv "18-01-SUMMARY.md" "17-01-SUMMARY.md"  # if exists
+# etc.
+```
+
+Also handle CONTEXT.md and DISCOVERY.md (these don't have phase prefixes, so no rename needed).
+</step>
+
+<step name="update_roadmap">
+Update ROADMAP.md:
+
+1. **Remove the phase section entirely:**
+   - Delete from `### Phase {target}:` to the next phase heading (or section end)
+
+2. **Remove from phase list:**
+   - Delete line `- [ ] **Phase {target}: {Name}**` or similar
+
+3. **Remove from Progress table:**
+   - Delete the row for Phase {target}
+
+4. **Renumber all subsequent phases:**
+   - `### Phase 18:` → `### Phase 17:`
+   - `- [ ] **Phase 18:` → `- [ ] **Phase 17:`
+   - Table rows: `| 18. Dashboard |` → `| 17. Dashboard |`
+   - Plan references: `18-01:` → `17-01:`
+
+5. **Update dependency references:**
+   - `**Depends on:** Phase 18` → `**Depends on:** Phase 17`
+   - For the phase that depended on the removed phase:
+     - `**Depends on:** Phase 17` (removed) → `**Depends on:** Phase 16`
+
+6. **Renumber decimal phases:**
+   - `### Phase 17.1:` → `### Phase 16.1:` (if integer 17 removed)
+   - Update all references consistently
+
+Write updated ROADMAP.md.
+</step>
+
+<step name="update_state">
+Update STATE.md:
+
+1. **Update total phase count:**
+   - `Phase: 16 of 20` → `Phase: 16 of 19`
+
+2. **Recalculate progress percentage:**
+   - New percentage based on completed plans / new total plans
+
+Do NOT add a "Roadmap Evolution" note - the git commit is the record.
+
+Write updated STATE.md.
+</step>
+
+<step name="update_file_contents">
+Search for and update phase references inside plan files:
+
+```bash
+# Find files that reference the old phase numbers
+grep -r "Phase 18" .planning/phases/17-*/ 2>/dev/null
+grep -r "Phase 19" .planning/phases/18-*/ 2>/dev/null
+# etc.
+```
+
+Update any internal references to reflect new numbering.
+</step>
+
+<step name="commit">
+Stage and commit the removal:
+
+```bash
+git add .planning/
+git commit -m "chore: remove phase {target} ({original-phase-name})"
+```
+
+The commit message preserves the historical record of what was removed.
+</step>
+
+<step name="completion">
+Present completion summary:
+
+```
+Phase {target} ({original-name}) removed.
+
+Changes:
+- Deleted: .planning/phases/{target}-{slug}/
+- Renumbered: Phases {first-renumbered}-{last-old} → {first-renumbered-1}-{last-new}
+- Updated: ROADMAP.md, STATE.md
+- Committed: chore: remove phase {target} ({original-name})
+
+Current roadmap: {total-remaining} phases
+Current position: Phase {current} of {new-total}
+
+---
+
+## What's Next
+
+Would you like to:
+- `/gsd:progress` — see updated roadmap status
+- Continue with current phase
+- Review roadmap
+
+---
+```
+</step>
+
+</process>
+
+<anti_patterns>
+
+- Don't remove completed phases (have SUMMARY.md files)
+- Don't remove current or past phases
+- Don't leave gaps in numbering - always renumber
+- Don't add "removed phase" notes to STATE.md - git commit is the record
+- Don't ask about each decimal phase - just renumber them
+- Don't modify completed phase directories
+</anti_patterns>
+
+<edge_cases>
+
+**Removing a decimal phase (e.g., 17.1):**
+- Only affects other decimals in same series (17.2 → 17.1, 17.3 → 17.2)
+- Integer phases unchanged
+- Simpler operation
+
+**No subsequent phases to renumber:**
+- Removing the last phase (e.g., Phase 20 when that's the end)
+- Just delete and update ROADMAP.md, no renumbering needed
+
+**Phase directory doesn't exist:**
+- Phase may be in ROADMAP.md but directory not created yet
+- Skip directory deletion, proceed with ROADMAP.md updates
+
+**Decimal phases under removed integer:**
+- Removing Phase 17 when 17.1, 17.2 exist
+- 17.1 → 16.1, 17.2 → 16.2
+- They maintain their position in execution order (after current last integer)
+
+</edge_cases>
+
+<success_criteria>
+Phase removal is complete when:
+
+- [ ] Target phase validated as future/unstarted
+- [ ] Phase directory deleted (if existed)
+- [ ] All subsequent phase directories renumbered
+- [ ] Files inside directories renamed ({old}-01-PLAN.md → {new}-01-PLAN.md)
+- [ ] ROADMAP.md updated (section removed, all references renumbered)
+- [ ] STATE.md updated (phase count, progress percentage)
+- [ ] Dependency references updated in subsequent phases
+- [ ] Changes committed with descriptive message
+- [ ] No gaps in phase numbering
+- [ ] User informed of changes
+</success_criteria>

package/commands/gsd/verify-work.md

@@ -0,0 +1,71 @@
+---
+name: gsd:verify-work
+description: Guide manual user acceptance testing of recently built features
+argument-hint: "[optional: phase or plan number, e.g., '4' or '04-02']"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Edit
+  - Write
+  - AskUserQuestion
+---
+
+<objective>
+Guide the user through manual acceptance testing of recently built features.
+
+Purpose: Validate that what Claude thinks was built actually works from the user's perspective. The USER performs all testing — Claude generates the test checklist, guides the process, and captures issues.
+
+Output: Validation of features, any issues logged to phase-scoped ISSUES.md
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/verify-work.md
+@~/.claude/get-shit-done/templates/uat-issues.md
+</execution_context>
+
+<context>
+Scope: $ARGUMENTS (optional)
+- If provided: Test specific phase or plan (e.g., "4" or "04-02")
+- If not provided: Test most recently completed plan
+
+**Load project state:**
+@.planning/STATE.md
+
+**Load roadmap:**
+@.planning/ROADMAP.md
+</context>
+
+<process>
+1. Validate arguments (if provided, parse as phase or plan number)
+2. Find relevant SUMMARY.md (specified or most recent)
+3. Follow verify-work.md workflow:
+   - Extract testable deliverables
+   - Generate test checklist
+   - Guide through each test via AskUserQuestion
+   - Collect and categorize issues
+   - Log issues to `.planning/phases/XX-name/{phase}-{plan}-ISSUES.md`
+   - Present summary with verdict
+4. Offer next steps based on results:
+   - If all passed: Continue to next phase
+   - If issues found: `/gsd:plan-fix {phase} {plan}` to create fix plan
+</process>
+
+<anti_patterns>
+- Don't run automated tests (that's for CI/test suites)
+- Don't make assumptions about test results — USER reports outcomes
+- Don't skip the guidance — walk through each test
+- Don't dismiss minor issues — log everything user reports
+- Don't fix issues during testing — capture for later
+</anti_patterns>
+
+<success_criteria>
+- [ ] Test scope identified from SUMMARY.md
+- [ ] Checklist generated based on deliverables
+- [ ] User guided through each test
+- [ ] All test results captured (pass/fail/partial/skip)
+- [ ] Any issues logged to phase-scoped ISSUES.md (not global)
+- [ ] Summary presented with verdict
+- [ ] User knows next steps based on results
+</success_criteria>

package/get-shit-done/templates/uat-issues.md

@@ -0,0 +1,143 @@
+# UAT Issues Template
+
+Template for `.planning/phases/XX-name/{phase}-{plan}-ISSUES.md` - phase-scoped issues discovered during user acceptance testing.
+
+**Purpose:** Capture issues found during /gsd:verify-work. Unlike global ISSUES.md (for deferred enhancements), this file tracks bugs and problems in specific delivered work.
+
+**Location:** Same directory as the SUMMARY.md being tested.
+
+---
+
+## File Template
+
+```markdown
+# UAT Issues: Phase [X] Plan [Y]
+
+**Tested:** [date]
+**Source:** [path to SUMMARY.md that was tested]
+**Tester:** User via /gsd:verify-work
+
+## Open Issues
+
+### UAT-001: [Brief description]
+
+**Discovered:** [date]
+**Phase/Plan:** [XX]-[YY]
+**Severity:** [Blocker/Major/Minor/Cosmetic]
+**Feature:** [Which feature from the test checklist]
+**Description:** [User's description of the problem]
+**Expected:** [What should have happened]
+**Actual:** [What actually happened]
+**Repro:** [Steps to reproduce, if captured]
+
+### UAT-002: [Brief description]
+
+...
+
+## Resolved Issues
+
+[Moved here after /gsd:plan-fix executes and fixes are verified]
+
+### UAT-001: [Brief description]
+**Resolved:** [date] - Fixed in [phase]-[plan]-FIX.md
+**Commit:** [hash]
+
+---
+
+*Phase: XX-name*
+*Plan: YY*
+*Tested: [date]*
+```
+
+---
+
+## Severity Guide
+
+| Severity | Definition | Example |
+|----------|------------|---------|
+| **Blocker** | Feature completely unusable | App crashes on button click |
+| **Major** | Feature works but significant problem | Form submits but data not saved |
+| **Minor** | Feature usable but has issues | Button text slightly cut off |
+| **Cosmetic** | Visual only, no functional impact | Wrong shade of color |
+
+---
+
+## UAT Numbering
+
+- **Prefix:** `UAT-` (distinguishes from ISS- enhancement issues)
+- **Scope:** Per-file numbering (UAT-001, UAT-002, etc. within each file)
+- **No global numbering:** Each {phase}-{plan}-ISSUES.md has its own sequence
+
+---
+
+<good_examples>
+```markdown
+# UAT Issues: Phase 5 Plan 2
+
+**Tested:** 2025-01-15
+**Source:** .planning/phases/05-auth/05-02-SUMMARY.md
+**Tester:** User via /gsd:verify-work
+
+## Open Issues
+
+### UAT-001: Login form doesn't show validation errors
+
+**Discovered:** 2025-01-15
+**Phase/Plan:** 05-02
+**Severity:** Major
+**Feature:** User login form
+**Description:** When I enter an invalid email, nothing happens. No error message appears.
+**Expected:** Red error message below email field saying "Invalid email format"
+**Actual:** Field border turns red but no text explanation
+**Repro:**
+1. Go to /login
+2. Enter "notanemail" in email field
+3. Click Login button
+
+### UAT-002: Password field allows paste
+
+**Discovered:** 2025-01-15
+**Phase/Plan:** 05-02
+**Severity:** Cosmetic
+**Feature:** User login form
+**Description:** Can paste into password field. Minor UX inconsistency.
+**Expected:** Paste disabled (matches signup form)
+**Actual:** Paste works in login but not signup
+**Repro:** Ctrl+V in password field
+
+## Resolved Issues
+
+[None yet]
+
+---
+
+*Phase: 05-auth*
+*Plan: 02*
+*Tested: 2025-01-15*
+```
+</good_examples>
+
+<guidelines>
+**When to create:**
+- First time /gsd:verify-work finds an issue for a plan
+- One file per plan tested
+
+**Location:**
+- `.planning/phases/XX-name/{phase}-{plan}-ISSUES.md`
+- Lives alongside SUMMARY.md being tested
+
+**Difference from global ISSUES.md:**
+- Global ISSUES.md: Deferred enhancements (Rule 5 - nice-to-haves)
+- UAT ISSUES.md: Actual problems found during testing
+
+**Workflow:**
+1. /gsd:verify-work creates this file with issues
+2. /gsd:plan-fix reads this file and creates FIX.md plan
+3. After FIX.md executes, issues move to "Resolved" section
+4. File becomes historical record of what was found and fixed
+
+**Resolution:**
+- Don't delete resolved issues - move to "Resolved Issues" section
+- Include fix reference (commit hash, plan that fixed it)
+- File serves as audit trail
+</guidelines>

package/get-shit-done/workflows/verify-work.md

@@ -0,0 +1,202 @@
+<purpose>
+Guide manual user acceptance testing of recently built features. Extract deliverables from SUMMARY.md, generate test checklist, guide user through each test, log issues to phase-scoped file.
+
+The USER performs all testing — Claude generates the checklist, guides the process, and captures issues.
+</purpose>
+
+<process>
+
+<step name="identify">
+**Determine what to test:**
+
+If $ARGUMENTS provided:
+- Parse as phase number (e.g., "4") or plan number (e.g., "04-02")
+- Find corresponding SUMMARY.md file(s)
+
+If no arguments:
+- Find most recently modified SUMMARY.md
+
+```bash
+find .planning/phases -name "*SUMMARY.md" -type f -exec ls -lt {} + | head -5
+```
+
+Read the SUMMARY.md to understand what was built.
+</step>
+
+<step name="extract">
+**Extract testable deliverables from SUMMARY.md:**
+
+Parse for:
+1. **Accomplishments** - Features/functionality added
+2. **Files Created/Modified** - What changed
+3. **User-facing changes** - UI, workflows, interactions
+
+Focus on USER-OBSERVABLE outcomes, not implementation details.
+
+Examples:
+- "Check-in menu item added to navigation" → User can see/click Check-in in nav
+- "HomePage refreshes after check-in" → After check-in, home shows updated state
+</step>
+
+<step name="generate">
+**Generate manual test checklist:**
+
+Create structured test plan:
+
+```
+# User Acceptance Test: [Plan/Phase Name]
+
+**Scope:** [What was built - from SUMMARY.md]
+**Testing:** Manual user validation
+
+## Pre-flight
+- [ ] Application builds and runs without errors
+- [ ] Application launches to expected state
+
+## Feature Tests
+
+### [Feature 1 from deliverables]
+**What to test:** [User-observable behavior]
+**Steps:**
+1. [Specific action to take]
+2. [What to look for]
+3. [Expected result]
+
+### [Feature 2 from deliverables]
+...
+
+## Edge Cases
+- [ ] [Relevant edge case based on feature]
+- [ ] [Another edge case]
+
+## Visual/UX Check
+- [ ] UI matches expected design
+- [ ] No visual glitches or layout issues
+- [ ] Responsive to interactions
+```
+
+Present this checklist to user.
+</step>
+
+<step name="guide">
+**Guide user through each test:**
+
+For each test item, use AskUserQuestion:
+- header: "[Feature name]"
+- question: "[Test description] - Did this work as expected?"
+- options:
+  - "Pass" — Works correctly
+  - "Fail" — Doesn't work as expected
+  - "Partial" — Works but with issues
+  - "Skip" — Can't test right now
+
+**If Pass:** Move to next test
+
+**If Fail or Partial:**
+Follow up with AskUserQuestion:
+- header: "Issue details"
+- question: "What went wrong?"
+- options:
+  - "Crashes/errors" — Application error or exception
+  - "Wrong behavior" — Does something unexpected
+  - "Missing feature" — Expected functionality not present
+  - "UI/visual issue" — Looks wrong but functions
+  - "Let me describe" — Free-form description needed
+</step>
+
+<step name="collect">
+**Collect and categorize issues:**
+
+For each failed/partial test, gather:
+- Feature affected
+- What went wrong (from user input)
+- Severity:
+  - **Blocker** — Can't use the feature at all
+  - **Major** — Feature works but significant problem
+  - **Minor** — Small issue, feature still usable
+  - **Cosmetic** — Visual only, no functional impact
+</step>
+
+<step name="log">
+**Log issues to phase-scoped file:**
+
+If any issues found:
+
+1. Create `.planning/phases/XX-name/{phase}-{plan}-ISSUES.md` if doesn't exist
+2. Use template from `@~/.claude/get-shit-done/templates/uat-issues.md`
+3. Add each issue:
+
+```markdown
+### UAT-[NNN]: [Brief description]
+
+**Discovered:** [date] during user acceptance testing
+**Phase/Plan:** [phase]-[plan] that was tested
+**Severity:** [Blocker/Major/Minor/Cosmetic]
+**Description:** [User's description of the problem]
+**Expected:** [What should have happened]
+**Actual:** [What actually happened]
+```
+
+**Note:** Issues go to phase-scoped file, NOT global `.planning/ISSUES.md`. This keeps UAT findings tied to the specific work being tested and enables `/gsd:plan-fix` to address them.
+</step>
+
+<step name="summarize">
+**Present test summary:**
+
+```
+# Test Results: [Plan/Phase Name]
+
+**Tests run:** [N]
+**Passed:** [N]
+**Failed:** [N]
+**Partial:** [N]
+**Skipped:** [N]
+
+## Issues Found
+[List any issues with severity]
+
+## Verdict
+[Based on results:]
+- ALL PASS: "All tests passed. Feature validated."
+- MINOR ISSUES: "Feature works with minor issues logged."
+- MAJOR ISSUES: "Significant issues found - review before proceeding."
+- BLOCKERS: "Blocking issues found - must fix before continuing."
+
+## Next Steps
+[Based on verdict:]
+- If clean: Suggest proceeding to next phase
+- If issues: Suggest /gsd:plan-fix to address
+```
+</step>
+
+<step name="offer">
+**Offer next actions based on results:**
+
+Use AskUserQuestion:
+- header: "Next"
+- question: "What would you like to do?"
+- options (based on results):
+
+If all passed:
+- "Continue to next phase" — Proceed with confidence
+- "Test more" — Run additional manual tests
+- "Done" — Finish testing session
+
+If issues found:
+- "Plan fixes" — Create plan to address issues (/gsd:plan-fix)
+- "Log and continue" — Issues logged, proceed anyway
+- "Review issues" — Look at logged issues in detail
+- "Done" — Finish testing session
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Test scope identified from SUMMARY.md
+- [ ] Checklist generated based on deliverables
+- [ ] User guided through each test via AskUserQuestion
+- [ ] All test results captured (pass/fail/partial/skip)
+- [ ] Any issues logged to phase-scoped ISSUES.md
+- [ ] Summary presented with verdict
+- [ ] User knows next steps based on results
+</success_criteria>

package/package.json

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