diff --git a/get-shit-done/bin/gsd-tools.cjs b/get-shit-done/bin/gsd-tools.cjs index 51e340cea..6988065bd 100755 --- a/get-shit-done/bin/gsd-tools.cjs +++ b/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; } diff --git a/get-shit-done/bin/lib/core.cjs b/get-shit-done/bin/lib/core.cjs index b40db3d86..49652445f 100644 --- a/get-shit-done/bin/lib/core.cjs +++ b/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 /get-shit-done/bin/gsd-tools.cjs, + * so agents/ is at /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, }; diff --git a/get-shit-done/bin/lib/init.cjs b/get-shit-done/bin/lib/init.cjs index fd984a64a..a2ec48553 100644 --- a/get-shit-done/bin/lib/init.cjs +++ b/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; } diff --git a/get-shit-done/bin/lib/verify.cjs b/get-shit-done/bin/lib/verify.cjs index c0610f4c8..b11a5c3a1 100644 --- a/get-shit-done/bin/lib/verify.cjs +++ b/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, }; diff --git a/tests/agent-install-validation.test.cjs b/tests/agent-install-validation.test.cjs new file mode 100644 index 000000000..c64c7f701 --- /dev/null +++ b/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 /get-shit-done/bin/gsd-tools.cjs, + * so the agents dir is at /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'); + }); +});