diff --git a/.claude/commands/prp-core/prp-commit-batch.md b/.claude/commands/prp-core/prp-commit-batch.md new file mode 100644 index 00000000..d3628e98 --- /dev/null +++ b/.claude/commands/prp-core/prp-commit-batch.md @@ -0,0 +1,140 @@ +--- +description: Split working tree changes into multiple logical commits with smart grouping +argument-hint: [grouping strategy] (blank = auto-detect logical groups) +--- + +# Batch Commit + +**Strategy**: $ARGUMENTS + +--- + +## Your Mission + +Analyze all uncommitted changes, determine the optimal number of logical commits, then create each commit using the `/prp-commit` workflow. + +--- + +## Phase 1: ASSESS — Survey All Changes + +```bash +git status --short +git diff --stat +git diff --cached --stat +``` + +If nothing to commit, stop. + +--- + +## Phase 2: ANALYZE — Determine Logical Groups + +Examine the changes and group them by logical unit. Consider: + +### Grouping Strategies + +| Strategy Input | Behavior | +|---------------|----------| +| (blank / auto) | Group by logical change unit (feature, fix, refactor, etc.) | +| `by-type` | Group by change type: feat, fix, refactor, docs, test, chore | +| `by-directory` | Group by top-level directory | +| `by-feature` | Group by feature/domain area | +| `atomic` | One commit per file | + +### Auto-Detection Heuristic + +When no strategy is specified, analyze the diff to identify: + +1. **Distinct features**: New files + their tests + config changes = one group +2. **Refactors**: Renamed/moved files + import updates = one group +3. **Fixes**: Bug fix changes separate from feature work +4. **Docs**: Documentation-only changes +5. **Chore**: Config, dependency, tooling changes + +**CRITICAL**: Each commit must leave the codebase in a valid state (compiles, passes lint). + +--- + +## Phase 3: PROPOSE — Present Commit Plan + +```markdown +## Batch Commit Plan + +**Total changes**: {N} files ({additions}+ / {deletions}-) + +I recommend **{N}** commits: + +| # | Type | Message | Files | +/- | +|---|------|---------|-------|-----| +| 1 | feat | {message} | {file list or pattern} | +{N}/-{N} | +| 2 | fix | {message} | {file list or pattern} | +{N}/-{N} | +| 3 | refactor | {message} | {file list or pattern} | +{N}/-{N} | + +**Order**: {explanation of commit order — dependencies first, features before tests, etc.} + +Proceed? You can adjust grouping, merge, or split any items. +``` + +**GATE**: Wait for user approval or adjustments. + +--- + +## Phase 4: EXECUTE — Create Each Commit + +For each approved commit group: + +1. **Reset staging area** (if needed): + ```bash + git reset HEAD + ``` + +2. **Stage only the files for this commit**: + ```bash + git add {specific files} + ``` + +3. **Verify staging is correct**: + ```bash + git diff --cached --name-only + ``` + +4. **Commit** with conventional message: + ```bash + git commit -m "{type}: {description}" + ``` + +5. **Confirm** before moving to next group + +Repeat for each commit group in order. + +--- + +## Phase 5: SUMMARIZE + +```markdown +## Batch Commit Complete + +**Commits created**: {N} + +| # | Hash | Message | Files | +|---|------|---------|-------| +| 1 | {short-hash} | {type}: {message} | {N} files | +| 2 | {short-hash} | {type}: {message} | {N} files | +| 3 | {short-hash} | {type}: {message} | {N} files | + +**Total**: {files} files changed, {insertions} insertions, {deletions} deletions + +Next: `git push` or `/prp-pr` +``` + +--- + +## Examples + +``` +/prp-commit-batch # Auto-detect logical groups +/prp-commit-batch by-type # Group by conventional commit type +/prp-commit-batch by-directory # Group by directory +/prp-commit-batch by-feature # Group by feature domain +/prp-commit-batch atomic # One commit per file +``` diff --git a/.claude/commands/prp-core/prp-plan-batch.md b/.claude/commands/prp-core/prp-plan-batch.md new file mode 100644 index 00000000..0e0ae150 --- /dev/null +++ b/.claude/commands/prp-core/prp-plan-batch.md @@ -0,0 +1,136 @@ +--- +description: Generate implementation plans for multiple PRD phases or a list of features in batch +argument-hint: +--- + +# Batch Plan Generator + +**Input**: $ARGUMENTS + +--- + +## Your Mission + +Generate implementation plans for multiple features or PRD phases by invoking the `/prp-plan` workflow for each. + +--- + +## Phase 1: ANALYZE — Determine What to Plan + +### If input is a PRD file path: + +Read the PRD and extract ALL pending phases from the Implementation Phases table: + +```bash +cat "$ARGUMENTS" +``` + +Parse the phases table. Collect all phases with `Status: pending`. + +**Respect dependencies**: Only plan phases whose dependencies are `complete` or are being planned in this batch (sequential execution handles ordering). + +### If input is a feature list: + +Split the input into individual features. Each becomes a standalone plan. + +### Determine batch size: + +| Scenario | Count | +|----------|-------| +| PRD with N pending phases | Plan all phases with met dependencies | +| Comma-separated features | One plan per feature | +| Single complex feature | 1 (redirect to `/prp-plan` directly) | + +--- + +## Phase 2: PROPOSE — Present Plan to User + +```markdown +## Batch Plan Generation + +**Source**: {PRD file or feature list} + +I'll generate **{N}** implementation plans: + +| # | Plan | Source | Dependencies Met? | Can Parallelize? | +|---|------|--------|--------------------|------------------| +| 1 | {phase/feature name} | Phase 1 of PRD | Yes | - | +| 2 | {phase/feature name} | Phase 2 of PRD | Yes (depends on 1) | - | +| 3 | {phase/feature name} | Phase 3 of PRD | Yes | with 4 | +| 4 | {phase/feature name} | Phase 4 of PRD | Yes | with 3 | + +**Generation order**: {sequence accounting for dependencies} + +Proceed? +``` + +**GATE**: Wait for user approval. + +--- + +## Phase 3: GENERATE — Create Each Plan + +For each approved item, invoke the full `/prp-plan` workflow: + +1. Process plans **sequentially** in dependency order +2. For each plan: + - If from a PRD: pass the PRD path and specify the target phase + - If from a feature list: pass the feature description directly + - Follow ALL phases of `/prp-plan` (Parse → Explore → Research → Design → Architect → Generate) + - The generated plan goes to `.claude/PRPs/plans/{name}.plan.md` + - If sourced from a PRD, update the PRD's Implementation Phases table (set status to `in-progress`, add PRP Plan link) +3. Brief confirmation after each plan before proceeding + +### Cross-Plan Consistency + +- Reference shared interfaces or contracts defined in earlier plans +- Use consistent naming for shared concepts +- Note cross-plan integration points explicitly in each plan + +--- + +## Phase 4: SUMMARIZE — Batch Report + +```markdown +## Batch Plan Generation Complete + +**Source**: {input} +**Plans Generated**: {N} + +| # | Plan | File | Tasks | Parallel? | +|---|------|------|-------|-----------| +| 1 | {name} | `.claude/PRPs/plans/{file}.plan.md` | {N} | - | +| 2 | {name} | `.claude/PRPs/plans/{file}.plan.md` | {N} | - | +| 3 | {name} | `.claude/PRPs/plans/{file}.plan.md` | {N} | with 4 | +| 4 | {name} | `.claude/PRPs/plans/{file}.plan.md` | {N} | with 3 | + +### Execution Strategy + +**Sequential plans** (have dependencies): +{List in order} + +**Parallelizable plans** (independent): +{List groups that can run in separate worktrees} + +### Next Steps + +- **Implement first**: `/prp-implement .claude/PRPs/plans/{first-plan}.plan.md` +- **Ralph loop**: `/prp-ralph .claude/PRPs/plans/{first-plan}.plan.md --max-iterations 20` +- **Parallel worktrees** (for independent plans): + ```bash + git worktree add -b {branch} ../{dir} + cd ../{dir} && claude "/prp-implement .claude/PRPs/plans/{plan}.plan.md" + ``` +``` + +--- + +## Examples + +``` +# All pending phases from a PRD +/prp-plan-batch .claude/PRPs/prds/user-auth.prd.md + +# List of independent features +/prp-plan-batch "pagination API, search filters, CSV export" +``` diff --git a/.claude/commands/prp-core/prp-pr-batch.md b/.claude/commands/prp-core/prp-pr-batch.md new file mode 100644 index 00000000..def270af --- /dev/null +++ b/.claude/commands/prp-core/prp-pr-batch.md @@ -0,0 +1,130 @@ +--- +description: Create PRs for multiple feature branches at once +argument-hint: [base-branch] (default: main) +--- + +# Batch PR Creator + +**Base branch**: $ARGUMENTS (default: main) + +--- + +## Your Mission + +Identify all branches with unpushed/un-PR'd work, then create a PR for each using the `/prp-pr` workflow. + +--- + +## Phase 1: DISCOVER — Find Branches Needing PRs + +```bash +# List all local branches except main/master +git branch --list | grep -v -E '^\*?\s*(main|master)$' + +# For each branch, check if it has a PR already +for branch in $(git branch --list --format='%(refname:short)' | grep -v -E '^(main|master)$'); do + echo "=== $branch ===" + # Check commits ahead of base + git log origin/${base:-main}..$branch --oneline 2>/dev/null | head -5 + # Check for existing PR + gh pr list --head "$branch" --json number,url --jq '.[0].url // "no PR"' 2>/dev/null +done +``` + +Filter to branches that: +- Have commits ahead of base branch +- Do NOT already have an open PR + +--- + +## Phase 2: PROPOSE — Present PR Plan + +```markdown +## Batch PR Plan + +**Base branch**: {base} + +I found **{N}** branches ready for PRs: + +| # | Branch | Commits | Summary | Existing PR? | +|---|--------|---------|---------|--------------| +| 1 | {branch} | {N} commits | {1-line summary from commits} | None | +| 2 | {branch} | {N} commits | {1-line summary from commits} | None | +| 3 | {branch} | {N} commits | {1-line summary from commits} | None | + +**Skipped** (already have PRs): +{List of branches with existing PRs, or "None"} + +Proceed with creating PRs for all {N} branches? +``` + +**GATE**: Wait for user approval. User can exclude specific branches. + +--- + +## Phase 3: CREATE — Generate Each PR + +For each approved branch: + +1. **Switch to the branch**: + ```bash + git checkout {branch} + ``` + +2. **Invoke the `/prp-pr` workflow**: + - Follow ALL phases of `/prp-pr` (Validate → Discover template → Analyze → Push → Create) + - Pass the base branch argument + - Let it handle template detection, commit analysis, and PR creation + +3. **Record the PR URL** for the summary + +4. **Brief confirmation** before moving to next branch + +### Cross-PR Awareness + +When creating multiple PRs: +- Note related PRs in each PR body (e.g., "Related: #123, #124") +- If branches have dependency ordering, mention it in PR descriptions +- Use consistent labeling if the project uses labels + +--- + +## Phase 4: SUMMARIZE + +```markdown +## Batch PR Creation Complete + +**PRs Created**: {N} + +| # | Branch | PR | Title | Status | +|---|--------|----|-------|--------| +| 1 | {branch} | #{number} | {title} | Created | +| 2 | {branch} | #{number} | {title} | Created | +| 3 | {branch} | #{number} | {title} | Created | + +### Review Order + +{Suggested review/merge order based on dependencies, or "Any order — all independent"} + +### Next Steps + +- Review PRs: `/prp-review {pr-number}` +- Multi-agent review: `/prp-review-agents {pr-number}` +``` + +--- + +## Phase 5: RESTORE — Return to Original Branch + +```bash +git checkout {original-branch} +``` + +--- + +## Examples + +``` +/prp-pr-batch # PRs for all branches, base = main +/prp-pr-batch develop # PRs for all branches, base = develop +``` diff --git a/.claude/commands/prp-core/prp-prd-batch.md b/.claude/commands/prp-core/prp-prd-batch.md new file mode 100644 index 00000000..e325cdb1 --- /dev/null +++ b/.claude/commands/prp-core/prp-prd-batch.md @@ -0,0 +1,181 @@ +--- +description: Generate multiple PRDs from a broad initiative, product vision, or feature list +argument-hint: +--- + +# Batch PRD Generator + +**Input**: $ARGUMENTS + +--- + +## Your Mission + +Decompose a broad initiative or feature list into the optimal number of independent PRDs, then generate each one by invoking the `/prp-prd` workflow. + +--- + +## Phase 1: ANALYZE — Determine Optimal PRD Count & Decomposition + +Read and understand the input. Classify it: + +| Input Type | Example | Action | +|------------|---------|--------| +| Milestone / epic | "Q3 platform launch: auth, billing, marketplace, analytics" | Identify distinct project areas, determine optimal count | +| Broad initiative | "Build a multi-tenant SaaS platform" | Decompose into logical product areas | +| Feature list | "auth, billing, admin dashboard, notifications" | Validate separation, merge or split as needed | +| Single complex feature | "User management with RBAC, SSO, and audit logging" | Split into bounded deliverables | + +### Step 1: Determine Optimal Number of PRDs + +Before decomposing, explicitly analyze the scope to determine how many PRDs are needed: + +1. **Extract distinct deliverables** — List every capability, project, or feature area mentioned or implied in the description +2. **Cluster by domain** — Group related deliverables into cohesive product domains (e.g., "login + SSO + password reset" → single "Authentication" PRD) +3. **Apply sizing heuristics**: + - Each PRD should map to **1-5 implementation phases** (roughly 1-4 weeks of work per phase) + - If a cluster exceeds ~5 phases, split it further + - If a cluster has only 1 trivial phase, merge it into an adjacent domain +4. **Count and justify** — Arrive at the optimal N with explicit reasoning: + ``` + Scope analysis: + - Identified {X} distinct capabilities in the description + - Clustered into {Y} domains after merging related items + - Split {Z} oversized domains → final count: {N} PRDs + - Rationale: {why N is the right number, not N-1 or N+1} + ``` + +**For milestone-type inputs** (roadmap items, epics, quarterly goals), pay special attention to: +- Each milestone may contain **multiple independent projects** — each project typically warrants its own PRD +- Shared infrastructure across projects should be its own PRD if non-trivial +- Identify which projects are truly independent vs. which share foundations + +### Step 2: Validate Decomposition Quality + +Each PRD should be: +- **Independent**: Can be built, deployed, and validated without other PRDs being complete (or has minimal, explicit dependencies) +- **Bounded**: Completable in 1-5 implementation phases +- **Cohesive**: Covers a single product area or domain +- **Valuable**: Delivers user-visible value on its own + +### Anti-patterns to avoid: +- Too granular (e.g., one PRD per API endpoint) — merge related items +- Too broad (e.g., "the entire backend") — split by domain +- Overlapping scope between PRDs — draw clear boundaries +- Circular dependencies — reorder or merge +- Milestone with N items ≠ N PRDs — cluster by domain, not by bullet point + +--- + +## Phase 2: PROPOSE — Present Plan to User + +Present the decomposition for approval, including the count rationale from Phase 1: + +```markdown +## Batch PRD Plan + +**Initiative**: {restated input} +**Input type**: {Milestone / Broad initiative / Feature list / Complex feature} + +### Optimal Count Analysis + +- Identified **{X}** distinct capabilities in the description +- Clustered into **{Y}** domains after merging related items +- {Split/merged adjustments if any} +- **Optimal count: {N} PRDs** — {one-sentence rationale} + +### Proposed PRDs + +| # | PRD Name | Scope | Dependencies | Est. Phases | +|---|----------|-------|--------------|-------------| +| 1 | {name} | {1-2 sentence scope} | None | {N} | +| 2 | {name} | {1-2 sentence scope} | PRD 1 | {N} | +| 3 | {name} | {1-2 sentence scope} | None | {N} | + +**Dependency graph**: +{Simple ASCII showing which PRDs depend on others, or "All independent" if none} + +**Suggested order**: {execution order accounting for dependencies} + +Should I proceed? You can also: +- Merge/split any items +- Adjust scope boundaries +- Change the count +``` + +**GATE**: Wait for user approval or adjustments before proceeding. + +--- + +## Phase 3: GENERATE — Create Each PRD + +For each approved PRD, invoke the full `/prp-prd` workflow: + +### Execution Strategy + +1. Process PRDs **sequentially** (each builds context for the next) +2. For each PRD: + - Pass the scoped description as input to the `/prp-prd` process + - Follow ALL phases of `/prp-prd` (Foundation questions → Grounding → Deep Dive → etc.) + - **IMPORTANT**: For batch mode, answer Foundation/Deep Dive/Scope questions using context from the initiative description and previously generated PRDs. Only pause for user input when genuinely ambiguous. + - Generate the PRD file to `.claude/PRPs/prds/{kebab-case-name}.prd.md` +3. After each PRD, briefly confirm completion before moving to the next + +### Cross-PRD Consistency + +Maintain consistency across generated PRDs: +- **Shared terminology**: Use same terms for same concepts across all PRDs +- **Dependency references**: When PRD B depends on PRD A, reference the specific file and phase +- **Non-overlapping scope**: Ensure no capability appears in multiple PRDs +- **Aligned technical approach**: Consistent architecture decisions + +--- + +## Phase 4: SUMMARIZE — Batch Report + +After all PRDs are generated: + +```markdown +## Batch PRD Generation Complete + +**Initiative**: {input} +**PRDs Generated**: {N} + +| # | PRD | File | Phases | Dependencies | +|---|-----|------|--------|--------------| +| 1 | {name} | `.claude/PRPs/prds/{file}.prd.md` | {N} | - | +| 2 | {name} | `.claude/PRPs/prds/{file}.prd.md` | {N} | PRD 1 | +| 3 | {name} | `.claude/PRPs/prds/{file}.prd.md` | {N} | - | + +### Dependency Order + +{Recommended execution sequence, noting which can run in parallel} + +### Open Questions Across PRDs + +{Aggregated open questions that span multiple PRDs} + +### Next Steps + +- **Sequential**: Run `/prp-plan .claude/PRPs/prds/{first-prd}.prd.md` to start +- **Parallel (independent PRDs)**: Use git worktrees for PRDs with no dependencies +- **Batch plan**: Run `/prp-plan-batch` to generate plans for all pending phases +``` + +--- + +## Examples + +``` +# Milestone with multiple projects +/prp-prd-batch "Q3 Milestone: launch self-serve onboarding, migrate billing to Stripe, add team workspaces, build analytics dashboard, implement webhook system" + +# Broad initiative +/prp-prd-batch "Build an e-commerce platform with product catalog, cart, checkout, and order management" + +# Explicit feature list +/prp-prd-batch "user authentication with SSO, role-based access control, audit logging, user profile management" + +# Single complex feature that needs splitting +/prp-prd-batch "Real-time collaboration system: presence indicators, cursor tracking, conflict resolution, change history" +``` diff --git a/README.md b/README.md index e401914a..bf54595c 100644 --- a/README.md +++ b/README.md @@ -41,13 +41,7 @@ Contact me directly at hello@rasmuswiding.com The minimum viable packet an AI needs to ship production-ready code on the first pass. -A PRP supplies an AI coding agent with everything it needs to deliver a vertical slice of working software—no more, no less. - -### How PRP Differs from Traditional PRD - -A traditional PRD clarifies _what_ the product must do and _why_ customers need it, but deliberately avoids _how_ it will be built. - -A PRP keeps the goal and justification sections of a PRD yet adds AI-critical layers: +A PRP keeps the goal and justification sections of a traditional PRD yet adds AI-critical layers: - **Context**: Precise file paths, library versions, code snippet examples - **Patterns**: Existing codebase conventions to follow @@ -57,167 +51,155 @@ A PRP keeps the goal and justification sections of a PRD yet adds AI-critical la ## Quick Start -### Option 1: Copy Commands to Your Project - ```bash -# From your project root +# Copy commands into your project cp -r /path/to/PRPs-agentic-eng/.claude/commands/prp-core .claude/commands/ -``` - -### Option 2: Clone Repository -```bash +# Or clone the repo git clone https://github.com/Wirasm/PRPs-agentic-eng.git -cd PRPs-agentic-eng ``` --- -## Commands +## Commands Reference -The `.claude/commands/prp-core/` directory contains the core PRP workflow commands: +All commands live in `.claude/commands/prp-core/` and are invoked with `/` in Claude Code. ### Core Workflow -| Command | Description | -| ---------------- | -------------------------------------------------------- | -| `/prp-prd` | Interactive PRD generator with implementation phases | -| `/prp-plan` | Create implementation plan (from PRD or free-form input) | -| `/prp-implement` | Execute a plan with validation loops | +| Command | Args | Description | +|---------|------|-------------| +| `/prp-prd` | `[feature idea]` | Interactive PRD generator — problem-first, hypothesis-driven, with phased implementation table | +| `/prp-plan` | `` | Create implementation plan (auto-selects next PRD phase if given a PRD) | +| `/prp-implement` | `` | Execute plan with validation loops (type-check, lint, test, build) | -### Issue & Debug Workflow +### Issue & Debug -| Command | Description | -| ------------------------ | ------------------------------------------------ | -| `/prp-issue-investigate` | Analyze GitHub issue, create implementation plan | -| `/prp-issue-fix` | Execute fix from investigation artifact | -| `/prp-debug` | Deep root cause analysis with 5 Whys methodology | +| Command | Args | Description | +|---------|------|-------------| +| `/prp-issue-investigate` | `` | Analyze issue with parallel codebase agents + 5 Whys RCA | +| `/prp-issue-fix` | `` | Implement fix from investigation, create PR, self-review | +| `/prp-debug` | ` [--quick]` | Deep root cause analysis (5 Whys, or 2-3 with `--quick`) | ### Git & Review -| Command | Description | -| ------------- | ------------------------------------------------- | -| `/prp-commit` | Smart commit with natural language file targeting | -| `/prp-pr` | Create PR with template support | -| `/prp-review` | Comprehensive PR code review | - -### Autonomous Loop +| Command | Args | Description | +|---------|------|-------------| +| `/prp-commit` | `[target]` | Smart commit with natural language targeting (`"typescript files"`, `"except tests"`, `"staged"`) | +| `/prp-pr` | `[base-branch]` | Push & create PR with template support | +| `/prp-review` | ` [--approve \| --request-changes]` | Single-agent comprehensive PR review | +| `/prp-review-agents` | ` [aspects]` | Multi-agent review (7 specialists: code, tests, types, docs, errors, comments, simplify) | -| Command | Description | -| ------------------- | ------------------------------------------------ | -| `/prp-ralph` | Start autonomous loop until all validations pass | -| `/prp-ralph-cancel` | Cancel active Ralph loop | +### Research ---- +| Command | Args | Description | +|---------|------|-------------| +| `/prp-codebase-question` | ` [--web] [--follow-up]` | Research-only codebase exploration with parallel agents | -## Ralph Loop (Autonomous Execution) +### Autonomous Loop (Ralph) -Based on [Geoffrey Huntley's Ralph Wiggum technique](https://ghuntley.com/ralph/) - a self-referential loop that keeps iterating until the job is actually done. +| Command | Args | Description | +|---------|------|-------------| +| `/prp-ralph` | ` [--max-iterations N]` | Implement → validate → fix → repeat until all checks pass | +| `/prp-ralph-cancel` | — | Cancel active Ralph loop | -### How It Works +### Batch Commands -``` -/prp-ralph .claude/PRPs/plans/my-feature.plan.md --max-iterations 20 -``` +Run multiple operations in a single session. The agent analyzes your input, determines the optimal number of items to generate, then invokes the corresponding single command for each. -1. Claude implements the plan tasks -2. Runs all validation commands (type-check, lint, tests, build) -3. If any validation fails → fixes and re-validates -4. Loop continues until ALL validations pass -5. Outputs `COMPLETE` and exits +| Command | Args | Description | +|---------|------|-------------| +| `/prp-prd-batch` | `` | Generate multiple PRDs from a broad initiative or feature list | +| `/prp-plan-batch` | `` | Generate plans for all pending PRD phases or a list of features | +| `/prp-commit-batch` | `[grouping strategy]` | Split working tree changes into logical commits | +| `/prp-pr-batch` | `[base-branch]` | Create PRs for multiple feature branches | -Each iteration, Claude sees its previous work in files and git history. It's not starting fresh - it's debugging itself. +--- -### Setup +## Workflow Patterns -The stop hook must be configured in `.claude/settings.local.json`: +### 1. Large Feature: PRD → Plan → Implement -```json -{ - "hooks": { - "Stop": [ - { - "hooks": [ - { - "type": "command", - "command": ".claude/hooks/prp-ralph-stop.sh" - } - ] - } - ] - } -} ``` +/prp-prd "user authentication system" + → .claude/PRPs/prds/user-auth.prd.md (with phased implementation table) -### Usage - -```bash -# Create a plan -/prp-plan "add user authentication with JWT" +/prp-plan .claude/PRPs/prds/user-auth.prd.md + → auto-selects next pending phase, creates plan -# Let Ralph loose -/prp-ralph .claude/PRPs/plans/add-user-auth.plan.md --max-iterations 20 +/prp-implement .claude/PRPs/plans/user-auth-phase-1.plan.md + → executes, validates, archives plan, updates PRD status -# Cancel if needed -/prp-ralph-cancel +Repeat /prp-plan for next phase. ``` -### Tips +### 2. Medium Feature: Direct to Plan -- Always use `--max-iterations` (default: 20) to prevent infinite loops -- Works best with plans that have clear, testable validation commands -- State is tracked in `.claude/prp-ralph.state.md` -- Progress and learnings are captured in the implementation report +``` +/prp-plan "add pagination to the API" +/prp-implement .claude/PRPs/plans/add-pagination.plan.md +``` ---- +### 3. Bug Fix: Issue Workflow -## Workflow Overview +``` +/prp-issue-investigate 123 +/prp-issue-fix 123 → creates PR with self-review +``` -### Large Features: PRD → Plan → Implement +### 4. Autonomous: Ralph Loop ``` -/prp-prd "user authentication system" - ↓ -Creates PRD with Implementation Phases table - ↓ -/prp-plan .claude/PRPs/prds/user-auth.prd.md - ↓ -Auto-selects next pending phase, creates plan - ↓ -/prp-implement .claude/PRPs/plans/user-auth-phase-1.plan.md - ↓ -Executes plan, updates PRD progress, archives plan - ↓ -Repeat /prp-plan for next phase +/prp-plan "add JWT authentication" +/prp-ralph .claude/PRPs/plans/add-jwt-auth.plan.md --max-iterations 20 ``` -### Medium Features: Direct to Plan +Ralph iterates (implement → validate → fix) until all checks pass, then exits. + +### 5. Batch: Multiple PRDs from Initiative ``` -/prp-plan "add pagination to the API" - ↓ -Creates implementation plan from description - ↓ -/prp-implement .claude/PRPs/plans/add-pagination.plan.md +/prp-prd-batch "Build a multi-tenant SaaS platform with auth, billing, and admin dashboard" + → agent determines 3 PRDs needed, generates each using /prp-prd ``` -### Bug Fixes: Issue Workflow +### 6. Parallel Development with Worktrees -``` -/prp-issue-investigate 123 - ↓ -Analyzes issue, creates investigation artifact - ↓ -/prp-issue-fix 123 - ↓ -Implements fix, creates PR +When PRD phases are marked parallel: + +```bash +git worktree add -b phase-3-ui ../project-phase-3 +git worktree add -b phase-4-tests ../project-phase-4 +# Run Claude in each worktree independently ``` --- -## Artifacts Structure +## Architecture: Agents & Patterns + +Commands use specialized subagents for intelligence gathering: -All artifacts are stored in `.claude/PRPs/`: +| Agent | Purpose | +|-------|---------| +| `codebase-explorer` | Finds WHERE code lives — files, patterns, conventions | +| `codebase-analyst` | Understands HOW code works — data flow, integration points | +| `web-researcher` | External docs, APIs, best practices, market research | +| `code-reviewer` | Guideline compliance, bugs, quality (high-confidence only) | +| `code-simplifier` | Simplifies code while preserving behavior (can push to PR) | +| `docs-impact-agent` | Updates docs affected by code changes (can push to PR) | +| `pr-test-analyzer` | Behavioral test coverage analysis | +| `silent-failure-hunter` | Finds swallowed errors, empty catches, silent fallbacks | +| `type-design-analyzer` | Type design quality (encapsulation, invariants, enforcement) | +| `comment-analyzer` | Verifies comments match actual behavior | + +**Common dispatch patterns:** +- **Parallel dual-agent**: `codebase-explorer` + `codebase-analyst` (used by `prp-plan`, `prp-prd`, `prp-issue-investigate`) +- **Sequential triple**: codebase agents first → `web-researcher` second +- **Multi-agent review**: 7 specialists dispatched by `prp-review-agents` + +--- + +## Artifacts Structure ``` .claude/PRPs/ @@ -227,36 +209,60 @@ All artifacts are stored in `.claude/PRPs/`: ├── reports/ # Implementation reports ├── issues/ # Issue investigation artifacts │ └── completed/ # Archived completed investigations -└── reviews/ # PR review reports +├── reviews/ # PR review reports +├── research/ # Codebase question outputs +├── debug/ # Root cause analysis reports +└── ralph-archives/ # Completed Ralph loop artifacts ``` --- -## PRD Phases +## Ralph Loop Setup -PRDs include an Implementation Phases table for tracking progress: +Add the stop hook to `.claude/settings.local.json`: + +```json +{ + "hooks": { + "Stop": [ + { + "hooks": [ + { + "type": "command", + "command": ".claude/hooks/prp-ralph-stop.sh" + } + ] + } + ] + } +} +``` + +--- + +## PRD Phase Tracking + +PRDs include an Implementation Phases table: ```markdown -| # | Phase | Description | Status | Parallel | Depends | PRP Plan | -| --- | ----- | ----------- | ----------- | -------- | ------- | -------- | -| 1 | Auth | User login | complete | - | - | [link] | -| 2 | API | Endpoints | in-progress | - | 1 | [link] | -| 3 | UI | Frontend | pending | with 4 | 2 | - | -| 4 | Tests | Test suite | pending | with 3 | 2 | - | +| # | Phase | Description | Status | Parallel | Depends | PRP Plan | +|---|-------|-------------|-------------|----------|---------|----------| +| 1 | Auth | User login | complete | - | - | [link] | +| 2 | API | Endpoints | in-progress | - | 1 | [link] | +| 3 | UI | Frontend | pending | with 4 | 2 | - | +| 4 | Tests | Test suite | pending | with 3 | 2 | - | ``` -- **Status**: `pending` → `in-progress` → `complete` -- **Parallel**: Phases that can run concurrently (in separate worktrees) -- **Depends**: Phases that must complete first +Status: `pending` → `in-progress` → `complete`. Phases marked parallel can run in separate worktrees. --- -## PRP Best Practices +## Best Practices -1. **Context is King**: Include ALL necessary documentation, examples, and caveats -2. **Validation Loops**: Provide executable tests/lints the AI can run and fix -3. **Information Dense**: Use keywords and patterns from the codebase -4. **Bounded Scope**: Each plan should be completable by an AI in one loop +1. **Context is King** — Include ALL necessary docs, examples, and caveats in PRPs +2. **Validation Loops** — Provide executable tests the AI can run and fix +3. **Bounded Scope** — Each plan should be completable in one AI loop +4. **Codebase First** — Explore existing patterns before introducing new ones --- @@ -265,49 +271,22 @@ PRDs include an Implementation Phases table for tracking progress: ``` your-project/ ├── .claude/ -│ ├── commands/prp-core/ # PRP commands -│ ├── PRPs/ # Generated artifacts -│ └── agents/ # Custom subagents -├── PRPs/ -│ ├── templates/ # PRP templates -│ └── ai_docs/ # Library documentation -├── CLAUDE.md # Project-specific guidelines +│ ├── commands/prp-core/ # PRP commands (copy these) +│ ├── agents/ # Specialized subagents +│ ├── hooks/ # Ralph stop hook +│ ├── skills/ # Autonomous skill definitions +│ └── PRPs/ # Generated artifacts (gitignored or committed per preference) +├── CLAUDE.md # Project-specific AI guidelines └── src/ # Your source code ``` --- -## Parallel Development with Worktrees - -When PRD phases can run in parallel: - -```bash -# Phase 3 and 4 can run concurrently -git worktree add -b phase-3-ui ../project-phase-3 -git worktree add -b phase-4-tests ../project-phase-4 - -# Run Claude in each -cd ../project-phase-3 && claude -cd ../project-phase-4 && claude -``` - ---- - ## Resources -### Templates (PRPs/templates/) - -- `prp_base.md` - Comprehensive PRP template -- `prp_story_task.md` - Story/task template -- `prp_planning.md` - Planning template - -### AI Documentation (PRPs/ai_docs/) - -Curated documentation for Claude Code context injection. - -### Legacy Commands - -Previous command versions are preserved in `old-prp-commands/` for reference. +- **Templates**: `PRPs/templates/` — PRP base, story/task, planning templates +- **AI Docs**: `PRPs/ai_docs/` — Curated Claude Code documentation for context injection +- **Legacy Commands**: `old-prp-commands/` — Previous command versions for reference ---