gsd-antigravity-kit 2.0.1 → 2.1.0

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

@@ -4,7 +4,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { normalizePhaseName, findPhaseInternal, generateSlugInternal, normalizeMd, toPosixPath, output, error } = require('./core.cjs');
+const { normalizePhaseName, findPhaseInternal, generateSlugInternal, normalizeMd, toPosixPath, planningDir, output, error } = require('./core.cjs');
 const { reconstructFrontmatter } = require('./frontmatter.cjs');
 
 function cmdTemplateSelect(cwd, planPath, raw) {
@@ -131,6 +131,10 @@ function cmdTemplateFill(cwd, templateType, options, raw) {
     must_haves: { truths: [], artifacts: [], key_links: [] },
     ...fields,
     };
+    const planBase = planningDir(cwd);
+    const projectRef = toPosixPath(path.relative(cwd, path.join(planBase, 'PROJECT.md')));
+    const roadmapRef = toPosixPath(path.relative(cwd, path.join(planBase, 'ROADMAP.md')));
+    const stateRef = toPosixPath(path.relative(cwd, path.join(planBase, 'STATE.md')));
     body = [
     `# Phase ${options.phase} Plan ${planNum}: [Title]`,
     '',
@@ -140,9 +144,9 @@ function cmdTemplateFill(cwd, templateType, options, raw) {
     '- **Output:** [Concrete deliverable]',
     '',
     '## Context',
-    '@.planning/PROJECT.md',
-    '@.planning/ROADMAP.md',
-    '@.planning/STATE.md',
+    `@${projectRef}`,
+    `@${roadmapRef}`,
+    `@${stateRef}`,
     '',
     '## Tasks',
     '',

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

@@ -181,7 +181,8 @@ function buildCheckpoint(currentTest) {
 function parseUatItems(content) {
   const items = [];
   // Match test blocks: ### N. Name\nexpected: ...\nresult: ...\n
-  const testPattern = /###\s*(\d+)\.\s*([^\n]+)\nexpected:\s*([^\n]+)\nresult:\s*(\w+)(?:\n(?:reported|reason|blocked_by):\s*[^\n]*)?/g;
+  // Accept both bare (result: pending) and bracketed (result: [pending]) formats (#2273)
+  const testPattern = /###\s*(\d+)\.\s*([^\n]+)\nexpected:\s*([^\n]+)\nresult:\s*\[?(\w+)\]?(?:\n(?:reported|reason|blocked_by):\s*[^\n]*)?/g;
   let match;
   while ((match = testPattern.exec(content)) !== null) {
   const [, num, name, expected, result] = match;

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

@@ -5,7 +5,7 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const { safeReadFile, loadConfig, normalizePhaseName, escapeRegex, execGit, findPhaseInternal, getMilestoneInfo, stripShippedMilestones, extractCurrentMilestone, planningDir, planningRoot, output, error, checkAgentsInstalled, CONFIG_DEFAULTS } = require('./core.cjs');
+const { safeReadFile, loadConfig, normalizePhaseName, escapeRegex, execGit, findPhaseInternal, getMilestoneInfo, stripShippedMilestones, extractCurrentMilestone, planningDir, output, error, checkAgentsInstalled, CONFIG_DEFAULTS } = require('./core.cjs');
 const { extractFrontmatter, parseMustHavesBlock } = require('./frontmatter.cjs');
 const { writeStateMd } = require('./state.cjs');
 
@@ -534,11 +534,10 @@ function cmdValidateHealth(cwd, options, raw) {
   }
 
   const planBase = planningDir(cwd);
-  const planRoot = planningRoot(cwd);
-  const projectPath = path.join(planRoot, 'PROJECT.md');
+  const projectPath = path.join(planBase, 'PROJECT.md');
   const roadmapPath = path.join(planBase, 'ROADMAP.md');
   const statePath = path.join(planBase, 'STATE.md');
-  const configPath = path.join(planRoot, 'config.json');
+  const configPath = path.join(planBase, 'config.json');
   const phasesDir = path.join(planBase, 'phases');
 
   const errors = [];
@@ -649,55 +648,62 @@ function cmdValidateHealth(cwd, options, raw) {
     addIssue('warning', 'W008', 'config.json: workflow.nyquist_validation absent (defaults to enabled but agents may skip)', 'Run /gsd-health --repair to add key', true);
     if (!repairs.includes('addNyquistKey')) repairs.push('addNyquistKey');
     }
+    if (configParsed.workflow && configParsed.workflow.ai_integration_phase === undefined) {
+    addIssue('warning', 'W016', 'config.json: workflow.ai_integration_phase absent (defaults to enabled — run /gsd-ai-integration-phase before planning AI system phases)', 'Run /gsd-health --repair to add key', true);
+    if (!repairs.includes('addAiIntegrationPhaseKey')) repairs.push('addAiIntegrationPhaseKey');
+    }
   } catch { /* intentionally empty */ }
   }
 
-  // ─── Check 6: Phase directory naming (NN-name format) ─────────────────────
+  // ─── Read phase directories once for checks 6, 7, 7b, and 8 (#1973) ──────
+  let phaseDirEntries = [];
+  const phaseDirFiles = new Map(); // phase dir name → file list
   try {
-  const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
-  for (const e of entries) {
-    if (e.isDirectory() && !e.name.match(/^\d{2}(?:\.\d+)*-[\w-]+$/)) {
-    addIssue('warning', 'W005', `Phase directory "${e.name}" doesn't follow NN-name format`, 'Rename to match pattern (e.g., 01-setup)');
-    }
+  phaseDirEntries = fs.readdirSync(phasesDir, { withFileTypes: true }).filter(e => e.isDirectory());
+  for (const e of phaseDirEntries) {
+    try {
+    phaseDirFiles.set(e.name, fs.readdirSync(path.join(phasesDir, e.name)));
+    } catch { phaseDirFiles.set(e.name, []); }
   }
   } catch { /* intentionally empty */ }
 
+  // ─── Check 6: Phase directory naming (NN-name format) ─────────────────────
+  for (const e of phaseDirEntries) {
+  if (!e.name.match(/^\d{2}(?:\.\d+)*-[\w-]+$/)) {
+    addIssue('warning', 'W005', `Phase directory "${e.name}" doesn't follow NN-name format`, 'Rename to match pattern (e.g., 01-setup)');
+  }
+  }
+
   // ─── Check 7: Orphaned plans (PLAN without SUMMARY) ───────────────────────
-  try {
-  const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
-  for (const e of entries) {
-    if (!e.isDirectory()) continue;
-    const phaseFiles = fs.readdirSync(path.join(phasesDir, e.name));
-    const plans = phaseFiles.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md');
-    const summaries = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
-    const summaryBases = new Set(summaries.map(s => s.replace('-SUMMARY.md', '').replace('SUMMARY.md', '')));
+  for (const e of phaseDirEntries) {
+  const phaseFiles = phaseDirFiles.get(e.name) || [];
+  const plans = phaseFiles.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md');
+  const summaries = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
+  const summaryBases = new Set(summaries.map(s => s.replace('-SUMMARY.md', '').replace('SUMMARY.md', '')));
 
-    for (const plan of plans) {
+  for (const plan of plans) {
     const planBase = plan.replace('-PLAN.md', '').replace('PLAN.md', '');
     if (!summaryBases.has(planBase)) {
-      addIssue('info', 'I001', `${e.name}/${plan} has no SUMMARY.md`, 'May be in progress');
-    }
+    addIssue('info', 'I001', `${e.name}/${plan} has no SUMMARY.md`, 'May be in progress');
     }
   }
-  } catch { /* intentionally empty */ }
+  }
 
   // ─── Check 7b: Nyquist VALIDATION.md consistency ────────────────────────
-  try {
-  const phaseEntries = fs.readdirSync(phasesDir, { withFileTypes: true });
-  for (const e of phaseEntries) {
-    if (!e.isDirectory()) continue;
-    const phaseFiles = fs.readdirSync(path.join(phasesDir, e.name));
-    const hasResearch = phaseFiles.some(f => f.endsWith('-RESEARCH.md'));
-    const hasValidation = phaseFiles.some(f => f.endsWith('-VALIDATION.md'));
-    if (hasResearch && !hasValidation) {
+  for (const e of phaseDirEntries) {
+  const phaseFiles = phaseDirFiles.get(e.name) || [];
+  const hasResearch = phaseFiles.some(f => f.endsWith('-RESEARCH.md'));
+  const hasValidation = phaseFiles.some(f => f.endsWith('-VALIDATION.md'));
+  if (hasResearch && !hasValidation) {
     const researchFile = phaseFiles.find(f => f.endsWith('-RESEARCH.md'));
+    try {
     const researchContent = fs.readFileSync(path.join(phasesDir, e.name, researchFile), 'utf-8');
     if (researchContent.includes('## Validation Architecture')) {
       addIssue('warning', 'W009', `Phase ${e.name}: has Validation Architecture in RESEARCH.md but no VALIDATION.md`, 'Re-run /gsd-plan-phase with --research to regenerate');
     }
-    }
+    } catch { /* intentionally empty */ }
+  }
   }
-  } catch { /* intentionally empty */ }
 
   // ─── Check 7c: Agent installation (#1371) ──────────────────────────────────
   // Verify GSD agents are installed. Missing agents cause Task(subagent_type=...)
@@ -730,20 +736,29 @@ function cmdValidateHealth(cwd, options, raw) {
   }
 
   const diskPhases = new Set();
-  try {
-    const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
-    for (const e of entries) {
-    if (e.isDirectory()) {
-      const dm = e.name.match(/^(\d+[A-Z]?(?:\.\d+)*)/i);
-      if (dm) diskPhases.add(dm[1]);
-    }
-    }
-  } catch { /* intentionally empty */ }
+  for (const e of phaseDirEntries) {
+    const dm = e.name.match(/^(\d+[A-Z]?(?:\.\d+)*)/i);
+    if (dm) diskPhases.add(dm[1]);
+  }
+
+  // Build a set of phases explicitly marked not-yet-started in the ROADMAP
+  // summary list (- [ ] **Phase N:**). These phases are intentionally absent
+  // from disk -- W006 must not fire for them (#2009).
+  const notStartedPhases = new Set();
+  const uncheckedPattern = /-\s*\[\s\]\s*\*{0,2}Phase\s+(\d+[A-Z]?(?:\.\d+)*)[:\s*]/gi;
+  let um;
+  while ((um = uncheckedPattern.exec(roadmapContent)) !== null) {
+    notStartedPhases.add(um[1]);
+    // Also add zero-padded variant so 1 and 01 both match
+    notStartedPhases.add(String(parseInt(um[1], 10)).padStart(2, '0'));
+  }
 
   // Phases in ROADMAP but not on disk
   for (const p of roadmapPhases) {
     const padded = String(parseInt(p, 10)).padStart(2, '0');
     if (!diskPhases.has(p) && !diskPhases.has(padded)) {
+    // Skip phases explicitly flagged as not-yet-started in the summary list
+    if (notStartedPhases.has(p) || notStartedPhases.has(padded)) continue;
     addIssue('warning', 'W006', `Phase ${p} in ROADMAP.md but no directory on disk`, 'Create phase directory or remove from roadmap');
     }
   }
@@ -822,6 +837,40 @@ function cmdValidateHealth(cwd, options, raw) {
   } catch { /* parse error already caught in Check 5 */ }
   }
 
+  // ─── Check 11: Stale / orphan git worktrees (#2167) ────────────────────────
+  try {
+  const worktreeResult = execGit(cwd, ['worktree', 'list', '--porcelain']);
+  if (worktreeResult.exitCode === 0 && worktreeResult.stdout) {
+    const blocks = worktreeResult.stdout.split('\n\n').filter(Boolean);
+    // Skip the first block — it is always the main worktree
+    for (let i = 1; i < blocks.length; i++) {
+    const lines = blocks[i].split('\n');
+    const wtLine = lines.find(l => l.startsWith('worktree '));
+    if (!wtLine) continue;
+    const wtPath = wtLine.slice('worktree '.length);
+
+    if (!fs.existsSync(wtPath)) {
+      // Orphan: path no longer exists on disk
+      addIssue('warning', 'W017',
+      `Orphan git worktree: ${wtPath} (path no longer exists on disk)`,
+      'Run: git worktree prune');
+    } else {
+      // Check if stale (older than 1 hour)
+      try {
+      const stat = fs.statSync(wtPath);
+      const ageMs = Date.now() - stat.mtimeMs;
+      const ONE_HOUR = 60 * 60 * 1000;
+      if (ageMs > ONE_HOUR) {
+        addIssue('warning', 'W017',
+        `Stale git worktree: ${wtPath} (last modified ${Math.round(ageMs / 60000)} minutes ago)`,
+        `Run: git worktree remove ${wtPath} --force`);
+      }
+      } catch { /* stat failed — skip */ }
+    }
+    }
+  }
+  } catch { /* git worktree not available or not a git repo — skip silently */ }
+
   // ─── Perform repairs if requested ─────────────────────────────────────────
   const repairActions = [];
   if (options.repair && repairs.length > 0) {
@@ -861,9 +910,12 @@ function cmdValidateHealth(cwd, options, raw) {
       }
       // Generate minimal STATE.md from ROADMAP.md structure
       const milestone = getMilestoneInfo(cwd);
+      const projectRef = path
+        .relative(cwd, path.join(planningDir(cwd), 'PROJECT.md'))
+        .split(path.sep).join('/');
       let stateContent = `# Session State\n\n`;
       stateContent += `## Project Reference\n\n`;
-      stateContent += `See: .planning/PROJECT.md\n\n`;
+      stateContent += `See: ${projectRef}\n\n`;
       stateContent += `## Position\n\n`;
       stateContent += `**Milestone:** ${milestone.version} ${milestone.name}\n`;
       stateContent += `**Current phase:** (determining...)\n`;
@@ -891,6 +943,23 @@ function cmdValidateHealth(cwd, options, raw) {
       }
       break;
       }
+      case 'addAiIntegrationPhaseKey': {
+      if (fs.existsSync(configPath)) {
+        try {
+        const configRaw = fs.readFileSync(configPath, 'utf-8');
+        const configParsed = JSON.parse(configRaw);
+        if (!configParsed.workflow) configParsed.workflow = {};
+        if (configParsed.workflow.ai_integration_phase === undefined) {
+          configParsed.workflow.ai_integration_phase = true;
+          fs.writeFileSync(configPath, JSON.stringify(configParsed, null, 2), 'utf-8');
+        }
+        repairActions.push({ action: repair, success: true, path: 'config.json' });
+        } catch (err) {
+        repairActions.push({ action: repair, success: false, error: err.message });
+        }
+      }
+      break;
+      }
     }
     } catch (err) {
     repairActions.push({ action: repair, success: false, error: err.message });

package/.agent/skills/gsd/migration_report.md

@@ -1,7 +1,7 @@
 # GSD Migration Report
 
-- **Timestamp**: 2026-04-08T07:18:24.858917
-- **Version**: 1.34.2 -> 1.34.2
+- **Timestamp**: 2026-04-18T00:54:51.140135
+- **Version**: 1.37.1 -> 1.37.1
 - **Skill Name**: gsd
 
 ✅ All recognized source directories were successfully mapped and migrated.

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

@@ -17,6 +17,29 @@ Spawned by `discuss-phase` via `Task()`. You do NOT present output directly to t
 - Return structured markdown output for the main agent to synthesize
 </role>
 
+<documentation_lookup>
+When you need library or framework documentation, check in this order:
+
+1. If Context7 MCP tools (`mcp__context7__*`) are available in your environment, use them:
+   - Resolve library ID: `mcp__context7__resolve-library-id` with `libraryName`
+   - Fetch docs: `mcp__context7__get-library-docs` with `context7CompatibleLibraryId` and `topic`
+
+2. If Context7 MCP is not available (upstream bug anthropics/antigravity-code#13898 strips MCP
+   tools from agents with a `tools:` frontmatter restriction), use the CLI fallback via Bash:
+
+   Step 1 — Resolve library ID:
+   ```bash
+   npx --yes ctx7@latest library <name> "<query>"
+   ```
+   Step 2 — Fetch documentation:
+   ```bash
+   npx --yes ctx7@latest docs <libraryId> "<query>"
+   ```
+
+Do not skip documentation lookups because MCP tools are unavailable — the CLI fallback
+works via Bash and produces equivalent output.
+</documentation_lookup>
+
 <input>
 Agent receives via prompt:
 

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

@@ -0,0 +1,133 @@
+---
+name: gsd-ai-researcher
+description: Researches a chosen AI framework's official docs to produce implementation-ready guidance — best practices, syntax, core patterns, and pitfalls distilled for the specific use case. Writes the Framework Quick Reference and Implementation Guidance sections of AI-SPEC.md. Spawned by /gsd-ai-integration-phase orchestrator.
+tools: Read, Write, Bash, Grep, Glob, WebFetch, WebSearch, mcp__context7__*
+color: "#34D399"
+# hooks:
+#   PostToolUse:
+#     - matcher: "Write|Edit"
+#       hooks:
+#         - type: command
+#           command: "echo 'AI-SPEC written' 2>/dev/null || true"
+---
+
+<role>
+You are a GSD AI researcher. Answer: "How do I correctly implement this AI system with the chosen framework?"
+Write Sections 3–4b of AI-SPEC.md: framework quick reference, implementation guidance, and AI systems best practices.
+</role>
+
+<documentation_lookup>
+When you need library or framework documentation, check in this order:
+
+1. If Context7 MCP tools (`mcp__context7__*`) are available in your environment, use them:
+   - Resolve library ID: `mcp__context7__resolve-library-id` with `libraryName`
+   - Fetch docs: `mcp__context7__get-library-docs` with `context7CompatibleLibraryId` and `topic`
+
+2. If Context7 MCP is not available (upstream bug anthropics/antigravity-code#13898 strips MCP
+   tools from agents with a `tools:` frontmatter restriction), use the CLI fallback via Bash:
+
+   Step 1 — Resolve library ID:
+   ```bash
+   npx --yes ctx7@latest library <name> "<query>"
+   ```
+   Step 2 — Fetch documentation:
+   ```bash
+   npx --yes ctx7@latest docs <libraryId> "<query>"
+   ```
+
+Do not skip documentation lookups because MCP tools are unavailable — the CLI fallback
+works via Bash and produces equivalent output.
+</documentation_lookup>
+
+<required_reading>
+Read `C:/projects/GSD-Antigravity/.antigravity/get-shit-done/references/ai-frameworks.md` for framework profiles and known pitfalls before fetching docs.
+</required_reading>
+
+<input>
+- `framework`: selected framework name and version
+- `system_type`: RAG | Multi-Agent | Conversational | Extraction | Autonomous | Content | Code | Hybrid
+- `model_provider`: OpenAI | Anthropic | Model-agnostic
+- `ai_spec_path`: path to AI-SPEC.md
+- `phase_context`: phase name and goal
+- `context_path`: path to CONTEXT.md if it exists
+
+**If prompt contains `<required_reading>`, read every listed file before doing anything else.**
+</input>
+
+<documentation_sources>
+Use context7 MCP first (fastest). Fall back to WebFetch.
+
+| Framework | Official Docs URL |
+|-----------|------------------|
+| CrewAI | https://docs.crewai.com |
+| LlamaIndex | https://docs.llamaindex.ai |
+| LangChain | https://python.langchain.com/docs |
+| LangGraph | https://langchain-ai.github.io/langgraph |
+| OpenAI Agents SDK | https://openai.github.io/openai-agents-python |
+| Antigravity Agent SDK | https://docs.anthropic.com/en/docs/antigravity-code/sdk |
+| AutoGen / AG2 | https://ag2ai.github.io/ag2 |
+| Google ADK | https://google.github.io/adk-docs |
+| Haystack | https://docs.haystack.deepset.ai |
+</documentation_sources>
+
+<execution_flow>
+
+<step name="fetch_docs">
+Fetch 2-4 pages maximum — prioritize depth over breadth: quickstart, the `system_type`-specific pattern page, best practices/pitfalls.
+Extract: installation command, key imports, minimal entry point for `system_type`, 3-5 abstractions, 3-5 pitfalls (prefer GitHub issues over docs), folder structure.
+</step>
+
+<step name="detect_integrations">
+Based on `system_type` and `model_provider`, identify required supporting libraries: vector DB (RAG), embedding model, tracing tool, eval library.
+Fetch brief setup docs for each.
+</step>
+
+<step name="write_sections_3_4">
+**ALWAYS use the Write tool to create files** — never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
+
+Update AI-SPEC.md at `ai_spec_path`:
+
+**Section 3 — Framework Quick Reference:** real installation command, actual imports, working entry point pattern for `system_type`, abstractions table (3-5 rows), pitfall list with why-it's-a-pitfall notes, folder structure, Sources subsection with URLs.
+
+**Section 4 — Implementation Guidance:** specific model (e.g., `antigravity-sonnet-4-6`, `gpt-4o`) with params, core pattern as code snippet with inline comments, tool use config, state management approach, context window strategy.
+</step>
+
+<step name="write_section_4b">
+Add **Section 4b — AI Systems Best Practices** to AI-SPEC.md. Always included, independent of framework choice.
+
+**4b.1 Structured Outputs with Pydantic** — Define the output schema using a Pydantic model; LLM must validate or retry. Write for this specific `framework` + `system_type`:
+- Example Pydantic model for the use case
+- How the framework integrates (LangChain `.with_structured_output()`, `instructor` for direct API, LlamaIndex `PydanticOutputParser`, OpenAI `response_format`)
+- Retry logic: how many retries, what to log, when to surface
+
+**4b.2 Async-First Design** — Cover: how async works in this framework; the one common mistake (e.g., `asyncio.run()` in an event loop); stream vs. await (stream for UX, await for structured output validation).
+
+**4b.3 Prompt Engineering Discipline** — System vs. user prompt separation; few-shot: inline vs. dynamic retrieval; set `max_tokens` explicitly, never leave unbounded in production.
+
+**4b.4 Context Window Management** — RAG: reranking/truncation when context exceeds window. Multi-agent/Conversational: summarisation patterns. Autonomous: framework compaction handling.
+
+**4b.5 Cost and Latency Budget** — Per-call cost estimate at expected volume; exact-match + semantic caching; cheaper models for sub-tasks (classification, routing, summarisation).
+</step>
+
+</execution_flow>
+
+<quality_standards>
+- All code snippets syntactically correct for the fetched version
+- Imports match actual package structure (not approximate)
+- Pitfalls specific — "use async where supported" is useless
+- Entry point pattern is copy-paste runnable
+- No hallucinated API methods — note "verify in docs" if unsure
+- Section 4b examples specific to `framework` + `system_type`, not generic
+</quality_standards>
+
+<success_criteria>
+- [ ] Official docs fetched (2-4 pages, not just homepage)
+- [ ] Installation command correct for latest stable version
+- [ ] Entry point pattern runs for `system_type`
+- [ ] 3-5 abstractions in context of use case
+- [ ] 3-5 specific pitfalls with explanations
+- [ ] Sections 3 and 4 written and non-empty
+- [ ] Section 4b: Pydantic example for this framework + system_type
+- [ ] Section 4b: async pattern, prompt discipline, context management, cost budget
+- [ ] Sources listed in Section 3
+</success_criteria>

package/.agent/skills/gsd/references/agents/gsd-code-fixer.md

@@ -15,7 +15,7 @@ Spawned by `/gsd-code-review-fix` workflow. You produce REVIEW-FIX.md artifact i
 Your job: Read REVIEW.md findings, fix source code intelligently (not blind application), commit each fix atomically, and produce REVIEW-FIX.md report.
 
 **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.
+If the prompt contains a `<required_reading>` 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>
@@ -194,7 +194,7 @@ The **Fix:** section may contain:
 If a finding references multiple files (in Fix section or Issue section):
 - Collect ALL file paths into `files` array
 - Apply fix to each file
-- Commit all modified files atomically (single commit, multiple files in `--files` list)
+- Commit all modified files atomically (single commit, list every file path after the message — `commit` uses positional paths, not `--files`)
 
 **Parsing Rules:**
 
@@ -210,7 +210,7 @@ If a finding references multiple files (in Fix section or Issue section):
 <execution_flow>
 
 <step name="load_context">
-**1. Read mandatory files:** Load all files from `<files_to_read>` block if present.
+**1. Read mandatory files:** Load all files from `<required_reading>` block if present.
 
 **2. Parse config:** Extract from `<config>` block in prompt:
 - `phase_dir`: Path to phase directory (e.g., `.planning/phases/02-code-review-command`)
@@ -308,20 +308,21 @@ For each finding in sorted order:
 
 **If verification passed:**
 
-Use gsd-tools commit command with conventional format:
+Use `gsd-sdk query commit` with conventional format (message first, then every staged file path):
 ```bash
-.agent/skills/gsd/bin/gsd-tools.cjs" commit \
+gsd-sdk query commit \
   "fix({padded_phase}): {finding_id} {short_description}" \
-  --files {all_modified_files}
+  {all_modified_files}
 ```
 
 Examples:
 - `fix(02): CR-01 fix SQL injection in auth.py`
 - `fix(03): WR-05 add null check before array access`
 
-**Multiple files:** List ALL modified files in `--files` (space-separated):
+**Multiple files:** List ALL modified files after the message (space-separated):
 ```bash
---files src/api/auth.ts src/types/user.ts tests/auth.test.ts
+gsd-sdk query commit "fix(02): CR-01 ..." \
+  src/api/auth.ts src/types/user.ts tests/auth.test.ts
 ```
 
 **Extract commit hash:**
@@ -442,7 +443,7 @@ _Iteration: {N}_
 
 **DO record which files will be touched** before every fix attempt — this is your rollback list. Rollback is `git checkout -- {file}`, not content capture.
 
-**DO commit each fix atomically** — one commit per finding, listing ALL modified files in `--files` argument.
+**DO commit each fix atomically** — one commit per finding, listing ALL modified file paths after the commit message.
 
 **DO use Edit tool (preferred)** over Write tool for targeted changes. Edit provides better diff visibility.
 
@@ -504,7 +505,7 @@ Fixes are committed **per-finding**. This has operational implications:
 
 - [ ] All in-scope findings attempted (either fixed or skipped with reason)
 - [ ] Each fix committed atomically with `fix({padded_phase}): {id} {description}` format
-- [ ] All modified files listed in each commit's `--files` argument (multi-file fix support)
+- [ ] All modified files listed after each commit message (multi-file fix support)
 - [ ] REVIEW-FIX.md created with accurate counts, status, and iteration number
 - [ ] No source files left in broken state (failed fixes rolled back via git checkout)
 - [ ] No partial or uncommitted changes remain after execution

package/.agent/skills/gsd/references/agents/gsd-code-reviewer.md

@@ -13,7 +13,7 @@ You are a GSD code reviewer. You analyze source files for bugs, security vulnera
 Spawned by `/gsd-code-review` workflow. You produce REVIEW.md artifact in the phase directory.
 
 **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.
+If the prompt contains a `<required_reading>` 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>
@@ -81,7 +81,7 @@ Additional checks:
 <execution_flow>
 
 <step name="load_context">
-**1. Read mandatory files:** Load all files from `<files_to_read>` block if present.
+**1. Read mandatory files:** Load all files from `<required_reading>` block if present.
 
 **2. Parse config:** Extract from `<config>` block:
 - `depth`: quick | standard | deep (default: standard)

package/.agent/skills/gsd/references/agents/gsd-codebase-mapper.md

@@ -23,9 +23,20 @@ You are spawned by `/gsd-map-codebase` with one of four focus areas:
 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.
+If the prompt contains a `<required_reading>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
 </role>
 
+**Context budget:** Load project skills first (lightweight). Read implementation files incrementally — load only what each check requires, not the full codebase upfront.
+
+**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
+4. Do NOT load full `AGENTS.md` files (100KB+ context cost)
+5. Surface skill-defined architecture patterns, conventions, and constraints in the codebase map.
+
+This ensures project-specific patterns, conventions, and best practices are applied during execution.
+
 <why_this_matters>
 **These documents are consumed by other GSD commands:**
 
@@ -149,7 +160,7 @@ Write document(s) to `.planning/codebase/` using the templates below.
 **Document naming:** UPPERCASE.md (e.g., STACK.md, ARCHITECTURE.md)
 
 **Template filling:**
-1. Replace `[YYYY-MM-DD]` with current date
+1. Replace `[YYYY-MM-DD]` with the date provided in your prompt (the `Today's date:` line). NEVER guess or infer the date — always use the exact date from the prompt.
 2. Replace `[Placeholder text]` with findings from exploration
 3. If something is not found, use "Not detected" or "Not applicable"
 4. Always include file paths with backticks