fix: detect missing GSD agents and warn when subagent_type falls back to general-purpose

When GSD agents are not installed in .claude/agents/, Task(subagent_type="gsd-*")
silently falls back to general-purpose, losing specialized instructions, structured
outputs, and verification protocols.

What changed:
- Added checkAgentsInstalled() to core.cjs that validates all expected agents exist on disk
- All init commands now include agents_installed and missing_agents in their output
- Health check (validate health) reports W010 when agents are missing or incomplete
- New validate agents subcommand for standalone agent installation diagnostics

Fixes #1371

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

get-shit-done/bin/gsd-tools.cjs

@@ -58,6 +58,7 @@
  * Validation:
  *   validate consistency               Check phase numbering, disk/roadmap sync
  *   validate health [--repair]         Check .planning/ integrity, optionally repair
+ *   validate agents                    Check GSD agent installation status
  *
  * Progress:
  *   progress [json|table|bar]          Render progress in various formats
@@ -643,8 +644,10 @@ async function runCommand(command, args, cwd, raw) {
       } else if (subcommand === 'health') {
         const repairFlag = args.includes('--repair');
         verify.cmdValidateHealth(cwd, { repair: repairFlag }, raw);
+      } else if (subcommand === 'agents') {
+        verify.cmdValidateAgents(cwd, raw);
       } else {
-        error('Unknown validate subcommand. Available: consistency, health');
+        error('Unknown validate subcommand. Available: consistency, health, agents');
       }
       break;
     }

get-shit-done/bin/lib/core.cjs

@@ -931,6 +931,58 @@ function getRoadmapPhaseInternal(cwd, phaseNum) {
   }
 }
 
+// ─── Agent installation validation (#1371) ───────────────────────────────────
+
+/**
+ * Resolve the agents directory from the GSD install location.
+ * gsd-tools.cjs lives at <configDir>/get-shit-done/bin/gsd-tools.cjs,
+ * so agents/ is at <configDir>/agents/.
+ *
+ * @returns {string} Absolute path to the agents directory
+ */
+function getAgentsDir() {
+  // __dirname is get-shit-done/bin/lib/ → go up 3 levels to configDir
+  return path.join(__dirname, '..', '..', '..', 'agents');
+}
+
+/**
+ * Check which GSD agents are installed on disk.
+ * Returns an object with installation status and details.
+ *
+ * @returns {{ agents_installed: boolean, missing_agents: string[], installed_agents: string[], agents_dir: string }}
+ */
+function checkAgentsInstalled() {
+  const agentsDir = getAgentsDir();
+  const expectedAgents = Object.keys(MODEL_PROFILES);
+  const installed = [];
+  const missing = [];
+
+  if (!fs.existsSync(agentsDir)) {
+    return {
+      agents_installed: false,
+      missing_agents: expectedAgents,
+      installed_agents: [],
+      agents_dir: agentsDir,
+    };
+  }
+
+  for (const agent of expectedAgents) {
+    const agentFile = path.join(agentsDir, `${agent}.md`);
+    if (fs.existsSync(agentFile)) {
+      installed.push(agent);
+    } else {
+      missing.push(agent);
+    }
+  }
+
+  return {
+    agents_installed: installed.length > 0 && missing.length === 0,
+    missing_agents: missing,
+    installed_agents: installed,
+    agents_dir: agentsDir,
+  };
+}
+
 // ─── Model alias resolution ───────────────────────────────────────────────────
 
 /**
@@ -1172,4 +1224,6 @@ module.exports = {
   filterSummaryFiles,
   getPhaseFileStats,
   readSubdirectories,
+  getAgentsDir,
+  checkAgentsInstalled,
 };

get-shit-done/bin/lib/init.cjs

@@ -5,7 +5,7 @@
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
-const { loadConfig, resolveModelInternal, findPhaseInternal, getRoadmapPhaseInternal, pathExistsInternal, generateSlugInternal, getMilestoneInfo, getMilestonePhaseFilter, stripShippedMilestones, extractCurrentMilestone, normalizePhaseName, planningPaths, planningDir, planningRoot, toPosixPath, output, error } = require('./core.cjs');
+const { loadConfig, resolveModelInternal, findPhaseInternal, getRoadmapPhaseInternal, pathExistsInternal, generateSlugInternal, getMilestoneInfo, getMilestonePhaseFilter, stripShippedMilestones, extractCurrentMilestone, normalizePhaseName, planningPaths, planningDir, planningRoot, toPosixPath, output, error, checkAgentsInstalled } = require('./core.cjs');
 
 function getLatestCompletedMilestone(cwd) {
   const milestonesPath = path.join(planningRoot(cwd), 'MILESTONES.md');
@@ -31,6 +31,12 @@ function getLatestCompletedMilestone(cwd) {
  */
 function withProjectRoot(cwd, result) {
   result.project_root = cwd;
+  // Inject agent installation status into all init outputs (#1371).
+  // Workflows that spawn named subagents use this to detect when agents
+  // are missing and would silently fall back to general-purpose.
+  const agentStatus = checkAgentsInstalled();
+  result.agents_installed = agentStatus.agents_installed;
+  result.missing_agents = agentStatus.missing_agents;
   return result;
 }
 

