---
name: oat-project-implement
version: 2.1.8
description: Use when plan.md is ready for execution. Dispatches one phase implementer per phase, owns independent phase review and bounded fix routing, and supports plan-declared worktree-isolated parallel phases.
oat_gateable: true
argument-hint: '[--retry-limit <N>] [--dry-run]'
disable-model-invocation: true
user-invocable: true
allowed-tools: Read, Write, Bash(git:*), Bash(oat:*), Bash(oat project log:*), Glob, Grep, AskUserQuestion, Task
---

# Implementation Phase

Execute the implementation plan task-by-task with full state tracking.

## Prerequisites

**Required:** Complete implementation plan. If missing, run the `oat-project-plan` skill first.

## Shared Subagent Dispatch Contract

Before resolving or launching any phase implementer, optional nested worker,
fix continuation, or reviewer, read and follow
`.agents/skills/oat-project-dispatch-subagents/SKILL.md`. The project adapter
resolves lifecycle scope and then requires
`.agents/skills/oat-dispatch-subagents/SKILL.md` for provider-neutral
selection, recovery, and evidence. This explicit two-skill load is mandatory;
do not rely on ambient skill discovery. This implementation skill retains
lifecycle sequencing, verification, integration, and approval-aware final
closeout.
Correctness must not require a provider restart or hot reload.

Read
`.agents/skills/subagent-orchestration/references/model-selection-principles.md`.
After resolving `ACTIVE_PROVIDER`, read exactly one active-provider selection
reference from `.agents/skills/subagent-orchestration/references/` and the
matching mechanics reference from
`.agents/skills/oat-dispatch-subagents/references/` (`provider-cursor.md`,
`provider-codex.md`, or `provider-claude.md`). Do not merge provider guidance
or mechanics.

## Project Log Append Points

Defer entry flags to `oat project log append --help`; never pre-check config:
the helper no-ops when the feature is off.

- After every accepted subagent dispatch, use `oat project log append` at
  `$PROJECT_PATH/implementation.md#<run-anchor>`; never mirror that record.
- Before validating the review artifact or updating project bookkeeping, consume
  exactly one brief artifact-mode confirmation of reconnaissance:
- `**Reconnaissance:** attempted`
- `**Reconnaissance:** not-attempted`
  Missing, duplicate, or invalid signals are incomplete-artifact errors: stop
  and fail closed before validation, bookkeeping, or logging.
- For `attempted`, require complete `## Review Orchestration` evidence. After
  validation, append exactly once through `oat project log append`, referencing
  the artifact without copying records.
- For `not-attempted`, the artifact must not contain `## Review Orchestration`;
  do not invoke `oat project log append` or create a log entry.
- Before every STOP or park return, invoke `oat project log append` for a
  structural entry naming the triggering condition.
- After every phase outcome, invoke `oat project log append` for a structural
  entry with the verdict and fix-loop count.
- After every parallel-group merge attempt, invoke `oat project log append` for
  a structural entry with the merge result.

## Autonomy Policy

When `OAT_AUTONOMOUS=1`, read
`references/docs/autonomy-contract.md` and keep `OAT_NON_INTERACTIVE=1` set for
this run. Autonomy-specific behavior is routed with the rest of the workflow:

- delegation authorization: `references/dispatch-and-dry-run.md`;
- HiLL resolution and checkpoint review/receive:
  `references/plan-and-resume.md`;
- final review, final HiLL approval, and lifecycle-tail sequencing:
  `references/completion-and-closeout.md`.

These are additive autonomous branches. When `OAT_AUTONOMOUS` is not exactly
`1`, preserve every existing interactive prompt and preference path. Never
persist either autonomy environment signal in project artifacts or config;
record only the gate decision and its review/dispatch provenance.

## Mode Assertion

**OAT MODE: Implementation**

**Purpose:** Execute plan tasks with TDD discipline, track progress, handle blockers.

**CRITICAL — Bookkeeping commits are mandatory, not optional.**
After every code commit and after every phase/review-fix completion, you MUST commit the OAT tracking files (project: `implementation.md`, `state.md`, `plan.md`) as a separate bookkeeping commit. Refresh the repo dashboard with `oat state refresh` before staging when available, but do not stage `.oat/state.md`; it is generated dashboard state and is normally gitignored. Do not defer, batch, or skip these commits under the reasoning that they "aren't related to the implementation." Skipping a bookkeeping commit is the primary cause of cross-session state drift and will cause the next implementation run to fail bookkeeping cross-checks. If bookkeeping commits feel frequent, that is the intended design — they are cheap and they prevent drift.

**CRITICAL — Review boundaries require a committed artifact baseline.**
Do not enter checkpoint review, final review, revise, or PR-final handoff with dirty core project artifacts (`discovery.md`, `spec.md`, `design.md`, `plan.md`, `implementation.md`, `state.md`). If one of those boundaries is next and artifact bookkeeping is still uncommitted, stop and create the bookkeeping commit first.

