implement · diff
git:20260422.d71693a to git:20260425.a0c906f
147 added, 27 removed. Audit A to A.
---
name: implement
- description: Executes an approved plan by breaking work into parallelizable chunks and spawning implementation sub-agents. Automatically reviews the result for completeness. Use after a plan is approved.
- argument-hint: "[plan file path]"
+ description: Executes an approved plan with one primary implementation stream by default, using bounded parallel sidecars only when the write scopes are truly disjoint. Supports default Claude execution or an explicit Codex executor option. Automatically reviews the result for completeness and intent fidelity. Use after a plan is approved.
+ argument-hint: "[plan file path] [claude|codex|--codex]"
disable-model-invocation: true
---
# Implementation Agent
## Plan to Execute: $ARGUMENTS
- ## Step 1: Load and Review Plan
+ ## Step 1: Resolve Executor and Load Plan
- - If a path is provided: Read from $ARGUMENTS
+ Interpret `$ARGUMENTS` as:
+ - default: Claude execution
+ - `claude` or `--claude`: explicitly use Claude as the primary executor
+ - `--codex` or standalone `codex`: use Codex as the primary executor
+ - any remaining path-like argument: plan path
+
+ Examples:
+ - `/implement ./tmp/ready-plans/2026-04-21-foo.md`
+ - `/implement claude ./tmp/ready-plans/2026-04-21-foo.md`
+ - `/implement --codex ./tmp/ready-plans/2026-04-21-foo.md`
+ - `/implement codex ./tmp/ready-plans/2026-04-21-foo.md`
+
+ If Codex execution was explicitly requested but the Codex plugin is unavailable,
+ do not silently fall back to Claude. Tell the user and wait for direction.
+
+ - If a path is provided after parsing executor flags: Read from that path
- If no path: Find the most recent plan in `./tmp/ready-plans/`
- Review the plan to understand: implementation phases, task checklist, technical requirements, dependencies between tasks, and success criteria.
+ If the plan includes a `Source Artifacts` section or references a supporting
+ brief / dossier path, read those artifacts too before implementing.
+ Treat the sources of truth as:
+ - **Brief / intent artifact**: why this work exists, what outcome matters, and
+ what must not be optimized away
+ - **Plan**: execution shape, task ordering, file-level implementation details
+ - **Dossier**: supporting evidence and anchors, not the authoritative execution
+ contract
+
+ If no separate brief artifact exists, treat the plan's `Intent / Why`, `Locked
+ Decisions`, `Known Mismatches / Assumptions`, and success criteria as the
+ minimum intent source of truth.
+
+ Review the plan to understand: implementation phases, task checklist, technical
+ requirements, dependencies between tasks, success criteria, and original user
+ intent.
+
## Step 2: Identify Dangerous Commands
**BEFORE ANY IMPLEMENTATION**, scan the plan for commands that must NOT be run automatically:
- Environment variable changes
- Package installations that change `package.json`
- Any destructive operations
**Collect into a "Manual Steps" list** and present to the user before proceeding.
> **Note:** Schema/migration handling is done automatically in Step 5.5 after implementation and review — do NOT handle it here.
- ## Step 3: Break Plan into Chunks
+ ## Step 3: Choose Execution Strategy
- 1. **Identify Independent Units**: Group related tasks that can be completed together
- 2. **Respect Dependencies**: Schema before API, backend before frontend, types before implementations
- 3. **Chunk Size**: 2-5 related tasks with clear boundaries
+ Default to **one primary implementer** owning the plan end-to-end.
+ Only split work into parallel chunks when **all** of the following are true:
+ - write scopes are genuinely disjoint
+ - the integration contract between chunks is already clear in the plan
+ - parallelism will not hide missing last-mile wiring
+ - one primary implementer still owns final integration and finish-line checks
+
+ Keep these with the primary implementer unless there is an unusually clean
+ reason not to:
+ - schema and shared types
+ - routing / bootstrap / exports
+ - auth / permissions / tokens
+ - jobs / async orchestration / dispatch semantics
+ - final frontend-to-backend wiring
+
```
- Phase 1: Foundation (Sequential) → Schema, types
- Phase 2: Core (Parallel) → Backend chunks, frontend chunks
- Phase 3: Integration (Sequential) → Connect frontend to backend
+ Primary stream: schema/types → backend/runtime wiring → frontend wiring → finish-line verification
+ Optional sidecars: bounded disjoint tasks that cannot break the primary stream's integration work
```
- **Late-phase tasks have higher skip risk** — flag any cross-cutting items sitting in late phases and consider promoting them.
+ ## Step 4: Start the Primary Execution Lane
- ## Step 4: Spawn Implementation Agents
+ If the executor is **Claude**:
- Use `Task tool` with `subagent_type: "implementer"` for each chunk.
+ Use `Task tool` with `subagent_type: "implementer"` for the primary stream.
- - **Parallel**: Spawn multiple agents simultaneously for independent chunks
- - **Sequential**: Wait for dependent chunks to complete before next phase
- - Each agent prompt must include: specific tasks, relevant context, file paths, success criteria — AND re-inject the plan's cross-cutting constraints (gotchas, mismatches, scope guards), since sub-agents don't inherit harness-level context and anything not repeated per-phase gets silently dropped.
+ If you choose to parallelize, keep it bounded:
+ - **Primary implementer**: owns the mainline path and final integration
+ - **Sidecar implementers**: own only clearly disjoint file sets
+ - **Sequential**: wait whenever a later chunk depends on an earlier chunk's result
+ - Every agent prompt must include: specific tasks, relevant context, file paths, success criteria, and explicit ownership boundaries
+ - Every agent prompt must include the brief / intent source when available, not
+ just the task list
+ - Tell every implementer that a task is not complete until the end-to-end
+ runtime or user-facing path is actually wired and still preserves the brief's
+ intended outcome
- ## Step 5: Automatic Implementation Review
+ If the executor is **Codex** and the plugin is available:
- After all implementation agents complete, **automatically spawn an implementation-reviewer**:
+ - Use **one** primary `/codex:rescue --wait --fresh --model gpt-5.4 --effort high` run for the end-to-end implementation
+ - Pass the same implementation contract used for the Claude implementer:
+ - brief / intent artifact first, plan second
+ - one primary owner for the whole stream
+ - no silent scope drift
+ - finish-line runtime wiring required
+ - run `npm run typecheck` and `npm run lint` during the work
+ - update the plan progress where practical
+ - Do **not** launch multiple Codex rescue jobs for the same primary stream unless the user explicitly asks for more delegation
+ - Do **not** also spawn a Claude implementer for the same primary stream
+ Suggested Codex executor prompt:
+
```
+ /codex:rescue --wait --fresh --model gpt-5.4 --effort high implement the plan at [plan path]. Supporting brief / intent artifact: [path if available]. Treat the brief as the source of truth for why and the plan as the source of truth for how. You are the primary implementation authority for this run. Do not silently simplify or defer scope. A task is not complete until the end-to-end runtime or user-facing path is wired and still preserves the intended outcome. Run npm run typecheck and npm run lint as you work. Update the plan progress where practical and report any remaining manual steps or unresolved blockers clearly.
+ ```
+
+ ## Step 5: Parallel Review Gates
+
+ After the primary execution lane completes, always run a Claude
+ `implementation-reviewer` pass.
+
+ If the Codex plugin is available in this session, launch the Claude reviewer
+ and the Codex review lane in parallel and **wait for both** before continuing.
+ Do not treat the first result that returns as sufficient.
+
+ **Claude review lane:**
+
+ ```
Task tool:
subagent_type: "implementation-reviewer"
- prompt: "Review the implementation against the plan at [path].
+ prompt: "Review the implementation against the supporting brief / intent artifact first, then against the plan at [path].
+ Supporting brief / intent artifact: [path if available]. Treat the brief as the source of truth for why and the plan as the source of truth for how.
Run npm run typecheck and npm run lint.
Check every task in the plan was completed.
- Flag any gaps, missing integrations, or convention violations.
+ Flag any gaps, missing integrations, convention violations, or brief-intent regressions.
Report completeness status for each plan task."
```
+ **Codex review lane (if available):**
+
+ ```
+ /codex:review --wait review the implementation diff against the supporting brief / intent artifact first, then against [plan path]. Treat the brief as the source of truth for why and the plan as the source of truth for how. Focus on whether the code preserves the brief's intended outcome, still respects its constraints and non-goals, actually satisfies the plan, and reaches the finish line at runtime.
+ ```
+
+ ```
+ /codex:adversarial-review --wait focus on missing plan tasks, brief-intent regressions, runtime wiring, auth and permission gaps, transaction boundaries, race conditions, background-job registration, dead query-param flows, and whether the implementation actually reached the finish line
+ ```
+
+ After both lanes finish, combine the findings into one review result. Triage the
+ combined findings:
+ - **Auto-fixable** — apply the fixes directly
+ - **Needs user input** — surface clearly to the user
+
+ Do not ask the user questions from either lane before both lanes complete.
+ Always wait for every active review lane, merge overlapping findings, and then
+ present one combined set of user-facing questions or decisions.
+
+ If you apply fixes after either lane reports issues:
+ - rerun the Claude `implementation-reviewer`
+ - rerun `/codex:review` if the Codex plugin is available
+ - rerun `/codex:adversarial-review` too when the fixes affect architecture,
+ flow control, auth, async work, or finish-line wiring
+ - wait for all active review lanes again before continuing
+
+ If the Codex plugin is unavailable, run only the Claude review lane and treat
+ it as the review gate.
+
## Step 5.5: Generate Dev Migration SQL (If Schema Changed)
- After the implementation-reviewer completes, check if `schema.ts` was modified:
+ After the review gates are complete and any auto-fixable issues are resolved,
+ check if `schema.ts` was modified:
```bash
git diff origin/main --name-only | grep schema.ts
```
If schema.ts was changed:
1. Run `npm run db:diff:dev` and capture the output.
2. Present TWO separate blocks to the user:
**Schema changes (migration SQL):**
```sql
BEGIN;
-- the generated migration SQL here
COMMIT;
```
**Apply migration to dev database:**
```bash
npm run db:migrate:dev
```
(Or whatever the actual command is — run it and show the result.)
3. Only include additive SQL (CREATE, ADD). If destructive SQL (DROP, ALTER type) appears, flag it and ask the user to confirm before proceeding.
If schema.ts was NOT changed, skip this step silently.
## Step 6: Move Plan to Done
- Once all tasks pass review and the implementation is complete, move the plan file from `./tmp/ready-plans/` to `./tmp/done-plans/`:
+ Once all tasks pass the review gates, brief intent is still preserved, and the
+ implementation is complete, move the plan file from `./tmp/ready-plans/` to
+ `./tmp/done-plans/`:
```bash
mv ./tmp/ready-plans/<plan-file>.md ./tmp/done-plans/
```
- Create `./tmp/done-plans/` if it doesn't exist. Only move the plan when all tasks are confirmed complete — if the reviewer found unresolved issues, wait until they are fixed.
+ Create `./tmp/done-plans/` if it doesn't exist. Only move the plan when all
+ tasks are confirmed complete — if the review pass found unresolved issues, wait
+ until they are fixed.
## Step 7: Present Results
- Present the implementation-reviewer's findings to the user:
+ Present the combined final review findings to the user:
```
Implementation complete.
Quality checks:
typecheck: PASS/FAIL
lint: PASS/FAIL
+ Executor used:
+ Claude / Codex
+
+ Intent fidelity:
+ brief / why preserved: PASS/FAIL
+
Completeness: X/Y tasks done
[List any MISSING or PARTIAL items]
Issues found: [count]
[Summarize key issues if any]
+ Questions needing user input:
+ - [Only include items that neither review lane could safely auto-resolve]
+
Manual steps remaining:
- [ ] [Dangerous commands from Step 2, if any]
Schema changes:
[If Step 5.5 ran, show the migration SQL and apply command here]
[If no schema changes, show "None"]
Plan moved to: ./tmp/done-plans/<plan-file>.md
Next steps:
- Fix any issues flagged above
- `/prepare-pr` — Commit, build, and open/update a PR
```
- If the reviewer found issues, offer to fix them before the user commits. Only move the plan to `done-plans/` after all issues are resolved.
+ If either review lane found issues, offer to fix them before the user commits.
+ Only move the plan to `done-plans/` after all issues are resolved.