get-shit-done-cc 1.5.27 → 1.5.29

package/agents/gsd-codebase-mapper.md

@@ -31,7 +31,7 @@ Your job: Explore thoroughly, then write document(s) directly. Return confirmati
 | refactor, cleanup | CONCERNS.md, ARCHITECTURE.md |
 | setup, config | STACK.md, STRUCTURE.md |
 
-**`/gsd:execute-plan`** references codebase docs to:
+**`/gsd:execute-phase`** references codebase docs to:
 - Follow existing conventions when writing code
 - Know where to place new files (STRUCTURE.md)
 - Match testing patterns (TESTING.md)

package/agents/gsd-executor.md

@@ -8,10 +8,7 @@ color: yellow
 <role>
 You are a GSD plan executor. You execute PLAN.md files atomically, creating per-task commits, handling deviations automatically, pausing at checkpoints, and producing SUMMARY.md files.
 
-You are spawned by either:
-
-- `/gsd:execute-plan` command (single plan execution)
-- `/gsd:execute-phase` orchestrator (parallel plan execution)
+You are spawned by `/gsd:execute-phase` orchestrator.
 
 Your job: Execute the plan completely, commit each task, create SUMMARY.md, update STATE.md.
 </role>

package/agents/gsd-phase-researcher.md

@@ -444,7 +444,9 @@ Orchestrator provides:
 **Load phase context (MANDATORY):**
 
 ```bash
-PHASE_DIR=$(ls -d .planning/phases/${PHASE}-* 2>/dev/null | head -1)
+# Match both zero-padded (05-*) and unpadded (5-*) folders
+PADDED_PHASE=$(printf "%02d" ${PHASE} 2>/dev/null || echo "${PHASE}")
+PHASE_DIR=$(ls -d .planning/phases/${PADDED_PHASE}-* .planning/phases/${PHASE}-* 2>/dev/null | head -1)
 
 # Read CONTEXT.md if exists (from /gsd:discuss-phase)
 cat "${PHASE_DIR}"/*-CONTEXT.md 2>/dev/null
@@ -518,14 +520,14 @@ Run through verification protocol checklist:
 
 Use the output format template. Populate all sections with verified findings.
 
-Write to: `${PHASE_DIR}/${PHASE}-RESEARCH.md`
+Write to: `${PHASE_DIR}/${PADDED_PHASE}-RESEARCH.md`
 
 Where `PHASE_DIR` is the full path (e.g., `.planning/phases/01-foundation`)
 
 ## Step 6: Commit Research
 
 ```bash
-git add "${PHASE_DIR}/${PHASE}-RESEARCH.md"
+git add "${PHASE_DIR}/${PADDED_PHASE}-RESEARCH.md"
 git commit -m "docs(${PHASE}): research phase domain
 
 Phase ${PHASE}: ${PHASE_NAME}
@@ -558,7 +560,7 @@ When research finishes successfully:
 
 ### File Created
 
-`${PHASE_DIR}/${PHASE}-RESEARCH.md`
+`${PHASE_DIR}/${PADDED_PHASE}-RESEARCH.md`
 
 ### Confidence Assessment
 

package/agents/gsd-plan-checker.md

@@ -244,8 +244,9 @@ issue:
 Gather verification context from the phase directory and project state.
 
 ```bash
-# Phase directory (provided in prompt)
-PHASE_DIR=".planning/phases/${PHASE_ARG}"
+# Normalize phase and find directory
+PADDED_PHASE=$(printf "%02d" ${PHASE_ARG} 2>/dev/null || echo "${PHASE_ARG}")
+PHASE_DIR=$(ls -d .planning/phases/${PADDED_PHASE}-* .planning/phases/${PHASE_ARG}-* 2>/dev/null | head -1)
 
 # List all PLAN.md files
 ls "$PHASE_DIR"/*-PLAN.md 2>/dev/null

package/agents/gsd-planner.md

@@ -808,7 +808,9 @@ Triggered by `--gaps` flag. Creates plans to address verification or UAT failure
 **1. Find gap sources:**
 
 ```bash
