get-shit-done-cc 1.5.28 → 1.5.29

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/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/discuss-phase.md

@@ -35,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**
@@ -47,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/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,14 +91,13 @@ grep -A5 "Phase ${PHASE}:" .planning/ROADMAP.md 2>/dev/null
 ## 4. Ensure Phase Directory Exists
 
 ```bash
-# Match both zero-padded (05-*) and unpadded (5-*) folders
-PADDED_PHASE=$(printf "%02d" ${PHASE})
-PHASE_DIR=$(ls -d .planning/phases/${PADDED_PHASE}-* .planning/phases/${PHASE}-* 2>/dev/null | head -1)
+# 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 ' ' '-')
-  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
 ```
 

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/templates/context.md

@@ -4,6 +4,8 @@ Template for `.planning/phases/XX-name/{phase}-CONTEXT.md` - captures implementa
 
 **Purpose:** Document decisions that downstream agents need. Researcher uses this to know WHAT to investigate. Planner uses this to know WHAT choices are locked vs flexible.
 
+**Key principle:** Categories are NOT predefined. They emerge from what was actually discussed for THIS phase. A CLI phase has CLI-relevant sections, a UI phase has UI-relevant sections.
+
 **Downstream consumers:**
 - `gsd-phase-researcher` — Reads decisions to focus research (e.g., "card layout" → research card component patterns)
 - `gsd-planner` — Reads decisions to create specific tasks (e.g., "infinite scroll" → task includes virtualization)
@@ -28,11 +30,14 @@ Template for `.planning/phases/XX-name/{phase}-CONTEXT.md` - captures implementa
 <decisions>
 ## Implementation Decisions
 
-### [Category discussed, e.g., UI]
+### [Area 1 that was discussed]
 - [Specific decision made]
 - [Another decision if applicable]
 
-### [Category discussed, e.g., Behavior]
+### [Area 2 that was discussed]
+- [Specific decision made]
+
+### [Area 3 that was discussed]
 - [Specific decision made]
 
 ### Claude's Discretion
@@ -65,6 +70,9 @@ Template for `.planning/phases/XX-name/{phase}-CONTEXT.md` - captures implementa
 ```
 
 <good_examples>
+
+**Example 1: Visual feature (Post Feed)**
+
 ```markdown
 # Phase 3: Post Feed - Context
 
@@ -81,18 +89,17 @@ Display posts from followed users in a scrollable feed. Users can view posts and
 <decisions>
 ## Implementation Decisions
 
-### UI
+### Layout style
 - Card-based layout, not timeline or list
 - Each card shows: author avatar, name, timestamp, full post content, reaction counts
 - Cards have subtle shadows, rounded corners — modern feel
-- Show 10 posts initially, load more on scroll
 
-### Behavior
+### Loading behavior
 - Infinite scroll, not pagination
 - Pull-to-refresh on mobile
 - New posts indicator at top ("3 new posts") rather than auto-inserting
 
-### Empty State
+### Empty state
 - Friendly illustration + "Follow people to see posts here"
 - Suggest 3-5 accounts to follow based on interests
 
@@ -108,7 +115,6 @@ Display posts from followed users in a scrollable feed. Users can view posts and
 
 - "I like how Twitter shows the new posts indicator without disrupting your scroll position"
 - Cards should feel like Linear's issue cards — clean, not cluttered
-- No infinite scroll fatigue — maybe show "You're all caught up" after ~50 posts
 
 </specifics>
 
@@ -116,7 +122,6 @@ Display posts from followed users in a scrollable feed. Users can view posts and
 ## Deferred Ideas
 
 - Commenting on posts — Phase 5
-- Reaction picker (not just counts) — Phase 5
 - Bookmarking posts — add to backlog
 
 </deferred>