**CRITICAL — Intentional artifact divergence must be recorded.**
If implementation intentionally diverges from `spec.md`, `design.md`, or `plan.md`, record the delta in `implementation.md` before the next phase/review boundary. Include what diverged, why it diverged, whether the implementation or original artifact is now source of truth, and any follow-up artifact updates or explicit deferral. Do not leave accepted design drift only in chat, a review artifact, or code comments; final summary generation depends on `implementation.md` preserving the delta.

## Progress Indicators (User-Facing)

When executing this skill, provide lightweight progress feedback so the user can tell what's happening after they confirm.

- Print a phase banner once at start using horizontal separators, e.g.:

  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  OAT ▸ IMPLEMENT
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

- For each task, announce a compact header before doing work:
  - `OAT ▸ IMPLEMENT {task_id}: {task_name}`
- Before multi-step "bookkeeping" work (updating artifacts/state, verification, committing, dashboard refresh), print 2–5 short step indicators, e.g.:
  - `[1/4] Updating implementation.md + state.md…`
  - `[2/4] Running verification…`
  - `[3/4] Committing…`
  - `[4/4] Refreshing dashboard…`
- For long-running operations (tests/lint/type-check/build, reviews, large diffs), print a start line and a completion line (duration optional).
- Keep it concise; don't print a line for every shell command.

**BLOCKED Activities:**

- No skipping tasks
- No changing plan structure
- No scope expansion

**ALLOWED Activities:**

- Executing tasks in order
- Making minor adaptations within task scope
- Logging decisions and issues
- Marking blockers for user review

**Self-Correction Protocol:**
If you catch yourself:

- Skipping ahead in tasks → STOP (execute in order)
- Expanding scope → STOP (log as "deferred")
- Changing plan structure → STOP (update plan.md first)

**Recovery:**

1. Acknowledge the deviation
2. Return to current task
3. Document in implementation.md

## Process

### Step 0: Resolve Active Project

OAT stores active project context in `.oat/config.local.json` (`activeProject`, local-only).

```bash
PROJECT_PATH=$(oat config get activeProject 2>/dev/null || true)
PROJECTS_ROOT="${OAT_PROJECTS_ROOT:-$(oat config get projects.root 2>/dev/null || echo ".oat/projects/shared")}"
PROJECTS_ROOT="${PROJECTS_ROOT%/}"
```

**If `PROJECT_PATH` is missing/invalid:**

- Ask the user for `{project-name}`
- Set `PROJECT_PATH` to `${PROJECTS_ROOT}/{project-name}`
- Write it for future phases:
  ```bash
  mkdir -p .oat
  oat config set activeProject "$PROJECT_PATH"
  ```

**If `PROJECT_PATH` is valid:** derive `{project-name}` as the directory name (basename of the path).

### Route Loading Contract

Do not read every implementation reference at skill start. Load exactly one
route when execution reaches it, complete that route, then return here to select
the next route. The shared dispatch skill and its one active-provider reference
remain mandatory before any launch.

| When                                                                                     | Read                                    |
| ---------------------------------------------------------------------------------------- | --------------------------------------- |
| After resolving the active project; before capability, tier, or dispatch resolution      | `references/dispatch-and-dry-run.md`    |
| After dispatch preflight succeeds; before plan validation or resume                      | `references/plan-and-resume.md`         |
| When the next incomplete phase or parallel group is ready                                | `references/phase-execution.md`         |
| Only after phase execution completes, or when handling a terminal blocker/final closeout | `references/completion-and-closeout.md` |

Rules:

- Never preload a later route "for context."
- Re-enter this router after each route reaches its terminal condition.
- A phase implementer receives only its Phase Scope and role contract; it does
  not receive these root-workflow references.
- Optional nested workers receive only their bounded scope and relevant
  repository context.
- Reviewers receive only the bounded review scope, commit range, allowed files,
  and review artifact contract. They do not read this implementation skill.
- Preserve every invariant in the routed references; progressive disclosure
  changes loading order, not behavior.

### Execution Order

1. Resolve the active project below.
2. Load `references/dispatch-and-dry-run.md`; stop there for a completed dry run.
3. Load `references/plan-and-resume.md` and resolve the next execution boundary.
4. Load `references/phase-execution.md` once per ready phase/group, returning to
   the plan/resume route until all phases complete.
5. Load `references/completion-and-closeout.md` only for blockers, completion,
   final verification/review, approval sequencing, and handoff.

## Success Criteria

- One exact target-pinned phase implementer directly executed each phase's
  tasks in dependency order
- Each planned task produced exactly one verified bounded commit
- Root dispatched exactly one accepted phase reviewer per review round
- Blocking findings returned to the original phase handle when resumable
- Optional nested dispatch was absent by default and fully evidenced when used
- Only plan-declared phase worktrees ran in parallel
- TDD discipline followed
- Each task result and commit was verified against HEAD and its file boundary
- Implementation.md tracks all progress
- Final verification passes
- Final review passes (no Critical/Important findings)
- The configured implementation exit gate has an allowed and fresh disposition
  before approval-aware sequencing, completion state, or success output
- No unresolved blockers