get-shit-done/bin/lib/verify.cjs

@@ -5,7 +5,7 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const { safeReadFile, loadConfig, normalizePhaseName, execGit, findPhaseInternal, getMilestoneInfo, stripShippedMilestones, extractCurrentMilestone, planningDir, planningRoot, output, error } = require('./core.cjs');
+const { safeReadFile, loadConfig, normalizePhaseName, execGit, findPhaseInternal, getMilestoneInfo, stripShippedMilestones, extractCurrentMilestone, planningDir, planningRoot, output, error, checkAgentsInstalled } = require('./core.cjs');
 const { extractFrontmatter, parseMustHavesBlock } = require('./frontmatter.cjs');
 const { writeStateMd } = require('./state.cjs');
 
@@ -699,6 +699,24 @@ function cmdValidateHealth(cwd, options, raw) {
     }
   } catch { /* intentionally empty */ }
 
+  // ─── Check 7c: Agent installation (#1371) ──────────────────────────────────
+  // Verify GSD agents are installed. Missing agents cause Task(subagent_type=...)
+  // to silently fall back to general-purpose, losing specialized instructions.
+  try {
+    const agentStatus = checkAgentsInstalled();
+    if (!agentStatus.agents_installed) {
+      if (agentStatus.installed_agents.length === 0) {
+        addIssue('warning', 'W010',
+          `No GSD agents found in ${agentStatus.agents_dir} — Task(subagent_type="gsd-*") will fall back to general-purpose`,
+          'Run the GSD installer: npx get-shit-done-cc@latest');
+      } else {
+        addIssue('warning', 'W010',
+          `Missing ${agentStatus.missing_agents.length} GSD agents: ${agentStatus.missing_agents.join(', ')} — affected workflows will fall back to general-purpose`,
+          'Run the GSD installer: npx get-shit-done-cc@latest');
+      }
+    }
+  } catch { /* intentionally empty — agent check is non-blocking */ }
+
   // ─── Check 8: Run existing consistency checks ─────────────────────────────
   // Inline subset of cmdValidateConsistency
   if (fs.existsSync(roadmapPath)) {
@@ -838,6 +856,24 @@ function cmdValidateHealth(cwd, options, raw) {
   }, raw);
 }
 
