fix: add <available_agent_types> to all workflows spawning named agents

PR #1139 added <available_agent_types> sections to execute-phase.md and
plan-phase.md to prevent /clear from causing silent fallback to
general-purpose. However, 14 other workflows and 2 commands that also
spawn named GSD agents were missed, leaving them vulnerable to the same
regression after /clear.

Added <available_agent_types> listing to: research-phase, quick,
audit-milestone, diagnose-issues, discuss-phase-assumptions,
execute-plan, map-codebase, new-milestone, new-project, ui-phase,
ui-review, validate-phase, verify-work (workflows) and debug,
research-phase (commands).

Added regression test that enforces every workflow/command spawning
named subagent_type must have a matching <available_agent_types>
section listing all spawned types.

Fixes #1357

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

commands/gsd/debug.md

@@ -17,6 +17,11 @@ Debug issues using scientific method with subagent isolation.
 **Why subagent:** Investigation burns context fast (reading files, forming hypotheses, testing). Fresh 200k context per investigation. Main context stays lean for user interaction.
 </objective>
 
+<available_agent_types>
+Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):
+- gsd-debugger — Diagnoses and fixes issues
+</available_agent_types>
+
 <context>
 User's issue: $ARGUMENTS
 

commands/gsd/research-phase.md

@@ -23,6 +23,11 @@ Research how to implement a phase. Spawns gsd-phase-researcher agent with phase
 **Why subagent:** Research burns context fast (WebSearch, Context7 queries, source verification). Fresh 200k context for investigation. Main context stays lean for user interaction.
 </objective>
 
+<available_agent_types>
+Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):
+- gsd-phase-researcher — Researches technical approaches for a phase
+</available_agent_types>
+
 <context>
 Phase number: $ARGUMENTS (required)
 

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

@@ -6,6 +6,11 @@ Verify milestone achieved its definition of done by aggregating phase verificati
 Read all files referenced by the invoking prompt's execution_context before starting.
 </required_reading>
 
+<available_agent_types>
+Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):
+- gsd-integration-checker — Checks cross-phase integration
+</available_agent_types>
+
 <process>
 
 ## 0. Initialize Milestone Context

get-shit-done/workflows/diagnose-issues.md

@@ -6,6 +6,11 @@ After UAT finds gaps, spawn one debug agent per gap. Each agent investigates aut
 Orchestrator stays lean: parse gaps, spawn agents, collect results, update UAT.
 </purpose>
 
+<available_agent_types>
+Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):
+- gsd-debugger — Diagnoses and fixes issues
+</available_agent_types>
+
 <paths>
 DEBUG_DIR=.planning/debug
 

get-shit-done/workflows/discuss-phase-assumptions.md

@@ -6,6 +6,11 @@ You are a thinking partner, not an interviewer. Analyze the codebase deeply, sur
 believe based on evidence, and ask the user only to correct what's wrong.
 </purpose>
 
+<available_agent_types>
+Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):
+- gsd-assumptions-analyzer — Analyzes codebase to surface implementation assumptions
+</available_agent_types>
+
 <downstream_awareness>
 **CONTEXT.md feeds into:**
 

get-shit-done/workflows/execute-plan.md

@@ -9,6 +9,11 @@ Read config.json for planning behavior settings.
 @~/.claude/get-shit-done/references/git-integration.md
 </required_reading>
 
+<available_agent_types>
+Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):
+- gsd-executor — Executes plan tasks, commits, creates SUMMARY.md
+</available_agent_types>
+
 <process>
 
 <step name="init_context" priority="first">

get-shit-done/workflows/map-codebase.md

@@ -6,6 +6,11 @@ Each agent has fresh context, explores a specific focus area, and **writes docum
 Output: .planning/codebase/ folder with 7 structured documents about the codebase state.
 </purpose>
 
+<available_agent_types>
+Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):
+- gsd-codebase-mapper — Maps project structure and dependencies
+</available_agent_types>
+
 <philosophy>
 **Why dedicated mapper agents:**
 - Fresh context per domain (no token contamination)

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

@@ -10,6 +10,13 @@ Read all files referenced by the invoking prompt's execution_context before star
 
 </required_reading>
 
+<available_agent_types>
+Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):
+- gsd-project-researcher — Researches project-level technical decisions
+- gsd-research-synthesizer — Synthesizes findings from parallel research agents
+- gsd-roadmapper — Creates phased execution roadmaps
+</available_agent_types>
+
 <process>
 
 ## 1. Load Context

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

@@ -6,6 +6,13 @@ Initialize a new project through unified flow: questioning, research (optional),
 Read all files referenced by the invoking prompt's execution_context before starting.
 </required_reading>
 
+<available_agent_types>
+Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):
+- gsd-project-researcher — Researches project-level technical decisions
+- gsd-research-synthesizer — Synthesizes findings from parallel research agents
+- gsd-roadmapper — Creates phased execution roadmaps
+</available_agent_types>
+
 <auto_mode>
 
 ## Auto Mode Detection

get-shit-done/workflows/quick.md

@@ -14,6 +14,15 @@ Flags are composable: `--discuss --research --full` gives discussion + research
 Read all files referenced by the invoking prompt's execution_context before starting.
 </required_reading>
 
