gsd-antigravity-kit 1.21.1 → 1.22.0

package/.agent/skills/gsd/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gsd
-version: 1.21.1
+version: 1.22.0
 description: "Antigravity GSD (Get Stuff Done) - A spec-driven hierarchical planning and execution system. Triggers on project planning, phase management, and GSD slash commands."
 ---
 
@@ -130,4 +130,4 @@ General documentation on the GSD philosophy, usage patterns, and configuration.
 4.  **One Context**: Keep separate contexts (channels/threads) for Planning vs Execution to avoid contamination.
 
 ---
-*Generated by gsd-converter on 2026-02-27*
+*Generated by gsd-converter on 2026-03-01*

package/.agent/skills/gsd/assets/templates/context.md

@@ -54,6 +54,20 @@ Template for `.planning/phases/XX-name/{phase_num}-CONTEXT.md` - captures implem
 
 </specifics>
 
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- [Component/hook/utility]: [How it could be used in this phase]
+
+### Established Patterns
+- [Pattern]: [How it constrains/enables this phase]
+
+### Integration Points
+- [Where new code connects to existing system]
+
+</code_context>
+
 <deferred>
 ## Deferred Ideas
 

package/.agent/skills/gsd/bin/lib/core.cjs

@@ -76,6 +76,7 @@ function loadConfig(cwd) {
     research: true,
     plan_checker: true,
     verifier: true,
+    nyquist_validation: false,
     parallelization: true,
     brave_search: false,
   };
@@ -109,6 +110,7 @@ function loadConfig(cwd) {
       research: get('research', { section: 'workflow', field: 'research' }) ?? defaults.research,
       plan_checker: get('plan_checker', { section: 'workflow', field: 'plan_check' }) ?? defaults.plan_checker,
       verifier: get('verifier', { section: 'workflow', field: 'verifier' }) ?? defaults.verifier,
+      nyquist_validation: get('nyquist_validation', { section: 'workflow', field: 'nyquist_validation' }) ?? defaults.nyquist_validation,
       parallelization,
       brave_search: get('brave_search') ?? defaults.brave_search,
       model_overrides: parsed.model_overrides || null,

package/.agent/skills/gsd/bin/lib/phase.cjs

@@ -193,6 +193,11 @@ function cmdFindPhase(cwd, phase, raw) {
   }
 }
 
