@benzotti/jedi 0.1.42 → 0.1.45

package/framework/commands/create-plan.md

@@ -1,39 +1,192 @@
 ---
 name: create-plan
 description: "JDI: Create implementation plan"
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+argument-hint: "<feature to plan> [--worktree | --worktree-lightweight | --status]"
+context: |
+  !cat .jdi/config/state.yaml 2>/dev/null | head -25
+  !ls .jdi/plans/*.plan.md 2>/dev/null | tail -5
 ---
 
 # /jdi:create-plan
 
-Create an implementation plan using a single planner agent (includes research).
+Create an implementation plan using a single planner agent (includes research). Deterministic workflow — every invocation follows the same numbered steps, in order, without skipping.
+
+**This skill follows `<JDI:StrictnessProtocol />` and `<JDI:SilentDiscovery />`. Read those components before executing any step below.**
+
+---
 
 ## Flags
 
 - `--worktree` — Create git worktree with full environment before planning (follow `.claude/commands/jdi/worktree.md` steps)
 - `--worktree-lightweight` — Same but skip databases/web server (deps + migrate only)
+- `--status` — Status mode: generate a plan progress report using `state.yaml` + the current plan. Does NOT spawn the planner. See Status Mode section below.
 
 > **Do NOT use the built-in `EnterWorktree` tool.** Always follow `/jdi:worktree` Direct Execution steps.
 
-## Orchestration
-
-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. **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}"
-   ```
-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**.
+---
+
+## Status Mode (`--status`)
+
+When `--status` is passed, run this workflow instead of the planning workflow. All other flags are ignored.
+
+### 1. Read State
+
+Read `.jdi/config/state.yaml` and the current plan file (index + every task file listed in `task_files:`).
+
+### 2. Generate Tables
+
+Produce four tables — **Completed**, **In Progress**, **Blocked**, **Not Started** — listing each task with its `agent:` pin, `priority:` band, and any notes pulled from state.
+
+### 3. Output and Stop
+
+Print the report to stdout. Then **STOP**. Do NOT spawn the planner. Do NOT write any files. Do NOT advance state. The user may run `/jdi:create-plan "<feature>"` (without `--status`) when they want to plan new work.
+
+---
+
+## Orchestration (Planning Mode)
+
+The steps below are numbered and ordered. Do NOT skip, merge, or reorder them. Each step ends with a clear state transition — if you cannot produce that transition, STOP and ask.
+
+### 1. Worktree Setup (if flagged)
+
+If `--worktree` or `--worktree-lightweight` is present, derive a branch name from the task description, follow the Direct Execution steps in `framework/commands/worktree.md`, and `cd` into `.worktrees/<name>`. Confirm the working directory changed before proceeding.
+
+If no worktree flag is present, skip this step entirely — do not mention it to the user.
+
+### 2. Silent Discovery
+
+Execute `<JDI:SilentDiscovery />` now. Read the scaffolding files listed in that component and store the result internally as `PRE_DISCOVERED_CONTEXT`. Do NOT print the discovery output to the user.
+
+**Additional reads for this skill:**
+- `.jdi/REQUIREMENTS.yaml` → `risks:` block (for the planner's Risks section)
+- Prior plan's `SUMMARY.md` if it exists (for carryover candidates)
+- `.jdi/codebase/SUMMARY.md` if it exists (for codebase context)
+
+Append these to `PRE_DISCOVERED_CONTEXT`.
+
+**If scaffolding files are missing:** record `missing: true` for each in `PRE_DISCOVERED_CONTEXT`. Do not error. The planner will create missing files from templates in step 5.
+
+### 3. Agent Discovery
+
+Enumerate available agents in this order (earlier roots override later ones on name collision). For each discovered `.md` file, read the frontmatter `name:` and `description:` and record a `source:` field so `implement-plan` picks the correct spawn pattern.
+
+1. **JDI framework specialists (primary — `source: jdi`)** — list `.jdi/framework/agents/jdi-*.md` (installed projects). If that directory does not exist, fall back to `framework/agents/jdi-*.md` (self-hosting jedi repo).
+2. **Project-local Claude Code subagents (`source: claude-code`)** — list `.claude/agents/*.md`.
+3. **User-global Claude Code subagents (`source: claude-code`)** — list `~/.claude/agents/*.md`.
+
+Store the merged catalogue as `AVAILABLE_AGENTS`. If none of the roots exist, set `AVAILABLE_AGENTS = []`. Do NOT fail.
+
+> **Why source matters:** JDI specialists (`jdi-backend`, `jdi-frontend`, etc.) are NOT registered Claude Code subagents — they live in `framework/agents/`. `implement-plan` must spawn them via `subagent_type="general-purpose"` with identity injected via prompt text. Registered Claude Code subagents (`source: claude-code`) can be spawned by name directly. See `framework/jedi.md` Critical Constraints and `framework/components/meta/AgentRouter.md` §4.
+
+See `framework/components/meta/AgentRouter.md` §1 for the full discovery + routing rules the planner will apply.
+
+### 4. Quick Mode Detection
+
+If the feature description looks trivial (single file, <30 minutes, no architectural impact — e.g. "rename var X", "add a log line"), recommend `/jdi:quick "<description>"` instead. Present this as a suggestion, not a redirect:
+
+> "This looks small enough for `/jdi:quick`, which skips the planner entirely. Want to use that instead, or stick with `/jdi:create-plan`?"
+
+**Wait for the user's answer. Do not proceed until they respond.** If they pick quick, STOP — do not spawn the planner.
+
+### 5. Spawn Planner
+
+Spawn `jdi-planner` via `Task(subagent_type="general-purpose")`. The spawn prompt MUST include:
+
+- The feature description (`$ARGUMENTS`)
+- `PRE_DISCOVERED_CONTEXT` as a YAML block — planner must NOT re-read scaffolding
+- `AVAILABLE_AGENTS` catalogue — planner pins specialists via AgentRouter
+- Explicit instruction: _"Do NOT re-prompt the user for anything already in PRE_DISCOVERED_CONTEXT. Surface open questions ONLY for facts you cannot infer."_
+- Spec path: `.jdi/framework/agents/jdi-planner.md`
+
+The planner creates split plan files (index `.plan.md` + per-task `.T{n}.md` files) directly via Write tool (sandbox override for plan files). It writes `available_agents:` into the index frontmatter and pins an `agent:` field in every task file.
+
+### 6. Verify Planner Output
+
+After the planner returns, confirm:
+
+- Index file `.jdi/plans/{plan-id}.plan.md` exists
+- Every entry in `task_files:` exists on disk
+- Every task file's frontmatter contains an `agent:` field (unless `AVAILABLE_AGENTS` was empty)
+- The index frontmatter contains `available_agents:` matching what you passed in
+
+If any check fails, STOP and report the gap to the user. Do not advance state on incomplete output.
+
+### 7. Execute Deferred Ops
+
+If the planner returned `files_to_create` (scaffolding it could not write inside its sandbox), create those files now via the Write tool.
+
+### 8. Update State
+
+Run the state CLI — do NOT manually edit `state.yaml`:
+
+```bash
+bun run src/index.ts state plan-ready --plan-path ".jdi/plans/{plan-file}" --plan-name "{plan name}"
+```
+
+(In installed projects: `npx jdi state plan-ready ...`)
+
+### 9. Present Summary
+
+Present the plan summary to the user:
+
+- Plan name, objective, and sprint goal
+- Task manifest table: `ID | Task | Agent | Priority | Requires`
+- Any open questions the planner surfaced
+- File list (index + task files)
+
+End with the exact prompt: _"Provide feedback to refine, or say **approved** to finalise."_
+
+**Wait for the user's answer. Do not advance state. Do not invoke any other skill. Do not begin implementation.**
+
+### 10. Review Loop
+
+- **Feedback:** apply the requested changes in place (edit existing plan files, increment revision counter in frontmatter), re-present the summary, and ask the same question again.
+- **Approval** (user says "approved", "lgtm", "looks good", or equivalent): run `bun run src/index.ts state approved`, output the completion message, and STOP.
+
+**Never loop back to step 5.** Feedback refines; it does not restart.
+
+---
+
+## Edge Cases
+
+Pre-written responses for known deviations. When one applies, follow the scripted response rather than improvising.
+
+| Situation | Response |
+|-----------|----------|
+| Scaffolding files missing (`.jdi/PROJECT.yaml` etc.) | Planner creates them from `framework/templates/` in step 5. Do NOT ask the user for values the template's defaults cover. |
+| `.claude/agents/` empty on both levels | Set `AVAILABLE_AGENTS = []`, note in summary, and proceed. The planner falls back to tech-stack defaults. |
+| Feature description is vague ("improve X") | Ask 2-3 targeted follow-ups BEFORE spawning the planner. Do not waste a planner invocation on an underspecified prompt. |
+| Worktree flag but worktree already exists | Ask the user: reuse the existing worktree, or pick a new name? Do not silently proceed. |
+| `--status` with no current plan | Output "No current plan — run `/jdi:create-plan \"<feature>\"` to create one" and STOP. |
+| Planner returns without writing any files | STOP, report the failure, do NOT advance state. Ask the user to re-invoke or debug. |
+| User asks to implement during review loop | Remind them of the gate: "Planning and implementation are separate phases. Say `approved` to lock in the plan, then run `/jdi:implement-plan`." Do NOT auto-advance. |
+
+---
 
 ## 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.
+After the user approves the plan, your work is **DONE**.
+
+Output exactly: _"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.
+- Do NOT suggest implementation commands beyond the one-line completion message.
+
+Planning and implementation are separate human-gated phases. This gate exists because past sessions have drifted into implementation immediately after approval, producing work the user did not sanction.
+
+---
+
+## Collaborative Protocol
+
+<JDI:StrictnessProtocol />
+
+---
 
-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
+**References:** 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
+**Feature to plan:** $ARGUMENTS

package/framework/commands/generate-pr.md

@@ -1,19 +1,91 @@
 ---
 name: generate-pr
-description: "JDI: Generate pull request"
+description: "JDI: Generate comprehensive PR description and create the pull request"
+allowed-tools: Read, Bash, Task
+argument-hint: "[optional context hint]"
+context: |
+  !git branch --show-current 2>/dev/null
+  !git log --oneline main..HEAD 2>/dev/null | head -15
 ---
 
 # /jdi:generate-pr
 
-Generate a comprehensive PR description and create the pull request.
+Generate a PR description from the current branch's commits and create the pull request via the `jdi-pr-generator` specialist.
 
-## Delegation
+**This skill follows `<JDI:StrictnessProtocol />`. Read that component before executing any step below.**
 
-**Agent:** jdi-pr-generator
+---
+
+## Orchestration
+
+### 1. Branch Pre-flight
+
+Run these checks in parallel:
+
+- `git branch --show-current` — confirm we're not on `main`/`master`
+- `git log --oneline main..HEAD` — confirm there are commits to include
+- `git status --short` — confirm working tree is clean
+
+If any check fails, STOP and report:
+
+| Failure | Message |
+|---------|---------|
+| On `main`/`master` | "You're on the base branch. Switch to a feature branch first." |
+| Zero commits ahead of base | "No commits to include in a PR. Make commits first." |
+| Dirty working tree | "Working tree has uncommitted changes. Commit or stash before generating a PR." |
+
+### 2. Existing PR Check
+
+Run `gh pr list --head {current-branch}`. If a PR already exists for this branch, STOP:
+
+> "PR #{existing} already exists for this branch. Use `/jdi:pr-feedback` to address comments, or update the existing PR directly."
+
+### 3. Delegate to jdi-pr-generator
+
+Spawn the specialist via Task tool. JDI specialists spawn as `general-purpose` with identity injected via prompt text:
+
+```
+Task(
+  subagent_type="general-purpose",
+  prompt="You are jdi-pr-generator. Read .jdi/framework/agents/jdi-pr-generator.md
+  for your full role and instructions. Also read
+  .jdi/framework/components/meta/AgentBase.md for the JDI base protocol.
+
+  Generate PR for current branch. Context hint: $ARGUMENTS"
+)
+```
 
-Use Task tool with subagent_type="general-purpose" and prompt:
+### 4. Confirm Before Creating
 
-Read ./.jdi/framework/components/meta/AgentBase.md for the base protocol.
-You are jdi-pr-generator. Read ./.jdi/framework/agents/jdi-pr-generator.md for instructions.
+The generator returns a draft title and body. Present both to the user and ask:
+
+> "Create the PR with this title and body, or revise first?"
+
+**Wait for the user's answer. Do NOT auto-run `gh pr create`.** Creating a PR is visible to collaborators — it requires explicit approval.
+
+### 5. Create PR
+
+On approval, run `gh pr create` with the confirmed title and body. Report the PR URL. Then **STOP**.
+
+---
+
+## Edge Cases
+
+| Situation | Response |
+|-----------|----------|
+| On `main`/`master` | STOP at step 1. Refuse to generate. |
+| No commits ahead of base | STOP at step 1. Nothing to PR. |
+| Dirty working tree | STOP at step 1. Ask the user to commit or stash. |
+| Existing PR for branch | STOP at step 2. Redirect to `/jdi:pr-feedback`. |
+| `gh` not authenticated | Report the error verbatim. Do NOT attempt to create the PR via other means. |
+| User wants to target a non-default base | Pass the base to `gh pr create --base {branch}` at step 5, after explicit confirmation. |
+
+---
+
+## Collaborative Protocol
+
+<JDI:StrictnessProtocol />
+
+---
 
-Generate PR for current branch: $ARGUMENTS
+**Context:** $ARGUMENTS

package/framework/commands/implement-plan.md

@@ -1,38 +1,218 @@
 ---
 name: implement-plan
 description: "JDI: Execute implementation plan"
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+argument-hint: "[--team | --single | --dry-run | --skip-qa]"
+context: |
+  !cat .jdi/config/state.yaml 2>/dev/null | head -30
 ---
 
 # /jdi:implement-plan
 
-Execute a PLAN.md with complexity-based routing.
+Execute an approved plan with complexity-based routing. Deterministic workflow — every invocation follows the same numbered steps, in order, without skipping.
 
-**Flags:** `--team` (force Agent Teams) | `--single` (force single agent) | `--dry-run` (preview without writing)
+**This skill follows `<JDI:StrictnessProtocol />` and `<JDI:SilentDiscovery />`. Read those components before executing any step below.**
+
+---
+
+## Flags
+
+- `--team` — Force Agent Teams mode regardless of complexity signals
+- `--single` — Force single-agent mode regardless of complexity signals
+- `--dry-run` — Preview without writing: list files that would change and agents that would be spawned, then STOP
+- `--skip-qa` — Skip the post-task `jdi-qa-tester` verification pass
 
 > **Do NOT use the built-in `EnterWorktree` tool.** If `state.yaml` has `worktree.active: true`, just `cd` into `worktree.path`.
 
+---
+
 ## 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, `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. **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`.
-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 | 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.
-
-Plan to execute: $ARGUMENTS
+The steps below are numbered and ordered. Do NOT skip, merge, or reorder them. Each step ends with a clear state transition — if you cannot produce that transition, STOP and ask.
+
+### 1. Silent Discovery
+
+Execute `<JDI:SilentDiscovery />` now. Read the scaffolding files listed in that component and store the result internally as `DISCOVERED_STATE`. Do NOT print the discovery output to the user.
+
+**Additional reads for this skill:**
+- `.jdi/codebase/SUMMARY.md` if it exists
+- `.jdi/framework/learnings/general.md` (always)
+- Domain-specific learnings based on `DISCOVERED_STATE.tech_stack`: PHP → `backend.md`, TS/React → `frontend.md`, testing → `testing.md`, devops → `devops.md`
+
+Learnings override defaults. Record which learnings files were found in `DISCOVERED_STATE.learnings_loaded`.
+
+### 2. Load Plan
+
+Read the plan index file (path from `$ARGUMENTS` or from `DISCOVERED_STATE.current_plan.path`). Parse the frontmatter for:
+
+- `tasks:` or `task_files:` (legacy monolithic vs split plan)
+- `deps:` and `waves:`
+- `tech_stack:`
+- `available_agents:` catalogue
+- `primary_agent:` pin
+
+**Format detection:** if frontmatter contains `task_files:`, this is a split plan — read each task file's frontmatter in a single batch. If absent, this is a legacy monolithic plan — all tasks are inline in the index.
+
+**Plan status gate:** if the plan's status in `state.yaml` is not `approved`, STOP and tell the user: "Plan is in status `{status}` — run `/jdi:create-plan` (or the review loop) to reach `approved` before implementing."
+
+### 3. Resolve Per-Task Agents
+
+For every task file listed in `task_files:`, record the `agent:` field from its frontmatter. This is the `subagent_type` you will pass to the Task tool when spawning.
+
+**Resolution order:**
+1. Task-level `agent:` pin from the task file frontmatter
+2. Plan-level `primary_agent:` from the index frontmatter
+3. Tech-stack default: PHP → `jdi-backend`, TS/React → `jdi-frontend`, otherwise → `general-purpose`
+
+**NEVER default everything to `general-purpose` silently.** See `framework/components/meta/AgentRouter.md`.
+
+### 4. Agent Existence Check
+
+For each pinned agent, read the matching `source:` from the plan's `available_agents` catalogue and confirm the spec exists:
+
+- **`source: jdi`** — check `.jdi/framework/agents/{name}.md` (installed projects) or `framework/agents/{name}.md` (self-hosting jedi repo)
+- **`source: claude-code`** — check `.claude/agents/{name}.md` (project-local) or `~/.claude/agents/{name}.md` (user-global)
+
+If the spec is NOT found, downgrade to `general-purpose` (with a `jdi-backend` / `jdi-frontend` spec load in the prompt) and record an `agent_downgrade:` entry listing the original pin, the downgrade target, and the reason. This entry MUST appear in the final summary — never silently change a pin.
+
+### 5. Complexity Routing
+
+Apply `<JDI:ComplexityRouter />`:
+- **Simple** (≤3 tasks, single stack/wave) → single-agent mode
+- **Complex** (>3 tasks OR multi-stack OR multi-wave) → Agent Teams swarm
+
+**Override flags:** `--team` forces Agent Teams mode; `--single` forces single-agent mode. Overrides win over complexity signals.
+
+Record the routing decision and reasoning in `DISCOVERED_STATE.routing`.
+
+### 6. Dry Run Check
+
+If `--dry-run` is present, output:
+- The resolved agent per task
+- Any `agent_downgrade:` entries
+- The routing decision
+- The list of files each task claims to touch (from task spec)
+
+Then **STOP**. Do NOT spawn agents, do NOT advance state, do NOT edit files.
+
+### 7. Advance State to Executing
+
+Run `bun run src/index.ts state executing` (in installed projects: `npx jdi state executing`). Do NOT manually edit `state.yaml`.
+
+### 8. Spawn and Execute
+
+**Platform constraint:** JDI specialists (`source: jdi`) are NOT registered Claude Code subagents and MUST be spawned via `subagent_type="general-purpose"` with identity injected via prompt text (`"You are {agent}. Read .jdi/framework/agents/{agent}.md..."`). Registered Claude Code subagents (`source: claude-code`) are spawned directly by name. See `framework/jedi.md` Critical Constraints and `framework/components/meta/AgentRouter.md` §4.
+
+**Single-agent mode:**
+- `source: jdi` → `Task(subagent_type="general-purpose", prompt="You are {plan.primary_agent}. Read .jdi/framework/agents/{plan.primary_agent}.md... PLAN: {index-path}")`
+- `source: claude-code` → `Task(subagent_type="{plan.primary_agent}", prompt="<standard spawn prompt> PLAN: {index-path}")`
+
+For split plans, the agent reads task files one at a time via the `file:` field in `state.yaml`.
+
+**Agent Teams mode:** Spawn ONE Task call per task using the source-aware pattern above. Pass `TASK_FILE: {task-file-path}` so the agent loads only its assigned task.
+
+**Prompt scoping rules (non-negotiable):**
+- One task = one spawn. Never bundle multiple tasks into one prompt.
+- Give exact file paths. Cap exploration explicitly: "read only your TASK_FILE and the files it names."
+- Request short reports (<400 words). Agents can be truncated mid-task; scoped prompts survive the budget ceiling.
+- Include a `## Project Context` block in every spawn prompt: type, tech stack, quality gates, working directory. Saves 2-3 discovery tool calls per spawn.
+- For split plans, the agent reads the `TASK_FILE` itself — do not inline task content into the prompt.
+
+**Wave-based execution:** honour `waves:` from the plan frontmatter. Spawn all tasks in wave N in parallel; wait for all returns before starting wave N+1.
+
+### 9. Advance Task State
+
+After each task's programmer returns successfully, run:
+
+```bash
+bun run src/index.ts state advance-task {task-id}
+```
+
+Do NOT advance state for tasks that failed or were skipped. Do NOT batch advance calls — advance per task, in order.
+
+### 10. Post-Task Verify (jdi-qa-tester)
+
+After each task's programmer returns, invoke `jdi-qa-tester` in `post-task-verify` mode with the task's `done_when` criteria and `files_modified` list. If verification fails with **S1** or **S2** severity, **halt the plan** and escalate to the user. Otherwise record the verification result in the task summary and proceed to commit.
+
+- **a11y-check trigger:** if `files_modified` includes UI files (components, views, templates, CSS affecting render), additionally invoke `jdi-qa-tester` in `a11y-check` mode and record the result in the same task summary.
+- **contract-check trigger:** if `files_modified` includes contract-bearing files — API routes, Controllers/Actions, DTOs, FormRequests, OpenAPI specs, exported TypeScript types, `packages/*/src/index.ts`, DB migrations, generated client code — additionally invoke `jdi-qa-tester` in `contract-check` mode. Treat any contract failure as at least **S2** and halt the plan.
+- **Skip rules:** Skipped entirely if `--skip-qa` is passed. Also skipped automatically if `files_modified` contains ONLY `.md`, `.yaml`, or `.yml` files (documentation/config doesn't get regression-tested). The programmer's structured return field `qa_verification_needed: false` is also honoured.
+- **Contract-check exception to the skip rule:** if any file in `files_modified` is a contract-bearing YAML/JSON spec (OpenAPI / Swagger — e.g. `openapi.yaml`, `swagger.json`, `api/*.yaml`, `**/openapi*.{yml,yaml,json}`; GraphQL SDL — `**/*.graphql`, `**/schema.gql`; JSON Schema — `**/schemas/**/*.json`), still invoke `contract-check` even when the doc-only skip rule would otherwise apply. `post-task-verify` and `a11y-check` remain skipped in this case — only `contract-check` runs.
+
+### 11. Execute Deferred Ops
+
+Collect `files_to_create` returns from every agent and execute them via Write tool. Apply any pending commit operations. Do NOT skip this step — sandbox-returned artefacts are real work.
+
+### 12. Run Verification Gates
+
+Execute the project's quality gates in order: tests, lint, typecheck (exact commands come from `DISCOVERED_STATE.quality_gates`). Record pass/fail per gate.
+
+If any gate fails, STOP — do not advance state to `complete`. Report the failure and enter the review loop at step 14.
+
+### 13. Advance State to Complete
+
+Run `bun run src/index.ts state complete`. Do NOT manually edit `state.yaml`.
+
+### 14. Present Summary
+
+Present the implementation summary to the user:
+
+- Tasks completed (with per-task agent and verification result)
+- Files changed (grouped by task)
+- Quality gate results
+- Any `agent_downgrade:` events
+- Deviations from the spec
+
+End with the exact prompt: _"Provide feedback to adjust, or say **approved** to finalise."_
+
+**Wait for the user's answer. Do NOT suggest commits or PRs yet.**
+
+### 15. Review Loop
+
+- **Feedback:** apply the requested code changes, re-run verification gates, increment the revision counter, and re-present the summary.
+- **Approval:** suggest a conventional commit or PR generation as the next step. Do NOT auto-run either — the user decides.
+
+**Never loop back to step 8.** Feedback refines existing tasks; it does not re-spawn agents for tasks that already completed.
+
+---
+
+## Edge Cases
+
+Pre-written responses for known deviations. When one applies, follow the scripted response rather than improvising.
+
+| Situation | Response |
+|-----------|----------|
+| Plan status is not `approved` | STOP at step 2. Tell the user to approve the plan first. Do NOT force-advance. |
+| Pinned agent not installed | Downgrade to `general-purpose`, record the downgrade, continue. Surface in the final summary. |
+| Task file missing (listed in `task_files:` but not on disk) | STOP. Report the missing file. Do NOT advance state. |
+| Programmer returns with `status: blocked` | HALT the plan. Do NOT advance task state. Surface the blocker to the user and wait. |
+| QA verification S1 or S2 failure | HALT the plan immediately. Record the failure in state. Wait for user direction before continuing. |
+| Verification gate failure at step 12 | STOP before completing. Report the failure, enter review loop. Do NOT advance state to `complete`. |
+| `--dry-run` with no changes needed | Output "no-op: plan is already at target state" and STOP. |
+| Worktree active but path missing | Ask the user: recreate the worktree, or proceed in current directory? Do NOT silently proceed. |
+| Wave has zero tasks ready | Skip the empty wave, log it, continue to the next wave. |
+| User asks to skip verification during review | Remind them of `--skip-qa` flag semantics. Do NOT skip silently. |
+
+---
+
+## HARD STOP — Verification Gate
+
+Before presenting the summary (step 14), all three must be true:
+
+1. Every task has either `advance-task` applied OR a documented failure in the summary
+2. Every QA verification trigger that fired has a recorded result
+3. Every quality gate has passed OR been explicitly flagged as failing in the summary
+
+If ANY of these is not true, STOP. Do not present a summary that implies success when work remains. Silent gaps are the failure mode this gate exists to prevent.
+
+---
+
+## Collaborative Protocol
+
+<JDI:StrictnessProtocol />
+
+---
+
+**References:** 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`, `.jdi/framework/components/meta/AgentRouter.md`
+
+**Plan to execute:** $ARGUMENTS