+<available_agent_types>
+Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):
+- gsd-phase-researcher — Researches technical approaches for a phase
+- gsd-planner — Creates detailed plans from phase scope
+- gsd-plan-checker — Reviews plan quality before execution
+- gsd-executor — Executes plan tasks, commits, creates SUMMARY.md
+- gsd-verifier — Verifies phase completion, checks quality gates
+</available_agent_types>
+
 <process>
 **Step 1: Parse arguments and get task description**
 

get-shit-done/workflows/research-phase.md

@@ -4,6 +4,11 @@ Research how to implement a phase. Spawns gsd-phase-researcher with phase contex
 Standalone research command. For most workflows, use `/gsd:plan-phase` which integrates research automatically.
 </purpose>
 
+<available_agent_types>
+Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):
+- gsd-phase-researcher — Researches technical approaches for a phase
+</available_agent_types>
+
 <process>
 
 ## Step 0: Resolve Model Profile

get-shit-done/workflows/ui-phase.md

@@ -8,6 +8,12 @@ UI-SPEC.md locks spacing, typography, color, copywriting, and design system deci
 @~/.claude/get-shit-done/references/ui-brand.md
 </required_reading>
 
+<available_agent_types>
+Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):
+- gsd-ui-researcher — Researches UI/UX approaches
+- gsd-ui-checker — Reviews UI implementation quality
+</available_agent_types>
+
 <process>
 
 ## 1. Initialize

get-shit-done/workflows/ui-review.md

@@ -6,6 +6,11 @@ Retroactive 6-pillar visual audit of implemented frontend code. Standalone comma
 @~/.claude/get-shit-done/references/ui-brand.md
 </required_reading>
 
+<available_agent_types>
+Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):
+- gsd-ui-auditor — Audits UI against design requirements
+</available_agent_types>
+
 <process>
 
 ## 0. Initialize

get-shit-done/workflows/validate-phase.md

@@ -6,6 +6,11 @@ Audit Nyquist validation gaps for a completed phase. Generate missing tests. Upd
 @~/.claude/get-shit-done/references/ui-brand.md
 </required_reading>
 
+<available_agent_types>
+Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):
+- gsd-nyquist-auditor — Validates verification coverage
+</available_agent_types>
+
 <process>
 
 ## 0. Initialize

get-shit-done/workflows/verify-work.md

@@ -4,6 +4,12 @@ Validate built features through conversational testing with persistent state. Cr
 User tests, Claude records. One test at a time. Plain text responses.
 </purpose>
 
+<available_agent_types>
+Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):
+- gsd-planner — Creates detailed plans from phase scope
+- gsd-plan-checker — Reviews plan quality before execution
+</available_agent_types>
+
 <philosophy>
 **Show expected, ask if reality matches.**
 

tests/agent-frontmatter.test.cjs

@@ -152,6 +152,52 @@ describe('SPAWN: spawn type consistency', () => {
     );
   });
 
+  test('workflows spawning named agents have <available_agent_types> listing (#1357)', () => {
+    // After /clear, Claude Code re-reads workflow instructions but loses agent
+    // context. Without an <available_agent_types> section, the orchestrator may
+    // fall back to general-purpose, silently breaking agent capabilities.
+    // PR #1139 added this to plan-phase and execute-phase but missed all other
+    // workflows that spawn named GSD agents.
+    const dirs = [WORKFLOWS_DIR, COMMANDS_DIR];
+    for (const dir of dirs) {
+      if (!fs.existsSync(dir)) continue;
+      const files = fs.readdirSync(dir).filter(f => f.endsWith('.md'));
+      for (const file of files) {
+        const content = fs.readFileSync(path.join(dir, file), 'utf-8');
+        // Find all named subagent_type references (excluding general-purpose)
+        const matches = [...content.matchAll(/subagent_type="([^"]+)"/g)];
+        const namedAgents = matches
+          .map(m => m[1])
+          .filter(t => t !== 'general-purpose');
+
+        if (namedAgents.length === 0) continue;
+
+        // Workflow spawns named agents — must have <available_agent_types>
+        assert.ok(
+          content.includes('<available_agent_types>'),
+          `${file} spawns named agents (${[...new Set(namedAgents)].join(', ')}) ` +
+          `but has no <available_agent_types> section — after /clear, the ` +
+          `orchestrator may fall back to general-purpose (#1357)`
+        );
+
+        // Every spawned agent type must appear in the listing
+        for (const agent of new Set(namedAgents)) {
+          const agentTypesMatch = content.match(
+            /<available_agent_types>([\s\S]*?)<\/available_agent_types>/
+          );
+          assert.ok(
+            agentTypesMatch,
+            `${file} has malformed <available_agent_types> section`
+          );
+          assert.ok(
+            agentTypesMatch[1].includes(agent),
+            `${file} spawns ${agent} but does not list it in <available_agent_types>`
+          );
+        }
+      }
+    }
+  });
+
   test('execute-phase has Copilot sequential fallback in runtime_compatibility', () => {
     const content = fs.readFileSync(
       path.join(WORKFLOWS_DIR, 'execute-phase.md'), 'utf-8'