@benzotti/jedi 0.1.42 → 0.1.45

package/framework/commands/pr-review.md

@@ -1,33 +1,92 @@
 ---
 name: pr-review
-description: "JDI: Review pull request"
+description: "JDI: Review pull request with learnings-aware analysis"
+allowed-tools: Read, Bash, Task
+argument-hint: "<pr-number-or-url> [--no-comments]"
+context: |
+  !git branch --show-current 2>/dev/null
 ---
 
 # /jdi:pr-review
 
-Review a pull request with learnings-aware analysis.
+Review a pull request against the team's learnings and coding standards.
+
+**This skill follows `<JDI:StrictnessProtocol />`. Read that component before executing any step below.**
+
+---
 
 ## Flags
 
-- `--no-comments` — Do not post comments to GitHub. Write review to `.jdi/reviews/PR-{number}-review.md` instead.
+- `--no-comments` — Do not post comments to GitHub. Write the review to `.jdi/reviews/PR-{number}-review.md` instead.
+
+---
+
+## Orchestration
+
+### 1. Parse PR Reference
+
+Extract the PR number from `$ARGUMENTS`. Accept either a bare number (`123`) or a GitHub URL (`https://github.com/org/repo/pull/123`). If neither form is present, STOP:
+
+> "I need a PR number or URL. Try `/jdi:pr-review 123` or `/jdi:pr-review https://github.com/org/repo/pull/123`."
+
+### 2. Parse Flags
+
+Check for `--no-comments`. Map to the `post="false"` parameter for the `PRReview` component.
+
+### 3. Verify PR Exists
+
+Run `gh pr view {number}` to confirm the PR is reachable. If `gh` errors, STOP and report the failure — do NOT fabricate a review.
+
+### 4. Delegate to Reviewer
 
-## Delegation
+Spawn the reviewer via Task tool. JDI specialists spawn as `general-purpose` with identity injected via prompt text:
 
-Parse flags from $ARGUMENTS. Map `--no-comments` to `post="false"`.
+```
+Task(
+  subagent_type="general-purpose",
+  prompt="Read .jdi/framework/components/meta/AgentBase.md for the base protocol.
 
-Use Task tool with subagent_type="general-purpose" and prompt:
+  Read learnings before reviewing — these represent the team's coding standards
+  and MUST be cross-referenced during review:
+  - Always: .jdi/framework/learnings/general.md
+  - PHP/Laravel PRs: also .jdi/framework/learnings/backend.md
+  - React/TypeScript PRs: also .jdi/framework/learnings/frontend.md
+  - Test changes: also .jdi/framework/learnings/testing.md
+  - CI/Docker changes: also .jdi/framework/learnings/devops.md
 
-Read ./.jdi/framework/components/meta/AgentBase.md for the base protocol.
+  Apply learnings as additional review criteria — flag violations and praise adherence.
 
-Read learnings before reviewing — these represent the team's coding standards and MUST be cross-referenced during review:
-- Always read: `.jdi/framework/learnings/general.md`
-- For PHP/Laravel PRs: also read `.jdi/framework/learnings/backend.md`
-- For React/TypeScript PRs: also read `.jdi/framework/learnings/frontend.md`
-- For test changes: also read `.jdi/framework/learnings/testing.md`
-- For CI/Docker changes: also read `.jdi/framework/learnings/devops.md`
-Apply learnings as additional review criteria — flag violations and praise adherence.
+  Read .jdi/framework/components/quality/PRReview.md for review instructions.
+  {If --no-comments: invoke as <JDI:PRReview post=\"false\" />}
 
-Read ./.jdi/framework/components/quality/PRReview.md for review instructions.
-{If --no-comments flag was present: Include `post="false"` parameter — invoke as `<JDI:PRReview post="false" />`}
+  Review PR: {pr-number}"
+)
+```
+
+### 5. Present Result
+
+After the reviewer returns, summarise: number of comments posted (or file path of the written review), severity breakdown, and any blocking issues.
+
+Then **STOP**. Do NOT merge, approve, or take any follow-up action.
+
+---
+
+## Edge Cases
+
+| Situation | Response |
+|-----------|----------|
+| No PR reference in arguments | STOP at step 1. Ask for a number or URL. |
+| `gh pr view` fails (not logged in, wrong repo) | Report the error verbatim. Do NOT attempt a workaround. |
+| PR is already merged | Note it in the summary and review anyway — learnings may still apply. |
+| PR is a draft | Review as normal; flag that the PR is draft in the summary. |
+| `.jdi/framework/learnings/` missing | Reviewer falls back to base review criteria. Record the missing learnings in the summary. |
+
+---
+
+## Collaborative Protocol
+
+<JDI:StrictnessProtocol />
+
+---
 
