fix(#2419): warn when agents_installed is false in new-project and new-milestone workflows

Parse agents_installed from init JSON in both workflows and surface a
clear warning — including the "agent type not found" error message —
before attempting subagent spawning when agents are not globally installed.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

get-shit-done/workflows/new-milestone.md

@@ -208,7 +208,25 @@ AGENT_SKILLS_SYNTHESIZER=$(gsd-sdk query agent-skills gsd-synthesizer 2>/dev/nul
 AGENT_SKILLS_ROADMAPPER=$(gsd-sdk query agent-skills gsd-roadmapper 2>/dev/null)
 ```
 
-Extract from init JSON: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `research_enabled`, `current_milestone`, `project_exists`, `roadmap_exists`, `latest_completed_milestone`, `phase_dir_count`, `phase_archive_path`.
+Extract from init JSON: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `research_enabled`, `current_milestone`, `project_exists`, `roadmap_exists`, `latest_completed_milestone`, `phase_dir_count`, `phase_archive_path`, `agents_installed`.
+
+**If `agents_installed` is `false`:** Warn the user before proceeding:
+
+```
+⚠️  Agents are not installed — subagent spawning will fail with "agent type not found".
+Run the GSD installer to install agents globally:
+  npx get-shit-done-cc --claude --global
+Without agents installed, research and roadmap steps cannot run.
+```
+
+Ask via AskUserQuestion:
+- header: "Missing Agents"
+- question: "GSD agents are not installed. Subagent spawning will fail. How do you want to proceed?"
+- options:
+  - "Continue anyway" — I will install agents before research/roadmap steps
+  - "Cancel" — Let me install agents first, then return
+
+**If "Cancel":** Exit. **If "Continue anyway":** Proceed with the workflow but note that spawning steps may fail until agents are installed.
 
 ## 7.5 Reset-phase safety (only when `--reset-phase-numbers`)
 

get-shit-done/workflows/new-project.md

@@ -64,7 +64,25 @@ AGENT_SKILLS_SYNTHESIZER=$(gsd-sdk query agent-skills gsd-synthesizer 2>/dev/nul
 AGENT_SKILLS_ROADMAPPER=$(gsd-sdk query agent-skills gsd-roadmapper 2>/dev/null)
 ```
 
-Parse JSON for: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `project_exists`, `has_codebase_map`, `planning_exists`, `has_existing_code`, `has_package_file`, `is_brownfield`, `needs_codebase_map`, `has_git`, `project_path`.
+Parse JSON for: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `project_exists`, `has_codebase_map`, `planning_exists`, `has_existing_code`, `has_package_file`, `is_brownfield`, `needs_codebase_map`, `has_git`, `project_path`, `agents_installed`.
+
+**If `agents_installed` is `false`:** Warn the user before proceeding:
+
+```
+⚠️  Agents are not installed — subagent spawning will fail with "agent type not found".
+Run the GSD installer to install agents globally:
+  npx get-shit-done-cc --claude --global
+Without agents installed, research and roadmap steps cannot run.
+```
+
+Ask via AskUserQuestion:
+- header: "Missing Agents"
+- question: "GSD agents are not installed. Subagent spawning will fail. How do you want to proceed?"
+- options:
+  - "Continue anyway" — I will install agents before research/roadmap steps
+  - "Cancel" — Let me install agents first, then return
+
+**If "Cancel":** Exit. **If "Continue anyway":** Proceed with the workflow but note that spawning steps may fail until agents are installed.
 
 **Detect runtime and set instruction file name:**
 

tests/bug-2419-project-researcher-agent.test.cjs

@@ -0,0 +1,96 @@
+/**
+ * Bug #2419: gsd-project-researcher agent type not found
+ *
+ * When gsd-new-project spawns gsd-project-researcher subagents, it fails with
+ * "agent type not found" if the user has a local-only install (agents in
+ * .claude/agents/ of a different project, not the global ~/.claude/agents/).
+ *
+ * Fix: new-project.md and new-milestone.md must parse agents_installed from
+ * the init JSON and warn the user (rather than silently failing) when agents
+ * are missing.
+ */
+
+const { describe, test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+
+const NEW_PROJECT_PATH = path.join(__dirname, '..', 'get-shit-done', 'workflows', 'new-project.md');
+const NEW_MILESTONE_PATH = path.join(__dirname, '..', 'get-shit-done', 'workflows', 'new-milestone.md');
+const AGENTS_DIR = path.join(__dirname, '..', 'agents');
+
+describe('gsd-project-researcher agent registration (#2419)', () => {
+  test('gsd-project-researcher.md exists in agents source dir', () => {
+    const agentFile = path.join(AGENTS_DIR, 'gsd-project-researcher.md');
+    assert.ok(
+      fs.existsSync(agentFile),
+      'agents/gsd-project-researcher.md must exist in the source agents directory'
+    );
+  });
+
+  test('gsd-project-researcher.md has correct name in frontmatter', () => {
+    const content = fs.readFileSync(path.join(AGENTS_DIR, 'gsd-project-researcher.md'), 'utf-8');
+    assert.ok(
+      content.includes('name: gsd-project-researcher'),
+      'agents/gsd-project-researcher.md must have name: gsd-project-researcher in frontmatter'
+    );
+  });
+
+  test('new-project.md parses agents_installed from init JSON', () => {
+    const content = fs.readFileSync(NEW_PROJECT_PATH, 'utf-8');
+    assert.ok(
+      content.includes('agents_installed'),
+      'new-project.md must parse agents_installed from the init JSON to detect missing agents'
+    );
+  });
+
+  test('new-project.md warns user when agents_installed is false', () => {
+    const content = fs.readFileSync(NEW_PROJECT_PATH, 'utf-8');
+    assert.ok(
+      content.includes('agents_installed') && content.includes('agent type not found') ||
+      content.includes('agents_installed') && content.includes('missing') ||
+      content.includes('agents_installed') && content.includes('not installed'),
+      'new-project.md must warn the user when agents are not installed (agents_installed is false)'
+    );
+  });
+
+  test('new-milestone.md parses agents_installed from init JSON', () => {
+    const content = fs.readFileSync(NEW_MILESTONE_PATH, 'utf-8');
+    assert.ok(
+      content.includes('agents_installed'),
+      'new-milestone.md must parse agents_installed from the init JSON to detect missing agents'
+    );
+  });
+
+  test('new-milestone.md warns user when agents_installed is false', () => {
+    const content = fs.readFileSync(NEW_MILESTONE_PATH, 'utf-8');
+    assert.ok(
+      content.includes('agents_installed') && (
+        content.includes('agent type not found') ||
+        content.includes('missing') ||
+        content.includes('not installed')
+      ),
+      'new-milestone.md must warn the user when agents are not installed (agents_installed is false)'
+    );
+  });
+
+  test('new-project.md lists gsd-project-researcher in available_agent_types', () => {
+    const content = fs.readFileSync(NEW_PROJECT_PATH, 'utf-8');
+    const agentTypesMatch = content.match(/<available_agent_types>([\s\S]*?)<\/available_agent_types>/);
+    assert.ok(agentTypesMatch, 'new-project.md must have <available_agent_types> section');
+    assert.ok(
+      agentTypesMatch[1].includes('gsd-project-researcher'),
+      'new-project.md <available_agent_types> must list gsd-project-researcher'
+    );
+  });
+
+  test('new-milestone.md lists gsd-project-researcher in available_agent_types', () => {
+    const content = fs.readFileSync(NEW_MILESTONE_PATH, 'utf-8');
+    const agentTypesMatch = content.match(/<available_agent_types>([\s\S]*?)<\/available_agent_types>/);
+    assert.ok(agentTypesMatch, 'new-milestone.md must have <available_agent_types> section');
+    assert.ok(
+      agentTypesMatch[1].includes('gsd-project-researcher'),
+      'new-milestone.md <available_agent_types> must list gsd-project-researcher'
+    );
+  });
+});