Implement

---
name: implement
description: Execute an approved plan in small coherent slices from an isolated task worktree, updating progress, evidence, and docs as implementation evolves. Invoke automatically after an approved plan exists and the task worktree is ready.
---
Work from the active plan, not from memory alone.

## Steps

1. **Resolve the target plan path** (must run before any branch or plan-file operations):
   - `/implement` operates on single-file plans (`docs/plans/active/<date>-<slug>.md`) only.
   - Enumerate candidates: `.md` files directly under `docs/plans/active/` (excluding `.gitkeep`). **Ignore directories** — if a directory is the only entry, stop and report: this looks like a Ralph Loop directory plan (`_manifest.md` + `slice-*.md`); Ralph Loop's autonomous execution system was retired (see git history for the removed orchestration scripts, and `internal/org` for the current autonomous execution surface, `/org`). Convert the plan to a single-file plan via `/plan` and re-run `/implement`, or use `/org` for autonomous multi-seat execution.
   - If exactly one candidate file exists, use it.
   - If multiple candidate files exist, ask via AskUserQuestion which plan this `/implement` run targets, and use the selected path.
   - If none exist, stop and ask the user to run `/plan` first.
   - Downstream steps in this skill — and downstream skills (`/cross-review`, `/pr`) — MUST use this resolved path instead of rescanning `docs/plans/active/`.
2. **Resolve or resume the task worktree**, based on the plan resolved in Step 1:
   a. Read the resolved plan to extract metadata (type, issue number, slug).
   b. Determine branch name by running `./scripts/branch-name.sh from-plan <resolved-plan-path>`.
   c. Branch names must validate with `./scripts/branch-name.sh validate <branch-name>`. Allowed user-facing branch shapes are `<type>/<issue>/<slug>` (with issue) or `<type>/<slug>` (without issue), where `<type>` is one of `feat`, `fix`, `docs`, `chore`, `refactor`, `test`, `ci`, `build`, `perf`, `release`, or `security`.
   d. Run `./scripts/ralph-worktree.sh current`. If it returns a state file for the current worktree, use that state id. Otherwise run `./scripts/ralph-worktree.sh ensure --id plan-<slug> --kind standard --branch <branch-name> --path .claude/worktrees/<slug> --plan-path <absolute-plan-path> --canonical-ref <issue/spec/request reference> --cleanup-policy pr-success` unless a matching task worktree state already exists.
   e. If this `/implement` invocation is already running inside the returned worktree path, continue. If it is running outside that path, switch all subsequent commands and edits to the returned worktree path.
   f. If the resolved plan file is a legacy plan outside the task worktree, stop and migrate it intentionally instead of silently copying it; new `/plan` runs should already create plans inside the task worktree.
   g. Update the resolved plan file inside the task worktree: replace `Branch: TBD` (or any TBD variant) with the actual branch name.
3. **Pin the plan identity and initialize the pipeline cycle counter** (enforces the 2-cycle cap):
   a. Create `.harness/state/standard-pipeline/` if missing (`mkdir -p`). This directory is already covered by the existing `.harness/state/` gitignore.
   b. Write the Step-1 resolved absolute path plus worktree metadata to `.harness/state/standard-pipeline/active-plan.json` as `{"plan_path": "<absolute-path>", "worktree_path": "<absolute-worktree-path>", "branch": "<branch>", "base_sha": "<base-sha>", "worktree_state_id": "plan-<slug>", "created_at": "<UTC ISO8601>"}`. If the file already exists with a different `plan_path` or `worktree_state_id`, warn the user and ask whether to overwrite (resume) or abort.
   c. Handle `.harness/state/standard-pipeline/cycle-count.json`:
      - If the file is missing: initialize as `{"plan_path": "<absolute-path>", "cycle": 1}`.
      - If the file exists AND its `plan_path` matches the pinned plan: **preserve the existing counter** (do NOT reset to 1). This keeps the cap effective when the user resumes a plan after context compaction or a later session. Inform the user of the resumed cycle number.
      - If the file exists AND its `plan_path` differs from the pinned plan: warn and prompt via AskUserQuestion whether to reset the counter for the new plan or abort.
      - The counter reflects the **current** pipeline run (1 = first run, 2 = one re-run after cross-review ACTION_REQUIRED).