-Review PR: $ARGUMENTS
+**PR to review:** $ARGUMENTS

package/framework/commands/quick.md

@@ -1,19 +1,124 @@
 ---
 name: quick
-description: "JDI: Quick focused change"
+description: "JDI: Quick focused change (skips planner, relaxed standards)"
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit
+argument-hint: "<task description> [--dry-run]"
+context: |
+  !git status --short 2>/dev/null | head -20
 ---
 
 # /jdi:quick
 
-Execute a small, focused change directly without full orchestration.
+Execute a small, focused change directly without full orchestration. For trivial or prototype work only — no planner, no agent spawn, no waves.
 
-**Flags:** `--dry-run` (preview without writing files)
+**This skill follows `<JDI:StrictnessProtocol />`. Read that component before executing any step below.**
 
-## Direct Execution
+---
+
+## Flags
+
+- `--dry-run` — Preview the change without writing files. List intended edits and STOP.
+
+---
+
+## Scope Gate (read first)
+
+`/jdi:quick` is for:
+
+- Single-file edits, typo fixes, log lines, variable renames
+- Prototype / exploration code where throwaway is acceptable
+- Tasks under ~30 minutes with no architectural impact
+
+`/jdi:quick` is NOT for:
+
+- Production code requiring tests, review, or sign-off
+- Multi-file refactors or anything touching contracts (API routes, DTOs, exported types, migrations)
+- Work that spans tech stacks or layers
+
+If the task doesn't fit, redirect to `/jdi:create-plan "<feature>"` before writing any code.
+
+---
+
+## Orchestration
+
+The steps below are numbered and ordered. Do NOT skip, merge, or reorder them.
+
+### 1. Parse and Classify
+
+Read `$ARGUMENTS`. If the task description suggests production-grade work (tests required, multi-file, architectural), STOP and redirect:
+
+> "This looks bigger than `/jdi:quick` is meant for. Run `/jdi:create-plan "<feature>"` instead so we agree on scope before writing code."
+
+**Wait for the user's answer. Do not proceed until they confirm `/jdi:quick` is still the right fit.**
+
+### 2. Detect Tech Stack
+
+Read the target files (inferred from `$ARGUMENTS` or the user's follow-up). Identify the stack. Record in working memory.
+
+### 3. Dry Run Check
+
+If `--dry-run` is present, list the files you would edit and the intended change per file. Then **STOP**. Do NOT write anything.
+
+### 4. Execute Change
+
+Apply the edit directly via Edit tool. No agent spawn. No TaskCreate. Scope is intentionally narrow — one concern per invocation.
+
+### 5. Verification
+
+Run only the quality gates that are cheap and relevant:
+
+- Typecheck for TS changes (`tsc --noEmit` or project-equivalent)
+- Lint for the touched file only (not the whole repo)
+- Tests only if the user explicitly asked for them — `/jdi:quick` defaults to skipping
+
+If a gate fails, STOP and report. Do NOT auto-fix beyond the scope the user requested.
+
+### 6. Report
+
+Present a 3-line summary: files changed, gates run, next suggested action. End with:
+
+> "Commit as `proto:` / `quick:` / leave uncommitted? Your call."
+
+**Wait for the user's answer. Do NOT auto-commit.**
+
+---
+
+## Relaxed Standards Mode
+
+- Prototype / throwaway code accepted
+- Tests optional (default: skip)
+- Commit message prefix: `proto:` or `quick:`
+- Framed as exploration — NOT production
+- `jdi-qa-tester` is NOT invoked in `/jdi:quick` mode. If regression checks matter, route through `/jdi:implement-plan` instead.
+
+---
+
+## Edge Cases
+
+| Situation | Response |
+|-----------|----------|
+| Task description implies production work | Redirect to `/jdi:create-plan` at step 1. Do NOT proceed. |
+| `.jdi/` directory doesn't exist | Proceed anyway — `/jdi:quick` does not require JDI scaffolding. Skip any state updates. |
+| Typecheck or lint fails after edit | Report the failure. Do NOT auto-fix unrelated issues. |
+| User asks for tests mid-task | Honour the request; run the test command once, report, then stop. |
+| Target file doesn't exist | Ask the user: create it, or did they mean a different path? |
+
+---
+
+## HARD STOP
+
+Once the edit is applied and gates have run, the skill is **DONE**.
+
+- Do NOT auto-commit.
+- Do NOT advance state.
+- Do NOT invoke any other skill.
+
+---
+
+## Collaborative Protocol
+
+<JDI:StrictnessProtocol />
+
+---
 
-1. Parse task from $ARGUMENTS
-2. Detect tech stack from target files
-3. Execute changes directly (no agent spawn, no team, no waves)
-4. Run verification gates
-5. Commit with conventional format
-6. Brief state update (if .jdi/ exists)
+**Task:** $ARGUMENTS

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

@@ -22,26 +22,39 @@ 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):
+The planner MUST perform discovery before task breakdown. JDI specialists live
+in the framework itself, not in Claude Code's subagent registry — the
+orchestrator reads their specs and injects identity via prompt text when
+spawning (see `framework/jedi.md` Critical Constraints).
 
