@benzotti/jdi 0.1.46

package/framework/components/meta/AgentRouter.md

@@ -0,0 +1,318 @@
+---
+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. 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/jdi.md` Critical Constraints).
+
+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 JDI 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` — 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
+
+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 commands (reference — the planner uses `Glob` + `Read`):
+
+```bash
+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
+`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: 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
+    source: claude-code
+    description: Unity API patterns and optimisation (user-added)
+```
+
+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.
+
+---
+
+## 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` |
+| 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` |
+
+### JDI meta-framework routing
+
+Use these pins when the work being done is on the JDI 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.
+
+---
+
+## 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 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/jdi.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}",   # 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 `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 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}",
+  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`) spawned via the `source: jdi` pattern.
+
+### Mixed fallbacks
+
+- 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.
+
+---
+
+## 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. 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 JDI repo)
+   over `.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

@@ -0,0 +1,115 @@
+---
+name: AgentTeamsOrchestration
+category: meta
+description: Agent Teams orchestration quick-reference
+---
+
+# AgentTeamsOrchestration
+
+## Core Pattern (6 Steps)
+
+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, 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)
+
+---
+
+## Task Routing Table
+
+**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 Templates (~200 tokens)
+
+### `source: jdi` — JDI framework specialist (common case)
+
+```
+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}
+TASK_FILE: {task-file-path}
+WORKING_DIR: {working-directory}
+
+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
+3. Mark task completed via TaskUpdate
+
+Report: files_modified, files_to_create, commits_pending.
+No git commit (use commits_pending).
+```
+
+Spawned via `Task(subagent_type="general-purpose", ...)` — see
+`.jdi/framework/jdi.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.
+
+---
+
+## Deferred Operations Checklist
+
+After all specialist tasks complete:
+
+1. **Collect** — Aggregate `files_modified`, `files_to_create`, `commits_pending` from all SendMessage results
+2. **Create files** — Write tool for each `files_to_create` entry
+3. **Execute commits** — `git add` + `git commit` for each `commits_pending` entry
+4. **Record hashes** — Store real commit hashes in state.yaml
+5. **Verify** — Confirm all `files_modified` are present in working tree
+
+---
+
+## Team Lifecycle
+
+```
+TeamCreate → Spawn agents → Monitor (auto message delivery) →
+Collect results → Deferred ops → shutdown_request → TeamDelete
+```

package/framework/components/meta/ComplexityRouter.md

@@ -0,0 +1,116 @@
+# ComplexityRouter Component
+
+Evaluates plan complexity and returns the routing decision for implement-plan.
+
+---
+
+## Decision Matrix
+
+Read the plan index file (frontmatter + task manifest table) and extract these signals:
+
+| Signal | Simple | Complex |
+|--------|--------|---------|
+| Task count | ≤3 | >3 |
+| Tech stacks | Single (PHP-only OR TS-only) | Mixed (PHP + TS/React) |
+| Wave count | 1 (all tasks parallel or sequential) | >1 (multi-wave dependencies) |
+
+**Routing rule:** If ANY signal is "Complex" → use Agent Teams mode. All signals must be "Simple" for single-agent mode.
+
+**Override flags:**
+- `--team` in command arguments → force Agent Teams mode
+- `--single` in command arguments → force single-agent mode
+
+---
+
+## Output
+
+After evaluation, set the routing decision:
+
+```yaml
+mode: single-agent | agent-teams
+primary_agent: jdi-backend | jdi-frontend  # based on tech stack
+secondary_agents: []  # only populated in agent-teams mode
+reasoning: "{why this mode was chosen}"
+```
+
+---
+
+## Single-Agent Mode
+
+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 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 JDI 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: "general-purpose",   # MUST be general-purpose for JDI agents
+  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.
+
+## Project Context
+- Type: {project_type}
+- Tech stack: {tech_stack}
+- Quality gates: {quality_gates}
+- Working directory: {cwd}
+
+## 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.
+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)
+
+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
+
+Follow full orchestration from `.jdi/framework/components/meta/AgentTeamsOrchestration.md`:
+TeamCreate → TaskCreate per plan task → spawn specialists per tech-stack routing → wave-based coordination → collect deferred ops → shutdown → TeamDelete.
+
+---
+
+## Usage
+
+```
+<JDI:ComplexityRouter />
+```
+
+Referenced by implement-plan command stub. Evaluates at orchestration time, before any agents are spawned.

package/framework/components/meta/SilentDiscovery.md

@@ -0,0 +1,79 @@
+# SilentDiscovery Component
+
+The mandatory state-reading preamble that runs before any user-facing prompt in a JDI skill. Its purpose: make sure you never re-ask the user for facts that are already on disk.
+
+When a command references `<JDI:SilentDiscovery />`, you MUST gather context from the filesystem before presenting any question, routing decision, or recommendation. Store what you find internally as `DISCOVERED_STATE` — do NOT print discovery output to the user unless a later step explicitly calls for it.
+
+---
+
+## What to Read
+
+Read these files if they exist. If a file is missing, record that in `DISCOVERED_STATE` as `missing: true` and continue — do not error.
+
+| File | Purpose |
+|------|---------|
+| `.jdi/config/state.yaml` | Current phase, plan, task, and status. Source of truth for "where are we?" |
+| `.jdi/PROJECT.yaml` | Tech stack, project name, team configuration |
+| `.jdi/REQUIREMENTS.yaml` | Risks, constraints, non-functional requirements |
+| `.jdi/ROADMAP.yaml` | Phase structure, upcoming plans, milestones |
+| `.jdi/plans/*.plan.md` (glob) | Existing plan index files — check frontmatter for `provides`, `status`, completion |
+| `.jdi/codebase/SUMMARY.md` | Codebase index, if present |
+
+Additionally, if the skill is worktree-aware, read:
+
+| File | Purpose |
+|------|---------|
+| `.jdi/config/state.yaml → worktree` | Active worktree path and status |
+
+---
+
+## What to Derive
+
+From the raw reads above, compute and store these derived fields in `DISCOVERED_STATE`:
+
+- **`active_phase`** — current phase number and name (from ROADMAP.yaml + state.yaml position)
+- **`next_plan_number`** — next available plan id in the active phase (scan existing plan files)
+- **`tech_stack`** — from PROJECT.yaml
+- **`open_risks`** — from REQUIREMENTS.yaml `risks:` block (empty list if none)
+- **`prior_provides`** — union of all `provides:` fields from completed plans (cross-phase dependency map)
+- **`returning_user`** — true if any prior plans are completed or the current plan is in a non-initial status
+- **`missing_scaffolding`** — list of scaffolding files that didn't exist
+
+---
+
+## Discipline Rules
+
+These rules are non-negotiable when this component is referenced:
+
+1. **Silent by default.** Never print `DISCOVERED_STATE` as a conversation opener. It informs your recommendations; it is not the first thing the user sees.
+
+2. **Never re-ask what's already known.** If a fact is in `DISCOVERED_STATE`, treat it as authoritative. Do not ask "what's your tech stack?" if `DISCOVERED_STATE.tech_stack` is set.
+
+3. **Missing ≠ empty.** A missing file means "I don't know" — not "the user has no preferences". Record `missing: true` and surface it only if a later step needs that file.
+
+4. **Surface selectively.** When routing or recommending, pull the specific field you need and mention it briefly ("I can see you're on phase {n}, plan {id}..."). Do not dump the whole `DISCOVERED_STATE` object.
+
+5. **Refresh, don't stale.** If the skill has multiple passes (e.g. `/jdi:build` option D re-runs discovery after user input), re-read the files — do not rely on the first pass's findings for the second pass.
+
+---
+
+## Pass-Through to Spawned Agents
+
+When a skill that uses SilentDiscovery spawns a subagent (e.g. `create-plan` spawns `jdi-planner`), pass `DISCOVERED_STATE` into the spawn prompt as a named block:
+
+```
+Context already discovered: {DISCOVERED_STATE serialised as yaml}
+Do NOT re-read these scaffolding files. Surface open questions ONLY for facts you cannot infer from this block.
+```
+
+This avoids the common failure where the orchestrator reads scaffolding, spawns an agent, and the agent reads the same scaffolding again.
+
+---
+
+## Usage
+
+```
+<JDI:SilentDiscovery />
+```
+
+Referenced at the top of a skill's numbered workflow, typically as step 1 or 2. Always runs before any user-facing prompt.

package/framework/components/meta/StateUpdate.md

@@ -0,0 +1,56 @@
+---
+name: StateUpdate
+category: meta
+description: Record decisions, deviations, and blockers in state.yaml
+---
+
+# StateUpdate
+
+> **Status transitions are handled via CLI commands.** Do NOT manually edit `position`, `progress`, `current_plan`, `review`, or `session` fields in state.yaml. Use these commands instead:
+>
+> - `npx jdi state plan-ready --plan-path "{path}" --plan-name "{name}"`
+> - `npx jdi state approved`
+> - `npx jdi state executing`
+> - `npx jdi state complete`
+> - `npx jdi state advance-task {task-id}`
+
+Use state.yaml ONLY to record decisions, deviations, or blockers:
+
+## Record Decision
+
+Append to `decisions` array in `state.yaml`:
+
+```yaml
+- timestamp: "{ISO}"
+  phase: "{phase}"
+  decision: "{description}"
+  rationale: "{why}"
+  impact: "{what it affects}"
+```
+
+## Record Blocker
+
+Append to `blockers` array in `state.yaml`:
+
+```yaml
+- timestamp: "{ISO}"
+  type: "technical|external|decision"
+  description: "{what's blocked}"
+  impact: "{what can't proceed}"
+  resolution: null
+```
+
+## Record Deviation
+
+Append to `deviations` array in `state.yaml`:
+
+```yaml
+- timestamp: "{ISO}"
+  rule: "Rule 1|Rule 2|Rule 3|Rule 4"
+  description: "{what deviated}"
+  reason: "{why}"
+  task: "{task context}"
+  files: ["{affected files}"]
+```
+
+Deviation rules: 1=Auto-fixed bug, 2=Auto-added critical functionality, 3=Auto-fixed blocking issue, 4=Asked about architectural change.