-PHASE_DIR=$(ls -d .planning/phases/${PHASE_ARG}* 2>/dev/null | head -1)
+# Match both zero-padded (05-*) and unpadded (5-*) folders
+PADDED_PHASE=$(printf "%02d" ${PHASE_ARG} 2>/dev/null || echo "${PHASE_ARG}")
+PHASE_DIR=$(ls -d .planning/phases/${PADDED_PHASE}-* .planning/phases/${PHASE_ARG}-* 2>/dev/null | head -1)
 
 # Check for VERIFICATION.md (code verification gaps)
 ls "$PHASE_DIR"/*-VERIFICATION.md 2>/dev/null
@@ -1076,7 +1078,9 @@ Understand:
 **Load phase-specific context files (MANDATORY):**
 
 ```bash
-PHASE_DIR=$(ls -d .planning/phases/${PHASE}-* 2>/dev/null | head -1)
+# Match both zero-padded (05-*) and unpadded (5-*) folders
+PADDED_PHASE=$(printf "%02d" ${PHASE} 2>/dev/null || echo "${PHASE}")
+PHASE_DIR=$(ls -d .planning/phases/${PADDED_PHASE}-* .planning/phases/${PHASE}-* 2>/dev/null | head -1)
 
 # Read CONTEXT.md if exists (from /gsd:discuss-phase)
 cat "${PHASE_DIR}"/*-CONTEXT.md 2>/dev/null

package/bin/install.js

@@ -55,8 +55,6 @@ function parseConfigDirArg() {
 const explicitConfigDir = parseConfigDirArg();
 const hasHelp = args.includes('--help') || args.includes('-h');
 const forceStatusline = args.includes('--force-statusline');
-const forceNotify = args.includes('--force-notify');
-const noNotify = args.includes('--no-notify');
 
 console.log(banner);
 
@@ -70,8 +68,6 @@ if (hasHelp) {
     ${cyan}-c, --config-dir <path>${reset}   Specify custom Claude config directory
     ${cyan}-h, --help${reset}                Show this help message
     ${cyan}--force-statusline${reset}        Replace existing statusline config
-    ${cyan}--force-notify${reset}            Replace existing notification hook
-    ${cyan}--no-notify${reset}               Skip notification hook installation
 
   ${yellow}Examples:${reset}
     ${dim}# Install to default ~/.claude directory${reset}
@@ -221,10 +217,6 @@ function install(isGlobal) {
       const srcFile = path.join(hooksSrc, entry);
       const destFile = path.join(hooksDest, entry);
       fs.copyFileSync(srcFile, destFile);
-      // Make shell scripts executable
-      if (entry.endsWith('.sh')) {
-        fs.chmodSync(destFile, 0o755);
-      }
     }
     console.log(`  ${green}✓${reset} Installed hooks`);
   }
@@ -233,14 +225,11 @@ function install(isGlobal) {
   const settingsPath = path.join(claudeDir, 'settings.json');
   const settings = readSettings(settingsPath);
   const statuslineCommand = isGlobal
-    ? '$HOME/.claude/hooks/statusline.sh'
-    : '.claude/hooks/statusline.sh';
+    ? 'node "$HOME/.claude/hooks/statusline.js"'
+    : 'node .claude/hooks/statusline.js';
   const updateCheckCommand = isGlobal
-    ? '$HOME/.claude/hooks/gsd-check-update.sh'
-    : '.claude/hooks/gsd-check-update.sh';
-  const notifyCommand = isGlobal
-    ? '$HOME/.claude/hooks/gsd-notify.sh'
-    : '.claude/hooks/gsd-notify.sh';
+    ? 'node "$HOME/.claude/hooks/gsd-check-update.js"'
+    : 'node .claude/hooks/gsd-check-update.js';
 
   // Configure SessionStart hook for update checking
   if (!settings.hooks) {
@@ -267,13 +256,13 @@ function install(isGlobal) {
     console.log(`  ${green}✓${reset} Configured update check hook`);
   }
 
-  return { settingsPath, settings, statuslineCommand, notifyCommand };
+  return { settingsPath, settings, statuslineCommand };
 }
 
 /**
- * Apply statusline and notification config, then print completion message
+ * Apply statusline config, then print completion message
  */