@@ -126,6 +131,131 @@ Display posts from followed users in a scrollable feed. Users can view posts and
 *Phase: 03-post-feed*
 *Context gathered: 2025-01-20*
 ```
+
+**Example 2: CLI tool (Database backup)**
+
+```markdown
+# Phase 2: Backup Command - Context
+
+**Gathered:** 2025-01-20
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+CLI command to backup database to local file or S3. Supports full and incremental backups. Restore command is a separate phase.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Output format
+- JSON for programmatic use, table format for humans
+- Default to table, --json flag for JSON
+- Verbose mode (-v) shows progress, silent by default
+
+### Flag design
+- Short flags for common options: -o (output), -v (verbose), -f (force)
+- Long flags for clarity: --incremental, --compress, --encrypt
+- Required: database connection string (positional or --db)
+
+### Error recovery
+- Retry 3 times on network failure, then fail with clear message
+- --no-retry flag to fail fast
+- Partial backups are deleted on failure (no corrupt files)
+
+### Claude's Discretion
+- Exact progress bar implementation
+- Compression algorithm choice
+- Temp file handling
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- "I want it to feel like pg_dump — familiar to database people"
+- Should work in CI pipelines (exit codes, no interactive prompts)
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- Scheduled backups — separate phase
+- Backup rotation/retention — add to backlog
+
+</deferred>
+
+---
+
+*Phase: 02-backup-command*
+*Context gathered: 2025-01-20*
+```
+
+**Example 3: Organization task (Photo library)**
+
+```markdown
+# Phase 1: Photo Organization - Context
+
+**Gathered:** 2025-01-20
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Organize existing photo library into structured folders. Handle duplicates and apply consistent naming. Tagging and search are separate phases.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Grouping criteria
+- Primary grouping by year, then by month
+- Events detected by time clustering (photos within 2 hours = same event)
+- Event folders named by date + location if available
+
+### Duplicate handling
+- Keep highest resolution version
+- Move duplicates to _duplicates folder (don't delete)
+- Log all duplicate decisions for review
+
+### Naming convention
+- Format: YYYY-MM-DD_HH-MM-SS_originalname.ext
+- Preserve original filename as suffix for searchability
+- Handle name collisions with incrementing suffix
+
+### Claude's Discretion
+- Exact clustering algorithm
+- How to handle photos with no EXIF data
+- Folder emoji usage
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- "I want to be able to find photos by roughly when they were taken"
+- Don't delete anything — worst case, move to a review folder
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- Face detection grouping — future phase
+- Cloud sync — out of scope for now
+
+</deferred>
+
+---
+
+*Phase: 01-photo-organization*
+*Context gathered: 2025-01-20*
+```
+
 </good_examples>
 
 <guidelines>
@@ -133,11 +263,11 @@ Display posts from followed users in a scrollable feed. Users can view posts and
 
 The output should answer: "What does the researcher need to investigate? What choices are locked for the planner?"
 
-**Good content:**
+**Good content (concrete decisions):**
 - "Card-based layout, not timeline"
-- "Infinite scroll with pull-to-refresh"
-- "Show 10 posts initially"
-- "New posts indicator rather than auto-insert"
+- "Retry 3 times on network failure, then fail"
+- "Group by year, then by month"
+- "JSON for programmatic use, table for humans"
 
 **Bad content (too vague):**
 - "Should feel modern and clean"
@@ -148,7 +278,7 @@ The output should answer: "What does the researcher need to investigate? What ch
 **Sections explained:**
 
 - **Domain** — The scope anchor. Copied/derived from ROADMAP.md. Fixed boundary.
-- **Decisions** — Organized by category (UI, UX, Behavior, etc.). Actual choices made.
+- **Decisions** — Organized by areas discussed (NOT predefined categories). Section headers come from the actual discussion — "Layout style", "Flag design", "Grouping criteria", etc.
 - **Claude's Discretion** — Explicit acknowledgment of what Claude can decide during implementation.
 - **Specifics** — Product references, examples, "like X but..." statements.
 - **Deferred** — Ideas captured but explicitly out of scope. Prevents scope creep while preserving good ideas.

package/get-shit-done/workflows/discuss-phase.md

@@ -66,23 +66,44 @@ For now, let's focus on [phase domain]."
 Capture the idea in a "Deferred Ideas" section. Don't lose it, don't act on it.
 </scope_guardrail>
 
-<gray_area_categories>
-Use these categories when analyzing a phase. Not all apply to every phase.
-
-| Category | What it clarifies | Example questions |
-|----------|-------------------|-------------------|
-| **UI** | Visual presentation, layout, information density | "Card-based or list view?" "What info shows on each item?" |
-| **UX** | Interactions, flows, feedback | "How does loading work?" "What happens when you tap X?" |
-| **Behavior** | Runtime behavior, state changes | "Auto-refresh or manual?" "How does pagination work?" |
-| **Empty/Edge States** | What shows in unusual situations | "What appears with no data?" "How do errors display?" |
-| **Content** | What information is shown/hidden | "Show timestamps?" "How much preview text?" |
-
-**Categories to AVOID:**
-- **Scope** — The roadmap defines scope, not discussion
-- **Technical** — You figure out implementation
-- **Architecture** — You decide patterns
-- **Performance** — You handle optimization
-</gray_area_categories>
+<gray_area_identification>
+Gray areas are **implementation decisions the user cares about** — things that could go multiple ways and would change the result.
+
+**How to identify gray areas:**
+
+1. **Read the phase goal** from ROADMAP.md
+2. **Understand the domain** — What kind of thing is being built?
+   - Something users SEE → visual presentation, interactions, states matter
+   - Something users CALL → interface contracts, responses, errors matter
+   - Something users RUN → invocation, output, behavior modes matter
+   - Something users READ → structure, tone, depth, flow matter
+   - Something being ORGANIZED → criteria, grouping, handling exceptions matter
+3. **Generate phase-specific gray areas** — Not generic categories, but concrete decisions for THIS phase
+
+**Don't use generic category labels** (UI, UX, Behavior). Generate specific gray areas:
+
+```
+Phase: "User authentication"
+→ Session handling, Error responses, Multi-device policy, Recovery flow
+
+Phase: "Organize photo library"
+→ Grouping criteria, Duplicate handling, Naming convention, Folder structure
+
+Phase: "CLI for database backups"
+→ Output format, Flag design, Progress reporting, Error recovery
+
+Phase: "API documentation"
+→ Structure/navigation, Code examples depth, Versioning approach, Interactive elements
+```
+
+**The key question:** What decisions would change the outcome that the user should weigh in on?
+
+**Claude handles these (don't ask):**
+- Technical implementation details
+- Architecture patterns
+- Performance optimization
+- Scope (roadmap defines this)
+</gray_area_identification>
 
 <process>
 
@@ -169,47 +190,79 @@ We'll clarify HOW to implement this.
 
 **Then use AskUserQuestion (multiSelect: true):**
 - header: "Discuss"
-- question: "Which areas do you want to discuss?"
-- options: Generate 2-4 based on your analysis, each formatted as:
-  - "[Category] — [Specific gray area question]"
-  - Last option always: "None — you decide, proceed to planning"
+- question: "Which areas do you want to discuss for [phase name]?"
+- options: Generate 3-4 phase-specific gray areas, each formatted as:
+  - "[Specific area]" (label) — concrete, not generic
+  - [1-2 questions this covers] (description)
+
+**Do NOT include a "skip" or "you decide" option.** User ran this command to discuss — give them real choices.
 
-**Example options:**
+**Examples by domain:**
+
+For "Post Feed" (visual feature):
+```
+☐ Layout style — Cards vs list vs timeline? Information density?
+☐ Loading behavior — Infinite scroll or pagination? Pull to refresh?
+☐ Content ordering — Chronological, algorithmic, or user choice?
+☐ Post metadata — What info per post? Timestamps, reactions, author?
+```
+
+For "Database backup CLI" (command-line tool):
+```
+☐ Output format — JSON, table, or plain text? Verbosity levels?
+☐ Flag design — Short flags, long flags, or both? Required vs optional?
+☐ Progress reporting — Silent, progress bar, or verbose logging?
+☐ Error recovery — Fail fast, retry, or prompt for action?
+```
+
+For "Organize photo library" (organization task):
 ```
-☐ UI — Card layout or timeline? How much of each post shows?
-☐ Behavior — Infinite scroll or pagination? Pull to refresh?
-☐ Empty state — What appears when there are no posts?
-☐ None — You decide, proceed to planning
+☐ Grouping criteria — By date, location, faces, or events?
+☐ Duplicate handling — Keep best, keep all, or prompt each time?
+☐ Naming convention — Original names, dates, or descriptive?
+☐ Folder structure — Flat, nested by year, or by category?
 ```
 
-If user selects "None": Skip to write_context with minimal context.
-Otherwise: Continue to discuss_areas with selected areas.
+Continue to discuss_areas with selected areas.
 </step>
 
 <step name="discuss_areas">
 For each selected area, conduct a focused discussion loop.
 
+**Philosophy: 4 questions, then check.**
+
+Ask 4 questions per area before offering to continue or move on. Each answer often reveals the next question.
+
 **For each area:**
 
 1. **Announce the area:**
    ```
-   Let's talk about [Category].
+   Let's talk about [Area].
    ```
 
-2. **Ask focused questions using AskUserQuestion:**
-   - header: "[Category]"
-   - question: Specific question about that gray area
-   - options: 2-3 concrete choices + "Let me describe" + "You decide"
+2. **Ask 4 questions using AskUserQuestion:**
+   - header: "[Area]"
+   - question: Specific decision for this area
+   - options: 2-3 concrete choices (AskUserQuestion adds "Other" automatically)
+   - Include "You decide" as an option when reasonable — captures Claude discretion
 
-3. **Follow up based on response:**
-   - If they chose an option: Capture it, ask if there's more about this area
-   - If "Let me describe": Receive their input, reflect it back, confirm understanding
-   - If "You decide": Note that Claude has discretion here
+3. **After 4 questions, check:**
+   - header: "[Area]"
+   - question: "More questions about [area], or move to next?"
+   - options: "More questions" / "Next area"
 
-4. **Loop control — Always offer:**
-   - "Ask more about [Category]" — Continue probing this area
-   - "Move to next area" — Done with this category
-   - "That's enough, create context" — Done with all discussion
+   If "More questions" → ask 4 more, then check again
+   If "Next area" → proceed to next selected area
+
+4. **After all areas complete:**
+   - header: "Done"
+   - question: "That covers [list areas]. Ready to create context?"
+   - options: "Create context" / "Revisit an area"
+
+**Question design:**
+- Options should be concrete, not abstract ("Cards" not "Option A")
+- Each answer should inform the next question
+- If user picks "Other", receive their input, reflect it back, confirm
 
 **Scope creep handling:**
 If user mentions something outside the phase domain:
@@ -217,14 +270,10 @@ If user mentions something outside the phase domain:
 "[Feature] sounds like a new capability — that belongs in its own phase.
 I'll note it as a deferred idea.
 
-Back to [current domain]: [return to current question]"
+Back to [current area]: [return to current question]"
 ```
 
 Track deferred ideas internally.
-
-**Continue until:**
-- User says "Move to next area" and all selected areas are done, OR
-- User says "That's enough, create context"
 </step>
 
 <step name="write_context">

package/hooks/gsd-check-update.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+// Check for GSD updates in background, write result to cache
+// Called by SessionStart hook - runs once per session
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync, spawn } = require('child_process');
+
+const homeDir = os.homedir();
+const cacheDir = path.join(homeDir, '.claude', 'cache');
+const cacheFile = path.join(cacheDir, 'gsd-update-check.json');
+const versionFile = path.join(homeDir, '.claude', 'get-shit-done', 'VERSION');
+
+// Ensure cache directory exists
+if (!fs.existsSync(cacheDir)) {
+  fs.mkdirSync(cacheDir, { recursive: true });
+}
+
+// Run check in background (spawn detached process)
+const child = spawn(process.execPath, ['-e', `
+  const fs = require('fs');
+  const { execSync } = require('child_process');
+
+  const cacheFile = ${JSON.stringify(cacheFile)};
+  const versionFile = ${JSON.stringify(versionFile)};
+
+  let installed = '0.0.0';
+  try {
+    installed = fs.readFileSync(versionFile, 'utf8').trim();
+  } catch (e) {}
+
+  let latest = null;
+  try {
+    latest = execSync('npm view get-shit-done-cc version', { encoding: 'utf8', timeout: 10000 }).trim();
+  } catch (e) {}
+
+  const result = {
+    update_available: latest && installed !== latest,
+    installed,
+    latest: latest || 'unknown',
+    checked: Math.floor(Date.now() / 1000)
+  };
+
+  fs.writeFileSync(cacheFile, JSON.stringify(result));
+`], {
+  detached: true,
+  stdio: 'ignore'
+});
+
+child.unref();

