get-shit-done-ios 0.7.0 → 0.9.0

package/agents/gsd-codebase-mapper.md

@@ -15,6 +15,9 @@ You are spawned by `/gsd:map-codebase` with one of four focus areas:
 - **concerns**: Identify technical debt and issues → write CONCERNS.md
 
 Your job: Explore thoroughly, then write document(s) directly. Return confirmation only.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
 </role>
 
 <why_this_matters>

package/agents/gsd-debugger.md

@@ -15,6 +15,9 @@ You are spawned by:
 
 Your job: Find the root cause through hypothesis testing, maintain debug file state, optionally fix and verify (depending on mode).
 
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
+
 **Core responsibilities:**
 - Investigate autonomously (user reports symptoms, you find cause)
 - Maintain persistent debug file state (survives context resets)

package/agents/gsd-executor.md

@@ -18,8 +18,26 @@ Spawned by `/gsd:execute-phase` orchestrator.
 Your job: Execute the plan completely, commit each task, create SUMMARY.md, update STATE.md.
 
 **iOS context:** All implementation work targets iOS 17+ using Swift, SwiftUI, and native Apple frameworks. Prefer Swift concurrency (async/await, actors) over Combine where appropriate. Follow Apple Human Interface Guidelines and App Store Review Guidelines throughout execution.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
 </role>
 
+<project_context>
+Before executing, discover project context:
+
+**Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
+
+**Project skills:** Check `.agents/skills/` directory if it exists:
+1. List available skills (subdirectories)
+2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
+3. Load specific `rules/*.md` files as needed during implementation
+4. Do NOT load full `AGENTS.md` files (100KB+ context cost)
+5. Follow skill rules relevant to your current task
+
+This ensures project-specific patterns, conventions, and best practices are applied during execution.
+</project_context>
+
 <execution_flow>
 
 <step name="load_project_state" priority="first">

package/agents/gsd-integration-checker.md

@@ -10,6 +10,9 @@ You are an integration checker. You verify that phases work together as a system
 
 Your job: Check cross-phase wiring (exports used, APIs called, data flows) and verify E2E user flows complete without breaks.
 
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
+
 **Critical mindset:** Individual phases can pass while the system fails. A component can exist without being imported. An API can exist without being called. Focus on connections, not existence.
 </role>
 

package/agents/gsd-phase-researcher.md

@@ -10,6 +10,9 @@ You are a GSD phase researcher. You answer "What do I need to know to PLAN this
 
 Spawned by `/gsd:plan-phase` (integrated) or `/gsd:research-phase` (standalone).
 
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
+
 **Core responsibilities:**
 - Investigate the phase's technical domain
 - Identify standard stack, patterns, and pitfalls
@@ -18,6 +21,21 @@ Spawned by `/gsd:plan-phase` (integrated) or `/gsd:research-phase` (standalone).
 - Return structured result to orchestrator
 </role>
 
+<project_context>
+Before researching, discover project context:
+
+**Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
+
+**Project skills:** Check `.agents/skills/` directory if it exists:
+1. List available skills (subdirectories)
+2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
+3. Load specific `rules/*.md` files as needed during implementation
+4. Do NOT load full `AGENTS.md` files (100KB+ context cost)
+5. Follow skill rules relevant to your current task
+
+This ensures project-specific patterns, conventions, and best practices are applied during research.
+</project_context>
+
 <upstream_input>
 **CONTEXT.md** (if exists) — User decisions from `/gsd:discuss-phase`
 
@@ -330,6 +348,37 @@ Verified patterns from official sources:
    - What's unclear: [the gap]
    - Recommendation: [how to handle]
 
