everything-claude-code/commands/prp-implement.md

description, argument-hint

description	argument-hint
Execute an implementation plan with rigorous validation loops	<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: ✅ 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] | ✅ Complete | |
| 2 | [task name] | ✅ Complete | Deviated — [reason] |

## Validation Results

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

## Files Changed

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

## Deviations from Plan
[List any deviations with WHAT and WHY, or "None"]

## Issues Encountered
[List any problems and how they were resolved, or "None"]

## Tests Written

| Test File | Tests | Coverage |
|---|---|---|
| `path/to/test` | N tests | [area covered] |

## Next Steps
- [ ] Code review via `/code-review`
- [ ] Create PR via `/prp-pr`

Update PRD (if applicable)

If this implementation was for a PRD phase:

1. Update the phase status from in-progress to complete
2. Add report path as reference

Archive Plan

mkdir -p .claude/PRPs/plans/completed
mv "$ARGUMENTS" .claude/PRPs/plans/completed/

CHECKPOINT: Report created. PRD updated. Plan archived.

---

Phase 6 — OUTPUT

Report to user:

## Implementation Complete

- **Plan**: [plan file path] → archived to completed/
- **Branch**: [current branch name]
- **Status**: ✅ All tasks complete

### Validation Summary

| Check | Status |
|---|---|
| Type Check | ✅ |
| Lint | ✅ |
| Tests | ✅ (N written) |
| Build | ✅ |
| Integration | ✅ or N/A |

### Files Changed
- [N] files created, [M] files updated

### Deviations
[Summary or "None — implemented exactly as planned"]

### Artifacts
- Report: `.claude/PRPs/reports/{name}-report.md`
- Archived Plan: `.claude/PRPs/plans/completed/{name}.plan.md`

### PRD Progress (if applicable)
| Phase | Status |
|---|---|
| Phase 1 | ✅ Complete |
| Phase 2 | ⏳ Next |
| ... | ... |

> Next step: Run `/prp-pr` to create a pull request, or `/code-review` to review changes first.

---

Handling Failures

Type Check Fails

1. Read the error message carefully
2. Fix the type error in the source file
3. Re-run type-check
4. Continue only when clean

Tests Fail

1. Identify whether the bug is in the implementation or the test
2. Fix the root cause (usually the implementation)
3. Re-run tests
4. Continue only when green

Lint Fails

1. Run auto-fix first
2. If errors remain, fix manually
3. Re-run lint
4. Continue only when clean

Build Fails

1. Usually a type or import issue — check error message
2. Fix the offending file
3. Re-run build
4. Continue only when successful

Integration Test Fails

1. Check server started correctly
2. Verify endpoint/route exists
3. Check request format matches expected
4. Fix and re-run

---

Success Criteria

• TASKS_COMPLETE: All tasks from the plan executed
• TYPES_PASS: Zero type errors
• LINT_PASS: Zero lint errors
• TESTS_PASS: All tests green, new tests written
• BUILD_PASS: Build succeeds
• REPORT_CREATED: Implementation report saved
• PLAN_ARCHIVED: Plan moved to completed/

---

Next Steps

• Run /code-review to review changes before committing
• Run /prp-commit to commit with a descriptive message
• Run /prp-pr to create a pull request
• Run /prp-plan <next-phase> if the PRD has more phases