package/framework/commands/pr-feedback.md

@@ -1,20 +1,75 @@
 ---
 name: pr-feedback
-description: "JDI: Address PR feedback"
+description: "JDI: Address PR review comments systematically"
+allowed-tools: Read, Bash, Task
+argument-hint: "<pr-number-or-url>"
+context: |
+  !git branch --show-current 2>/dev/null
 ---
 
 # /jdi:pr-feedback
 
-Address PR review comments systematically.
+Address review comments on a pull request via the `jdi-pr-feedback` specialist.
 
-## Delegation
+**This skill follows `<JDI:StrictnessProtocol />`. Read that component before executing any step below.**
 
-**Agent:** jdi-pr-feedback
+---
+
+## Orchestration
+
+### 1. Parse PR Reference
+
+Extract the PR number from `$ARGUMENTS`. Accept a bare number or a full GitHub URL. If neither is present, STOP and ask for one.
+
+### 2. Fetch Unresolved Comments
+
+Run `gh api repos/{owner}/{repo}/pulls/{number}/comments` (or equivalent) to confirm there are unresolved comments. If there are none, STOP:
+
+> "PR #{number} has no unresolved review comments. Nothing to address."
+
+### 3. Delegate to jdi-pr-feedback
+
+Spawn the specialist via Task tool. JDI specialists spawn as `general-purpose` with identity injected via prompt text:
+
+```
+Task(
+  subagent_type="general-purpose",
+  prompt="You are jdi-pr-feedback. Read .jdi/framework/agents/jdi-pr-feedback.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 all listed
+  components before starting.
+
+  Address feedback for PR: {pr-number}"
+)
+```
+
+### 4. Present Result
 
