feat: add PRP workflow commands adapted from PRPs-agentic-eng (#848)

* feat: add PRP workflow commands adapted from PRPs-agentic-eng Add 5 new PRP workflow commands and extend 2 existing commands: New commands: - prp-prd.md: Interactive PRD generator with 8 phases - prp-plan.md: Deep implementation planning with codebase analysis - prp-implement.md: Plan executor with rigorous validation loops - prp-commit.md: Quick commit with natural language file targeting - prp-pr.md: GitHub PR creation from current branch Extended commands: - code-review.md: Added GitHub PR review mode alongside local review - plan.md: Added cross-reference to /prp-plan for deeper planning Adapted from PRPs-agentic-eng by Wirasm. Sub-agents remapped to inline Claude instructions. ECC conventions applied throughout (YAML frontmatter, Phase headings, tables, no XML tags). Artifacts stored in .claude/PRPs/{prds,plans,reports,reviews}/. * fix: address PR #848 review feedback - Remove external URLs from all 6 command files (keep attribution text) - Quote $ARGUMENTS in prp-implement.md to handle paths with spaces - Fix empty git add expansion in prp-commit.md (use xargs -r) - Rewrite sub-agent language in prp-prd.md as direct instructions - Fix code-review.md: add full-file fetch for PR reviews, replace || fallback chains with project-type detection, use proper GitHub API for inline review comments - Fix nested backticks in prp-plan.md Plan Template (use 4-backtick fence) - Clarify $ARGUMENTS parsing in prp-pr.md for base branch + flags - Fix fragile integration test pattern in prp-implement.md (proper PID tracking, wait-for-ready loop, clean shutdown) * fix: address second-pass review feedback on PR #848 - Add required 'side' field to GitHub review comments API call (code-review.md) - Replace GNU-only xargs -r with portable alternative (prp-commit.md) - Add failure check after server readiness timeout (prp-implement.md) - Fix unsafe word-splitting in file-fetch loop using read -r (code-review.md) - Make git reset pathspec tolerant of zero matches (prp-commit.md) - Quote PRD file path in cat command (prp-plan.md) - Fix plan filename placeholder inconsistency (prp-plan.md) - Add PR template directory scan before fixed-path fallbacks (prp-pr.md)
2026-04-13 05:03:28 +08:00 · 2026-03-31 14:12:23 -07:00
parent f90f269b92
commit c02d6e9f94
7 changed files with 1891 additions and 10 deletions
--- a/commands/prp-implement.md
+++ b/commands/prp-implement.md
@@ -0,0 +1,385 @@
+---
+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:
+
+```bash
+# 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:
+
+```bash
+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
+
+```bash
+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
+
+```bash
+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:
+   ```bash
+   # 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
+
+```bash
+# 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).
+
+```bash
+[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
+
+```bash
+[project build command]
+```
+
+Build must succeed with zero errors.
+
+### Level 4: Integration Testing (if applicable)
+
+```bash
+# 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
+
+```bash
+mkdir -p .claude/PRPs/reports
+```
+
+Write report to `.claude/PRPs/reports/{plan-name}-report.md`:
+
+```markdown
+# 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
+
+```bash
+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