-1. `.claude/agents/*.md` — project-local specialists (highest priority)
-2. `~/.claude/agents/*.md` — user-global specialists
+Merge these roots in order (earlier roots override later ones on name
+collision):
+
+1. `.jdi/framework/agents/jdi-*.md` — JDI specialists installed in the project
+   (primary source for any project using JDI). When working on the jedi repo
+   itself, fall back to `framework/agents/jdi-*.md` in the repo root.
+2. `.claude/agents/*.md` — project-local Claude Code subagents (user-added
+   specialists, takes precedence over user-global)
+3. `~/.claude/agents/*.md` — user-global Claude Code subagents
 
 For each `.md` file, read the YAML frontmatter and extract:
 
-- `name` — the subagent_type value passed to the Task tool
+- `name` — identity used in the spawn prompt (JDI agents) or as the
+  `subagent_type` value (Claude Code registered subagents)
 - `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.
+Record each entry with a `source:` field so `implement-plan` knows how to spawn
+it: `jdi` for JDI framework specialists, `claude-code` for registered
+subagents. Agents whose frontmatter is unreadable or missing `name` are skipped.
 
-Discovery command (reference — the planner may use `Glob` + `Read`):
+Discovery commands (reference — the planner uses `Glob` + `Read`):
 
 ```bash
-ls ~/.claude/agents/ 2>/dev/null
+ls .jdi/framework/agents/jdi-*.md 2>/dev/null || ls framework/agents/jdi-*.md 2>/dev/null
 ls .claude/agents/ 2>/dev/null
+ls ~/.claude/agents/ 2>/dev/null
 ```
 
 The resulting catalogue MUST be written into the plan index frontmatter as
@@ -50,20 +63,24 @@ implement-plan pass can see exactly which agents were visible at plan time.
 
 ```yaml
 available_agents:
+  - name: jdi-backend
+    source: jdi
+    description: PHP/Laravel backend specialist — APIs, migrations, contracts
+  - name: jdi-frontend
+    source: jdi
+    description: TS/React frontend specialist — components, types, client code
+  - name: jdi-qa-tester
+    source: jdi
+    description: Post-task verification, a11y, contract checks
   - 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
