Implement

---
description: Execute an implementation plan with validation loops
argument-hint: <path/to/plan.md>
---

# Implement Plan

**Plan**: $ARGUMENTS

## Your Mission

Execute the plan end-to-end with rigorous self-validation.

**Core Philosophy**: Validation loops catch mistakes early. Run checks after every change. Fix issues immediately.

**Golden Rule**: If validation fails, fix it before moving on. Never accumulate broken state.

---

## Phase 1: LOAD

### Read the Plan

Load the plan file and extract:

- **Summary** - What we're building
- **Patterns to Mirror** - Code to copy from
- **Files to Change** - CREATE/UPDATE list
- **Tasks** - Implementation order
- **Validation Commands** - How to verify
- **Issue ID** - Check the plan's Metadata table for an Issue ID (e.g., `ISSUE-5`). If present, the file at `issues/<ID>.md` will be updated after implementation is complete.

**If plan not found:**

Error: Plan not found at $ARGUMENTS Create a plan first: /plan "feature description"

---

## Phase 2: PREPARE

### Git State

```bash
git branch --show-current
git status

State	Action
On main, clean	Create branch: git checkout -b feature/{plan-name}
On main, dirty	STOP: "Stash or commit changes first"
On feature branch	Use it

---

Phase 3: EXECUTE

For each task in the plan:

3.1 Verify Assumptions

Before writing any code for a task:

• Read the target file you're about to create or modify
• Read adjacent files — files it imports from, and files that import it
• Verify the plan's references — do the functions, interfaces, tables, or endpoints the plan mentions actually exist? Do they match the plan's expectations?
• If assumptions are wrong, adapt your approach before implementing. Document what differs from the plan.

3.2 Implement

• Read the MIRROR file reference and understand the pattern to follow
• Make the change as specified in the plan
• Check integration: verify your change connects correctly to adjacent code — do imports resolve? Do callers/callees still work? Does the data flow correctly across boundaries?

3.3 Validate Immediately

After EVERY task:

pnpm run build

If it fails:

1. Read the error
2. Fix the issue
3. Re-run validation
4. Only proceed when passing

3.4 Track Progress

Task 1: CREATE src/x.ts ✅
Task 2: UPDATE src/y.ts ✅

If you deviate from the plan, document what changed and why.

---

Phase 4: VALIDATE

Run All Checks

# Type check
pnpm run build

# Lint
pnpm run lint

# Tests
pnpm test

All must pass with zero errors.

Write Tests

You MUST write tests for new code:

• Every new function needs at least one test
• Error cases and edge cases need tests
• Update existing tests if behavior changed
• Test across boundaries — don't just test functions in isolation. If you added an API endpoint, test that the endpoint returns the correct response shape and data. If you added a service method, test that it integrates correctly with its callers.

If tests fail:

1. Determine: bug in implementation or test?
2. Fix the actual issue
3. Re-run until green

REQUIRED: End-to-End Verification

⚠️ Do NOT proceed to Phase 5 (Report) until all E2E steps below pass.

Re-read the plan and find the end-to-end testing section. Execute every E2E test listed in the plan as a checklist:

• Start the application (dev servers, databases, etc.)
• For EACH end-to-end test in the plan:
  • Execute the test exactly as described
  • Verify the expected outcome matches the plan
  • If it fails: fix the issue, re-run, confirm it passes
• Confirm all E2E tests pass before proceeding

If the plan has no E2E tests, perform a basic smoke test: start the app, exercise the new/changed feature manually, verify it works.

This is a hard gate. You cannot report the implementation as complete until E2E verification passes. Static checks and unit tests alone are never sufficient.

---

Phase 5: REPORT

Create Report

Output path: .agents/reports/{plan-name}-report.md

mkdir -p .agents/reports

# Implementation Report

**Plan**: `{plan-path}`
**Branch**: `{branch-name}`
**Status**: COMPLETE

## Summary

{Brief description of what was implemented}

## Tasks Completed

| # | Task | File | Status |
|---|------|------|--------|
| 1 | {description} | `src/x.ts` | ✅ |
| 2 | {description} | `src/y.ts` | ✅ |

## Validation Results

| Check | Result |
|-------|--------|
| Type check | ✅ |
| Lint | ✅ |
| Tests | ✅ ({N} passed) |

## Files Changed

| File | Action | Lines |
|------|--------|-------|
| `src/x.ts` | CREATE | +{N} |
| `src/y.ts` | UPDATE | +{N}/-{M} |

## Deviations from Plan

{List any deviations with rationale, or "None"}

## Tests Written

| Test File | Test Cases |
|-----------|------------|
| `src/x.test.ts` | {list} |

Archive Plan

mkdir -p .agents/plans/completed
mv $ARGUMENTS .agents/plans/completed/

---

Phase 6: UPDATE ISSUE (if issue specified in plan)

This phase is mandatory if the plan's Metadata table contains an Issue ID. Skip only if the Issue ID field is "N/A" or absent.

The issue lives at issues/<ID>.md with YAML frontmatter for metadata and markdown body for description, acceptance criteria, technical notes, and an Activity log. Read it first, then update.

6.1 Read the Issue

Read issues/<ID>.md to confirm it exists and to capture current frontmatter (status, etc.) before editing.

6.2 Update Status

Edit the status field in frontmatter to reflect completion:

• in-review if the project uses a review state before merge (default)
• done if there is no review step

Allowed values: todo | in-progress | in-review | done.

6.3 Append an Activity Entry

Append an entry to the ## Activity section at the bottom of the file (create the section if absent). Format:

### {YYYY-MM-