package/hooks/statusline.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// Claude Code Statusline - GSD Edition
+// Shows: model | current task | directory | context usage
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Read JSON from stdin
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const model = data.model?.display_name || 'Claude';
+    const dir = data.workspace?.current_dir || process.cwd();
+    const session = data.session_id || '';
+    const remaining = data.context_window?.remaining_percentage;
+
+    // Context window display (shows USED percentage)
+    let ctx = '';
+    if (remaining != null) {
+      const rem = Math.round(remaining);
+      const used = 100 - rem;
+
+      // Build progress bar (10 segments)
+      const filled = Math.floor(used / 10);
+      const bar = '█'.repeat(filled) + '░'.repeat(10 - filled);
+
+      // Color based on usage
+      if (used < 50) {
+        ctx = ` \x1b[32m${bar} ${used}%\x1b[0m`;
+      } else if (used < 65) {
+        ctx = ` \x1b[33m${bar} ${used}%\x1b[0m`;
+      } else if (used < 80) {
+        ctx = ` \x1b[38;5;208m${bar} ${used}%\x1b[0m`;
+      } else {
+        ctx = ` \x1b[5;31m💀 ${bar} ${used}%\x1b[0m`;
+      }
+    }
+
+    // Current task from todos
+    let task = '';
+    const homeDir = os.homedir();
+    const todosDir = path.join(homeDir, '.claude', 'todos');
+    if (session && fs.existsSync(todosDir)) {
+      const files = fs.readdirSync(todosDir)
+        .filter(f => f.startsWith(session) && f.includes('-agent-') && f.endsWith('.json'))
+        .map(f => ({ name: f, mtime: fs.statSync(path.join(todosDir, f)).mtime }))
+        .sort((a, b) => b.mtime - a.mtime);
+
+      if (files.length > 0) {
+        try {
+          const todos = JSON.parse(fs.readFileSync(path.join(todosDir, files[0].name), 'utf8'));
+          const inProgress = todos.find(t => t.status === 'in_progress');
+          if (inProgress) task = inProgress.activeForm || '';
+        } catch (e) {}
+      }
+    }
+
+    // GSD update available?
+    let gsdUpdate = '';
+    const cacheFile = path.join(homeDir, '.claude', 'cache', 'gsd-update-check.json');
+    if (fs.existsSync(cacheFile)) {
+      try {
+        const cache = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+        if (cache.update_available) {
+          gsdUpdate = '\x1b[33m⬆ /gsd:update\x1b[0m │ ';
+        }
+      } catch (e) {}
+    }
+
+    // Output
+    const dirname = path.basename(dir);
+    if (task) {
+      process.stdout.write(`${gsdUpdate}\x1b[2m${model}\x1b[0m │ \x1b[1m${task}\x1b[0m │ \x1b[2m${dirname}\x1b[0m${ctx}`);
+    } else {
+      process.stdout.write(`${gsdUpdate}\x1b[2m${model}\x1b[0m │ \x1b[2m${dirname}\x1b[0m${ctx}`);
+    }
+  } catch (e) {
+    // Silent fail - don't break statusline on parse errors
+  }
+});