+## Validation Architecture
+
+> Skip this section entirely if workflow.nyquist_validation is false in .planning/config.json
+
+### Test Framework
+| Property | Value |
+|----------|-------|
+| Framework | {framework name + version} |
+| Config file | {path or "none — see Wave 0"} |
+| Quick run command | `{command}` |
+| Full suite command | `{command}` |
+| Estimated runtime | ~{N} seconds |
+
+### Phase Requirements → Test Map
+| Req ID | Behavior | Test Type | Automated Command | File Exists? |
+|--------|----------|-----------|-------------------|-------------|
+| REQ-XX | {behavior description} | unit | `swift test --filter {TestModule}.{testName}` | ✅ yes / ❌ Wave 0 gap |
+
+### Nyquist Sampling Rate
+- **Minimum sample interval:** After every committed task → run: `{quick run command}`
+- **Full suite trigger:** Before merging final task of any plan wave
+- **Phase-complete gate:** Full suite green before `/gsd:verify-work` runs
+- **Estimated feedback latency per task:** ~{N} seconds
+
+### Wave 0 Gaps (must be created before implementation)
+- [ ] `{Tests/TestFile.swift}` — covers REQ-{XX}
+- [ ] `{Tests/Helpers/SharedFixtures.swift}` — shared fixtures for phase {N}
+- [ ] Framework config: Xcode test plan or Package.swift test targets — if no framework detected
+
+*(If no gaps: "None — existing test infrastructure covers all phase requirements")*
+
 ## Sources
 
 ### Primary (HIGH confidence)
@@ -370,6 +419,8 @@ INIT=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs init phase-op "${PHASE}")
 
 Extract from init JSON: `phase_dir`, `padded_phase`, `phase_number`, `commit_docs`.
 
