implement - SKILL.md Agent Skill

name: implement 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: Resolve Executor and Load Plan

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/

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: Choose Execution Strategy

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

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

Step 4: Start the Primary Execution Lane

If the executor is Claude:

Use Task tool with subagent_type: "implementer" for the primary stream.

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

If the executor is Codex and the plugin is available:

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 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, 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 review gates are complete and any auto-fixable issues are resolved, check if schema.ts was modified:

git diff origin/main --name-only | grep schema.ts

If schema.ts was changed:

Run npm run db:diff:dev and capture the output.
Present TWO separate blocks to the user:

Schema changes (migration SQL):

BEGIN;
-- the generated migration SQL here
COMMIT;

Apply migration to dev database:

npm run db:migrate:dev

(Or whatever the actual command is — run it and show the result.)

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 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/:

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 review pass found unresolved issues, wait until they are fixed.

Step 7: Present Results

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 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.