@benzotti/jedi 0.1.41 → 0.1.43

package/dist/index.js

@@ -12791,7 +12791,7 @@ var stateCommand = defineCommand({
 // package.json
 var package_default = {
   name: "@benzotti/jedi",
-  version: "0.1.41",
+  version: "0.1.43",
   description: "JDI - Context-efficient AI development framework for Claude Code",
   type: "module",
   bin: {

package/framework/agents/jdi-planner.md

@@ -4,7 +4,7 @@ description: Creates executable phase plans with task breakdown and dependency m
 category: workflow
 team: Product & Research
 model: opus
-requires_components: [TaskBreakdown, WaveComputation]
+requires_components: [TaskBreakdown, WaveComputation, AgentRouter]
 ---
 
 # JDI Planner Agent
@@ -94,6 +94,28 @@ Never use time estimates. Use S/M/L sizing in task manifests and plan summaries.
 4. Research: standard stack, architecture patterns, common pitfalls
 5. Findings feed directly into planning (no separate RESEARCH.md)
 
+### Step 0a: Agent Discovery (MANDATORY — read AgentRouter first)
+
+<JDI:AgentRouter mode="discover" />
+
+Before breaking down tasks, you MUST enumerate the Claude Code agents
+available to this session by listing `.claude/agents/` (project-local, if it
+exists) and `~/.claude/agents/` (user-global). Read each `.md` file's YAML
+frontmatter and extract `name` and `description`. Project-local agents
+override user-global agents on name collision.
+
+This catalogue is written into the plan index frontmatter as `available_agents`
+and is used in Step 3 to pin each task to a specialist via the `agent:` field
+in its task file frontmatter.
+
+If discovery returns zero specialists (no `.claude/agents/` on either root),
+record `available_agents: []`, set `primary_agent: general-purpose`, and use
+tech-stack defaults. Never silently skip this step — `available_agents` MUST
+appear in the plan index even when empty.
+
+See `.jdi/framework/components/meta/AgentRouter.md` for the full routing tables
+(Unity / Unreal / Godot / non-game).
+
 ### Step 0b: Reference Analysis (when provided)
 
 If the user provides reference PRs, tickets, or example implementations:
@@ -130,8 +152,35 @@ implementation_steps:
 verification:
   - {How to verify completion}
 done_when: {Specific completion criterion}
+agent: {specialist chosen via AgentRouter — e.g. unity-ui-specialist}
+agent_rationale: {One sentence explaining why this specialist is the best fit}
 ```
 
+### Step 3a: Agent Assignment (MANDATORY when available_agents is non-empty)
+
+<JDI:AgentRouter mode="match" />
+
+For every task produced in Step 3, pick exactly one specialist from the
+`available_agents` catalogue discovered in Step 0a. Use the priority hierarchy
+from `AgentRouter.md`:
+
+1. Explicit user instruction
+2. Files touched by the task (path patterns — e.g. `Assets/Scripts/UI/**`)
+3. Task type + tech_stack
+4. Task objective keywords
+5. Checkpoint type (`checkpoint:human-verify` → `qa-tester`)
+6. Tech-stack default
+7. Fallback to `general-purpose`
+
+Write the selection into each task file's frontmatter as `agent:` and a short
+`agent_rationale:` explaining the choice. Also set `primary_agent` in the plan
+index frontmatter to the first task's agent (or the most common one across all
+tasks in single-agent mode).
+
+**Forbidden:** inventing agent names not present in `available_agents`; routing
+a task to an agent whose description clearly does not match (e.g. a shader
+task to `narrative-director`); leaving `agent:` blank when specialists exist.
+
 ### Step 4: Dependency Analysis
 
 <JDI:TaskBreakdown mode="dependencies" />
@@ -181,4 +230,13 @@ task_count: {n}
 overall_size: S | M | L
 wave: {assigned_wave}
 provides: [what this plan delivers]
+available_agents: [list of discovered Claude Code agents with name+description]
+primary_agent: {agent chosen for single-agent mode}
+task_agents:
+  - task_id: T1
+    agent: unity-ui-specialist
+    rationale: "Edits Canvas HUD — UI Toolkit expertise needed"
+  - task_id: T2
+    agent: gameplay-programmer
+    rationale: "Combat state machine work in Assets/Scripts/Combat"
 ```

package/framework/commands/create-plan.md

@@ -19,20 +19,21 @@ Create an implementation plan using a single planner agent (includes research).
 1. **Worktree** (if flagged): derive name from task, follow worktree.md steps, `cd` into `.worktrees/<name>`
 2. Read codebase context (`.jdi/codebase/SUMMARY.md` if exists)
 3. Read scaffolding (.jdi/PROJECT.yaml, REQUIREMENTS.yaml, ROADMAP.yaml) — create from templates if missing
-4. Quick Mode Detection — suggest /jdi:quick for trivial tasks
-5. Spawn `jdi-planner` agent (subagent_type="general-purpose") — creates split plan files (index .plan.md + per-task .T{n}.md files). The planner MUST write these files directly via Write tool (sandbox override for plan files).
-6. Collect and execute deferred ops — if the agent returned `files_to_create`, create them now using Write tool. Verify split plan files exist: index `.plan.md` + individual `.T{n}.md` task files.
-7. **Update state via CLI** — do NOT manually edit state.yaml. Run:
+4. **Agent Discovery (MANDATORY)** — before spawning the planner, enumerate available Claude Code agents by listing `.claude/agents/` (project-local) and `~/.claude/agents/` (user-global). Read each `.md` file's frontmatter for `name` and `description`. Pass the resulting catalogue into the planner's spawn prompt as `AVAILABLE_AGENTS` so it can pin specialists per task. If neither directory exists, pass an empty list. See `.jdi/framework/components/meta/AgentRouter.md` for the full routing rules.
+5. Quick Mode Detection — suggest /jdi:quick for trivial tasks
+6. Spawn `jdi-planner` agent (subagent_type="general-purpose") — creates split plan files (index .plan.md + per-task .T{n}.md files). The planner MUST write these files directly via Write tool (sandbox override for plan files). The planner MUST write the `available_agents` catalogue into the plan index frontmatter and pin an `agent:` field in every task file via AgentRouter.
+7. Collect and execute deferred ops — if the agent returned `files_to_create`, create them now using Write tool. Verify split plan files exist: index `.plan.md` + individual `.T{n}.md` task files. Verify each task file's frontmatter contains an `agent:` field (unless `available_agents` is empty).
+8. **Update state via CLI** — do NOT manually edit state.yaml. Run:
    ```bash
    npx jdi state plan-ready --plan-path ".jdi/plans/{plan-file}" --plan-name "{plan name}"
    ```
-8. **Present summary** (name, objective, task table, files) then ask: _"Provide feedback to refine, or say **approved** to finalise."_
-9. **Review loop**: Feedback → revise plan in-place, increment revision, re-present summary. Repeat until approved. Approval → run `npx jdi state approved`, then **STOP**.
+9. **Present summary** (name, objective, task table including the assigned `agent:` per task, files) then ask: _"Provide feedback to refine, or say **approved** to finalise."_
+10. **Review loop**: Feedback → revise plan in-place, increment revision, re-present summary. Repeat until approved. Approval → run `npx jdi state approved`, then **STOP**.
 
 ## HARD STOP — Planning Gate
 
 After the user approves the plan, your work is **DONE**. Output: _"Plan approved and locked in. Let me know when you want to implement."_ Then **STOP completely**. Do NOT invoke `/jdi:implement-plan`, do NOT spawn implementation agents, do NOT begin writing source code. Planning and implementation are separate human-gated phases.
 
-Agent base (read FIRST for cache): .jdi/framework/components/meta/AgentBase.md | Agent spec: .jdi/framework/agents/jdi-planner.md
+Agent base (read FIRST for cache): .jdi/framework/components/meta/AgentBase.md | Agent spec: .jdi/framework/agents/jdi-planner.md | Agent routing: .jdi/framework/components/meta/AgentRouter.md
 
 Feature to plan: $ARGUMENTS

package/framework/commands/implement-plan.md

@@ -14,22 +14,25 @@ Execute a PLAN.md with complexity-based routing.
 ## Orchestration
 
 1. Read codebase context (`.jdi/codebase/SUMMARY.md` if exists)
-2. Read plan index file and state.yaml — parse frontmatter for tasks, deps, waves, tech_stack
+2. Read plan index file and state.yaml — parse frontmatter for tasks, deps, waves, tech_stack, `available_agents`, and `primary_agent`
 3. **Read learnings:** Always read `.jdi/framework/learnings/general.md`. Then read domain-specific learnings based on tech_stack from plan frontmatter: PHP → `backend.md`, TS/React → `frontend.md`. Follow any conventions found — learnings override defaults.
 4. **Format detection:** If frontmatter contains `task_files:`, this is a split plan — task details are in separate files. If absent, legacy monolithic plan — all tasks inline.
-5. **Complexity routing** (`<JDI:ComplexityRouter />`): Simple (≤3 tasks, single stack/wave) → single agent. Complex → Agent Teams swarm. Override: `--team` / `--single`
-6. **Tech routing**: PHP → jdi-backend | TS/React → jdi-frontend | Full-stack → both
-7. Execute:
-   - **Single agent:** Pass `PLAN: {index-path}`. For split plans, agent reads task files one at a time via `file:` field in state.yaml.
-   - **Agent Teams:** For split plans, pass `TASK_FILE: {task-file-path}` in each agent's spawn prompt so they load only their assigned task file(s). For legacy plans, pass `PLAN: {plan-path}` as before.
-8. Collect and execute deferred ops (files, commits)
-9. Run verification (tests, lint, typecheck)
-10. **Update state via CLI** — do NOT manually edit state.yaml. Run `npx jdi state executing` before execution and `npx jdi state complete` after. Use `npx jdi state advance-task {task-id}` after each task completes.
-11. **Present summary** (tasks completed, files changed, verification results, deviations) then ask: _"Provide feedback to adjust, or say **approved** to finalise."_
-12. **Review loop**: Feedback → apply code changes, run tests, increment revision, re-present. Approval → suggest commit/PR. Natural conversation — no separate command needed.
+5. **Read per-task agents (MANDATORY for split plans)** — for every task file listed in `task_files`, read its frontmatter and record the `agent:` field. This is the `subagent_type` you will pass to the Task tool when spawning. Missing `agent:` → fall back to `primary_agent` → fall back to tech-stack default (`jdi-backend` / `jdi-frontend` / `general-purpose`). NEVER default everything to `general-purpose` silently. See `.jdi/framework/components/meta/AgentRouter.md`.
+6. **Agent existence check** — for each pinned agent, confirm it is actually installed (`.claude/agents/{name}.md` project-local, or `~/.claude/agents/{name}.md` user-global). If it is NOT installed, downgrade to `general-purpose` and record a `agent_downgrade:` entry to surface in the summary. Never silently change the pin.
+7. **Complexity routing** (`<JDI:ComplexityRouter />`): Simple (≤3 tasks, single stack/wave) → single agent. Complex → Agent Teams swarm. Override: `--team` / `--single`
+8. **Tech routing (fallback only when no pins exist)**: PHP → jdi-backend | TS/React → jdi-frontend | Full-stack → both. Pins ALWAYS override this fallback.
+9. Execute:
+   - **Single agent:** Spawn with `subagent_type: {plan.primary_agent}` (NOT `general-purpose`). Pass `PLAN: {index-path}`. For split plans, the agent reads task files one at a time via `file:` field in state.yaml.
+   - **Agent Teams:** For split plans, spawn ONE Task tool call per task with `subagent_type: {task.agent}` (the pin from the task file frontmatter), passing `TASK_FILE: {task-file-path}` so it loads only its assigned task. For legacy plans, pass `PLAN: {plan-path}` and use `primary_agent`.
+   - **Prompt scoping** — one task = one spawn. Never bundle multiple tasks into one prompt. Give exact file paths, cap exploration ("read only your TASK_FILE + its named targets"), and request short reports (<400 words). Agents can be truncated mid-task; scoped prompts survive the budget ceiling.
+10. Collect and execute deferred ops (files, commits)
+11. Run verification (tests, lint, typecheck)
+12. **Update state via CLI** — do NOT manually edit state.yaml. Run `npx jdi state executing` before execution and `npx jdi state complete` after. Use `npx jdi state advance-task {task-id}` after each task completes.
+13. **Present summary** (tasks completed, files changed, verification results, **which specialist ran which task**, any `agent_downgrade` events, deviations) then ask: _"Provide feedback to adjust, or say **approved** to finalise."_
+14. **Review loop**: Feedback → apply code changes, run tests, increment revision, re-present. Approval → suggest commit/PR. Natural conversation — no separate command needed.
 
 Agent base (read FIRST for cache): .jdi/framework/components/meta/AgentBase.md | Agent specs: .jdi/framework/agents/jdi-backend.md, .jdi/framework/agents/jdi-frontend.md
-Orchestration: .jdi/framework/components/meta/AgentTeamsOrchestration.md | Routing: .jdi/framework/components/meta/ComplexityRouter.md
+Orchestration: .jdi/framework/components/meta/AgentTeamsOrchestration.md | Routing: .jdi/framework/components/meta/ComplexityRouter.md | Agent routing: .jdi/framework/components/meta/AgentRouter.md
 
 When spawning agents, detect project type and include a `## Project Context` block (type, tech stack, quality gates, working directory) in the spawn prompt. This saves agents 2-3 discovery tool calls.
 

package/framework/components/meta/AgentBase.md

@@ -11,6 +11,19 @@ Standards inherited by all JDI agents via `<JDI:AgentBase />`. Default loads Cor
 - Batch file reads: issue all Read calls in a single turn rather than sequentially.
 - Batch git operations: combine related commands into a single Bash call where possible.
 
+## Budget Discipline
+
+You have a finite per-invocation budget (tokens, tool calls, wall time). Long runs can be terminated mid-task before you produce your final report. To survive:
+
+1. **Batch reads in parallel** — one turn with all Read calls, not sequential.
+2. **Cap exploration** — read only the files your spawn prompt names. If more are needed, report what you need and stop rather than wandering.
+3. **Write fixes before verifying** — Edit calls persist even if you are later truncated. Save the report for last.
+4. **Short reports (<400 words)** — terse file list + one sentence per change. Long formal reports are where truncation bites.
+5. **One concern per invocation** — address what was asked, do not expand scope.
+6. **Don't re-read files you just edited** — the harness tracks state.
+
+If your work exceeds one invocation, complete what you can, return a progress report naming exactly what remains, and let the orchestrator re-spawn you.
+
 ## Component Resolution
 
 When a spec contains `<JDI:*>` tags:

package/framework/components/meta/AgentRouter.md

@@ -0,0 +1,230 @@
+---
+name: AgentRouter
+category: meta
+description: Enumerate Claude Code agents and route tasks to the best specialist
+---
+
+# AgentRouter
+
+Enumerates the Claude Code agents available to the current session and routes
+individual plan tasks to the most appropriate specialist. Used by `jdi-planner`
+at plan-creation time to pin `agent:` into each task's frontmatter, and by
+`implement-plan` (via `ComplexityRouter` and `AgentTeamsOrchestration`) at
+execution time to honour those pins when spawning via the Task tool.
+
+The point of this component is simple: **stop defaulting every subagent call to
+`general-purpose`**. If the user has installed domain specialists (e.g.
+`unity-specialist`, `unity-ui-specialist`, `gameplay-programmer`,
+`godot-gdscript-specialist`, `ue-gas-specialist`), JDI plans must surface them
+into the plan and implement-plan must use them.
+
+---
+
+## 1. Agent Discovery (at plan time)
+
+The planner MUST perform discovery before task breakdown. Merge two roots (the
+project-local list overrides the user-global list on name collision):
+
+1. `.claude/agents/*.md` — project-local specialists (highest priority)
+2. `~/.claude/agents/*.md` — user-global specialists
+
+For each `.md` file, read the YAML frontmatter and extract:
+
+- `name` — the subagent_type value passed to the Task tool
+- `description` — the one-line capability blurb used for routing decisions
+- `model` (optional) — preferred model if specified
+- `tools` (optional) — tool allowlist if the agent is tool-restricted
+
+Agents whose frontmatter is unreadable or missing `name` are skipped.
+
+Discovery command (reference — the planner may use `Glob` + `Read`):
+
+```bash
+ls ~/.claude/agents/ 2>/dev/null
+ls .claude/agents/ 2>/dev/null
+```
+
+The resulting catalogue MUST be written into the plan index frontmatter as
+`available_agents:` (see `framework/templates/PLAN.md`) so reviewers and the
+implement-plan pass can see exactly which agents were visible at plan time.
+
+```yaml
+available_agents:
+  - name: unity-specialist
+    description: Authority on Unity-specific patterns, APIs, and optimisation
+  - name: unity-ui-specialist
+    description: Unity UI Toolkit / UGUI / runtime UI performance
+  - name: gameplay-programmer
+    description: Implements game mechanics, player systems, combat
+  - name: qa-tester
+    description: Writes test cases, bug reports, regression checklists
+```
+
+If discovery returns zero agents (or `.claude/agents/` doesn't exist on either
+root), the planner falls back to the legacy routing (tech-stack default:
+`jdi-backend` or `jdi-frontend`) and records `available_agents: []` so it is
+explicit rather than silent.
+
+---
+
+## 2. Task-to-Agent Matching (at plan time)
+
+For each task in the plan, the planner selects ONE primary agent using this
+signal hierarchy (highest to lowest):
+
+| Priority | Signal | Example |
+|----------|--------|---------|
+| 1 | Explicit user instruction | "use the unity-specialist for this task" |
+| 2 | Files touched by the task | `Assets/Scripts/UI/**` → `unity-ui-specialist` |
+| 3 | Task type + tech_stack | Unity C# gameplay → `gameplay-programmer` or `unity-specialist` |
+| 4 | Task objective keywords | "shader", "VFX", "render pipeline" → `unity-shader-specialist` |
+| 5 | Checkpoint type | `checkpoint:human-verify` → `qa-tester` |
+| 6 | Tech-stack default | PHP → `jdi-backend`, TS/React → `jdi-frontend`, C#/Unity → `unity-specialist` |
+| 7 | Fallback | `general-purpose` (only if no specialists exist) |
+
+### Unity routing cheat sheet (common case for game projects)
+
+| Signal | Preferred agent |
+|--------|-----------------|
+| `Assets/Scripts/**/UI/**` or TMPro/UGUI/UI Toolkit references | `unity-ui-specialist` |
+| `Assets/Scripts/**/DOTS/**` or Jobs/Burst/ECS references | `unity-dots-specialist` |
+| Shader Graph, HLSL, VFX Graph, render pipeline | `unity-shader-specialist` |
+| Addressables, asset bundles, memory budgets | `unity-addressables-specialist` |
+| Gameplay mechanics, combat, movement, abilities | `gameplay-programmer` |
+| AI, behaviour trees, pathfinding, perception | `ai-programmer` |
+| Core engine/framework, performance-critical systems | `engine-programmer` or `performance-analyst` |
+| General Unity API guidance, bootstrapping, subsystem integration | `unity-specialist` |
+| Tests, QA checklists, regression scripts | `qa-tester` |
+| Any task that edits code — no better specialist available | `gameplay-programmer` (games) or `general-purpose` (non-game) |
+
+### Unreal routing cheat sheet
+
+| Signal | Preferred agent |
+|--------|-----------------|
+| Blueprints and Blueprint architecture | `ue-blueprint-specialist` |
+| UMG / CommonUI widgets | `ue-umg-specialist` |
+| Gameplay Ability System, abilities, attribute sets | `ue-gas-specialist` |
+| Replication, RPCs, prediction | `ue-replication-specialist` |
+| General UE API and subsystem guidance | `unreal-specialist` |
+
+### Godot routing cheat sheet
+
+| Signal | Preferred agent |
+|--------|-----------------|
+| GDScript code, typed signals, node architecture | `godot-gdscript-specialist` |
+| GDExtension / C++ / Rust bindings | `godot-gdextension-specialist` |
+| Godot shading language, visual shaders, particles | `godot-shader-specialist` |
+| General Godot API and node/scene guidance | `godot-specialist` |
+
+### Non-game defaults
+
+| Signal | Preferred agent |
+|--------|-----------------|
+| PHP backend | `jdi-backend` |
+| TypeScript / React frontend | `jdi-frontend` |
+| Full-stack | `jdi-backend` + `jdi-frontend` |
+
+---
+
+## 3. Output Format (written into plan files)
+
+### Plan index (`{phase}-{plan}-{slug}.plan.md`) frontmatter
+
+```yaml
+available_agents:
+  - name: unity-specialist
+    description: ...
+  - name: gameplay-programmer
+    description: ...
+
+# Primary agent for single-agent mode (first task's agent, or most common)
+primary_agent: unity-specialist
+```
+
+### Task file (`{phase}-{plan}-{slug}.T{n}.md`) frontmatter
+
+```yaml
+agent: unity-ui-specialist   # REQUIRED when available_agents is non-empty
+agent_rationale: "Edits Canvas-based HUD — UI Toolkit expertise needed"
+```
+
+`agent_rationale` is a short free-text note explaining WHY the planner picked
+this specialist. Reviewers can use it to challenge bad routings.
+
+---
+
+## 4. Execution (at implement-plan time)
+
+`implement-plan` MUST read the task's `agent:` field from each task file and
+pass it as `subagent_type` when spawning via the Task tool.
+
+### Single-agent mode
+
+```
+Task(
+  subagent_type: "{plan.primary_agent}",   # NOT "general-purpose"
+  name: "{plan.primary_agent}",
+  prompt: "<standard single-agent spawn prompt from ComplexityRouter>"
+)
+```
+
+If `plan.primary_agent` is missing (legacy plan or empty `available_agents`),
+fall back to `general-purpose` with a `jdi-backend` / `jdi-frontend` spec load.
+
+### Agent-teams mode
+
+For each task, read its `agent:` frontmatter field and spawn ONE Task tool call
+per task with `subagent_type` set to that value:
+
+```
+Task(
+  subagent_type: "{task.agent}",           # per-task specialist
+  name: "{task.agent}-{task_id}",
+  prompt: "<spawn prompt from AgentTeamsOrchestration with TASK_FILE: {task file}>"
+)
+```
+
+Tasks with no `agent:` field fall back to the tech-stack default
+(`jdi-backend` / `jdi-frontend` / `general-purpose`).
+
+### Mixed fallbacks
+
+- If the discovered specialist name does NOT match a valid subagent type in the
+  current session (e.g. plan was created on a different machine), downgrade to
+  `general-purpose` and log a warning in the implement-plan summary: `agent
+  downgrade: {planned} → general-purpose (not installed)`.
+- Never silently change the pin; always surface downgrades in the summary.
+
+---
+
+## 5. Validation Rules
+
+The planner MUST NOT:
+
+1. Invent agent names that are not in `available_agents`.
+2. Route a task to an agent whose description clearly does not match the task
+   (e.g. `narrative-director` for a shader task).
+3. Leave `agent:` blank when `available_agents` is non-empty.
+
+The implement-plan pass MUST:
+
+1. Read `agent:` from every task file before spawning.
+2. Surface any downgrade in the summary.
+3. Prefer project-local `.claude/agents/` over `~/.claude/agents/` on name
+   collision.
+
+---
+
+## Usage
+
+```
+<JDI:AgentRouter mode="discover" />     # at plan time — enumerate + match
+<JDI:AgentRouter mode="spawn" />        # at implement time — honour pins
+```
+
+Referenced by:
+- `framework/agents/jdi-planner.md` (discover + match)
+- `framework/components/meta/ComplexityRouter.md` (spawn)
+- `framework/components/meta/AgentTeamsOrchestration.md` (spawn)
+- `framework/commands/create-plan.md` (discover)
+- `framework/commands/implement-plan.md` (spawn)

package/framework/components/meta/AgentTeamsOrchestration.md

@@ -8,38 +8,60 @@ description: Agent Teams orchestration quick-reference
 
 ## Core Pattern (6 Steps)
 
-1. **Pre-flight** — Read command spec, `<JDI:CodebaseContext />`, read state.yaml, set status to "executing"
+1. **Pre-flight** — Read command spec, `<JDI:CodebaseContext />`, read state.yaml, set status to "executing". Read each task file's `agent:` frontmatter field so you know which specialist to spawn per task (see `.jdi/framework/components/meta/AgentRouter.md`).
 2. **Create Team** — `TeamCreate(team_name: "{team-name}")`
 3. **Create Tasks** — TaskCreate per work unit, set `addBlockedBy` dependencies
-4. **Spawn Teammates** — Task tool with `subagent_type: "general-purpose"`. Include in prompt: agent spec path, team context, task assignments
+4. **Spawn Teammates** — Task tool with `subagent_type: "{task.agent}"` (the pin from the task file frontmatter — e.g. `unity-ui-specialist`, `gameplay-programmer`). Never hardcode `general-purpose` when a pin exists. Verify the pinned agent is installed before spawning; if not, downgrade to `general-purpose` and record `agent_downgrade:` in the summary. Include in prompt: agent spec path, team context, task assignments. **Scope tightly** — one task per spawn, exact file targets, capped exploration, short reports (<400 words). See `AgentBase.md` § Budget Discipline.
 5. **Coordinate** — Automatic message delivery for results, TaskList to monitor, SendMessage to guide/unblock
-6. **Cleanup** — shutdown_request to all → TeamDelete → set status "complete" → report
+6. **Cleanup** — shutdown_request to all → TeamDelete → set status "complete" → report (include which specialist ran which task and any downgrade events)
 
 ---
 
 ## Task Routing Table
 
-| Task Stack | Agent(s) | Spawn Count |
+**Primary source of truth:** each task's `agent:` frontmatter field, assigned
+by `jdi-planner` via `AgentRouter` at plan time. The table below is the
+**fallback** used only when a task has no pin (legacy plans or empty
+`available_agents`).
+
+| Task Stack (fallback) | Agent(s) | Spawn Count |
 |-----------|----------|-------------|
 | PHP only | jdi-backend | 1 |
 | TS/React only | jdi-frontend | 1 |
 | Full-stack | jdi-backend + jdi-frontend | 2 |
 | Config/docs | jdi-backend (default) | 1 |
 
+**Examples of honouring pins** (real values — not fallbacks):
+
+| Task pin | Subagent type passed to Task tool |
+|----------|-----------------------------------|
+| `agent: unity-specialist` | `unity-specialist` |
+| `agent: unity-ui-specialist` | `unity-ui-specialist` |
+| `agent: gameplay-programmer` | `gameplay-programmer` |
+| `agent: qa-tester` | `qa-tester` |
+| `agent: ue-gas-specialist` | `ue-gas-specialist` |
+| `agent: godot-gdscript-specialist` | `godot-gdscript-specialist` |
+
 ---
 
 ## Specialist Spawn Prompt Template (~200 tokens)
 
 ```
-You are {agent-name}. Read .jdi/framework/agents/{spec}.md and .jdi/framework/components/meta/AgentBase.md.
+You are {task.agent}. Your Claude Code agent definition has already been
+loaded from .claude/agents/{task.agent}.md (or ~/.claude/agents/{task.agent}.md)
+— follow it. Also read .jdi/framework/components/meta/AgentBase.md for the
+JDI base protocol. If your Claude Code agent definition has requires_components
+in frontmatter, batch-read them before starting.
 
 TEAM: {team-name}
 PLAN: {plan-path}
 TASK_FILE: {task-file-path}
 WORKING_DIR: {working-directory}
 
-Read your TASK_FILE for task details (objective, files, steps, verification).
-If TASK_FILE is not provided (legacy plan), claim tasks from TaskList and read task details from the PLAN file.
+Read your TASK_FILE for task details (objective, files, steps, verification,
+and the `agent_rationale` explaining why you were picked for this task).
+If TASK_FILE is not provided (legacy plan), claim tasks from TaskList and read
+task details from the PLAN file.
 
 1. Implement using Edit tool
 2. SendMessage to coordinator with structured return
@@ -49,6 +71,10 @@ Report: files_modified, files_to_create, commits_pending.
 No git commit (use commits_pending).
 ```
 
+The `subagent_type` passed to the Task tool is the `agent:` pin from the task
+file frontmatter — NOT `general-purpose`. See
+`.jdi/framework/components/meta/AgentRouter.md` for full rules.
+
 ---
 
 ## Deferred Operations Checklist

package/framework/components/meta/ComplexityRouter.md

@@ -37,15 +37,24 @@ reasoning: "{why this mode was chosen}"
 
 ## Single-Agent Mode
 
-Spawn one specialist agent directly via Task tool. Follow cache-optimised load order (AgentBase first):
+Spawn one specialist agent directly via Task tool. Follow cache-optimised load
+order (AgentBase first).
+
+**Pinning rule:** read `primary_agent` from the plan index frontmatter. If set
+and the agent is installed (verify against `.claude/agents/{name}.md` or
+`~/.claude/agents/{name}.md`), use it as the `subagent_type`. If unset or not
+installed, fall back to `general-purpose` and record a `agent_downgrade:` note
+in the summary. Never silently default to `general-purpose` when a pin exists.
+See `.jdi/framework/components/meta/AgentRouter.md`.
 
 ```
 Task(
-  subagent_type: "general-purpose",
-  name: "{primary_agent}",
-  prompt: "Read .jdi/framework/components/meta/AgentBase.md for the base protocol.
-You are {primary_agent}. Read .jdi/framework/agents/{primary_agent}.md for your spec.
-If your spec has requires_components in frontmatter, batch-read all listed components before starting.
+  subagent_type: "{plan.primary_agent}",   # e.g. unity-specialist — NOT hardcoded
+  name: "{plan.primary_agent}",
+  prompt: "You are {plan.primary_agent}. Your Claude Code agent definition has
+already been loaded from .claude/agents/{name}.md (or ~/.claude/agents/{name}.md)
+— follow it. Also read .jdi/framework/components/meta/AgentBase.md for the
+JDI base protocol.
 
 ## Project Context
 - Type: {project_type}
@@ -55,13 +64,20 @@ If your spec has requires_components in frontmatter, batch-read all listed compo
 
 ## Task
 Execute all tasks in the plan sequentially. PLAN: {plan-path}.
-For split plans (task_files in frontmatter), read each task file one at a time from the file: field in state.yaml.
+For split plans (task_files in frontmatter), read each task file one at a time
+from the file: field in state.yaml.
 Report: files_modified, files_to_create, commits_pending."
 )
 ```
 
 No TeamCreate, no TaskCreate, no cross-agent coordination.
 
+### Legacy fallback (no pins)
+
+When `primary_agent` is missing or empty (legacy plan with no AgentRouter
+discovery), use `subagent_type: "general-purpose"` and load the jdi-backend /
+jdi-frontend spec inside the prompt as before.
+
 ---
 
 ## Agent Teams Mode

package/framework/templates/PLAN-TASK.md

@@ -5,6 +5,13 @@ task_name: {Task Name}
 type: auto
 wave: 1
 depends_on: []
+
+# Agent routing (written by jdi-planner via AgentRouter — see
+# framework/components/meta/AgentRouter.md). implement-plan reads `agent` and
+# passes it as `subagent_type` when spawning via the Task tool. `agent_rationale`
+# is a human-readable justification so reviewers can challenge the pick.
+agent: general-purpose
+agent_rationale: "{Why this specialist was chosen}"
 ---
 
 # Task {n}: {Task Name}

package/framework/templates/PLAN.md

@@ -30,6 +30,13 @@ tags: [tag1, tag2, tag3]
 tech_stack:
   added: []
   patterns: []
+
+# Agent Routing (populated by jdi-planner via AgentRouter)
+# available_agents is the catalogue discovered from .claude/agents/ at plan time.
+# primary_agent is used by single-agent mode in implement-plan.
+# Per-task agents live in each {slug}.T{n}.md file under `agent:`.
+available_agents: []
+primary_agent: general-purpose
 ---
 
 # Phase {X} Plan {YY}: {Plan Name}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@benzotti/jedi",
-  "version": "0.1.41",
+  "version": "0.1.43",
   "description": "JDI - Context-efficient AI development framework for Claude Code",
   "type": "module",
   "bin": {