+    source: claude-code
+    description: Unity API patterns and optimisation (user-added)
 ```
 
-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.
+If discovery returns zero agents (no JDI install and no `.claude/agents/`),
+the planner records `available_agents: []` and falls back to the legacy
+tech-stack default (`jdi-backend` / `jdi-frontend` / `general-purpose`) so
+the empty state is explicit rather than silent.
 
 ---
 
@@ -123,6 +140,29 @@ signal hierarchy (highest to lowest):
 | PHP backend | `jdi-backend` |
 | TypeScript / React frontend | `jdi-frontend` |
 | Full-stack | `jdi-backend` + `jdi-frontend` |
+| Orchestration / sprint / risk / scope | `jdi-producer` |
+| Performance profiling / budgets / regression | `jdi-perf-analyst` |
+| Security review / vuln audit / secrets / privacy | `jdi-security` |
+| Test case writing / regression checklist / post-task verify | `jdi-qa-tester` |
+
+### Jedi meta-framework routing
+
+Use these pins when the work being done is on the Jedi framework itself
+(editing files under `framework/`, writing plans about JDI, etc.).
+
+| Signal | Preferred agent |
+|--------|-----------------|
+| Framework design | `jdi-architect` |
+| Framework edits | `jdi-programmer` |
+| Framework tests | `jdi-quality` |
+| Plan creation | `jdi-planner` |
+| Sprint / risk / scope | `jdi-producer` |
+| Perf profiling | `jdi-perf-analyst` |
+| Security audit | `jdi-security` |
+| Post-task verify | `jdi-qa-tester` |
+
+> **Note:** `jdi-qa-tester` is automatically invoked by `implement-plan` after
+> every code-touching task — it does not need to be explicitly pinned per task.
 
 ---
 
@@ -155,44 +195,90 @@ 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.
+`implement-plan` MUST read the task's `agent:` field and the corresponding
+`source:` from `available_agents`, then spawn via the Task tool using the
+correct pattern for that source.
+
+> **Non-negotiable platform constraint:** Claude Code's Task tool only accepts
+> `subagent_type` values that are registered in its subagent list. JDI's
+> specialists live in `framework/agents/` — NOT in `.claude/agents/` — so they
+> are NOT registered subagent types. Passing `subagent_type="jdi-backend"`
+> (or any other JDI agent name) errors with `classifyHandoffIfNeeded is not
+> defined`. See `framework/jedi.md` Critical Constraints.
+>
+> The workaround: spawn `subagent_type="general-purpose"` and inject the JDI
+> agent's identity via the prompt text. Registered Claude Code specialists
+> (found under `.claude/agents/`) can still be spawned directly by name.
+
+### Source-aware spawn pattern
+
+| `source` in catalogue | `subagent_type` | Identity mechanism |
+|----------------------|-----------------|--------------------|
+| `jdi` | `"general-purpose"` | Prompt text: `"You are {task.agent}. Read .jdi/framework/agents/{task.agent}.md for instructions."` |
+| `claude-code` | `"{task.agent}"` | Native — Claude Code loads the agent spec from `.claude/agents/` |
 
 ### Single-agent mode
 
 ```
+# source: jdi (JDI framework specialist)
+Task(
+  subagent_type: "general-purpose",
+  name: "{plan.primary_agent}",
+  prompt: "You are {plan.primary_agent}. Read .jdi/framework/agents/{plan.primary_agent}.md
+  for your full role and instructions. Also read .jdi/framework/components/meta/AgentBase.md
+  for the JDI base protocol.
+
+  <standard single-agent spawn prompt from ComplexityRouter>"
+)
+
+# source: claude-code (user-added registered specialist)
 Task(
-  subagent_type: "{plan.primary_agent}",   # NOT "general-purpose"
+  subagent_type: "{plan.primary_agent}",   # e.g. unity-specialist
   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.
+fall back to `subagent_type="general-purpose"` with a `jdi-backend` /
+`jdi-frontend` spec load in the prompt.
 
 ### 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:
+For each task, read its `agent:` frontmatter field and the matching `source:`
+from the plan's `available_agents` catalogue. Spawn ONE Task tool call per task
+using the pattern that matches its source (see table above).
 
 ```
+# JDI specialist (source: jdi)
+Task(
+  subagent_type: "general-purpose",
+  name: "{task.agent}-{task_id}",
+  prompt: "You are {task.agent}. Read .jdi/framework/agents/{task.agent}.md for instructions.
+  <spawn prompt from AgentTeamsOrchestration with TASK_FILE: {task file}>"
+)
+
+# Claude Code registered specialist (source: claude-code)
 Task(
-  subagent_type: "{task.agent}",           # per-task specialist
+  subagent_type: "{task.agent}",
   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`).
+(`jdi-backend` / `jdi-frontend`) spawned via the `source: jdi` pattern.
 
 ### 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)`.
+- If a pinned `source: jdi` agent's spec file is not found at
+  `.jdi/framework/agents/{name}.md` (or `framework/agents/{name}.md` in the
+  self-hosting repo), downgrade to `general-purpose` with a `jdi-backend` /
+  `jdi-frontend` spec load. Record `agent_downgrade: {planned} → general-purpose
+  (spec not found)` in the summary.
+- If a pinned `source: claude-code` agent is not registered in the current
+  session (e.g. plan was created on a different machine), downgrade the same
+  way. Record `agent_downgrade: {planned} → general-purpose (not installed)`.
 - Never silently change the pin; always surface downgrades in the summary.
 
 ---
@@ -209,9 +295,11 @@ The planner MUST NOT:
 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.
+2. Read the matching `source:` from the plan's `available_agents` catalogue to
+   pick the correct spawn pattern (see §4).
+3. Surface any downgrade in the summary.
+4. Prefer `.jdi/framework/agents/` (or `framework/agents/` in the jedi repo)
+   over `.claude/agents/` over `~/.claude/agents/` on name collision.
 
 ---
 

package/framework/components/meta/AgentTeamsOrchestration.md