+Also check Nyquist validation config — read `.planning/config.json` and check if `workflow.nyquist_validation` is `true`. If `true`, include the Validation Architecture section in RESEARCH.md output (scan for test frameworks, map requirements to test types, identify Wave 0 gaps). If `false`, skip the Validation Architecture section entirely and omit it from output.
+
 Then read CONTEXT.md if exists:
 ```bash
 cat "$phase_dir"/*-CONTEXT.md 2>/dev/null
@@ -415,7 +466,33 @@ For each domain: Context7 first → Official docs → WebSearch → Cross-verify
 
 **Step 3b: Check for emerging APIs.** Before finalizing the Standard Stack section, actively search for new Apple frameworks and APIs released in the past 12 months relevant to this phase's domain. SwiftUI, SwiftData, and system frameworks evolve every WWDC — do not assume training data reflects the current state of any Apple API. Use Context7 and Apple Developer Documentation to verify current API availability. Flag iOS 18+ / iOS 26+ APIs that could simplify the phase implementation as conditional recommendations.
 
-## Step 4: Quality Check
+## Step 4: Validation Architecture Research (if nyquist_validation enabled)
+
+**Skip this step if** workflow.nyquist_validation is false in config.
+
+This step answers: "How will Claude's executor know, within seconds of committing each task, whether the output is correct?"
+
+### Detect Test Infrastructure
+Scan the codebase for test configuration:
+- Look for test config files: Xcode test plan (.xctestplan), Package.swift test targets
+- Look for test directories: Tests/, *Tests/
+- Look for test files: *Tests.swift, *Test.swift
+- Check for Swift Testing (`import Testing`) vs XCTest (`import XCTest`) usage
+
+### Map Requirements to Tests
+For each requirement in <phase_requirements>:
+- Identify the behavior to verify
+- Determine test type: unit / integration / contract / smoke / e2e / manual-only
+- Specify the automated command to run that test in < 30 seconds
+- Flag if only verifiable manually (justify why)
+
+### Identify Wave 0 Gaps
+List test files, fixtures, or utilities that must be created BEFORE implementation:
+- Missing test files for phase requirements
+- Missing test framework configuration
+- Missing shared fixtures or test utilities
+
+## Step 5: Quality Check
 
 - [ ] All domains investigated
 - [ ] Negative claims verified
@@ -423,7 +500,7 @@ For each domain: Context7 first → Official docs → WebSearch → Cross-verify
 - [ ] Confidence levels assigned honestly
 - [ ] "What might I have missed?" review
 
-## Step 5: Write RESEARCH.md
+## Step 6: Write RESEARCH.md
 
 **ALWAYS use Write tool to persist to disk** — mandatory regardless of `commit_docs` setting.
 
@@ -462,13 +539,13 @@ Write to: `$PHASE_DIR/$PADDED_PHASE-RESEARCH.md`
 
 ⚠️ `commit_docs` controls git only, NOT file writing. Always write first.
 
-## Step 6: Commit Research (optional)
+## Step 7: Commit Research (optional)
 
 ```bash
 node ~/.claude/get-shit-done/bin/gsd-tools.cjs commit "docs($PHASE): research phase domain" --files "$PHASE_DIR/$PADDED_PHASE-RESEARCH.md"
 ```
 
-## Step 7: Return Structured Result
+## Step 8: Return Structured Result
 
 </execution_flow>
 

package/agents/gsd-plan-checker.md

@@ -12,6 +12,9 @@ Spawned by `/gsd:plan-phase` orchestrator (after planner creates PLAN.md) or re-
 
 Goal-backward verification of PLANS before execution. Start from what the phase SHOULD deliver, verify plans address it.
 
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
+
 **Critical mindset:** Plans describe intent. You verify they deliver. A plan can have all tasks filled in but still miss the goal if:
 - Key requirements have no tasks
 - Tasks exist but don't actually achieve the requirement
@@ -23,6 +26,21 @@ Goal-backward verification of PLANS before execution. Start from what the phase
 You are NOT the executor or verifier — you verify plans WILL work before execution burns context.
 </role>
 
+<project_context>
+Before verifying, discover project context:
+
+**Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
+
+**Project skills:** Check `.agents/skills/` directory if it exists:
+1. List available skills (subdirectories)
+2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
+3. Load specific `rules/*.md` files as needed during implementation
+4. Do NOT load full `AGENTS.md` files (100KB+ context cost)
+5. Follow skill rules relevant to your current task
+
+This ensures project-specific patterns, conventions, and best practices are applied during verification.
+</project_context>
+
 <upstream_input>
 **CONTEXT.md** (if exists) — User decisions from `/gsd:discuss-phase`
 
@@ -294,6 +312,105 @@ issue:
   fix_hint: "Remove search task - belongs in future phase per user decision"
 ```
 
+## Dimension 8: Nyquist Compliance
+
+<dimension_8_skip_condition>
+Skip this entire dimension if:
+- workflow.nyquist_validation is false in .planning/config.json
+- The phase being checked has no RESEARCH.md (researcher was skipped)
+- The RESEARCH.md has no "Validation Architecture" section (researcher ran without Nyquist)
+
+If skipped, output: "Dimension 8: SKIPPED (nyquist_validation disabled or not applicable)"
+</dimension_8_skip_condition>
+
+<dimension_8_context>
+This dimension enforces the Nyquist-Shannon Sampling Theorem for AI code generation:
+if Claude's executor produces output at high frequency (one task per commit), feedback
+must run at equally high frequency. A plan that produces code without pre-defined
+automated verification is under-sampled — errors will be statistically missed.
+
+The gsd-phase-researcher already determined WHAT to test. This dimension verifies
+that the planner correctly incorporated that information into the actual task plans.
+</dimension_8_context>
+
+### Check 8a — Automated Verify Presence
+
+For EACH `<task>` element in EACH plan file for this phase:
+
+1. Does `<verify>` contain an `<automated>` command (or structured equivalent)?
+2. If `<automated>` is absent or empty:
+   - Is there a Wave 0 dependency that creates the test before this task runs?
+   - If no Wave 0 dependency exists → **BLOCKING FAIL**
+3. If `<automated>` says "MISSING":
+   - A Wave 0 task must reference the same test file path → verify this link is present
+   - If the link is broken → **BLOCKING FAIL**
+
+**PASS criteria:** Every task either has an `<automated>` verify command, OR explicitly
+references a Wave 0 task that creates the test scaffold it depends on.
+
+### Check 8b — Feedback Latency Assessment
+
+Review each `<automated>` command in the plans:
+
+1. Does the command appear to be a full E2E suite (XCUITest full suite, UI test all)?
+   - If yes: **WARNING** (non-blocking) — suggest adding a faster unit/smoke test as primary verify
+2. Does the command include watch mode flags?
+   - If yes: **BLOCKING FAIL** — watch mode is not suitable for CI/post-commit sampling
+3. Does the command include `sleep`, `wait`, or arbitrary delays > 30 seconds?
+   - If yes: **WARNING** — flag as latency risk
+
+### Check 8c — Sampling Continuity
+
+Review ALL tasks across ALL plans for this phase in wave order:
+
+1. Map each task to its wave number
+2. For each consecutive window of 3 tasks in the same wave: at least 2 must have
+   an `<automated>` verify command (not just Wave 0 scaffolding)
+3. If any 3 consecutive implementation tasks all lack automated verify: **BLOCKING FAIL**
+
+### Check 8d — Wave 0 Completeness
+
+If any plan contains `<automated>MISSING</automated>` or references Wave 0:
+
+1. Does a Wave 0 task exist for every MISSING reference?
+2. Does the Wave 0 task's `<files>` match the path referenced in the MISSING automated command?
+3. Is the Wave 0 task in a plan that executes BEFORE the dependent task?
+
+**FAIL condition:** Any MISSING automated verify without a matching Wave 0 task.
+
+### Dimension 8 Output Block
+
+Include this block in the plan-checker report:
+
+```
+## Dimension 8: Nyquist Compliance
+
+### Automated Verify Coverage
+| Task | Plan | Wave | Automated Command | Latency | Status |
+|------|------|------|-------------------|---------|--------|
+| {task name} | {plan} | {wave} | `{command}` | ~{N}s | ✅ PASS / ❌ FAIL |
+
+### Sampling Continuity Check
+Wave {N}: {X}/{Y} tasks verified → ✅ PASS / ❌ FAIL
+
+### Wave 0 Completeness
+- {test file} → Wave 0 task present ✅ / MISSING ❌
+
+### Overall Nyquist Status: ✅ PASS / ❌ FAIL
+
+### Revision Instructions (if FAIL)
+Return to planner with the following required changes:
+{list of specific fixes needed}
+```
+
+### Revision Loop Behavior
+
+If Dimension 8 FAILS:
+- Return to `gsd-planner` with the specific revision instructions above
+- The planner must address ALL failing checks before returning
+- This follows the same loop behavior as existing dimensions
+- Maximum 3 revision loops for Dimension 8 before escalating to user
+
 </verification_dimensions>
 
 <verification_process>
@@ -311,6 +428,8 @@ Orchestrator provides CONTEXT.md content in the verification prompt. If provided
 
 ```bash
 ls "$phase_dir"/*-PLAN.md 2>/dev/null
+# Read research for Nyquist validation data
+cat "$phase_dir"/*-RESEARCH.md 2>/dev/null
 node ~/.claude/get-shit-done/bin/gsd-tools.cjs roadmap get-phase "$phase_number"
 ls "$phase_dir"/*-BRIEF.md 2>/dev/null
 ```

package/agents/gsd-planner.md

@@ -15,6 +15,9 @@ Spawned by:
 
 Your job: Produce PLAN.md files that Claude executors can implement without interpretation. Plans are prompts, not documents that become prompts.
 
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
+
 **Core responsibilities:**
 - **FIRST: Parse and honor user decisions from CONTEXT.md** (locked decisions are NON-NEGOTIABLE)
 - Decompose phases into parallel-optimized plans with 2-3 tasks each
@@ -25,6 +28,21 @@ Your job: Produce PLAN.md files that Claude executors can implement without inte
 - Return structured results to orchestrator
 </role>
 
+<project_context>
+Before planning, discover project context:
+
+**Project instructions:** Read `./CLAUDE.md` if it exists in the working directory. Follow all project-specific guidelines, security requirements, and coding conventions.
+
+**Project skills:** Check `.agents/skills/` directory if it exists:
+1. List available skills (subdirectories)
+2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
+3. Load specific `rules/*.md` files as needed during implementation
+4. Do NOT load full `AGENTS.md` files (100KB+ context cost)
+5. Follow skill rules relevant to your current task
+
+This ensures project-specific patterns, conventions, and best practices are applied during planning.
+</project_context>
+
 <context_fidelity>
 ## CRITICAL: User Decision Fidelity
 
@@ -139,9 +157,21 @@ Every task has four required fields:
 - Good: "Create SignInWithAppleViewModel conforming to ObservableObject. Use ASAuthorizationAppleIDProvider for authentication flow, store credential in Keychain via KeychainService. Persist user profile to SwiftData User model. Use async/await (not Combine - simpler error propagation for one-shot operations)."
 - Bad: "Add authentication", "Make login work"
 
-**<verify>:** How to prove the task is complete.
-- Good: `swift test` passes, `xcodebuild build -scheme App -destination 'platform=iOS Simulator,name=iPhone 16'` succeeds with zero warnings
-- Bad: "It works", "Looks good"
+**<verify>:** How to prove the task is complete. Supports structured format:
+
+```xml
+<verify>
+  <automated>swift test --filter TestModule.testBehavior</automated>
+  <manual>Optional: human-readable description of what to check</manual>
+  <sampling_rate>run after this task commits, before next task begins</sampling_rate>
+</verify>
+```
+
+- Good: Specific automated command that runs in < 60 seconds
+- Bad: "It works", "Looks good", manual-only verification
+- Simple format also accepted: `swift test` passes, `xcodebuild build -scheme App -destination 'platform=iOS Simulator,name=iPhone 16'` succeeds with zero warnings
+
+**Nyquist Rule:** Every `<verify>` must include an `<automated>` command. If no test exists yet for this behavior, set `<automated>MISSING — Wave 0 must create {test_file} first</automated>` and create a Wave 0 task that generates the test scaffold.
 
 **<done>:** Acceptance criteria - measurable state of completion.
 - Good: "Sign in with Apple flow completes, user profile is persisted to SwiftData, subsequent app launch shows authenticated state"

package/agents/gsd-project-researcher.md

@@ -10,6 +10,9 @@ You are a GSD project researcher spawned by `/gsd:new-project` or `/gsd:new-mile
 
 Answer "What does this domain ecosystem look like for iOS?" Write research files in `.planning/research/` that inform roadmap creation. Always prioritize Apple-native frameworks and patterns. Consult `get-shit-done/references/ios-swift-guidelines.md` and `get-shit-done/references/ios-frameworks.md` as authoritative references.
 
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
+
 Your files feed the roadmap:
 
 | File | How Roadmap Uses It |

package/agents/gsd-research-synthesizer.md

@@ -14,6 +14,9 @@ You are spawned by:
 
 Your job: Create a unified research summary that informs roadmap creation. Extract key findings, identify patterns across research files, and produce roadmap implications.
 
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
+
 **Core responsibilities:**
 - Read all 4 research files (STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md)
 - Synthesize findings into executive summary

package/agents/gsd-roadmapper.md

@@ -14,6 +14,9 @@ You are spawned by:
 
 Your job: Transform requirements into a phase structure that delivers the iOS app. Every v1 requirement maps to exactly one phase. Every phase has observable success criteria that can be verified on a real device or simulator.
 
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
+
 **Core responsibilities:**
 - Derive phases from requirements (not impose arbitrary structure)
 - Validate 100% requirement coverage (no orphans)

package/agents/gsd-verifier.md

@@ -12,6 +12,9 @@ You are a GSD phase verifier. You verify that a phase achieved its GOAL, not jus
 
 Your job: Goal-backward verification. Start from what the phase SHOULD deliver, verify it actually exists and works in the codebase.
 
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
+
 **Critical mindset:** Do NOT trust SUMMARY.md claims. SUMMARYs document what Claude SAID it did. You verify what ACTUALLY exists in the code. These often differ.
 </role>
 

package/bin/install.js

@@ -127,15 +127,16 @@ function getGlobalDir(runtime, explicitDir = null) {
   return path.join(os.homedir(), '.claude');
 }
 
+const orange = '\x1b[38;2;255;158;100m';
 const banner = '\n' +
-  cyan + '   ██████╗ ███████╗██████╗\n' +
-  '  ██╔════╝ ██╔════╝██╔══██╗\n' +
-  '  ██║  ███╗███████╗██║  ██║\n' +
-  '  ██║   ██║╚════██║██║  ██║\n' +
-  '  ╚██████╔╝███████║██████╔╝\n' +
-  '   ╚═════╝ ╚══════╝╚═════╝' + reset + '\n' +
+  '  ' + cyan + ' ██████╗ ███████╗██████╗ ' + orange + '   ██╗ ██████╗ ███████╗' + reset + '\n' +
+  '  ' + cyan + '██╔════╝ ██╔════╝██╔══██╗' + orange + '██╗██║██╔═══██╗██╔════╝' + reset + '\n' +
+  '  ' + cyan + '██║  ███╗███████╗██║  ██║' + orange + '╚═╝██║██║   ██║███████╗' + reset + '\n' +
+  '  ' + cyan + '██║   ██║╚════██║██║  ██║' + orange + '██╗██║██║   ██║╚════██║' + reset + '\n' +
+  '  ' + cyan + '╚██████╔╝███████║██████╔╝' + orange + '╚═╝██║╚██████╔╝███████║' + reset + '\n' +
+  '  ' + cyan + ' ╚═════╝ ╚══════╝╚═════╝ ' + orange + '   ╚═╝ ╚═════╝ ╚══════╝' + reset + '\n' +
   '\n' +
-  '  GSD' + '\x1b[38;2;255;158;100m' + ':iOS' + reset + ' ' + dim + 'v' + pkg.version + reset + '\n' +
+  '  GSD' + orange + ':iOS' + reset + ' ' + dim + 'v' + pkg.version + reset + '\n' +
   '  A meta-prompting, context engineering and spec-driven\n' +
   '  development system for Claude Code by TÂCHES.\n' +
   '  iOS adaptation by the-andys.\n';
@@ -880,7 +881,7 @@ function uninstall(isGlobal, runtime = 'claude') {
   // 4. Remove GSD hooks
   const hooksDir = path.join(targetDir, 'hooks');
   if (fs.existsSync(hooksDir)) {
-    const gsdHooks = ['gsd-statusline.js', 'gsd-check-update.js', 'gsd-check-update.sh'];
+    const gsdHooks = ['gsd-statusline.js', 'gsd-check-update.js', 'gsd-check-update.sh', 'gsd-context-monitor.js'];
     let hookCount = 0;
     for (const hook of gsdHooks) {
       const hookPath = path.join(hooksDir, hook);
@@ -946,10 +947,32 @@ function uninstall(isGlobal, runtime = 'claude') {
       if (settings.hooks.SessionStart.length === 0) {
         delete settings.hooks.SessionStart;
       }
-      // Clean up empty hooks object
-      if (Object.keys(settings.hooks).length === 0) {
-        delete settings.hooks;
+    }
+
+    // Remove GSD hooks from PostToolUse
+    if (settings.hooks && settings.hooks.PostToolUse) {
+      const before = settings.hooks.PostToolUse.length;
+      settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter(entry => {
+        if (entry.hooks && Array.isArray(entry.hooks)) {
+          const hasGsdHook = entry.hooks.some(h =>
+            h.command && h.command.includes('gsd-context-monitor')
+          );
+          return !hasGsdHook;
+        }
+        return true;
+      });
+      if (settings.hooks.PostToolUse.length < before) {
+        settingsModified = true;
+        console.log(`  ${green}✓${reset} Removed context monitor hook from settings`);
       }
+      if (settings.hooks.PostToolUse.length === 0) {
+        delete settings.hooks.PostToolUse;
+      }
+    }
+
+    // Clean up empty hooks object
+    if (settings.hooks && Object.keys(settings.hooks).length === 0) {
+      delete settings.hooks;
     }
 
     if (settingsModified) {
@@ -1334,11 +1357,8 @@ function install(isGlobal, runtime = 'claude') {
     : targetDir.replace(process.cwd(), '.');
 
   // Path prefix for file references in markdown content
-  // For global installs: use full path
-  // For local installs: use relative
-  const pathPrefix = isGlobal
-    ? `${targetDir.replace(/\\/g, '/')}/`
-    : `./${dirName}/`;
+  // Always use absolute paths — Claude Code does not resolve @./ relative to project CWD
+  const pathPrefix = `${targetDir.replace(/\\/g, '/')}/`;
 
   let runtimeLabel = 'Claude Code';
   if (isOpencode) runtimeLabel = 'OpenCode';
@@ -1502,12 +1522,10 @@ function install(isGlobal, runtime = 'claude') {
   // Gemini shares same hook system as Claude Code for now
   const settingsPath = path.join(targetDir, 'settings.json');
   const settings = cleanupOrphanedHooks(readSettings(settingsPath));
-  const statuslineCommand = isGlobal
-    ? buildHookCommand(targetDir, 'gsd-statusline.js')
-    : 'node ' + dirName + '/hooks/gsd-statusline.js';
-  const updateCheckCommand = isGlobal
-    ? buildHookCommand(targetDir, 'gsd-check-update.js')
-    : 'node ' + dirName + '/hooks/gsd-check-update.js';
+  // Always use absolute paths for hook commands — relative paths fail when CWD changes
+  const statuslineCommand = buildHookCommand(targetDir, 'gsd-statusline.js');
+  const updateCheckCommand = buildHookCommand(targetDir, 'gsd-check-update.js');
+  const contextMonitorCommand = buildHookCommand(targetDir, 'gsd-context-monitor.js');
 
   // Enable experimental agents for Gemini CLI (required for custom sub-agents)
   if (isGemini) {
@@ -1544,6 +1562,27 @@ function install(isGlobal, runtime = 'claude') {
       });
       console.log(`  ${green}✓${reset} Configured update check hook`);
     }
+
+    // Configure PostToolUse hook for context window monitoring
+    if (!settings.hooks.PostToolUse) {
+      settings.hooks.PostToolUse = [];
+    }
+
+    const hasContextMonitorHook = settings.hooks.PostToolUse.some(entry =>
+      entry.hooks && entry.hooks.some(h => h.command && h.command.includes('gsd-context-monitor'))
+    );
+
+    if (!hasContextMonitorHook) {
+      settings.hooks.PostToolUse.push({
+        hooks: [
+          {
+            type: 'command',
+            command: contextMonitorCommand
+          }
+        ]
+      });
+      console.log(`  ${green}✓${reset} Configured context window monitor hook`);
+    }
   }
 
   // Write file manifest for future modification detection

package/commands/gsd/add-phase.md

@@ -19,11 +19,15 @@ Routes to the add-phase workflow which handles:
 </objective>
 
 <execution_context>
-@.planning/ROADMAP.md
-@.planning/STATE.md
 @~/.claude/get-shit-done/workflows/add-phase.md
 </execution_context>
 
+<context>
+Arguments: $ARGUMENTS (phase description)
+
+Roadmap and state are resolved in-workflow via `init phase-op` and targeted tool calls.
+</context>
+
 <process>
 **Follow the add-phase workflow** from `@~/.claude/get-shit-done/workflows/add-phase.md`.
 

package/commands/gsd/add-todo.md

@@ -23,10 +23,15 @@ Routes to the add-todo workflow which handles:
 </objective>
 
 <execution_context>
-@.planning/STATE.md
 @~/.claude/get-shit-done/workflows/add-todo.md
 </execution_context>
 
+<context>
+Arguments: $ARGUMENTS (optional todo description)
+
+State is resolved in-workflow via `init todos` and targeted reads.
+</context>
+
 <process>
 **Follow the add-todo workflow** from `@~/.claude/get-shit-done/workflows/add-todo.md`.
 

package/commands/gsd/audit-milestone.md

@@ -23,13 +23,7 @@ Verify milestone achieved its definition of done. Check requirements coverage, c
 <context>
 Version: $ARGUMENTS (optional — defaults to current milestone)
 
-**Original Intent:**
-@.planning/PROJECT.md
-@.planning/REQUIREMENTS.md
-
-**Planned Work:**
-@.planning/ROADMAP.md
-@.planning/config.json (if exists)
+Core planning files are resolved in-workflow (`init milestone-op`) and loaded only as needed.
 
 **Completed Work:**
 Glob: .planning/phases/*/*-SUMMARY.md

package/commands/gsd/check-todos.md

@@ -21,11 +21,15 @@ Routes to the check-todos workflow which handles:
 </objective>
 
 <execution_context>
-@.planning/STATE.md
-@.planning/ROADMAP.md
 @~/.claude/get-shit-done/workflows/check-todos.md
 </execution_context>
 
+<context>
+Arguments: $ARGUMENTS (optional area filter)
+
+Todo state and roadmap correlation are loaded in-workflow using `init todos` and targeted reads.
+</context>
+
 <process>
 **Follow the check-todos workflow** from `@~/.claude/get-shit-done/workflows/check-todos.md`.
 

package/commands/gsd/debug.md

@@ -129,7 +129,9 @@ Continue debugging {slug}. Evidence is in the debug file.
 </objective>
 
 <prior_state>
-Debug file: @.planning/debug/{slug}.md
+<files_to_read>
+- .planning/debug/{slug}.md (Debug session state)
+</files_to_read>
 </prior_state>
 
 <checkpoint_response>