-function finishInstall(settingsPath, settings, statuslineCommand, notifyCommand, shouldInstallStatusline, shouldInstallNotify) {
+function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallStatusline) {
   if (shouldInstallStatusline) {
     settings.statusLine = {
       type: 'command',
@@ -282,25 +271,6 @@ function finishInstall(settingsPath, settings, statuslineCommand, notifyCommand,
     console.log(`  ${green}✓${reset} Configured statusline`);
   }
 
-  if (shouldInstallNotify) {
-    if (!settings.hooks.Stop) {
-      settings.hooks.Stop = [];
-    }
-    // Remove any existing GSD notify hook first
-    settings.hooks.Stop = settings.hooks.Stop.filter(entry =>
-      !(entry.hooks && entry.hooks.some(h => h.command && h.command.includes('gsd-notify')))
-    );
-    settings.hooks.Stop.push({
-      hooks: [
-        {
-          type: 'command',
-          command: notifyCommand
-        }
-      ]
-    });
-    console.log(`  ${green}✓${reset} Configured completion notifications`);
-  }
-
   // Always write settings (hooks were already configured in install())
   writeSettings(settingsPath, settings);
 
@@ -365,66 +335,6 @@ function handleStatusline(settings, isInteractive, callback) {
   });
 }
 
-/**
- * Handle notification hook configuration with optional prompt
- */
-function handleNotifications(settings, isInteractive, callback) {
-  // Check if --no-notify flag was passed
-  if (noNotify) {
-    callback(false);
-    return;
-  }
-
-  // Check if GSD notify hook already exists
-  const hasExisting = settings.hooks?.Stop?.some(entry =>
-    entry.hooks && entry.hooks.some(h => h.command && h.command.includes('gsd-notify'))
-  );
-
-  // No existing - just install it
-  if (!hasExisting) {
-    callback(true);
-    return;
-  }
-
-  // Has existing and --force-notify flag
-  if (forceNotify) {
-    callback(true);
-    return;
-  }
-
-  // Has existing, non-interactive mode - skip
-  if (!isInteractive) {
-    console.log(`  ${yellow}⚠${reset} Skipping notifications (already configured)`);
-    console.log(`    Use ${cyan}--force-notify${reset} to replace\n`);
-    callback(false);
-    return;
-  }
-
-  // Has existing, interactive mode - prompt user
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout
-  });
-
-  console.log(`
-  ${yellow}⚠${reset} Existing notification hook detected
-
-  GSD includes completion notifications that alert you when:
-    • A phase completes planning or execution
-    • Claude stops and needs your input
-    • Works on Mac, Linux, and Windows
-
-  ${cyan}1${reset}) Keep existing
-  ${cyan}2${reset}) Replace with GSD notifications
-`);
-
-  rl.question(`  Choice ${dim}[1]${reset}: `, (answer) => {
-    rl.close();
-    const choice = answer.trim() || '1';
-    callback(choice === '2');
-  });
-}
-
 /**
  * Prompt for install location
  */
@@ -448,12 +358,10 @@ function promptLocation() {
     rl.close();
     const choice = answer.trim() || '1';
     const isGlobal = choice !== '2';
-    const { settingsPath, settings, statuslineCommand, notifyCommand } = install(isGlobal);
+    const { settingsPath, settings, statuslineCommand } = install(isGlobal);
     // Interactive mode - prompt for optional features
     handleStatusline(settings, true, (shouldInstallStatusline) => {
-      handleNotifications(settings, true, (shouldInstallNotify) => {
-        finishInstall(settingsPath, settings, statuslineCommand, notifyCommand, shouldInstallStatusline, shouldInstallNotify);
-      });
+      finishInstall(settingsPath, settings, statuslineCommand, shouldInstallStatusline);
     });
   });
 }