@@ -11,7 +11,11 @@ description: Agent Teams orchestration quick-reference
 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: "{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.
+4. **Spawn Teammates** — Task tool, one call per task. The spawn pattern depends on the `source:` field in `available_agents` (see `AgentRouter.md` §4):
+    - **`source: jdi`** (JDI framework specialists like `jdi-backend`, `jdi-frontend`, `jdi-qa-tester`) — `subagent_type: "general-purpose"` and inject identity via prompt text: `"You are {task.agent}. Read .jdi/framework/agents/{task.agent}.md for instructions."` This is the common case.
+    - **`source: claude-code`** (user-added registered subagents like `unity-ui-specialist`) — `subagent_type: "{task.agent}"` directly; Claude Code loads the spec natively.
+    - Verify the agent exists before spawning. For `jdi`, check `.jdi/framework/agents/{name}.md`. For `claude-code`, check `.claude/agents/{name}.md` or `~/.claude/agents/{name}.md`. Missing spec → 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 (include which specialist ran which task and any downgrade events)
 
@@ -44,14 +48,15 @@ by `jdi-planner` via `AgentRouter` at plan time. The table below is the
 
 ---
 
-## Specialist Spawn Prompt Template (~200 tokens)
+## Specialist Spawn Prompt Templates (~200 tokens)
+
+### `source: jdi` — JDI framework specialist (common case)
 
 ```
-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.
+You are {task.agent}. Read .jdi/framework/agents/{task.agent}.md for your
+full role and instructions. Also read .jdi/framework/components/meta/AgentBase.md
+for the JDI base protocol. If your spec has requires_components in frontmatter,
+batch-read them before starting.
 
 TEAM: {team-name}
 PLAN: {plan-path}
@@ -71,9 +76,22 @@ 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.
+Spawned via `Task(subagent_type="general-purpose", ...)` — see
+`.jdi/framework/jedi.md` Critical Constraints for why.
+
+### `source: claude-code` — registered Claude Code subagent
+
+```
+Your agent definition has already been loaded by Claude Code from
+.claude/agents/{task.agent}.md — follow it. Also read
+.jdi/framework/components/meta/AgentBase.md for the JDI base protocol.
+
+<same TEAM / PLAN / TASK_FILE / WORKING_DIR block + steps + report as above>
+```
+
+Spawned via `Task(subagent_type="{task.agent}", ...)` — Claude Code validates
+the subagent type against its registered list. See
+`.jdi/framework/components/meta/AgentRouter.md` §4 for full rules.
 
 ---
 

package/framework/components/meta/ComplexityRouter.md

@@ -40,21 +40,28 @@ reasoning: "{why this mode was chosen}"
 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`.
+**Pinning rule:** read `primary_agent` from the plan index frontmatter and the
+matching `source:` from `available_agents`. Verify the agent exists:
+
+- `source: jdi` → check `.jdi/framework/agents/{name}.md` (or
+  `framework/agents/{name}.md` in the self-hosting jedi repo)
+- `source: claude-code` → check `.claude/agents/{name}.md` or
+  `~/.claude/agents/{name}.md`
+
+If unset or not found, fall back to `general-purpose` and record an
+`agent_downgrade:` note in the summary. Never silently default to
+`general-purpose` when a pin exists.
+See `.jdi/framework/components/meta/AgentRouter.md` §4 for full spawn rules.
+
+### JDI specialist (source: jdi — the common case)
 
 ```
 Task(
-  subagent_type: "{plan.primary_agent}",   # e.g. unity-specialist — NOT hardcoded
+  subagent_type: "general-purpose",   # MUST be general-purpose for JDI agents
   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.
+  prompt: "You are {plan.primary_agent}. Read .jdi/framework/agents/{plan.primary_agent}.md
+for your full role and instructions. Also read
+.jdi/framework/components/meta/AgentBase.md for the JDI base protocol.
 
 ## Project Context
 - Type: {project_type}
@@ -70,6 +77,19 @@ Report: files_modified, files_to_create, commits_pending."
 )
 ```
 
+### Claude Code registered specialist (source: claude-code)
+
+```
+Task(
+  subagent_type: "{plan.primary_agent}",   # e.g. unity-specialist
+  name: "{plan.primary_agent}",
+  prompt: "Your agent definition has already been loaded from .claude/agents/.
+Also read .jdi/framework/components/meta/AgentBase.md for the JDI base protocol.
+
+<same Project Context + Task sections as above>"
+)
+```
+
 No TeamCreate, no TaskCreate, no cross-agent coordination.
 
 ### Legacy fallback (no pins)