gsd-antigravity-kit 1.24.0 → 1.25.1

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

@@ -1,6 +1,6 @@
 ---
 name: gsd
-version: 1.24.0
+version: 1.25.1
 description: "Antigravity GSD (Get Stuff Done) - A spec-driven hierarchical planning and execution system. Triggers on project planning, phase management, and GSD slash commands."
 ---
 
@@ -31,6 +31,7 @@ This skill should be used when:
 - `gsd:complete-milestone`
 - `gsd:debug`
 - `gsd:discuss-phase`
+- `gsd:do`
 - `gsd:execute-phase`
 - `gsd:gsd-tools`
 - `gsd:health`
@@ -41,6 +42,7 @@ This skill should be used when:
 - `gsd:map-codebase`
 - `gsd:new-milestone`
 - `gsd:new-project`
+- `gsd:note`
 - `gsd:pause-work`
 - `gsd:plan-milestone-gaps`
 - `gsd:plan-phase`
@@ -80,6 +82,7 @@ The following slash commands are available in this skill. Use them to drive the
 - **[`gsd:complete-milestone`](references/commands/complete-milestone.md)**: Archive completed milestone and prepare for next version
 - **[`gsd:debug`](references/commands/debug.md)**: Systematic debugging with persistent state across context resets
 - **[`gsd:discuss-phase`](references/commands/discuss-phase.md)**: Gather phase context through adaptive questioning before planning. Use --auto to skip interactive questions (Antigravity picks recommended defaults).
+- **[`gsd:do`](references/commands/do.md)**: Route freeform text to the right GSD command automatically
 - **[`gsd:execute-phase`](references/commands/execute-phase.md)**: Execute all plans in a phase with wave-based parallelization
 - **[`gsd:gsd-tools`](references/commands/gsd-tools.md)**: Direct access to GSD internal CLI tools for atomic operations (state, roadmap, phase, config, etc.)
 - **[`gsd:health`](references/commands/health.md)**: Diagnose planning directory health and optionally repair issues
@@ -90,6 +93,7 @@ The following slash commands are available in this skill. Use them to drive the
 - **[`gsd:map-codebase`](references/commands/map-codebase.md)**: Analyze codebase with parallel mapper agents to produce .planning/codebase/ documents
 - **[`gsd:new-milestone`](references/commands/new-milestone.md)**: Start a new milestone cycle — update PROJECT.md and route to requirements
 - **[`gsd:new-project`](references/commands/new-project.md)**: Initialize a new project with deep context gathering and PROJECT.md
+- **[`gsd:note`](references/commands/note.md)**: Zero-friction idea capture. Append, list, or promote notes to todos.
 - **[`gsd:pause-work`](references/commands/pause-work.md)**: Create context handoff when pausing work mid-phase
 - **[`gsd:plan-milestone-gaps`](references/commands/plan-milestone-gaps.md)**: Create phases to close all gaps identified by milestone audit
 - **[`gsd:plan-phase`](references/commands/plan-phase.md)**: Create detailed phase plan (PLAN.md) with verification loop
@@ -141,4 +145,4 @@ General documentation on the GSD philosophy, usage patterns, and configuration.
 5.  **CLI Invocation**: `gsd-tools` is **NOT** a global command. Always invoke it with the full node path: `node .agent/skills/gsd/bin/gsd-tools.cjs <command> [args]`. Never run `gsd-tools` bare.
 
 ---
-*Generated by gsd-converter on 2026-03-15*
+*Generated by gsd-converter on 2026-03-16*

package/.agent/skills/gsd/assets/templates/config.json

@@ -33,5 +33,8 @@
   "safety": {
     "always_confirm_destructive": true,
     "always_confirm_external_services": true
+  },
+  "hooks": {
+    "context_warnings": true
   }
 }