4. Read the current active plan using the path recorded in `active-plan.json`, then check that it passed the `/plan` approval gate (`/plan` step 12). Run this check on every `/implement` start, resumes included:
   - Read the plan's `- Status:` and `- Approved:` lines and run `./scripts/plan-visual.sh digest <plan-path>`.
   - The plan is approved when `Status` is `Approved` and the `sha256:` value on the `- Approved:` line equals the digest. Continue.
   - Otherwise (no `- Approved:` line, `TBD`, another status, or a digest mismatch, which means the plan text changed after approval; ticking checkboxes such as acceptance criteria does not change the digest), tell the user which case it is and ask with `AskUserQuestion` (Codex: numbered options):
     1. Redo the visual review and approval — run `/plan` steps 10 and 12 on this plan, then continue
     2. Continue without approval — note that choice under the plan's `## Progress checklist`
     3. Stop
5. Confirm acceptance criteria, verify plan, and test plan before editing code.
6. Implement in small slices that can be reviewed and verified independently. **Delegate each implementation slice to the `implementer` subagent** (Claude Code: `Task(subagent_type="implementer")`; Codex: the `.codex/agents/implementer.toml` custom agent) with a structured handoff carrying: plan path, slice objective, acceptance criteria addressed, files in scope, exact verification commands, and commit message format. The main session (orchestrator) stays on decomposition, handoff authoring, report adjudication, and plan upkeep. Inline implementation is allowed only for (a) trivial single-file edits where a handoff costs more than the change, or (b) implementer dispatch failure (fall back inline and note the fallback in the report, same convention as the post-implementation pipeline). See `.claude/rules/ralph/model-routing.md` and `.claude/rules/ralph/subagent-policy.md`. Before dispatching, commit any outstanding plan/bookkeeping edits (or confirm they do not overlap the slice's files in scope) so the implementer starts from an unambiguous baseline.
7. **Commit gate after each slice (Validation Gate):**
   - **Delegated slices**: the implementer has already run the handoff's verification commands and committed. The orchestrator's gate is adjudication: check the returned report (verification evidence present, commit-boundary evidence shows no in-scope or unexpected dirt (pre-existing out-of-scope bookkeeping noted in the report is acceptable), commit SHA is the new branch `HEAD` — `git rev-parse HEAD` matches the reported SHA (an existing-but-stale SHA would still satisfy `git log -1`)), and spot-check by re-running a verification command when the report leaves doubt. Do not re-stage or re-commit the slice; one slice = one commit, owned by the implementer.
   - **Inline slices** (trivial edit / dispatch-failure fallback): run `./scripts/run-verify.sh` (or equivalent), stage the slice's files, and commit with conventional format: `<type>: <description>` — the original gate, unchanged.
   - If verification fails in either mode, fix before proceeding. Do not accumulate unverified changes. See `.claude/rules/ralph/git-commit-strategy.md`.
8. Update the plan's progress checklist while working.
9. If the task splits cleanly, delegate focused research or review to subagents.
10. If repeated failures occur, reduce scope, inspect evidence, and revise the plan instead of thrashing.
11. Keep docs, contracts, and tests aligned with behavior changes.
12. Before presenting completion, run `./scripts/run-verify.sh` or equivalent deterministic checks.
13. After criteria met, run the post-implementation pipeline per `.claude/rules/ralph/subagent-policy.md`:
    a. `reviewer` → `/self-review` — stop if CRITICAL findings
    b. `verifier` → `/verify` — stop if fail verdict
    c. `tester` → `/test` — stop if fail verdict
    d. `doc-maintainer` → `/sync-docs`
    In Claude Code, use `Task(subagent_type=...)` calls. In Codex, use the
    matching `.codex/agents/` custom agents and keep the same order. If a
    subagent dispatch fails, run that step inline and note the fallback in the
    report.
    e. **Invoke `/cross-review` via the Skill tool** (optional, inline — if the reviewer CLI is unavailable, skip to `/pr`). The skill reads `cycle-count.json` and enforces `RALPH_STANDARD_MAX_PIPELINE_CYCLES` (default 2). On re-run after ACTION_REQUIRED fixes, `/cross-review` increments `cycle-count.json`.
    f. **Invoke `/pr` via the Skill tool** — do NOT run `gh pr create` directly. The `/pr` skill enforces the Japanese template, pre-checks, plan archiving, and task worktree/local branch cleanup. On success, `/pr` deletes `.harness/state/standard-pipeline/active-plan.json` and `cycle-count.json`.

## Scope discipline

- Work only on items listed in the plan's scope. If you discover work outside scope, record it in the plan's open questions or tech-debt, do not implement it.
- Each slice should map to one or more acceptance criteria. If a slice does not advance any criterion, question whether it belongs.

## Plan drift detection

- Before each major slice, re-read the plan to confirm alignment.
- If your implementation diverges from the plan (new files, changed interfaces, different approach), update the plan FIRST with a deviation note before continuing.
- Ticking checkboxes (acceptance criteria, checklists) does not change the plan's digest, so marking acceptance criteria done is fine. Any other change to the plan body does, including a deviation note, so the approval no longer matches: after writing it, redo `/plan` steps 10 and 12 for the affected figures before the next slice. Notes that only record progress go under `## Progress checklist`, which the digest skips.
- Never silently drift. The plan is the contract.

## Uncertainty management

- If you encounter ambiguity that the plan does not address, check repo context and subagents first (anti-bottleneck).
- If still uncertain, record the uncertainty in the plan's open questions and make the smallest safe choice.
- Do not make large irreversible decisions under uncertainty — flag them.

## Completion gate

Do NOT present a task as complete unless ALL of the following are true:

- [ ] `./scripts/run-verify.sh` exits 0 (or a project-specific verifier passes)
- [ ] Each slice is individually committed with a conventional commit message
- [ ] The active plan's progress checklist is fully updated
- [ ] Any discovered tech debt is recorded in `docs/tech-debt/`

If verification has not run, say so explicitly instead of claiming done.

## Anti-bottleneck

Before asking the user for confirmation, next steps, or choices, first check whether you can resolve the question through verification, repo context, subagents, or reasonable defaults. See the `anti-bottleneck` skill for the full checklist.

## Strong defaults

- One slice at a time
- Evidence before confidence
- Versioned plan over chat-only plan
- Smaller diffs over heroic rewrites
- Delegated slices over orchestrator-written code

## CLI execution modes

This skill runs under both Claude Code and Codex. The execution mode follows
the conventions in AGENTS.md and `.codex/AGENTS.override.md`.

| Aspect | Claude Code | Codex |
|--------|-------------|-------|
| Skill invocation | `/skill-name` slash command | `$skill-name` mention or the `/skills` menu (avoid the `/skill-name` form — it collides with built-ins) |
| Skill body path | `.claude/skills/<name>/SKILL.md` | `.agents/skills/<name>/SKILL.md` |
| Subagent mechanism | `Task(subagent_type=...)` when a policy delegates | `.codex/agents/` custom agents when a policy delegates |
| Structured prompts | `AskUserQuestion` | Numbered options printed to stdout, awaiting a digit reply |
| Artifacts | `docs/reports/`, `docs/plans/`, `docs/specs/` (shared) | Same (CLI-agnostic) |

The drift check (`./scripts/check-skill-sync.sh`) cross-checks both bodies and
invocation metadata — editing only one side will fail CI.