package/package.json

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

package/hooks/gsd-check-update.sh

@@ -1,20 +0,0 @@
-#!/bin/bash
-# Check for GSD updates in background, write result to cache
-# Called by SessionStart hook - runs once per session
-
-CACHE_FILE="$HOME/.claude/cache/gsd-update-check.json"
-mkdir -p "$HOME/.claude/cache"
-
-# Run check in background (non-blocking)
-(
-  installed=$(cat "$HOME/.claude/get-shit-done/VERSION" 2>/dev/null || echo "0.0.0")
-  latest=$(npm view get-shit-done-cc version 2>/dev/null)
-
-  if [[ -n "$latest" && "$installed" != "$latest" ]]; then
-    echo "{\"update_available\":true,\"installed\":\"$installed\",\"latest\":\"$latest\",\"checked\":$(date +%s)}" > "$CACHE_FILE"
-  else
-    echo "{\"update_available\":false,\"installed\":\"$installed\",\"latest\":\"${latest:-unknown}\",\"checked\":$(date +%s)}" > "$CACHE_FILE"
-  fi
-) &
-
-exit 0

package/hooks/gsd-notify.sh

@@ -1,59 +0,0 @@
-#!/bin/bash
-# GSD Completion Notification Hook
-# Cross-platform alert when Claude stops (task complete, needs input, etc.)
-
-input=$(cat)
-session_id=$(echo "$input" | jq -r '.session_id // empty')
-cwd=$(echo "$input" | jq -r '.cwd // empty')
-transcript_path=$(echo "$input" | jq -r '.transcript_path // empty')
-
-# Extract project name
-project="Claude Code"
-if [[ -n "$cwd" ]]; then
-  project=$(basename "$cwd")
-fi
-
-# Check todo list for current/completed task
-message=""
-if [[ -n "$session_id" ]]; then
-  todo_file=$(ls -t "$HOME/.claude/todos/${session_id}"*.json 2>/dev/null | head -1)
-  if [[ -f "$todo_file" ]]; then
-    # Get most recently completed task, or in-progress task
-    completed=$(jq -r '[.[] | select(.status=="completed")] | last | .content // empty' "$todo_file" 2>/dev/null)
-    if [[ -n "$completed" ]]; then
-      message="Completed: $completed"
-    else
-      in_progress=$(jq -r '.[] | select(.status=="in_progress") | .content' "$todo_file" 2>/dev/null | head -1)
-      if [[ -n "$in_progress" ]]; then
-        message="Paused: $in_progress"
-      fi
-    fi
-  fi
-fi
-
-# Fallback: generic message
-if [[ -z "$message" ]]; then
-  message="Ready for input"
-fi
-
-# Send notification based on OS
-case "$(uname -s)" in
-  Darwin)
-    osascript -e "display alert \"GSD: $project\" message \"$message\" as informational" &>/dev/null &
-    ;;
-  Linux)
-    if command -v notify-send &>/dev/null; then
-      notify-send "GSD: $project" "$message" --urgency=normal
-    elif command -v zenity &>/dev/null; then
-      zenity --info --title="GSD: $project" --text="$message" &
-    fi
-    ;;
-  MINGW*|CYGWIN*|MSYS*)
-    # Windows via PowerShell
-    if command -v powershell.exe &>/dev/null; then
-      powershell.exe -Command "Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.MessageBox]::Show('$message', 'GSD: $project', 'OK', 'Information')" &>/dev/null &
-    fi
-    ;;
-esac
-
-exit 0