package/.agent/skills/gsd/bin/help-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.24.0",
+  "version": "1.25.1",
   "commands": {
     "add-phase": {
       "description": "Add phase to end of current milestone in roadmap"
@@ -31,6 +31,9 @@
     "discuss-phase": {
       "description": "Gather phase context through adaptive questioning before planning. Use --auto to skip interactive questions (Antigravity picks recommended defaults)."
     },
+    "do": {
+      "description": "Route freeform text to the right GSD command automatically"
+    },
     "execute-phase": {
       "description": "Execute all plans in a phase with wave-based parallelization"
     },
@@ -58,6 +61,9 @@
     "new-project": {
       "description": "Initialize a new project with deep context gathering and PROJECT.md"
     },
+    "note": {
+      "description": "Zero-friction idea capture. Append, list, or promote notes to todos."
+    },
     "pause-work": {
       "description": "Create context handoff when pausing work mid-phase"
     },

package/.agent/skills/gsd/bin/hooks/gsd-context-monitor.js

@@ -43,6 +43,20 @@ process.stdin.on('end', () => {
       process.exit(0);
     }
 
+    // Check if context warnings are disabled via config
+    const cwd = data.cwd || process.cwd();
+    const configPath = path.join(cwd, '.planning', 'config.json');
+    if (fs.existsSync(configPath)) {
+      try {
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        if (config.hooks?.context_warnings === false) {
+          process.exit(0);
+        }
+      } catch (e) {
+        // Ignore config parse errors
+      }
+    }
+
     const tmpDir = os.tmpdir();
     const metricsPath = path.join(tmpDir, `antigravity-ctx-${sessionId}.json`);
 

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

@@ -4,7 +4,7 @@
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
-const { safeReadFile, loadConfig, isGitIgnored, execGit, normalizePhaseName, comparePhaseNum, getArchivedPhaseDirs, generateSlugInternal, getMilestoneInfo, resolveModelInternal, toPosixPath, output, error, findPhaseInternal } = require('./core.cjs');
+const { safeReadFile, loadConfig, isGitIgnored, execGit, normalizePhaseName, comparePhaseNum, getArchivedPhaseDirs, generateSlugInternal, getMilestoneInfo, getMilestonePhaseFilter, resolveModelInternal, stripShippedMilestones, toPosixPath, output, error, findPhaseInternal } = require('./core.cjs');
 const { extractFrontmatter } = require('./frontmatter.cjs');
 const { MODEL_PROFILES } = require('./model-profiles.cjs');
 
@@ -535,21 +535,42 @@ function cmdScaffold(cwd, type, options, raw) {
 
 function cmdStats(cwd, format, raw) {
   const phasesDir = path.join(cwd, '.planning', 'phases');
+  const roadmapPath = path.join(cwd, '.planning', 'ROADMAP.md');
   const reqPath = path.join(cwd, '.planning', 'REQUIREMENTS.md');
   const statePath = path.join(cwd, '.planning', 'STATE.md');
   const milestone = getMilestoneInfo(cwd);
+  const isDirInMilestone = getMilestonePhaseFilter(cwd);
 
   // Phase & plan stats (reuse progress pattern)
-  const phases = [];
+  const phasesByNumber = new Map();
   let totalPlans = 0;
   let totalSummaries = 0;
 
+  try {
+  const roadmapContent = stripShippedMilestones(fs.readFileSync(roadmapPath, 'utf-8'));
+  const headingPattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:\s*([^\n]+)/gi;
+  let match;
+  while ((match = headingPattern.exec(roadmapContent)) !== null) {
+    phasesByNumber.set(match[1], {
+    number: match[1],
+    name: match[2].replace(/\(INSERTED\)/i, '').trim(),
+    plans: 0,
+    summaries: 0,
+    status: 'Not Started',
+    });
+  }
+  } catch {}
+
   try {
   const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
-  const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort((a, b) => comparePhaseNum(a, b));
+  const dirs = entries
+    .filter(e => e.isDirectory())
+    .map(e => e.name)
+    .filter(isDirInMilestone)
+    .sort((a, b) => comparePhaseNum(a, b));
 
   for (const dir of dirs) {
-    const dm = dir.match(/^(\d+(?:\.\d+)*)-?(.*)/);
+    const dm = dir.match(/^(\d+[A-Z]?(?:\.\d+)*)-?(.*)/i);
     const phaseNum = dm ? dm[1] : dir;
     const phaseName = dm && dm[2] ? dm[2].replace(/-/g, ' ') : '';
     const phaseFiles = fs.readdirSync(path.join(phasesDir, dir));
@@ -560,16 +581,26 @@ function cmdStats(cwd, format, raw) {
     totalSummaries += summaries;
 
     let status;
-    if (plans === 0) status = 'Pending';
+    if (plans === 0) status = 'Not Started';
     else if (summaries >= plans) status = 'Complete';
     else if (summaries > 0) status = 'In Progress';
     else status = 'Planned';
 
-    phases.push({ number: phaseNum, name: phaseName, plans, summaries, status });
+    const existing = phasesByNumber.get(phaseNum);
+    phasesByNumber.set(phaseNum, {
+    number: phaseNum,
+    name: existing?.name || phaseName,
+    plans,
+    summaries,
+    status,
+    });
   }
   } catch {}
 
-  const percent = totalPlans > 0 ? Math.min(100, Math.round((totalSummaries / totalPlans) * 100)) : 0;
+  const phases = [...phasesByNumber.values()].sort((a, b) => comparePhaseNum(a.number, b.number));
+  const completedPhases = phases.filter(p => p.status === 'Complete').length;
+  const planPercent = totalPlans > 0 ? Math.min(100, Math.round((totalSummaries / totalPlans) * 100)) : 0;
+  const percent = phases.length > 0 ? Math.min(100, Math.round((completedPhases / phases.length) * 100)) : 0;
 
   // Requirements stats
   let requirementsTotal = 0;
@@ -589,7 +620,10 @@ function cmdStats(cwd, format, raw) {
   try {
   if (fs.existsSync(statePath)) {
     const stateContent = fs.readFileSync(statePath, 'utf-8');
-    const activityMatch = stateContent.match(/\*\*Last Activity:\*\*\s*(.+)/);
+    const activityMatch = stateContent.match(/^last_activity:\s*(.+)$/im)
+    || stateContent.match(/\*\*Last Activity:\*\*\s*(.+)/i)
+    || stateContent.match(/^Last Activity:\s*(.+)$/im)
+    || stateContent.match(/^Last activity:\s*(.+)$/im);
     if (activityMatch) lastActivity = activityMatch[1].trim();
   }
   } catch {}
@@ -597,14 +631,18 @@ function cmdStats(cwd, format, raw) {
   // Git stats
   let gitCommits = 0;
   let gitFirstCommitDate = null;
-  try {
   const commitCount = execGit(cwd, ['rev-list', '--count', 'HEAD']);
-  gitCommits = parseInt(commitCount.trim(), 10) || 0;
-  const firstDate = execGit(cwd, ['log', '--reverse', '--format=%as', '--max-count=1']);
-  gitFirstCommitDate = firstDate.trim() || null;
-  } catch {}
-
-  const completedPhases = phases.filter(p => p.status === 'Complete').length;
+  if (commitCount.exitCode === 0) {
+  gitCommits = parseInt(commitCount.stdout, 10) || 0;
+  }
+  const rootHash = execGit(cwd, ['rev-list', '--max-parents=0', 'HEAD']);
+  if (rootHash.exitCode === 0 && rootHash.stdout) {
+  const firstCommit = rootHash.stdout.split('\n')[0].trim();
+  const firstDate = execGit(cwd, ['show', '-s', '--format=%as', firstCommit]);
+  if (firstDate.exitCode === 0) {
+    gitFirstCommitDate = firstDate.stdout || null;
+  }
+  }
 
   const result = {
   milestone_version: milestone.version,
@@ -615,6 +653,7 @@ function cmdStats(cwd, format, raw) {
   total_plans: totalPlans,
   total_summaries: totalSummaries,
   percent,
+  plan_percent: planPercent,
   requirements_total: requirementsTotal,
   requirements_complete: requirementsComplete,
   git_commits: gitCommits,
@@ -627,7 +666,10 @@ function cmdStats(cwd, format, raw) {
   const filled = Math.round((percent / 100) * barWidth);
   const bar = '\u2588'.repeat(filled) + '\u2591'.repeat(barWidth - filled);
   let out = `# ${milestone.version} ${milestone.name} \u2014 Statistics\n\n`;
-  out += `**Progress:** [${bar}] ${totalSummaries}/${totalPlans} plans (${percent}%)\n`;
+  out += `**Progress:** [${bar}] ${completedPhases}/${phases.length} phases (${percent}%)\n`;
+  if (totalPlans > 0) {
+    out += `**Plans:** ${totalSummaries}/${totalPlans} complete (${planPercent}%)\n`;
+  }
   out += `**Phases:** ${completedPhases}/${phases.length} complete\n`;
   if (requirementsTotal > 0) {
     out += `**Requirements:** ${requirementsComplete}/${requirementsTotal} complete\n`;

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

@@ -4,7 +4,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { execSync } = require('child_process');
+const { execSync, spawnSync } = require('child_process');
 const { MODEL_PROFILES } = require('./model-profiles.cjs');
 
 // ─── Path helpers ────────────────────────────────────────────────────────────
@@ -187,24 +187,16 @@ function isGitIgnored(cwd, targetPath) {
 }
 
 function execGit(cwd, args) {
-  try {
-  const escaped = args.map(a => {
-    if (/^[a-zA-Z0-9._\-/=:@]+$/.test(a)) return a;
-    return "'" + a.replace(/'/g, "'\\''") + "'";
+  const result = spawnSync('git', args, {
+  cwd,
+  stdio: 'pipe',
+  encoding: 'utf-8',
   });
-  const stdout = execSync('git ' + escaped.join(' '), {
-    cwd,
-    stdio: 'pipe',
-    encoding: 'utf-8',
-  });
-  return { exitCode: 0, stdout: stdout.trim(), stderr: '' };
-  } catch (err) {
   return {
-    exitCode: err.status ?? 1,
-    stdout: (err.stdout ?? '').toString().trim(),
-    stderr: (err.stderr ?? '').toString().trim(),
+  exitCode: result.status ?? 1,
+  stdout: (result.stdout ?? '').toString().trim(),
+  stderr: (result.stderr ?? '').toString().trim(),
   };
-  }
 }
 
 // ─── Phase utilities ──────────────────────────────────────────────────────────
@@ -437,7 +429,7 @@ function resolveModelInternal(cwd, agentType) {
   // Check per-agent override first
   const override = config.model_overrides?.[agentType];
   if (override) {
-  return override === 'opus' ? 'inherit' : override;
+  return override;
   }
 
   // Fall back to profile lookup
@@ -445,8 +437,7 @@ function resolveModelInternal(cwd, agentType) {
   const agentModels = MODEL_PROFILES[agentType];
   if (!agentModels) return 'sonnet';
   if (profile === 'inherit') return 'inherit';
-  const resolved = agentModels[profile] || agentModels['balanced'] || 'sonnet';
-  return resolved === 'opus' ? 'inherit' : resolved;
+  return agentModels[profile] || agentModels['balanced'] || 'sonnet';
 }
 
 // ─── Misc utilities ───────────────────────────────────────────────────────────

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

@@ -357,6 +357,29 @@ function cmdInitPhaseOp(cwd, phase, raw) {
   const config = loadConfig(cwd);
   let phaseInfo = findPhaseInternal(cwd, phase);
 
+  // If the only disk match comes from an archived milestone, prefer the
+  // current milestone's ROADMAP entry so discuss-phase and similar flows
+  // don't attach to shipped work that reused the same phase number.
+  if (phaseInfo?.archived) {
+  const roadmapPhase = getRoadmapPhaseInternal(cwd, phase);
+  if (roadmapPhase?.found) {
+    const phaseName = roadmapPhase.phase_name;
+    phaseInfo = {
+    found: true,
+    directory: null,
+    phase_number: roadmapPhase.phase_number,
+    phase_name: phaseName,
+    phase_slug: phaseName ? phaseName.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') : null,
+    plans: [],
+    summaries: [],
+    incomplete_plans: [],
+    has_research: false,
+    has_context: false,
+    has_verification: false,
+    };
+  }
+  }
+
   // Fallback to ROADMAP.md if no directory exists (e.g., Plans: TBD)
   if (!phaseInfo) {
   const roadmapPhase = getRoadmapPhaseInternal(cwd, phase);

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

@@ -4,7 +4,8 @@
 
 const fs = require('fs');
 const path = require('path');
-const { safeReadFile, normalizePhaseName, execGit, findPhaseInternal, getMilestoneInfo, output, error } = require('./core.cjs');
+const os = require('os');
+const { safeReadFile, normalizePhaseName, execGit, findPhaseInternal, getMilestoneInfo, stripShippedMilestones, output, error } = require('./core.cjs');
 const { extractFrontmatter, parseMustHavesBlock } = require('./frontmatter.cjs');
 const { writeStateMd } = require('./state.cjs');
 
@@ -407,9 +408,10 @@ function cmdValidateConsistency(cwd, raw) {
   return;
   }
 
-  const roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
+  const roadmapContentRaw = fs.readFileSync(roadmapPath, 'utf-8');
+  const roadmapContent = stripShippedMilestones(roadmapContentRaw);
 
-  // Extract phases from ROADMAP
+  // Extract phases from ROADMAP (archived milestones already stripped)
   const roadmapPhases = new Set();
   const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:/gi;
   let m;
@@ -515,6 +517,19 @@ function cmdValidateConsistency(cwd, raw) {
 }
 
 function cmdValidateHealth(cwd, options, raw) {
+  // Guard: detect if CWD is the home directory (likely accidental)
+  const resolved = path.resolve(cwd);
+  if (resolved === os.homedir()) {
+  output({
+    status: 'error',
+    errors: [{ code: 'E010', message: `CWD is home directory (${resolved}) — health check would read the wrong .planning/ directory. Run from your project root instead.`, fix: 'cd into your project directory and retry' }],
+    warnings: [],
+    info: [{ code: 'I010', message: `Resolved CWD: ${resolved}` }],
+    repairable_count: 0,
+  }, raw);
+  return;
+  }
+
   const planningDir = path.join(cwd, '.planning');
   const projectPath = path.join(planningDir, 'PROJECT.md');
   const roadmapPath = path.join(planningDir, 'ROADMAP.md');
@@ -679,7 +694,8 @@ function cmdValidateHealth(cwd, options, raw) {
   // ─── Check 8: Run existing consistency checks ─────────────────────────────
   // Inline subset of cmdValidateConsistency
   if (fs.existsSync(roadmapPath)) {
-  const roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
+  const roadmapContentRaw = fs.readFileSync(roadmapPath, 'utf-8');
+  const roadmapContent = stripShippedMilestones(roadmapContentRaw);
   const roadmapPhases = new Set();
   const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:/gi;
   let m;

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

@@ -337,6 +337,8 @@ git commit -m "{type}({phase}-{plan}): {concise task description}
 ```
 
 **5. Record hash:** `TASK_COMMIT=$(git rev-parse --short HEAD)` — track for SUMMARY.
+
+**6. Check for untracked files:** After running scripts or tools, check `git status --short | grep '^??'`. For any new untracked files: commit if intentional, add to `.gitignore` if generated/runtime output. Never leave generated files untracked.
 </task_commit_protocol>
 
 <summary_creation>

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

@@ -238,6 +238,12 @@ Priority: Context7 > Official Docs > Official GitHub > Verified WebSearch > Unve
 npm install [packages]
 \`\`\`
 
+**Version verification:** Before writing the Standard Stack table, verify each recommended package version is current:
+\`\`\`bash
+npm view [package] version
+\`\`\`
+Document the verified version and publish date. Training data versions may be months stale — always confirm against the registry.
+
 ## Architecture Patterns
 
 ### Recommended Project Structure

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

@@ -68,7 +68,8 @@ 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?"
+- "More questions about [area], or move to next? (Remaining: [list unvisited areas])"
+- Show remaining unvisited areas so user knows what's still ahead
 - If more → ask 4 more, check again
 - After all areas → "Ready to create context?"
 

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

@@ -0,0 +1,30 @@
+---
+name: gsd:do
+description: Route freeform text to the right GSD command automatically
+argument-hint: "<description of what you want to do>"
+allowed-tools:
+  - Read
+  - Bash
+  - AskUserQuestion
+---
+<objective>
+Analyze freeform natural language input and dispatch to the most appropriate GSD command.
+
+Acts as a smart dispatcher — never does the work itself. Matches intent to the best GSD command using routing rules, confirms the match, then hands off.
+
+Use when you know what you want but don't know which `/gsd:*` command to run.
+</objective>
+
+<execution_context>
+@C:/projects/GSD-Antigravityreferences/workflows/do.md
+@C:/projects/GSD-Antigravity/.antigravity/get-shit-done/references/ui-brand.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+Execute the do workflow from @C:/projects/GSD-Antigravityreferences/workflows/do.md end-to-end.
+Route user intent to the best GSD command and invoke it.
+</process>

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

@@ -0,0 +1,34 @@
+---
+name: gsd:note
+description: Zero-friction idea capture. Append, list, or promote notes to todos.
+argument-hint: "<text> | list | promote <N> [--global]"
+allowed-tools:
+  - Read
+  - Write
+  - Glob
+  - Grep
+---
+<objective>
+Zero-friction idea capture — one Write call, one confirmation line.
+
+Three subcommands:
+- **append** (default): Save a timestamped note file. No questions, no formatting.
+- **list**: Show all notes from project and global scopes.
+- **promote**: Convert a note into a structured todo.
+
+Runs inline — no Task, no AskUserQuestion, no Bash.
+</objective>
+
+<execution_context>
+@C:/projects/GSD-Antigravityreferences/workflows/note.md
+@C:/projects/GSD-Antigravity/.antigravity/get-shit-done/references/ui-brand.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+Execute the note workflow from @C:/projects/GSD-Antigravityreferences/workflows/note.md end-to-end.
+Capture the note, list notes, or promote to todo — depending on arguments.
+</process>

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

@@ -456,9 +456,11 @@ After all areas are auto-resolved, skip the "Explore more gray areas" prompt and
 
 3. **After the current set of questions, check:**
    - header: "[Area]" (max 12 chars)
-   - question: "More questions about [area], or move to next?"
+   - question: "More questions about [area], or move to next? (Remaining: [list other unvisited areas])"
    - options: "More questions" / "Next area"
 
+   When building the question text, list the remaining unvisited areas so the user knows what's ahead. For example: "More questions about Layout, or move to next? (Remaining: Loading behavior, Content ordering)"
+
    If "More questions" → ask another 4 single questions, or another 2-5 question batch when `--batch` is active, then check again
    If "Next area" → proceed to next selected area
    If "Other" (free text) → interpret intent: continuation phrases ("chat more", "keep going", "yes", "more") map to "More questions"; advancement phrases ("done", "move on", "next", "skip") map to "Next area". If ambiguous, ask: "Continue with more questions about [area], or move to the next area?"

package/.agent/skills/gsd/references/workflows/do.md

@@ -0,0 +1,104 @@
+<purpose>
+Analyze freeform text from the user and route to the most appropriate GSD command. This is a dispatcher — it never does the work itself. Match user intent to the best command, confirm the routing, and hand off.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="validate">
+**Check for input.**
+
+If `$ARGUMENTS` is empty, ask via AskUserQuestion:
+
+```
+What would you like to do? Describe the task, bug, or idea and I'll route it to the right GSD command.
+```
+
+Wait for response before continuing.
+</step>
+
+<step name="check_project">
+**Check if project exists.**
+
+```bash
+INIT=$(node "C:/projects/GSD-Antigravity.agent/skills/gsd/bin/gsd-tools.cjs" state load 2>/dev/null)
+```
+
+Track whether `.planning/` exists — some routes require it, others don't.
+</step>
+
+<step name="route">
+**Match intent to command.**
+
+Evaluate `$ARGUMENTS` against these routing rules. Apply the **first matching** rule:
+
+| If the text describes... | Route to | Why |
+|--------------------------|----------|-----|
+| Starting a new project, "set up", "initialize" | `/gsd:new-project` | Needs full project initialization |
+| Mapping or analyzing an existing codebase | `/gsd:map-codebase` | Codebase discovery |
+| A bug, error, crash, failure, or something broken | `/gsd:debug` | Needs systematic investigation |
+| Exploring, researching, comparing, or "how does X work" | `/gsd:research-phase` | Domain research before planning |
+| Discussing vision, "how should X look", brainstorming | `/gsd:discuss-phase` | Needs context gathering |
+| A complex task: refactoring, migration, multi-file architecture, system redesign | `/gsd:add-phase` | Needs a full phase with plan/build cycle |
+| Planning a specific phase or "plan phase N" | `/gsd:plan-phase` | Direct planning request |
+| Executing a phase or "build phase N", "run phase N" | `/gsd:execute-phase` | Direct execution request |
+| Running all remaining phases automatically | `/gsd:autonomous` | Full autonomous execution |
+| A review or quality concern about existing work | `/gsd:verify-work` | Needs verification |
+| Checking progress, status, "where am I" | `/gsd:progress` | Status check |
+| Resuming work, "pick up where I left off" | `/gsd:resume-work` | Session restoration |
+| A note, idea, or "remember to..." | `/gsd:add-todo` | Capture for later |
+| Adding tests, "write tests", "test coverage" | `/gsd:add-tests` | Test generation |
+| Completing a milestone, shipping, releasing | `/gsd:complete-milestone` | Milestone lifecycle |
+| A specific, actionable, small task (add feature, fix typo, update config) | `/gsd:quick` | Self-contained, single executor |
+
+**Requires `.planning/` directory:** All routes except `/gsd:new-project`, `/gsd:map-codebase`, `/gsd:help`, and `/gsd:join-discord`. If the project doesn't exist and the route requires it, suggest `/gsd:new-project` first.
+
+**Ambiguity handling:** If the text could reasonably match multiple routes, ask the user via AskUserQuestion with the top 2-3 options. For example:
+
+```
+"Refactor the authentication system" could be:
+1. /gsd:add-phase — Full planning cycle (recommended for multi-file refactors)
+2. /gsd:quick — Quick execution (if scope is small and clear)
+
+Which approach fits better?
+```
+</step>
+
+<step name="display">
+**Show the routing decision.**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► ROUTING
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Input:** {first 80 chars of $ARGUMENTS}
+**Routing to:** {chosen command}
+**Reason:** {one-line explanation}
+```
+</step>
+
+<step name="dispatch">
+**Invoke the chosen command.**
+
+Run the selected `/gsd:*` command, passing `$ARGUMENTS` as args.
+
+If the chosen command expects a phase number and one wasn't provided in the text, extract it from context or ask via AskUserQuestion.
+
+After invoking the command, stop. The dispatched command handles everything from here.
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Input validated (not empty)
+- [ ] Intent matched to exactly one GSD command
+- [ ] Ambiguity resolved via user question (if needed)
+- [ ] Project existence checked for routes that require it
+- [ ] Routing decision displayed before dispatch
+- [ ] Command invoked with appropriate arguments
+- [ ] No work done directly — dispatcher only
+</success_criteria>

package/.agent/skills/gsd/references/workflows/execute-plan.md

@@ -279,6 +279,15 @@ TASK_COMMIT=$(git rev-parse --short HEAD)
 TASK_COMMITS+=("Task ${TASK_NUM}: ${TASK_COMMIT}")
 ```
 
+**6. Check for untracked generated files:**
+```bash
+git status --short | grep '^??'
+```
+If new untracked files appeared after running scripts or tools, decide for each:
+- **Commit it** — if it's a source file, config, or intentional artifact
+- **Add to .gitignore** — if it's a generated/runtime output (build artifacts, `.env` files, cache files, compiled output)
+- Do NOT leave generated files untracked
+
 </task_commit>
 
 <step name="checkpoint_protocol">

package/.agent/skills/gsd/references/workflows/help.md

@@ -116,6 +116,20 @@ Execute all plans in a phase.
 
 Usage: `/gsd:execute-phase 5`
 
+### Smart Router
+
+**`/gsd:do <description>`**
+Route freeform text to the right GSD command automatically.
+
+- Analyzes natural language input to find the best matching GSD command
+- Acts as a dispatcher — never does the work itself
+- Resolves ambiguity by asking you to pick between top matches
+- Use when you know what you want but don't know which `/gsd:*` command to run
+
+Usage: `/gsd:do fix the login button`
+Usage: `/gsd:do refactor the auth system`
+Usage: `/gsd:do I want to start a new milestone`
+
 ### Quick Mode
 
 **`/gsd:quick [--full] [--discuss] [--research]`**
@@ -241,6 +255,21 @@ Systematic debugging with persistent state across context resets.
 Usage: `/gsd:debug "login button doesn't work"`
 Usage: `/gsd:debug` (resume active session)
 
+### Quick Notes
+
+**`/gsd:note <text>`**
+Zero-friction idea capture — one command, instant save, no questions.
+
+- Saves timestamped note to `.planning/notes/` (or `C:/projects/GSD-Antigravity/.antigravity/notes/` globally)
+- Three subcommands: append (default), list, promote
+- Promote converts a note into a structured todo
+- Works without a project (falls back to global scope)
+
+Usage: `/gsd:note refactor the hook system`
+Usage: `/gsd:note list`
+Usage: `/gsd:note promote 3`
+Usage: `/gsd:note --global cross-project idea`
+
 ### Todo Management
 
 **`/gsd:add-todo [description]`**

package/.agent/skills/gsd/references/workflows/note.md

@@ -0,0 +1,156 @@
+<purpose>
+Zero-friction idea capture. One Write call, one confirmation line. No questions, no prompts.
+Runs inline — no Task, no AskUserQuestion, no Bash.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="storage_format">
+**Note storage format.**
+
+Notes are stored as individual markdown files:
+
+- **Project scope**: `.planning/notes/{YYYY-MM-DD}-{slug}.md` — used when `.planning/` exists in cwd
+- **Global scope**: `C:/projects/GSD-Antigravity/.antigravity/notes/{YYYY-MM-DD}-{slug}.md` — fallback when no `.planning/`, or when `--global` flag is present
+
+Each note file:
+
+```markdown
+---
+date: "YYYY-MM-DD HH:mm"
+promoted: false
+---
+
+{note text verbatim}
+```
+
+**`--global` flag**: Strip `--global` from anywhere in `$ARGUMENTS` before parsing. When present, force global scope regardless of whether `.planning/` exists.
+
+**Important**: Do NOT create `.planning/` if it doesn't exist. Fall back to global scope silently.
+</step>
+
+<step name="parse_subcommand">
+**Parse subcommand from $ARGUMENTS (after stripping --global).**
+
+| Condition | Subcommand |
+|-----------|------------|
+| Arguments are exactly `list` (case-insensitive) | **list** |
+| Arguments are exactly `promote <N>` where N is a number | **promote** |
+| Arguments are empty (no text at all) | **list** |
+| Anything else | **append** (the text IS the note) |
+
+**Critical**: `list` is only a subcommand when it's the ENTIRE argument. `/gsd:note list of groceries` saves a note with text "list of groceries". Same for `promote` — only a subcommand when followed by exactly one number.
+</step>
+
+<step name="append">
+**Subcommand: append — create a timestamped note file.**
+
+1. Determine scope (project or global) per storage format above
+2. Ensure the notes directory exists (`.planning/notes/` or `C:/projects/GSD-Antigravity/.antigravity/notes/`)
+3. Generate slug: first ~4 meaningful words of the note text, lowercase, hyphen-separated (strip articles/prepositions from the start)
+4. Generate filename: `{YYYY-MM-DD}-{slug}.md`
+   - If a file with that name already exists, append `-2`, `-3`, etc.
+5. Write the file with frontmatter and note text (see storage format)
+6. Confirm with exactly one line: `Noted ({scope}): {note text}`
+   - Where `{scope}` is "project" or "global"
+
+**Constraints:**
+- **Never modify the note text** — capture verbatim, including typos
+- **Never ask questions** — just write and confirm
+- **Timestamp format**: Use local time, `YYYY-MM-DD HH:mm` (24-hour, no seconds)
+</step>
+
+<step name="list">
+**Subcommand: list — show notes from both scopes.**
+
+1. Glob `.planning/notes/*.md` (if directory exists) — project notes
+2. Glob `C:/projects/GSD-Antigravity/.antigravity/notes/*.md` (if directory exists) — global notes
+3. For each file, read frontmatter to get `date` and `promoted` status
+4. Exclude files where `promoted: true` from active counts (but still show them, dimmed)
+5. Sort by date, number all active entries sequentially starting at 1
+6. If total active entries > 20, show only the last 10 with a note about how many were omitted
+
+**Display format:**
+
+```
+Notes:
+
+Project (.planning/notes/):
+  1. [2026-02-08 14:32] refactor the hook system to support async validators
+  2. [promoted] [2026-02-08 14:40] add rate limiting to the API endpoints
+  3. [2026-02-08 15:10] consider adding a --dry-run flag to build
+
+Global (C:/projects/GSD-Antigravity/.antigravity/notes/):
+  4. [2026-02-08 10:00] cross-project idea about shared config
+
+{count} active note(s). Use `/gsd:note promote <N>` to convert to a todo.
+```
+
+If a scope has no directory or no entries, show: `(no notes)`
+</step>
+
+<step name="promote">
+**Subcommand: promote — convert a note into a todo.**
+
+1. Run the **list** logic to build the numbered index (both scopes)
+2. Find entry N from the numbered list
+3. If N is invalid or refers to an already-promoted note, tell the user and stop
+4. **Requires `.planning/` directory** — if it doesn't exist, warn: "Todos require a GSD project. Run `/gsd:new-project` to initialize one."
+5. Ensure `.planning/todos/pending/` directory exists
+6. Generate todo ID: `{NNN}-{slug}` where NNN is the next sequential number (scan both `.planning/todos/pending/` and `.planning/todos/done/` for the highest existing number, increment by 1, zero-pad to 3 digits) and slug is the first ~4 meaningful words of the note text
+7. Extract the note text from the source file (body after frontmatter)
+8. Create `.planning/todos/pending/{id}.md`:
+
+```yaml
+---
+title: "{note text}"
+status: pending
+priority: P2
+source: "promoted from /gsd:note"
+created: {YYYY-MM-DD}
+theme: general
+---
+
+## Goal
+
+{note text}
+
+## Context
+
+Promoted from quick note captured on {original date}.
+
+## Acceptance Criteria
+
+- [ ] {primary criterion derived from note text}
+```
+
+9. Mark the source note file as promoted: update its frontmatter to `promoted: true`
+10. Confirm: `Promoted note {N} to todo {id}: {note text}`
+</step>
+
+</process>
+
+<edge_cases>
+1. **"list" as note text**: `/gsd:note list of things` saves note "list of things" (subcommand only when `list` is the entire arg)
+2. **No `.planning/`**: Falls back to global `C:/projects/GSD-Antigravity/.antigravity/notes/` — works in any directory
+3. **Promote without project**: Warns that todos require `.planning/`, suggests `/gsd:new-project`
+4. **Large files**: `list` shows last 10 when >20 active entries
+5. **Duplicate slugs**: Append `-2`, `-3` etc. to filename if slug already used on same date
+6. **`--global` position**: Stripped from anywhere — `--global my idea` and `my idea --global` both save "my idea" globally
+7. **Promote already-promoted**: Tell user "Note {N} is already promoted" and stop
+8. **Empty note text after stripping flags**: Treat as `list` subcommand
+</edge_cases>
+
+<success_criteria>
+- [ ] Append: Note file written with correct frontmatter and verbatim text
+- [ ] Append: No questions asked — instant capture
+- [ ] List: Both scopes shown with sequential numbering
+- [ ] List: Promoted notes shown but dimmed
+- [ ] Promote: Todo created with correct format
+- [ ] Promote: Source note marked as promoted
+- [ ] Global fallback: Works when no `.planning/` exists
+</success_criteria>

package/.agent/skills/gsd/references/workflows/plan-phase.md

@@ -174,12 +174,33 @@ If "Run discuss-phase first": Display `/gsd:discuss-phase {X}` and exit workflow
 
 ## 5. Handle Research
 
-**Skip if:** `--gaps` flag, `--skip-research` flag, or `research_enabled` is false (from init) without `--research` override.
+**Skip if:** `--gaps` flag or `--skip-research` flag.
 
 **If `has_research` is true (from init) AND no `--research` flag:** Use existing, skip to step 6.
 
 **If RESEARCH.md missing OR `--research` flag:**
 
+**If no explicit flag (`--research` or `--skip-research`) and not `--auto`:**
+Ask the user whether to research, with a contextual recommendation based on the phase:
+
+```
+AskUserQuestion([
+  {
+    question: "Research before planning Phase {X}: {phase_name}?",
+    header: "Research",
+    multiSelect: false,
+    options: [
+      { label: "Research first (Recommended)", description: "Investigate domain, patterns, and dependencies before planning. Best for new features, unfamiliar integrations, or architectural changes." },
+      { label: "Skip research", description: "Plan directly from context and requirements. Best for bug fixes, simple refactors, or well-understood tasks." }
+    ]
+  }
+])
+```
+
+If user selects "Skip research": skip to step 6.
+
+**If `--auto` and `research_enabled` is false:** Skip research silently (preserves automated behavior).
+
 Display banner:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

package/.agent/skills/gsd/references/workflows/settings.md

@@ -47,7 +47,7 @@ AskUserQuestion([
     multiSelect: false,
     options: [
       { label: "Quality", description: "Opus everywhere except verification (highest cost)" },
-      { label: "Balanced (Recommended)", description: "Opus for planning, Sonnet for execution/verification" },
+      { label: "Balanced (Recommended)", description: "Opus for planning, Sonnet for research/execution/verification" },
       { label: "Budget", description: "Sonnet for writing, Haiku for research/verification (lowest cost)" },
       { label: "Inherit", description: "Use current session model for all agents (best for OpenCode /model)" }
     ]
@@ -126,6 +126,15 @@ AskUserQuestion([
       { label: "Per Phase", description: "Create branch for each phase (gsd/phase-{N}-{name})" },
       { label: "Per Milestone", description: "Create branch for entire milestone (gsd/{version}-{name})" }
     ]
+  },
+  {
+    question: "Enable context window warnings? (injects advisory messages when context is getting full)",
+    header: "Ctx Warnings",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "Warn when context usage exceeds 65%. Helps avoid losing work." },
+      { label: "No", description: "Disable warnings. Allows Antigravity to reach auto-compact naturally. Good for long unattended runs." }
+    ]
   }
 ])
 ```
@@ -149,6 +158,9 @@ Merge new settings into existing config.json:
   },
   "git": {
     "branching_strategy": "none" | "phase" | "milestone"
+  },
+  "hooks": {
+    "context_warnings": true/false
   }
 }
 ```
@@ -220,6 +232,7 @@ Display:
 | UI Phase             | {On/Off} |
 | UI Safety Gate       | {On/Off} |
 | Git Branching        | {None/Per Phase/Per Milestone} |
+| Context Warnings     | {On/Off} |
 | Saved as Defaults    | {Yes/No} |
 
 These settings apply to future /gsd:plan-phase and /gsd:execute-phase runs.

package/.agent/skills/gsd/references/workflows/stats.md

@@ -16,7 +16,7 @@ STATS=$(node "$GSD_TOOLS" stats json)
 if [[ "$STATS" == @file:* ]]; then STATS=$(cat "${STATS#@file:}"); fi
 ```
 
-Extract fields from JSON: `milestone_version`, `milestone_name`, `phases`, `total_plans`, `total_summaries`, `percent`, `requirements_total`, `requirements_complete`, `git_commits`, `git_first_commit_date`, `last_activity`.
+Extract fields from JSON: `milestone_version`, `milestone_name`, `phases`, `phases_completed`, `phases_total`, `total_plans`, `total_summaries`, `percent`, `plan_percent`, `requirements_total`, `requirements_complete`, `git_commits`, `git_first_commit_date`, `last_activity`.
 </step>
 
 <step name="present_stats">
@@ -26,7 +26,10 @@ Present to the user with this format:
 # 📊 Project Statistics — {milestone_version} {milestone_name}
 
 ## Progress
-[████████░░] X/Y plans (Z%)
+[████████░░] X/Y phases (Z%)
+
+## Plans
+X/Y plans complete (Z%)
 
 ## Phases
 | Phase | Name | Plans | Completed | Status |

package/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.25.1] - 2026-03-16
+
+### Added
+- **GSD Sync 1.25.1**: Full synchronization with the latest GSD core, featuring optimized model profiles and enhanced state consistency.
+- **Selective Inclusion Engine**: Injected `parseIncludeFlag`, `applyIncludes`, and `buildPhaseBase` into the core CLI, enabling granular context management via the `--include` flag.
+- **Artifact Discovery**: Integrated `discoverPhaseArtifacts` for automated detection of hierarchical project files, improving context gathering automation.
+
+### Changed
+- **Skill Optimization**: Applied advanced refactoring via `gsd-converter`, reducing script overhead through 2-space indentation and condensed headers.
+- **Improved Portability**: Enhanced regex-based path mapping for even more robust environment isolation in Antigravity.
+
 ## [1.24.0] - 2026-03-15
 
 ### Added

package/README.md

@@ -3,8 +3,8 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Antigravity Compatible](https://img.shields.io/badge/Antigravity-Compatible-purple.svg?logo=google&logoColor=white)](https://github.com/google-deepmind/antigravity)
 [![NPM Version](https://img.shields.io/npm/v/gsd-antigravity-kit.svg?logo=npm)](https://www.npmjs.com/package/gsd-antigravity-kit)
-[![Release Version](https://img.shields.io/badge/Release-v1.24.0-blue?style=flat-square)](https://github.com/dturkuler/GSD-Antigravity/releases/latest)
-[![GSD Version](https://img.shields.io/badge/GSD-v1.24.0-orange?style=flat-square)](https://github.com/glittercowboy/get-shit-done)
+[![Release Version](https://img.shields.io/badge/Release-v1.25.1-blue?style=flat-square)](https://github.com/dturkuler/GSD-Antigravity/releases/latest)
+[![GSD Version](https://img.shields.io/badge/GSD-v1.25.1-orange?style=flat-square)](https://github.com/glittercowboy/get-shit-done)
 
 **GSD-Antigravity Kit** is the official bootstrapping and management utility for the [Get Shit Done (GSD)](https://github.com/glittercowboy/get-shit-done) protocol within the Antigravity AI framework. It serves as a high-performance **Installer** and **Skill Manager** that provision, optimizes, and maintains GSD skills in your AG environment.
 

package/docs/DEV_KNOWLEDGEBASE.md

@@ -6,6 +6,17 @@ This document tracks technical Root Cause Analysis (RCA) for bug fixes in the **
 
 ## Technical Analysis History
 
+### v1.25.1 (2026-03-16)
+*   **Context:** `gsd-tools.cjs` (Selective Inclusion and Artifact Discovery)
+*   **Issue:** Lack of standardized context slicing and automated artifact traversal in the core GSD engine, leading to inconsistent context gathering across different subagents.
+*   **Root Cause Analysis:** 
+    - The core engine was missing a unified way to handle partial context loading, forcing agents to either load the entire state or manually parse it.
+    - Artifact discovery relied on static paths which didn't always account for deeply nested or dynamically named phase directories.
+*   **How it was fixed:**
+    - **Smart Inclusions**: Injected `parseIncludeFlag`, `applyIncludes`, and `buildPhaseBase` into `gsd-tools.cjs`. This allows the `--include` flag to dynamically filter state/roadmap data, significantly reducing token overhead for long-running workflows.
+    - **Automated Discovery**: Integrated `discoverPhaseArtifacts()` to automatically traverse the `.planning/` hierarchy, ensuring that all relevant requirements, plans, and implementation notes are available to the agent without manual specification.
+    - **Model Profile Injection**: Injected a centralized `MODEL_PROFILES` object to ensure consistent model selection (e.g., using better models for planning and cheaper ones for simple tasks) across the entire GSD toolchain.
+
 ### v1.24.0 (2026-03-15)
 *   **Context:** `gsd-tools.cjs` (Engine Modernization)
 *   **Issue:** Technical debt in the core engine; increasing complexity of the monolithic `gsd-tools.cjs` script; and lack of granular control over phase/milestone state transitions.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "gsd-antigravity-kit",
-    "version": "1.24.0",
+    "version": "1.25.1",
     "description": "Installer for GSD-Antigravity skills",
     "main": "index.js",
     "bin": {