/prp-implement

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

> Adapted from PRPs-agentic-eng by Wirasm. Part of the PRP workflow series.

PRP Implement

Execute a plan file step-by-step with continuous validation. Every change is verified immediately — never accumulate broken state.

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

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

---

Phase 0 — DETECT

Package Manager Detection

| File Exists | Package Manager | Runner | |---|---|---| | `bun.lockb` | bun | `bun run` | | `pnpm-lock.yaml` | pnpm | `pnpm run` | | `yarn.lock` | yarn | `yarn` | | `package-lock.json` | npm | `npm run` | | `pyproject.toml` or `requirements.txt` | uv / pip | `uv run` or `python -m` | | `Cargo.toml` | cargo | `cargo` | | `go.mod` | go | `go` |

Validation Scripts

Check `package.json` (or equivalent) for available scripts:

# For Node.js projects
cat package.json | grep -A 20 '"scripts"'

Note available commands for: type-check, lint, test, build.

---

Phase 1 — LOAD

Read the plan file:

cat "$ARGUMENTS"

Extract these sections from the plan:

• **Summary** — What is being built
• **Patterns to Mirror** — Code conventions to follow
• **Files to Change** — What to create or modify
• **Step-by-Step Tasks** — Implementation sequence
• **Validation Commands** — How to verify correctness
• **Acceptance Criteria** — Definition of done

If the file doesn't exist or isn't a valid plan:

Error: Plan file not found or invalid.
Run /prp-plan <feature-description> to create a plan first.

**CHECKPOINT**: Plan loaded. All sections identified. Tasks extracted.

---

Phase 2 — PREPARE

Git State

git branch --show-current
git status --porcelain

Branch Decision

| Current State | Action | |---|---| | On feature branch | Use current branch | | On main, clean working tree | Create feature branch: `git checkout -b feat/{plan-name}` | | On main, dirty working tree | **STOP** — Ask user to stash or commit first | | In a git worktree for this feature | Use the worktree |

Sync Remote

git pull --rebase origin $(git branch --show-current) 2>/dev/null || true

**CHECKPOINT**: On correct branch. Working tree ready. Remote synced.

---

Phase 3 — EXECUTE

Process each task from the plan sequentially.

Per-Task Loop

For each task in **Step-by-Step Tasks**:

1. **Read MIRROR reference** — Open the pattern file referenced in the task's MIRROR field. Understand the convention before writing code.

2. **Implement** — Write the code following the pattern exactly. Apply GOTCHA warnings. Use specified IMPORTS.

3. **Validate immediately** — After EVERY file change:

   # Run type-check (adjust command per project)
   [type-check command from Phase 0]

If type-check fails → fix the error before moving to the next file.

4. **Track progress** — Log: `[done] Task N: [task name] — complete`

Handling Deviations

If implementation must deviate from the plan:

• Note **WHAT** changed
• Note **WHY** it changed
• Continue with the corrected approach
• These deviations will be captured in the report

**CHECKPOINT**: All tasks executed. Deviations logged.

---

Phase 4 — VALIDATE

Run all validation levels from the plan. Fix issues at each level before proceeding.

Level 1: Static Analysis

# Type checking — zero errors required
[project type-check command]

# Linting — fix automatically where possible
[project lint command]
[project lint-fix command]

If lint errors remain after auto-fix, fix manually.

Level 2: Unit Tests

Write tests for every new function (as specified in the plan's Testing Strategy).

[project test command for affected area]

• Every function needs at least one test
• Cover edge cases listed in the plan
• If a test fails → fix the implementation (not the test, unless the test is wrong)

Level 3: Build Check

[project build command]

Build must succeed with zero errors.

Level 4: Integration Testing (if applicable)

# Start server, run tests, stop server
[project dev server command] &
SERVER_PID=$!

# Wait for server to be ready (adjust port as needed)
SERVER_READY=0
for i in $(seq 1 30); do
  if curl -sf http://localhost:PORT/health >/dev/null 2>&1; then
    SERVER_READY=1
    break
  fi
  sleep 1
done

if [ "$SERVER_READY" -ne 1 ]; then
  kill "$SERVER_PID" 2>/dev/null || true
  echo "ERROR: Server failed to start within 30s" >&2
  exit 1
fi

[integration test command]
TEST_EXIT=$?

kill "$SERVER_PID" 2>/dev/null || true
wait "$SERVER_PID" 2>/dev/null || true

exit "$TEST_EXIT"

Level 5: Edge Case Testing

Run through edge cases from the plan's Testing Strategy checklist.

**CHECKPOINT**: All 5 validation levels pass. Zero errors.

---

Phase 5 — REPORT

Create Implementation Report

mkdir -p .claude/PRPs/reports

Write report to `.claude/PRPs/reports/{plan-name}-report.md`:

# Implementation Report: [Feature Name]

## Summary
[What was implemented]

## Assessment vs Reality

| Metric | Predicted (Plan) | Actual |
|---|---|---|
| Complexity | [from plan] | [actual] |
| Confidence | [from plan] | [actual] |
| Files Changed | [from plan] | [actual count] |

## Tasks Completed

| # | Task | Status | Notes |
|---|---|---|---|
| 1 | [task name] | [done] Complete | |
| 2 | [task name] | [done] Complete | Deviated — [reason] |

## Validation Results

| Level | Status | Notes |
|---|---|---|
| Static Analysis | [done] Pass | |
| Unit Tests | [done] Pass | N tests written |
| Build | [done] Pass | |
| Integration | [done] Pass | or N/A |
| Edge Cases | [done] Pass | |

## Files Changed

| File | Action | Lines |
|---|---|---|
| `path/to/file` | CREATED | +N |
| `path/to/file` | UPDATED | +N / -M |

## Deviati