-Use Task tool with subagent_type="general-purpose" and prompt:
+After the specialist returns, summarise: comments addressed, files touched, commits made. End with:
 
-Read ./.jdi/framework/components/meta/AgentBase.md for the base protocol.
-You are jdi-pr-feedback. Read ./.jdi/framework/agents/jdi-pr-feedback.md for instructions.
-If your spec has requires_components in frontmatter, batch-read all listed components before starting.
+> "Feedback applied. Review the diff, then run `/jdi:commit` or push when ready."
+
+**Wait for the user's response. Do NOT auto-push.**
+
+---
+
+## Edge Cases
+
+| Situation | Response |
+|-----------|----------|
+| No PR reference | STOP at step 1. Ask for a number or URL. |
+| No unresolved comments | STOP at step 2. Nothing to do. |
+| Specialist cannot address a specific comment | Surface the blocker; the user decides whether to override or defer. |
+| Working tree dirty before start | Ask whether to stash, commit, or abort. Do NOT silently mix unrelated changes. |
+| PR is closed or merged | STOP and report — feedback on closed PRs is not actionable via this skill. |
+
+---
+
+## Collaborative Protocol
+
+<JDI:StrictnessProtocol />
+
+---
 
-Address feedback for PR: $ARGUMENTS
+**PR to address:** $ARGUMENTS