package/hooks/statusline.sh

@@ -1,58 +0,0 @@
-#!/bin/bash
-# Claude Code Statusline - GSD Edition
-# Shows: model | current task | directory | context usage
-
-input=$(cat)
-model=$(echo "$input" | jq -r '.model.display_name')
-dir=$(echo "$input" | jq -r '.workspace.current_dir')
-session=$(echo "$input" | jq -r '.session_id')
-remaining=$(echo "$input" | jq -r '.context_window.remaining_percentage // empty')
-
-# Context window display (shows USED percentage)
-ctx=""
-if [ -n "$remaining" ]; then
-    rem=$(printf "%.0f" "$remaining")
-    used=$((100 - rem))
-
-    # Build progress bar (10 segments) - fills as context is consumed
-    filled=$((used / 10))
-    bar=""
-    for ((i=0; i<filled; i++)); do bar+="█"; done
-    for ((i=filled; i<10; i++)); do bar+="░"; done
-
-    # Color based on usage with blinking skull at 80%+
-    if [ "$used" -lt 50 ]; then
-        ctx=$' \033[32m'"$bar $used%"$'\033[0m'
-    elif [ "$used" -lt 65 ]; then
-        ctx=$' \033[33m'"$bar $used%"$'\033[0m'
-    elif [ "$used" -lt 80 ]; then
-        ctx=$' \033[38;5;208m'"$bar $used%"$'\033[0m'
-    else
-        # Blinking red with skull
-        ctx=$' \033[5;31m💀 '"$bar $used%"$'\033[0m'
-    fi
-fi
-
-# Current task from todos
-task=""
-todo=$(ls -t "$HOME/.claude/todos/${session}"-agent-*.json 2>/dev/null | head -1)
-if [[ -f "$todo" ]]; then
-    task=$(jq -r '.[] | select(.status=="in_progress") | .activeForm' "$todo" 2>/dev/null | head -1)
-fi
-
-# GSD update available?
-gsd_update=""
-if [[ -f "$HOME/.claude/cache/gsd-update-check.json" ]]; then
-    update_available=$(jq -r '.update_available' "$HOME/.claude/cache/gsd-update-check.json" 2>/dev/null)
-    if [[ "$update_available" == "true" ]]; then
-        gsd_update=$'\033[33m⬆ /gsd:update\033[0m │ '
-    fi
-fi
-
-# Output
-dirname=$(basename "$dir")
-if [[ -n "$task" ]]; then
-    printf '%s\033[2m%s\033[0m │ \033[1m%s\033[0m │ \033[2m%s\033[0m%s' "$gsd_update" "$model" "$task" "$dirname" "$ctx"
-else
-    printf '%s\033[2m%s\033[0m │ \033[2m%s\033[0m%s' "$gsd_update" "$model" "$dirname" "$ctx"
-fi