@@ -466,20 +374,16 @@ if (hasGlobal && hasLocal) {
   console.error(`  ${yellow}Cannot use --config-dir with --local${reset}`);
   process.exit(1);
 } else if (hasGlobal) {
-  const { settingsPath, settings, statuslineCommand, notifyCommand } = install(true);
+  const { settingsPath, settings, statuslineCommand } = install(true);
   // Non-interactive - respect flags
   handleStatusline(settings, false, (shouldInstallStatusline) => {
-    handleNotifications(settings, false, (shouldInstallNotify) => {
-      finishInstall(settingsPath, settings, statuslineCommand, notifyCommand, shouldInstallStatusline, shouldInstallNotify);
-    });
+    finishInstall(settingsPath, settings, statuslineCommand, shouldInstallStatusline);
   });
 } else if (hasLocal) {
-  const { settingsPath, settings, statuslineCommand, notifyCommand } = install(false);
+  const { settingsPath, settings, statuslineCommand } = install(false);
   // Non-interactive - respect flags
   handleStatusline(settings, false, (shouldInstallStatusline) => {
-    handleNotifications(settings, false, (shouldInstallNotify) => {
-      finishInstall(settingsPath, settings, statuslineCommand, notifyCommand, shouldInstallStatusline, shouldInstallNotify);
-    });
+    finishInstall(settingsPath, settings, statuslineCommand, shouldInstallStatusline);
   });
 } else {
   promptLocation();

package/commands/gsd/audit-milestone.md

@@ -18,7 +18,7 @@ Verify milestone achieved its definition of done. Check requirements coverage, c
 </objective>
 
 <execution_context>
-@~/.claude/get-shit-done/references/principles.md
+<!-- Spawns gsd-integration-checker agent which has all audit expertise baked in -->
 </execution_context>
 
 <context>

package/commands/gsd/create-roadmap.md

@@ -35,11 +35,9 @@ Roadmaps define what work happens in what order. Phases map to requirements.
 </objective>
 
 <execution_context>
-@~/.claude/get-shit-done/references/principles.md
 @~/.claude/get-shit-done/workflows/create-roadmap.md
 @~/.claude/get-shit-done/templates/roadmap.md
 @~/.claude/get-shit-done/templates/state.md
-@~/.claude/get-shit-done/references/goal-backward.md
 </execution_context>
 
 <context>

package/commands/gsd/define-requirements.md

@@ -36,7 +36,6 @@ Output: `.planning/REQUIREMENTS.md`
 </objective>
 
 <execution_context>
-@~/.claude/get-shit-done/references/principles.md
 @~/.claude/get-shit-done/workflows/define-requirements.md
 @~/.claude/get-shit-done/templates/requirements.md
 </execution_context>

package/commands/gsd/discuss-milestone.md

@@ -11,7 +11,6 @@ Output: Context gathered, then routes to /gsd:new-milestone
 </objective>
 
 <execution_context>
-@~/.claude/get-shit-done/references/principles.md
 @~/.claude/get-shit-done/workflows/discuss-milestone.md
 </execution_context>
 

package/commands/gsd/discuss-phase.md

@@ -18,7 +18,6 @@ Extract implementation decisions that downstream agents need — researcher and
 </objective>
 
 <execution_context>
-@~/.claude/get-shit-done/references/principles.md
 @~/.claude/get-shit-done/workflows/discuss-phase.md
 @~/.claude/get-shit-done/templates/context.md
 </execution_context>
@@ -36,10 +35,10 @@ Phase number: $ARGUMENTS (required)
 <process>
 1. Validate phase number (error if missing or not in roadmap)
 2. Check if CONTEXT.md exists (offer update/view/skip if yes)
-3. **Analyze phase** — Identify domain boundary and gray areas by category
-4. **Present gray areas** — Multi-select AskUserQuestion: which to discuss?
-5. **Deep-dive each area** — Loop per area until user says "move on"
-6. **Write CONTEXT.md** — Structured by decisions made
+3. **Analyze phase** — Identify domain and generate phase-specific gray areas
+4. **Present gray areas** — Multi-select: which to discuss? (NO skip option)
+5. **Deep-dive each area** — 4 questions per area, then offer more/next
+6. **Write CONTEXT.md** — Sections match areas discussed
 7. Offer next steps (research or plan)
 
 **CRITICAL: Scope guardrail**
@@ -48,18 +47,27 @@ Phase number: $ARGUMENTS (required)
 - If user suggests new capabilities: "That's its own phase. I'll note it for later."
 - Capture deferred ideas — don't lose them, don't act on them
 
-**Gray area categories (use what's relevant):**
-- **UI** — Layout, visual presentation, information density
-- **UX** — Interactions, flows, feedback
-- **Behavior** — Runtime behavior, state changes
-- **Empty/Edge States** — What shows in unusual situations
-- **Content** — What information is shown/hidden
+**Domain-aware gray areas:**
+Gray areas depend on what's being built. Analyze the phase goal:
+- Something users SEE → layout, density, interactions, states
+- Something users CALL → responses, errors, auth, versioning
+- Something users RUN → output format, flags, modes, error handling
+- Something users READ → structure, tone, depth, flow
+- Something being ORGANIZED → criteria, grouping, naming, exceptions
 
-**Do NOT ask about (downstream agents handle these):**
-- Technical implementation (researcher investigates)
-- Architecture choices (planner decides)
-- Performance concerns (researcher/planner handle)
-- Scope expansion (roadmap defines scope)
+Generate 3-4 **phase-specific** gray areas, not generic categories.
+
+**Probing depth:**
+- Ask 4 questions per area before checking
+- "More questions about [area], or move to next?"
+- If more → ask 4 more, check again
+- After all areas → "Ready to create context?"
+
+**Do NOT ask about (Claude handles these):**
+- Technical implementation
+- Architecture choices
+- Performance concerns
+- Scope expansion
 </process>
 
 <success_criteria>

package/commands/gsd/execute-phase.md

@@ -23,7 +23,6 @@ Context budget: ~15% orchestrator, 100% fresh per subagent.
 </objective>
 
 <execution_context>
-@~/.claude/get-shit-done/references/principles.md
 @~/.claude/get-shit-done/references/ui-brand.md
 @~/.claude/get-shit-done/workflows/execute-phase.md
 </execution_context>

package/commands/gsd/help.md

@@ -127,30 +127,16 @@ Result: Creates `.planning/phases/01-foundation/01-01-PLAN.md`
 
 ### Execution
 
-**`/gsd:execute-plan <path>`**
-Execute a single PLAN.md file.
-
-- Runs plan tasks sequentially
-- Creates SUMMARY.md after completion
-- Updates STATE.md with accumulated context
-- Use for interactive execution with checkpoints
-
-Usage: `/gsd:execute-plan .planning/phases/01-foundation/01-01-PLAN.md`
-
 **`/gsd:execute-phase <phase-number>`**
-Execute all unexecuted plans in a phase with parallel background agents.
+Execute all plans in a phase.
 
-- Analyzes plan dependencies and spawns independent plans concurrently
-- Use when phase has 2+ plans and you want "walk away" execution
-- Respects max_concurrent_agents from config.json
+- Groups plans by wave (from frontmatter), executes waves sequentially
+- Plans within each wave run in parallel via Task tool
+- Verifies phase goal after all plans complete
+- Updates REQUIREMENTS.md, ROADMAP.md, STATE.md
 
 Usage: `/gsd:execute-phase 5`
 
-Options (via `.planning/config.json` parallelization section):
-- `max_concurrent_agents`: Limit parallel agents (default: 3)
-- `skip_checkpoints`: Skip human checkpoints in background (default: true)
-- `min_plans_for_parallel`: Minimum plans to trigger parallelization (default: 2)
-
 ### Roadmap Management
 
 **`/gsd:add-phase <description>`**
@@ -373,7 +359,7 @@ Change anytime by editing `.planning/config.json`
 ```
 /gsd:insert-phase 5 "Critical security fix"
 /gsd:plan-phase 5.1
-/gsd:execute-plan .planning/phases/05.1-critical-security-fix/05.1-01-PLAN.md
+/gsd:execute-phase 5.1
 ```
 
 **Completing a milestone:**

package/commands/gsd/new-milestone.md

@@ -90,6 +90,8 @@ Milestone name: $ARGUMENTS (optional - will prompt if not provided)
    Last activity: [today] — Milestone v[X.Y] started
    ```
 
+   Keep Accumulated Context section (decisions, blockers) from previous milestone.
+
 6. **Cleanup:**
    - Delete MILESTONE-CONTEXT.md if exists (consumed)
 

package/commands/gsd/plan-milestone-gaps.md

@@ -19,8 +19,7 @@ One command creates all fix phases — no manual `/gsd:add-phase` per gap.
 </objective>
 
 <execution_context>
-@~/.claude/get-shit-done/references/principles.md
-@~/.claude/get-shit-done/workflows/plan-phase.md
+<!-- Spawns gsd-planner agent which has all planning expertise baked in -->
 </execution_context>
 
 <context>

package/commands/gsd/plan-phase.md

@@ -37,13 +37,7 @@ Phase number: $ARGUMENTS (optional - auto-detects next unplanned phase if not pr
 - `--gaps` — Gap closure mode (reads VERIFICATION.md, skips research)
 - `--skip-verify` — Skip planner → checker verification loop
 
-Check for existing research and plans:
-
-```bash
-ls .planning/phases/${PHASE}-*/*-RESEARCH.md 2>/dev/null
-ls .planning/phases/${PHASE}-*/*-PLAN.md 2>/dev/null
-```
-
+Normalize phase input in step 2 before any directory lookups.
 </context>
 
 <process>
@@ -56,7 +50,7 @@ ls .planning/ 2>/dev/null
 
 **If not found:** Error - user should run `/gsd:new-project` first.
 
-## 2. Parse Arguments
+## 2. Parse and Normalize Arguments
 
 Extract from $ARGUMENTS:
 
@@ -68,6 +62,24 @@ Extract from $ARGUMENTS:
 
 **If no phase number:** Detect next unplanned phase from roadmap.
 
+**Normalize phase to zero-padded format:**
+
+```bash
+# Normalize phase number (8 → 08, but preserve decimals like 2.1 → 02.1)
+if [[ "$PHASE" =~ ^[0-9]+$ ]]; then
+  PHASE=$(printf "%02d" "$PHASE")
+elif [[ "$PHASE" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
+  PHASE=$(printf "%02d.%s" "${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}")
+fi
+```
+
+**Check for existing research and plans:**
+
+```bash
+ls .planning/phases/${PHASE}-*/*-RESEARCH.md 2>/dev/null
+ls .planning/phases/${PHASE}-*/*-PLAN.md 2>/dev/null
+```
+
 ## 3. Validate Phase
 
 ```bash
@@ -79,13 +91,13 @@ grep -A5 "Phase ${PHASE}:" .planning/ROADMAP.md 2>/dev/null
 ## 4. Ensure Phase Directory Exists
 
 ```bash
+# PHASE is already normalized (08, 02.1, etc.) from step 2
 PHASE_DIR=$(ls -d .planning/phases/${PHASE}-* 2>/dev/null | head -1)
 if [ -z "$PHASE_DIR" ]; then
-  # Create phase directory from roadmap name with zero-padded phase number
+  # Create phase directory from roadmap name
   PHASE_NAME=$(grep "Phase ${PHASE}:" .planning/ROADMAP.md | sed 's/.*Phase [0-9]*: //' | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
-  PADDED_PHASE=$(printf "%02d" ${PHASE})
-  mkdir -p ".planning/phases/${PADDED_PHASE}-${PHASE_NAME}"
-  PHASE_DIR=".planning/phases/${PADDED_PHASE}-${PHASE_NAME}"
+  mkdir -p ".planning/phases/${PHASE}-${PHASE_NAME}"
+  PHASE_DIR=".planning/phases/${PHASE}-${PHASE_NAME}"
 fi
 ```
 
@@ -251,7 +263,7 @@ Fill prompt and spawn:
 </planning_context>
 
 <downstream_consumer>
-Output consumed by /gsd:execute-phase or /gsd:execute-plan
+Output consumed by /gsd:execute-phase
 Plans must be executable prompts with:
 
 - Frontmatter (wave, depends_on, files_modified, autonomous)

package/commands/gsd/progress.md

@@ -154,7 +154,7 @@ Read its `<objective>` section.
 
 **{phase}-{plan}: [Plan Name]** — [objective summary from PLAN.md]
 
-`/gsd:execute-plan [full-path-to-PLAN.md]`
+`/gsd:execute-phase {phase}`
 
 <sub>`/clear` first → fresh context window</sub>
 
@@ -226,7 +226,7 @@ UAT.md exists with gaps (diagnosed issues). User needs to plan fixes.
 ---
 
 **Also available:**
-- `/gsd:execute-plan [path]` — continue with other work first
+- `/gsd:execute-phase {phase}` — execute phase plans
 - `/gsd:verify-work {phase}` — run more UAT testing
 
 ---
@@ -359,7 +359,7 @@ Ready to plan the next milestone.
 - [ ] Rich context provided (recent work, decisions, issues)
 - [ ] Current position clear with visual progress
 - [ ] What's next clearly explained
-- [ ] Smart routing: /gsd:execute-plan if plan exists, /gsd:plan-phase if not
+- [ ] Smart routing: /gsd:execute-phase if plans exist, /gsd:plan-phase if not
 - [ ] User confirms before any action
 - [ ] Seamless handoff to appropriate gsd command
       </success_criteria>

package/commands/gsd/research-phase.md

@@ -26,17 +26,23 @@ Research how to implement a phase. Spawns gsd-phase-researcher agent with phase
 <context>
 Phase number: $ARGUMENTS (required)
 
-Check for existing research:
-```bash
-ls .planning/phases/${PHASE}-*/*RESEARCH.md 2>/dev/null
-```
+Normalize phase input in step 1 before any directory lookups.
 </context>
 
 <process>
 
-## 1. Parse and Validate Phase
+## 1. Normalize and Validate Phase
 
 ```bash
+# Normalize phase number (8 → 08, but preserve decimals like 2.1 → 02.1)
+if [[ "$ARGUMENTS" =~ ^[0-9]+$ ]]; then
+  PHASE=$(printf "%02d" "$ARGUMENTS")
+elif [[ "$ARGUMENTS" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
+  PHASE=$(printf "%02d.%s" "${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}")
+else
+  PHASE="$ARGUMENTS"
+fi
+
 grep -A5 "Phase ${PHASE}:" .planning/ROADMAP.md 2>/dev/null
 ```
 
@@ -118,7 +124,7 @@ Before declaring complete, verify:
 </quality_gate>
 
 <output>
-Write to: .planning/phases/{phase}-{slug}/{phase}-RESEARCH.md
+Write to: .planning/phases/${PHASE}-{slug}/${PHASE}-RESEARCH.md
 </output>
 ```
 
@@ -146,7 +152,7 @@ Continue research for Phase {phase_number}: {phase_name}
 </objective>
 
 <prior_state>
-Research file: @.planning/phases/{phase}-{slug}/{phase}-RESEARCH.md
+Research file: @.planning/phases/${PHASE}-{slug}/${PHASE}-RESEARCH.md
 </prior_state>
 
 <checkpoint_response>

package/get-shit-done/references/continuation-format.md

@@ -44,7 +44,7 @@ Standard format for presenting next steps after completing a command or workflow
 
 **02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
 
-`/gsd:execute-plan .planning/phases/02-auth/02-03-PLAN.md`
+`/gsd:execute-phase 2`
 
 <sub>`/clear` first → fresh context window</sub>
 
@@ -69,7 +69,7 @@ Add note that this is the last plan and what comes after:
 **02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
 <sub>Final plan in Phase 2</sub>
 
-`/gsd:execute-plan .planning/phases/02-auth/02-03-PLAN.md`
+`/gsd:execute-phase 2`
 
 <sub>`/clear` first → fresh context window</sub>
 
@@ -220,7 +220,7 @@ Extract: `**02-03: Refresh Token Rotation** — Add /api/auth/refresh with slidi
 ## To Continue
 
 Run `/clear`, then paste:
-/gsd:execute-plan .planning/phases/02-auth/02-03-PLAN.md
+/gsd:execute-phase 2
 ```
 
 User has no idea what 02-03 is about.