+/**
+ * Validate agent installation status (#1371).
+ * Returns detailed information about which agents are installed and which are missing.
+ */
+function cmdValidateAgents(cwd, raw) {
+  const { MODEL_PROFILES } = require('./model-profiles.cjs');
+  const agentStatus = checkAgentsInstalled();
+  const expected = Object.keys(MODEL_PROFILES);
+
+  output({
+    agents_dir: agentStatus.agents_dir,
+    agents_found: agentStatus.agents_installed,
+    installed: agentStatus.installed_agents,
+    missing: agentStatus.missing_agents,
+    expected,
+  }, raw);
+}
+
 module.exports = {
   cmdVerifySummary,
   cmdVerifyPlanStructure,
@@ -848,4 +884,5 @@ module.exports = {
   cmdVerifyKeyLinks,
   cmdValidateConsistency,
   cmdValidateHealth,
+  cmdValidateAgents,
 };

tests/agent-install-validation.test.cjs

@@ -0,0 +1,191 @@
+/**
+ * GSD Agent Installation Validation Tests (#1371)
+ *
+ * Validates that GSD detects missing or incomplete agent installations and
+ * surfaces warnings through init commands and health checks. When agents are
+ * not installed, Task(subagent_type="gsd-*") silently falls back to
+ * general-purpose, losing specialized instructions.
+ */
+
+const { test, describe, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const path = require('path');
+const { runGsdTools, createTempProject, cleanup } = require('./helpers.cjs');
+
+const AGENTS_DIR_NAME = 'agents';
+const MODEL_PROFILES = require('../get-shit-done/bin/lib/model-profiles.cjs').MODEL_PROFILES;
+const EXPECTED_AGENTS = Object.keys(MODEL_PROFILES);
+
+/**
+ * Create a fake GSD install directory structure that mirrors what the installer
+ * produces. gsd-tools.cjs lives at <configDir>/get-shit-done/bin/gsd-tools.cjs,
+ * so the agents dir is at <configDir>/agents/.
+ *
+ * We use --cwd to point at the project, and GSD_INSTALL_DIR env to override
+ * the agents directory location for testing.
+ */
+function createAgentsDir(configDir, agentNames = []) {
+  const agentsDir = path.join(configDir, AGENTS_DIR_NAME);
+  fs.mkdirSync(agentsDir, { recursive: true });
+  for (const name of agentNames) {
+    fs.writeFileSync(
+      path.join(agentsDir, `${name}.md`),
+      `---\nname: ${name}\ndescription: Test agent\ntools: Read, Bash\ncolor: cyan\n---\nAgent content.\n`
+    );
+  }
+  return agentsDir;
+}
+
+// ─── Init command agent validation ──────────────────────────────────────────
+
+describe('init commands: agents_installed field (#1371)', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = createTempProject();
+  });
+
+  afterEach(() => {
+    cleanup(tmpDir);
+  });
+
+  test('init execute-phase includes agents_installed=true when agents exist', () => {
+    // Create phase dir for init
+    const phaseDir = path.join(tmpDir, '.planning', 'phases', '01-setup');
+    fs.mkdirSync(phaseDir, { recursive: true });
+
+    // Create agents dir as sibling of get-shit-done/ (the installed layout)
+    // gsd-tools.cjs resolves agents from GSD_INSTALL_DIR or __dirname/../../agents
+    const gsdInstallDir = path.resolve(__dirname, '..', 'get-shit-done', 'bin');
+    const configDir = path.resolve(gsdInstallDir, '..', '..');
+    const agentsDir = path.join(configDir, 'agents');
+
+    // Agents already exist in the repo root /agents/ dir which is sibling to get-shit-done/
+    const result = runGsdTools('init execute-phase 1 --raw', tmpDir);
+    assert.ok(result.success, `Command failed: ${result.error}`);
+
+    const output = JSON.parse(result.output);
+    assert.strictEqual(typeof output.agents_installed, 'boolean',
+      'init execute-phase must include agents_installed field');
+    // The repo has agents/ dir with all gsd-*.md files, so this should be true
+    assert.strictEqual(output.agents_installed, true,
+      'agents_installed should be true when agents directory has gsd-*.md files');
+  });
+
+  test('init plan-phase includes agents_installed=true when agents exist', () => {
+    const phaseDir = path.join(tmpDir, '.planning', 'phases', '01-setup');
+    fs.mkdirSync(phaseDir, { recursive: true });
+
+    const result = runGsdTools('init plan-phase 1 --raw', tmpDir);
+    assert.ok(result.success, `Command failed: ${result.error}`);
+
+    const output = JSON.parse(result.output);
+    assert.strictEqual(typeof output.agents_installed, 'boolean',
+      'init plan-phase must include agents_installed field');
+    assert.strictEqual(output.agents_installed, true);
+  });
+
+  test('init execute-phase includes missing_agents list when agents are missing', () => {
+    const phaseDir = path.join(tmpDir, '.planning', 'phases', '01-setup');
+    fs.mkdirSync(phaseDir, { recursive: true });
+
+    const result = runGsdTools('init execute-phase 1 --raw', tmpDir);
+    assert.ok(result.success, `Command failed: ${result.error}`);
+
+    const output = JSON.parse(result.output);
+    assert.ok(Array.isArray(output.missing_agents),
+      'init execute-phase must include missing_agents array');
+  });
+
+  test('init quick includes agents_installed field', () => {
+    const result = runGsdTools(['init', 'quick', 'test description', '--raw'], tmpDir);
+    assert.ok(result.success, `Command failed: ${result.error}`);
+
+    const output = JSON.parse(result.output);
+    assert.strictEqual(typeof output.agents_installed, 'boolean',
+      'init quick must include agents_installed field');
+  });
+});
+
+// ─── Health check: agent installation ───────────────────────────────────────
+
+describe('validate health: agent installation check W010 (#1371)', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = createTempProject();
+    // Write minimal project files so health check doesn't fail on E001-E005
+    fs.writeFileSync(
+      path.join(tmpDir, '.planning', 'PROJECT.md'),
+      '# Project\n\n## What This Is\nTest\n\n## Core Value\nTest\n\n## Requirements\nTest\n'
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, '.planning', 'ROADMAP.md'),
+      '# Roadmap\n\n### Phase 1: Setup\n'
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, '.planning', 'STATE.md'),
+      '# Session State\n\n## Current Position\n\nPhase: 1\n'
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, '.planning', 'config.json'),
+      JSON.stringify({
+        model_profile: 'balanced',
+        commit_docs: true,
+        workflow: { nyquist_validation: true },
+      }, null, 2)
+    );
+    fs.mkdirSync(path.join(tmpDir, '.planning', 'phases', '01-setup'), { recursive: true });
+  });
+
+  afterEach(() => {
+    cleanup(tmpDir);
+  });
+
+  test('health check reports healthy when agents are installed (repo layout)', () => {
+    // In the repo, agents/ exists as a sibling of get-shit-done/, so the
+    // health check should find them via the gsd-tools.cjs path resolution
+    const result = runGsdTools('validate health --raw', tmpDir);
+    assert.ok(result.success, `Command failed: ${result.error}`);
+
+    const output = JSON.parse(result.output);
+    // Should not have W010 warning about missing agents
+    const w010 = (output.warnings || []).find(w => w.code === 'W010');
+    assert.ok(!w010, 'Should not warn about missing agents when agents/ dir exists with files');
+  });
+});
+
+// ─── validate agents subcommand ─────────────────────────────────────────────
+
+describe('validate agents subcommand (#1371)', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = createTempProject();
+  });
+
+  afterEach(() => {
+    cleanup(tmpDir);
+  });
+
+  test('validate agents returns status with agent list', () => {
+    const result = runGsdTools('validate agents --raw', tmpDir);
+    assert.ok(result.success, `Command failed: ${result.error}`);
+
+    const output = JSON.parse(result.output);
+    assert.ok('agents_dir' in output, 'Must include agents_dir path');
+    assert.ok('installed' in output, 'Must include installed array');
+    assert.ok('missing' in output, 'Must include missing array');
+    assert.ok('agents_found' in output, 'Must include agents_found boolean');
+  });
+
+  test('validate agents lists all expected agent types', () => {
+    const result = runGsdTools('validate agents --raw', tmpDir);
+    assert.ok(result.success, `Command failed: ${result.error}`);
+
+    const output = JSON.parse(result.output);
+    // The expected agents come from MODEL_PROFILES keys
+    assert.ok(output.expected.length > 0, 'Must have expected agents');
+  });
+});