+function extractObjective(content) {
+  const m = content.match(/<objective>\s*\n?\s*(.+)/);
+  return m ? m[1].trim() : null;
+}
+
 function cmdPhasePlanIndex(cwd, phase, raw) {
   if (!phase) {
     error('phase required for phase-plan-index');
@@ -242,9 +247,10 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
     const content = fs.readFileSync(planPath, 'utf-8');
     const fm = extractFrontmatter(content);
 
-    // Count tasks (## Task N patterns)
-    const taskMatches = content.match(/##\s*Task\s*\d+/gi) || [];
-    const taskCount = taskMatches.length;
+    // Count tasks: XML <task> tags (canonical) or ## Task N markdown (legacy)
+    const xmlTasks = content.match(/<task[\s>]/gi) || [];
+    const mdTasks = content.match(/##\s*Task\s*\d+/gi) || [];
+    const taskCount = xmlTasks.length || mdTasks.length;
 
     // Parse wave as integer
     const wave = parseInt(fm.wave, 10) || 1;
@@ -259,10 +265,11 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
       hasCheckpoints = true;
     }
 
-    // Parse files-modified
+    // Parse files_modified (underscore is canonical; also accept hyphenated for compat)
     let filesModified = [];
-    if (fm['files-modified']) {
-      filesModified = Array.isArray(fm['files-modified']) ? fm['files-modified'] : [fm['files-modified']];
+    const fmFiles = fm['files_modified'] || fm['files-modified'];
+    if (fmFiles) {
+      filesModified = Array.isArray(fmFiles) ? fmFiles : [fmFiles];
     }
 
     const hasSummary = completedPlanIds.has(planId);
@@ -274,7 +281,7 @@ function cmdPhasePlanIndex(cwd, phase, raw) {
       id: planId,
       wave,
       autonomous,
-      objective: fm.objective || null,
+      objective: extractObjective(content) || fm.objective || null,
       files_modified: filesModified,
       task_count: taskCount,
       has_summary: hasSummary,

package/.agent/skills/gsd/bin/lib/state.cjs

@@ -151,7 +151,8 @@ function cmdStateUpdate(cwd, field, value) {
 // ─── State Progression Engine ────────────────────────────────────────────────
 
 function stateExtractField(content, fieldName) {
-  const pattern = new RegExp(`\\*\\*${fieldName}:\\*\\*\\s*(.+)`, 'i');
+  const escaped = fieldName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const pattern = new RegExp(`\\*\\*${escaped}:\\*\\*\\s*(.+)`, 'i');
   const match = content.match(pattern);
   return match ? match[1].trim() : null;
 }

package/.agent/skills/gsd/references/agents/gsd-debugger.md

@@ -1027,7 +1027,7 @@ mv .planning/debug/{slug}.md .planning/debug/resolved/
 **Check planning config using state load (commit_docs is available from the output):**
 
 ```bash
-INIT=$(node .agent/skills/gsd/bin/gsd-tools.cjs state load)
+INIT=$(node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" state load)
 # commit_docs is in the JSON output
 ```
 
@@ -1044,7 +1044,7 @@ Root cause: {root_cause}"
 
 Then commit planning docs via CLI (respects `commit_docs` config automatically):
 ```bash
-node .agent/skills/gsd/bin/gsd-tools.cjs commit "docs: resolve debug {slug}" --files .planning/debug/resolved/{slug}.md
+node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" commit "docs: resolve debug {slug}" --files .planning/debug/resolved/{slug}.md
 ```
 
 Report completion and offer next steps.

package/.agent/skills/gsd/references/agents/gsd-executor.md

@@ -21,7 +21,7 @@ Before executing, discover project context:
 
 **Project instructions:** Read `./ANTIGRAVITY.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:
+**Project skills:** Check `.antigravity/skills/` or `.agents/skills/` directory if either 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
@@ -37,7 +37,7 @@ This ensures project-specific patterns, conventions, and best practices are appl
 Load execution context:
 
 ```bash
-INIT=$(node .agent/skills/gsd/bin/gsd-tools.cjs init execute-phase "${PHASE}")
+INIT=$(node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" init execute-phase "${PHASE}")
 ```
 
 Extract from init JSON: `executor_model`, `commit_docs`, `phase_dir`, `plans`, `incomplete_plans`.
@@ -171,6 +171,16 @@ Track auto-fix attempts per task. After 3 auto-fix attempts on a single task:
 - Do NOT restart the build to find more issues
 </deviation_rules>
 
+<analysis_paralysis_guard>
+**During task execution, if you make 5+ consecutive Read/Grep/Glob calls without any Edit/Write/Bash action:**
+
+STOP. State in one sentence why you haven't written anything yet. Then either:
+1. Write code (you have enough context), or
+2. Report "blocked" with the specific missing information.
+
+Do NOT continue reading. Analysis without action is a stuck signal.
+</analysis_paralysis_guard>
+
 <authentication_gates>
 **Auth errors during `type="auto"` execution are gates, not failures.**
 
@@ -190,7 +200,7 @@ Track auto-fix attempts per task. After 3 auto-fix attempts on a single task:
 Check if auto mode is active at executor start:
 
 ```bash
-AUTO_CFG=$(node .agent/skills/gsd/bin/gsd-tools.cjs config-get workflow.auto_advance 2>/dev/null || echo "false")
+AUTO_CFG=$(node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" config-get workflow.auto_advance 2>/dev/null || echo "false")
 ```
 
 Store the result for checkpoint handling below.
@@ -379,34 +389,34 @@ After SUMMARY.md, update STATE.md using gsd-tools:
 
 ```bash
 # Advance plan counter (handles edge cases automatically)
-node .agent/skills/gsd/bin/gsd-tools.cjs state advance-plan
+node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" state advance-plan
 
 # Recalculate progress bar from disk state
-node .agent/skills/gsd/bin/gsd-tools.cjs state update-progress
+node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" state update-progress
 
 # Record execution metrics
-node .agent/skills/gsd/bin/gsd-tools.cjs state record-metric \
+node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" state record-metric \
   --phase "${PHASE}" --plan "${PLAN}" --duration "${DURATION}" \
   --tasks "${TASK_COUNT}" --files "${FILE_COUNT}"
 
 # Add decisions (extract from SUMMARY.md key-decisions)
 for decision in "${DECISIONS[@]}"; do
-  node .agent/skills/gsd/bin/gsd-tools.cjs state add-decision \
+  node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" state add-decision \
     --phase "${PHASE}" --summary "${decision}"
 done
 
 # Update session info
-node .agent/skills/gsd/bin/gsd-tools.cjs state record-session \
+node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" state record-session \
   --stopped-at "Completed ${PHASE}-${PLAN}-PLAN.md"
 ```
 
 ```bash
 # Update ROADMAP.md progress for this phase (plan counts, status)
-node .agent/skills/gsd/bin/gsd-tools.cjs roadmap update-plan-progress "${PHASE_NUMBER}"
+node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" roadmap update-plan-progress "${PHASE_NUMBER}"
 
 # Mark completed requirements from PLAN.md frontmatter
 # Extract the `requirements` array from the plan's frontmatter, then mark each complete
-node .agent/skills/gsd/bin/gsd-tools.cjs requirements mark-complete ${REQ_IDS}
+node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" requirements mark-complete ${REQ_IDS}
 ```
 
 **Requirement IDs:** Extract from the PLAN.md frontmatter `requirements:` field (e.g., `requirements: [AUTH-01, AUTH-02]`). Pass all IDs to `requirements mark-complete`. If the plan has no requirements field, skip this step.
@@ -424,13 +434,13 @@ node .agent/skills/gsd/bin/gsd-tools.cjs requirements mark-complete ${REQ_IDS}
 
 **For blockers found during execution:**
 ```bash
-node .agent/skills/gsd/bin/gsd-tools.cjs state add-blocker "Blocker description"
+node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" state add-blocker "Blocker description"
 ```
 </state_updates>
 
 <final_commit>
 ```bash
-node .agent/skills/gsd/bin/gsd-tools.cjs commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md .planning/REQUIREMENTS.md
+node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md .planning/REQUIREMENTS.md
 ```
 
 Separate from per-task commits — captures execution results only.

package/.agent/skills/gsd/references/agents/gsd-phase-researcher.md

@@ -26,7 +26,7 @@ Before researching, discover project context:
 
 **Project instructions:** Read `./ANTIGRAVITY.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:
+**Project skills:** Check `.antigravity/skills/` or `.agents/skills/` directory if either 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 research
@@ -120,7 +120,7 @@ When researching "best library for X": find what the ecosystem actually uses, do
 Check `brave_search` from init context. If `true`, use Brave Search for higher quality results:
 
 ```bash
-node .agent/skills/gsd/bin/gsd-tools.cjs websearch "your query" --limit 10
+node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" websearch "your query" --limit 10
 ```
 
 **Options:**
@@ -359,7 +359,7 @@ Orchestrator provides: phase number/name, description/goal, requirements, constr
 
 Load phase context using init command:
 ```bash
-INIT=$(node .agent/skills/gsd/bin/gsd-tools.cjs init phase-op "${PHASE}")
+INIT=$(node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" init phase-op "${PHASE}")
 ```
 
 Extract from init JSON: `phase_dir`, `padded_phase`, `phase_number`, `commit_docs`.
@@ -461,7 +461,7 @@ Write to: `$PHASE_DIR/$PADDED_PHASE-RESEARCH.md`
 ## Step 7: Commit Research (optional)
 
 ```bash
-node .agent/skills/gsd/bin/gsd-tools.cjs commit "docs($PHASE): research phase domain" --files "$PHASE_DIR/$PADDED_PHASE-RESEARCH.md"
+node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" commit "docs($PHASE): research phase domain" --files "$PHASE_DIR/$PADDED_PHASE-RESEARCH.md"
 ```
 
 ## Step 8: Return Structured Result

package/.agent/skills/gsd/references/agents/gsd-plan-checker.md

@@ -31,7 +31,7 @@ Before verifying, discover project context:
 
 **Project instructions:** Read `./ANTIGRAVITY.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:
+**Project skills:** Check `.antigravity/skills/` or `.agents/skills/` directory if either 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 verification
@@ -365,7 +365,7 @@ If FAIL: return to planner with specific fixes. Same revision loop as other dime
 
 Load phase operation context:
 ```bash
-INIT=$(node .agent/skills/gsd/bin/gsd-tools.cjs init phase-op "${PHASE_ARG}")
+INIT=$(node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" init phase-op "${PHASE_ARG}")
 ```
 
 Extract from init JSON: `phase_dir`, `phase_number`, `has_plans`, `plan_count`.
@@ -376,7 +376,7 @@ Orchestrator provides CONTEXT.md content in the verification prompt. If provided
 ls "$phase_dir"/*-PLAN.md 2>/dev/null
 # Read research for Nyquist validation data
 cat "$phase_dir"/*-RESEARCH.md 2>/dev/null
-node .agent/skills/gsd/bin/gsd-tools.cjs roadmap get-phase "$phase_number"
+node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" roadmap get-phase "$phase_number"
 ls "$phase_dir"/*-BRIEF.md 2>/dev/null
 ```
 
@@ -389,7 +389,7 @@ Use gsd-tools to validate plan structure:
 ```bash
 for plan in "$PHASE_DIR"/*-PLAN.md; do
   echo "=== $plan ==="
-  PLAN_STRUCTURE=$(node .agent/skills/gsd/bin/gsd-tools.cjs verify plan-structure "$plan")
+  PLAN_STRUCTURE=$(node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" verify plan-structure "$plan")
   echo "$PLAN_STRUCTURE"
 done
 ```
@@ -407,7 +407,7 @@ Map errors/warnings to verification dimensions:
 Extract must_haves from each plan using gsd-tools:
 
 ```bash
-MUST_HAVES=$(node .agent/skills/gsd/bin/gsd-tools.cjs frontmatter get "$PLAN_PATH" --field must_haves)
+MUST_HAVES=$(node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" frontmatter get "$PLAN_PATH" --field must_haves)
 ```
 
 Returns JSON: `{ truths: [...], artifacts: [...], key_links: [...] }`
@@ -445,12 +445,14 @@ Session persists     | 01    | 3     | COVERED
 
 For each requirement: find covering task(s), verify action is specific, flag gaps.
 
+**Exhaustive cross-check:** Also read PROJECT.md requirements (not just phase goal). Verify no PROJECT.md requirement relevant to this phase is silently dropped. Any unmapped requirement is an automatic blocker — list it explicitly in issues.
+
 ## Step 5: Validate Task Structure
 
 Use gsd-tools plan-structure verification (already run in Step 2):
 
 ```bash
-PLAN_STRUCTURE=$(node .agent/skills/gsd/bin/gsd-tools.cjs verify plan-structure "$PLAN_PATH")
+PLAN_STRUCTURE=$(node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" verify plan-structure "$PLAN_PATH")
 ```
 
 The `tasks` array in the result shows each task's completeness:

package/.agent/skills/gsd/references/agents/gsd-planner.md

@@ -33,7 +33,7 @@ Before planning, discover project context:
 
 **Project instructions:** Read `./ANTIGRAVITY.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:
+**Project skills:** Check `.antigravity/skills/` or `.agents/skills/` directory if either 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 planning
@@ -234,6 +234,26 @@ This prevents the "scavenger hunt" anti-pattern where executors explore the code
 
 **Why TDD gets own plan:** TDD requires RED→GREEN→REFACTOR cycles consuming 40-50% context. Embedding in multi-task plans degrades quality.
 
+**Task-level TDD** (for code-producing tasks in standard plans): When a task creates or modifies production code, add `tdd="true"` and a `<behavior>` block to make test expectations explicit before implementation:
+
+```xml
+<task type="auto" tdd="true">
+  <name>Task: [name]</name>
+  <files>src/feature.ts, src/feature.test.ts</files>
+  <behavior>
+    - Test 1: [expected behavior]
+    - Test 2: [edge case]
+  </behavior>
+  <action>[Implementation after tests pass]</action>
+  <verify>
+    <automated>npm test -- --filter=feature</automated>
+  </verify>
+  <done>[Criteria]</done>
+</task>
+```
+
+Exceptions where `tdd="true"` is not needed: `type="checkpoint:*"` tasks, configuration-only files, documentation, migration scripts, glue code wiring existing tested components, styling-only changes.
+
 ## User Setup Detection
 
 For tasks involving external services, identify human-required configuration:
@@ -900,7 +920,7 @@ Group by plan, dimension, severity.
 ### Step 6: Commit
 
 ```bash
-node .agent/skills/gsd/bin/gsd-tools.cjs commit "fix($PHASE): revise plans based on checker feedback" --files .planning/phases/$PHASE-*/$PHASE-*-PLAN.md
+node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" commit "fix($PHASE): revise plans based on checker feedback" --files .planning/phases/$PHASE-*/$PHASE-*-PLAN.md
 ```
 
 ### Step 7: Return Revision Summary
@@ -939,7 +959,7 @@ node .agent/skills/gsd/bin/gsd-tools.cjs commit "fix($PHASE): revise plans based
 Load planning context:
 
 ```bash
-INIT=$(node .agent/skills/gsd/bin/gsd-tools.cjs init plan-phase "${PHASE}")
+INIT=$(node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" init plan-phase "${PHASE}")
 ```
 
 Extract from init JSON: `planner_model`, `researcher_model`, `checker_model`, `commit_docs`, `research_enabled`, `phase_dir`, `phase_number`, `has_research`, `has_context`.
@@ -995,7 +1015,7 @@ Apply discovery level protocol (see discovery_levels section).
 
 **Step 1 — Generate digest index:**
 ```bash
-node .agent/skills/gsd/bin/gsd-tools.cjs history-digest
+node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" history-digest
 ```
 
 **Step 2 — Select relevant phases (typically 2-4):**
@@ -1123,7 +1143,7 @@ Include all frontmatter fields.
 Validate each created PLAN.md using gsd-tools:
 
 ```bash
-VALID=$(node .agent/skills/gsd/bin/gsd-tools.cjs frontmatter validate "$PLAN_PATH" --schema plan)
+VALID=$(node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" frontmatter validate "$PLAN_PATH" --schema plan)
 ```
 
 Returns JSON: `{ valid, missing, present, schema }`
@@ -1136,7 +1156,7 @@ Required plan frontmatter fields:
 Also validate plan structure:
 
 ```bash
-STRUCTURE=$(node .agent/skills/gsd/bin/gsd-tools.cjs verify plan-structure "$PLAN_PATH")
+STRUCTURE=$(node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" verify plan-structure "$PLAN_PATH")
 ```
 
 Returns JSON: `{ valid, errors, warnings, task_count, tasks }`
@@ -1173,7 +1193,7 @@ Plans:
 
 <step name="git_commit">
 ```bash
-node .agent/skills/gsd/bin/gsd-tools.cjs commit "docs($PHASE): create phase plan" --files .planning/phases/$PHASE-*/$PHASE-*-PLAN.md .planning/ROADMAP.md
+node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" commit "docs($PHASE): create phase plan" --files .planning/phases/$PHASE-*/$PHASE-*-PLAN.md .planning/ROADMAP.md
 ```
 </step>
 

package/.agent/skills/gsd/references/agents/gsd-project-researcher.md

@@ -99,7 +99,7 @@ Always include current year. Use multiple query variations. Mark WebSearch-only
 Check `brave_search` from orchestrator context. If `true`, use Brave Search for higher quality results:
 
 ```bash
-node .agent/skills/gsd/bin/gsd-tools.cjs websearch "your query" --limit 10
+node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" websearch "your query" --limit 10
 ```
 
 **Options:**

package/.agent/skills/gsd/references/agents/gsd-research-synthesizer.md

@@ -131,7 +131,7 @@ Write to `.planning/research/SUMMARY.md`
 The 4 parallel researcher agents write files but do NOT commit. You commit everything together.
 
 ```bash
-node .agent/skills/gsd/bin/gsd-tools.cjs commit "docs: complete project research" --files .planning/research/
+node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" commit "docs: complete project research" --files .planning/research/
 ```
 
 ## Step 8: Return Summary

package/.agent/skills/gsd/references/agents/gsd-verifier.md

@@ -21,7 +21,7 @@ Before verifying, discover project context:
 
 **Project instructions:** Read `./ANTIGRAVITY.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:
+**Project skills:** Check `.antigravity/skills/` or `.agents/skills/` directory if either 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 verification
@@ -72,7 +72,7 @@ Set `is_re_verification = false`, proceed with Step 1.
 ```bash
 ls "$PHASE_DIR"/*-PLAN.md 2>/dev/null
 ls "$PHASE_DIR"/*-SUMMARY.md 2>/dev/null
-node .agent/skills/gsd/bin/gsd-tools.cjs roadmap get-phase "$PHASE_NUM"
+node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" roadmap get-phase "$PHASE_NUM"
 grep -E "^| $PHASE_NUM" .planning/REQUIREMENTS.md 2>/dev/null
 ```
 
@@ -109,7 +109,7 @@ must_haves:
 If no must_haves in frontmatter, check for Success Criteria:
 
 ```bash
-PHASE_DATA=$(node .agent/skills/gsd/bin/gsd-tools.cjs roadmap get-phase "$PHASE_NUM" --raw)
+PHASE_DATA=$(node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" roadmap get-phase "$PHASE_NUM" --raw)
 ```
 
 Parse the `success_criteria` array from the JSON output. If non-empty:
@@ -152,7 +152,7 @@ For each truth:
 Use gsd-tools for artifact verification against must_haves in PLAN frontmatter:
 
 ```bash
-ARTIFACT_RESULT=$(node .agent/skills/gsd/bin/gsd-tools.cjs verify artifacts "$PLAN_PATH")
+ARTIFACT_RESULT=$(node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" verify artifacts "$PLAN_PATH")
 ```
 
 Parse JSON result: `{ all_passed, passed, total, artifacts: [{path, exists, issues, passed}] }`
@@ -201,7 +201,7 @@ Key links are critical connections. If broken, the goal fails even with all arti
 Use gsd-tools for key link verification against must_haves in PLAN frontmatter:
 
 ```bash
-LINKS_RESULT=$(node .agent/skills/gsd/bin/gsd-tools.cjs verify key-links "$PLAN_PATH")
+LINKS_RESULT=$(node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" verify key-links "$PLAN_PATH")
 ```
 
 Parse JSON result: `{ all_verified, verified, total, links: [{from, to, via, verified, detail}] }`
@@ -283,12 +283,12 @@ Identify files modified in this phase from SUMMARY.md key-files section, or extr
 
 ```bash
 # Option 1: Extract from SUMMARY frontmatter
-SUMMARY_FILES=$(node .agent/skills/gsd/bin/gsd-tools.cjs summary-extract "$PHASE_DIR"/*-SUMMARY.md --fields key-files)
+SUMMARY_FILES=$(node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" summary-extract "$PHASE_DIR"/*-SUMMARY.md --fields key-files)
 
 # Option 2: Verify commits exist (if commit hashes documented)
 COMMIT_HASHES=$(grep -oE "[a-f0-9]{7,40}" "$PHASE_DIR"/*-SUMMARY.md | head -10)
 if [ -n "$COMMIT_HASHES" ]; then
-  COMMITS_VALID=$(node .agent/skills/gsd/bin/gsd-tools.cjs verify commits $COMMIT_HASHES)
+  COMMITS_VALID=$(node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" verify commits $COMMIT_HASHES)
 fi
 
 # Fallback: grep for files

package/.agent/skills/gsd/references/commands/debug.md

@@ -31,12 +31,12 @@ ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5
 ## 0. Initialize Context
 
 ```bash
-INIT=$(node .agent/skills/gsd/bin/gsd-tools.cjs state load)
+INIT=$(node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" state load)
 ```
 
 Extract `commit_docs` from init JSON. Resolve debugger model:
 ```bash
-DEBUGGER_MODEL=$(node .agent/skills/gsd/bin/gsd-tools.cjs resolve-model gsd-debugger --raw)
+debugger_model=$(node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" resolve-model gsd-debugger --raw)
 ```
 
 ## 1. Check Active Sessions

package/.agent/skills/gsd/references/commands/discuss-phase.md

@@ -10,6 +10,8 @@ allowed-tools:
   - Grep
   - AskUserQuestion
   - Task
+  - mcp__context7__resolve-library-id
+  - mcp__context7__query-docs
 ---
 
 <objective>
@@ -38,11 +40,12 @@ Context files are resolved in-workflow using `init phase-op` and roadmap/state t
 <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 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)
+3. **Scout codebase** — Find reusable assets, patterns, and integration points
+4. **Analyze phase** — Identify domain and generate code-informed gray areas
+5. **Present gray areas** — Multi-select: which to discuss? (NO skip option)
+6. **Deep-dive each area** — 4 questions per area, code-informed options, Context7 for library choices
+7. **Write CONTEXT.md** — Sections match areas discussed + code_context section
+8. Offer next steps (research or plan)
 
 **CRITICAL: Scope guardrail**
 - Phase boundary from ROADMAP.md is FIXED

package/.agent/skills/gsd/references/commands/research-phase.md

@@ -34,20 +34,20 @@ Normalize phase input in step 1 before any directory lookups.
 ## 0. Initialize Context
 
 ```bash
-INIT=$(node .agent/skills/gsd/bin/gsd-tools.cjs init phase-op "$ARGUMENTS")
+INIT=$(node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" init phase-op "$ARGUMENTS")
 ```
 
 Extract from init JSON: `phase_dir`, `phase_number`, `phase_name`, `phase_found`, `commit_docs`, `has_research`, `state_path`, `requirements_path`, `context_path`, `research_path`.
 
 Resolve researcher model:
 ```bash
-RESEARCHER_MODEL=$(node .agent/skills/gsd/bin/gsd-tools.cjs resolve-model gsd-phase-researcher --raw)
+RESEARCHER_MODEL=$(node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" resolve-model gsd-phase-researcher --raw)
 ```
 
 ## 1. Validate Phase
 
 ```bash
-PHASE_INFO=$(node .agent/skills/gsd/bin/gsd-tools.cjs roadmap get-phase "${phase_number}")
+PHASE_INFO=$(node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" roadmap get-phase "${phase_number}")
 ```
 
 **If `found` is false:** Error and exit. **If `found` is true:** Extract `phase_number`, `phase_name`, `goal` from JSON.

package/.agent/skills/gsd/references/docs/decimal-phase-calculation.md

@@ -6,7 +6,7 @@ Calculate the next decimal phase number for urgent insertions.
 
 ```bash
 # Get next decimal phase after phase 6
-node .agent/skills/gsd/bin/gsd-tools.cjs phase next-decimal 6
+node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" phase next-decimal 6
 ```
 
 Output:
@@ -32,14 +32,14 @@ With existing decimals:
 ## Extract Values
 
 ```bash
-DECIMAL_INFO=$(node .agent/skills/gsd/bin/gsd-tools.cjs phase next-decimal "${AFTER_PHASE}")
+DECIMAL_INFO=$(node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" phase next-decimal "${AFTER_PHASE}")
 DECIMAL_PHASE=$(echo "$DECIMAL_INFO" | jq -r '.next')
 BASE_PHASE=$(echo "$DECIMAL_INFO" | jq -r '.base_phase')
 ```
 
 Or with --raw flag:
 ```bash
-DECIMAL_PHASE=$(node .agent/skills/gsd/bin/gsd-tools.cjs phase next-decimal "${AFTER_PHASE}" --raw)
+DECIMAL_PHASE=$(node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" phase next-decimal "${AFTER_PHASE}" --raw)
 # Returns just: 06.1
 ```
 
@@ -57,7 +57,7 @@ DECIMAL_PHASE=$(node .agent/skills/gsd/bin/gsd-tools.cjs phase next-decimal "${A
 Decimal phase directories use the full decimal number:
 
 ```bash
-SLUG=$(node .agent/skills/gsd/bin/gsd-tools.cjs generate-slug "$DESCRIPTION" --raw)
+SLUG=$(node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" generate-slug "$DESCRIPTION" --raw)
 PHASE_DIR=".planning/phases/${DECIMAL_PHASE}-${SLUG}"
 mkdir -p "$PHASE_DIR"
 ```

package/.agent/skills/gsd/references/docs/git-integration.md

@@ -51,7 +51,7 @@ Phases:
 What to commit:
 
 ```bash
-node .agent/skills/gsd/bin/gsd-tools.cjs commit "docs: initialize [project-name] ([N] phases)" --files .planning/
+node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" commit "docs: initialize [project-name] ([N] phases)" --files .planning/
 ```
 
 </format>
@@ -129,7 +129,7 @@ SUMMARY: .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md
 What to commit:
 
 ```bash
-node .agent/skills/gsd/bin/gsd-tools.cjs commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md
+node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md
 ```
 
 **Note:** Code files NOT included - already committed per-task.
@@ -149,7 +149,7 @@ Current: [task name]
 What to commit:
 
 ```bash
-node .agent/skills/gsd/bin/gsd-tools.cjs commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/
+node "$HOME.agent/skills/gsd/bin/gsd-tools.cjs" commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/
 ```
 
 </format>