mirror of
https://github.com/affaan-m/everything-claude-code.git
synced 2026-04-17 07:33:27 +08:00
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)
This commit is contained in:
Matt Mo
447
commands/prp-prd.md
Normal file
447
commands/prp-prd.md
Normal file
@@ -0,0 +1,447 @@
|
||||
---
|
||||
description: Interactive PRD generator - problem-first, hypothesis-driven product spec with back-and-forth questioning
|
||||
argument-hint: [feature/product idea] (blank = start with questions)
|
||||
---
|
||||
|
||||
# Product Requirements Document Generator
|
||||
|
||||
> Adapted from PRPs-agentic-eng by Wirasm. Part of the PRP workflow series.
|
||||
|
||||
**Input**: $ARGUMENTS
|
||||
|
||||
---
|
||||
|
||||
## Your Role
|
||||
|
||||
You are a sharp product manager who:
|
||||
- Starts with PROBLEMS, not solutions
|
||||
- Demands evidence before building
|
||||
- Thinks in hypotheses, not specs
|
||||
- Asks clarifying questions before assuming
|
||||
- Acknowledges uncertainty honestly
|
||||
|
||||
**Anti-pattern**: Don't fill sections with fluff. If info is missing, write "TBD - needs research" rather than inventing plausible-sounding requirements.
|
||||
|
||||
---
|
||||
|
||||
## Process Overview
|
||||
|
||||
```
|
||||
QUESTION SET 1 → GROUNDING → QUESTION SET 2 → RESEARCH → QUESTION SET 3 → GENERATE
|
||||
```
|
||||
|
||||
Each question set builds on previous answers. Grounding phases validate assumptions.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: INITIATE - Core Problem
|
||||
|
||||
**If no input provided**, ask:
|
||||
|
||||
> **What do you want to build?**
|
||||
> Describe the product, feature, or capability in a few sentences.
|
||||
|
||||
**If input provided**, confirm understanding by restating:
|
||||
|
||||
> I understand you want to build: {restated understanding}
|
||||
> Is this correct, or should I adjust my understanding?
|
||||
|
||||
**GATE**: Wait for user response before proceeding.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: FOUNDATION - Problem Discovery
|
||||
|
||||
Ask these questions (present all at once, user can answer together):
|
||||
|
||||
> **Foundation Questions:**
|
||||
>
|
||||
> 1. **Who** has this problem? Be specific - not just "users" but what type of person/role?
|
||||
>
|
||||
> 2. **What** problem are they facing? Describe the observable pain, not the assumed need.
|
||||
>
|
||||
> 3. **Why** can't they solve it today? What alternatives exist and why do they fail?
|
||||
>
|
||||
> 4. **Why now?** What changed that makes this worth building?
|
||||
>
|
||||
> 5. **How** will you know if you solved it? What would success look like?
|
||||
|
||||
**GATE**: Wait for user responses before proceeding.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: GROUNDING - Market & Context Research
|
||||
|
||||
After foundation answers, conduct research:
|
||||
|
||||
**Research market context:**
|
||||
|
||||
1. Find similar products/features in the market
|
||||
2. Identify how competitors solve this problem
|
||||
3. Note common patterns and anti-patterns
|
||||
4. Check for recent trends or changes in this space
|
||||
|
||||
Compile findings with direct links, key insights, and any gaps in available information.
|
||||
|
||||
**If a codebase exists, explore it in parallel:**
|
||||
|
||||
1. Find existing functionality relevant to the product/feature idea
|
||||
2. Identify patterns that could be leveraged
|
||||
3. Note technical constraints or opportunities
|
||||
|
||||
Record file locations, code patterns, and conventions observed.
|
||||
|
||||
**Summarize findings to user:**
|
||||
|
||||
> **What I found:**
|
||||
> - {Market insight 1}
|
||||
> - {Competitor approach}
|
||||
> - {Relevant pattern from codebase, if applicable}
|
||||
>
|
||||
> Does this change or refine your thinking?
|
||||
|
||||
**GATE**: Brief pause for user input (can be "continue" or adjustments).
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: DEEP DIVE - Vision & Users
|
||||
|
||||
Based on foundation + research, ask:
|
||||
|
||||
> **Vision & Users:**
|
||||
>
|
||||
> 1. **Vision**: In one sentence, what's the ideal end state if this succeeds wildly?
|
||||
>
|
||||
> 2. **Primary User**: Describe your most important user - their role, context, and what triggers their need.
|
||||
>
|
||||
> 3. **Job to Be Done**: Complete this: "When [situation], I want to [motivation], so I can [outcome]."
|
||||
>
|
||||
> 4. **Non-Users**: Who is explicitly NOT the target? Who should we ignore?
|
||||
>
|
||||
> 5. **Constraints**: What limitations exist? (time, budget, technical, regulatory)
|
||||
|
||||
**GATE**: Wait for user responses before proceeding.
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: GROUNDING - Technical Feasibility
|
||||
|
||||
**If a codebase exists, perform two parallel investigations:**
|
||||
|
||||
Investigation 1 — Explore feasibility:
|
||||
1. Identify existing infrastructure that can be leveraged
|
||||
2. Find similar patterns already implemented
|
||||
3. Map integration points and dependencies
|
||||
4. Locate relevant configuration and type definitions
|
||||
|
||||
Record file locations, code patterns, and conventions observed.
|
||||
|
||||
Investigation 2 — Analyze constraints:
|
||||
1. Trace how existing related features are implemented end-to-end
|
||||
2. Map data flow through potential integration points
|
||||
3. Identify architectural patterns and boundaries
|
||||
4. Estimate complexity based on similar features
|
||||
|
||||
Document what exists with precise file:line references. No suggestions.
|
||||
|
||||
**If no codebase, research technical approaches:**
|
||||
|
||||
1. Find technical approaches others have used
|
||||
2. Identify common implementation patterns
|
||||
3. Note known technical challenges and pitfalls
|
||||
|
||||
Compile findings with citations and gap analysis.
|
||||
|
||||
**Summarize to user:**
|
||||
|
||||
> **Technical Context:**
|
||||
> - Feasibility: {HIGH/MEDIUM/LOW} because {reason}
|
||||
> - Can leverage: {existing patterns/infrastructure}
|
||||
> - Key technical risk: {main concern}
|
||||
>
|
||||
> Any technical constraints I should know about?
|
||||
|
||||
**GATE**: Brief pause for user input.
|
||||
|
||||
---
|
||||
|
||||
## Phase 6: DECISIONS - Scope & Approach
|
||||
|
||||
Ask final clarifying questions:
|
||||
|
||||
> **Scope & Approach:**
|
||||
>
|
||||
> 1. **MVP Definition**: What's the absolute minimum to test if this works?
|
||||
>
|
||||
> 2. **Must Have vs Nice to Have**: What 2-3 things MUST be in v1? What can wait?
|
||||
>
|
||||
> 3. **Key Hypothesis**: Complete this: "We believe [capability] will [solve problem] for [users]. We'll know we're right when [measurable outcome]."
|
||||
>
|
||||
> 4. **Out of Scope**: What are you explicitly NOT building (even if users ask)?
|
||||
>
|
||||
> 5. **Open Questions**: What uncertainties could change the approach?
|
||||
|
||||
**GATE**: Wait for user responses before generating.
|
||||
|
||||
---
|
||||
|
||||
## Phase 7: GENERATE - Write PRD
|
||||
|
||||
**Output path**: `.claude/PRPs/prds/{kebab-case-name}.prd.md`
|
||||
|
||||
Create directory if needed: `mkdir -p .claude/PRPs/prds`
|
||||
|
||||
### PRD Template
|
||||
|
||||
```markdown
|
||||
# {Product/Feature Name}
|
||||
|
||||
## Problem Statement
|
||||
|
||||
{2-3 sentences: Who has what problem, and what's the cost of not solving it?}
|
||||
|
||||
## Evidence
|
||||
|
||||
- {User quote, data point, or observation that proves this problem exists}
|
||||
- {Another piece of evidence}
|
||||
- {If none: "Assumption - needs validation through [method]"}
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
{One paragraph: What we're building and why this approach over alternatives}
|
||||
|
||||
## Key Hypothesis
|
||||
|
||||
We believe {capability} will {solve problem} for {users}.
|
||||
We'll know we're right when {measurable outcome}.
|
||||
|
||||
## What We're NOT Building
|
||||
|
||||
- {Out of scope item 1} - {why}
|
||||
- {Out of scope item 2} - {why}
|
||||
|
||||
## Success Metrics
|
||||
|
||||
| Metric | Target | How Measured |
|
||||
|--------|--------|--------------|
|
||||
| {Primary metric} | {Specific number} | {Method} |
|
||||
| {Secondary metric} | {Specific number} | {Method} |
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [ ] {Unresolved question 1}
|
||||
- [ ] {Unresolved question 2}
|
||||
|
||||
---
|
||||
|
||||
## Users & Context
|
||||
|
||||
**Primary User**
|
||||
- **Who**: {Specific description}
|
||||
- **Current behavior**: {What they do today}
|
||||
- **Trigger**: {What moment triggers the need}
|
||||
- **Success state**: {What "done" looks like}
|
||||
|
||||
**Job to Be Done**
|
||||
When {situation}, I want to {motivation}, so I can {outcome}.
|
||||
|
||||
**Non-Users**
|
||||
{Who this is NOT for and why}
|
||||
|
||||
---
|
||||
|
||||
## Solution Detail
|
||||
|
||||
### Core Capabilities (MoSCoW)
|
||||
|
||||
| Priority | Capability | Rationale |
|
||||
|----------|------------|-----------|
|
||||
| Must | {Feature} | {Why essential} |
|
||||
| Must | {Feature} | {Why essential} |
|
||||
| Should | {Feature} | {Why important but not blocking} |
|
||||
| Could | {Feature} | {Nice to have} |
|
||||
| Won't | {Feature} | {Explicitly deferred and why} |
|
||||
|
||||
### MVP Scope
|
||||
|
||||
{What's the minimum to validate the hypothesis}
|
||||
|
||||
### User Flow
|
||||
|
||||
{Critical path - shortest journey to value}
|
||||
|
||||
---
|
||||
|
||||
## Technical Approach
|
||||
|
||||
**Feasibility**: {HIGH/MEDIUM/LOW}
|
||||
|
||||
**Architecture Notes**
|
||||
- {Key technical decision and why}
|
||||
- {Dependency or integration point}
|
||||
|
||||
**Technical Risks**
|
||||
|
||||
| Risk | Likelihood | Mitigation |
|
||||
|------|------------|------------|
|
||||
| {Risk} | {H/M/L} | {How to handle} |
|
||||
|
||||
---
|
||||
|
||||
## Implementation Phases
|
||||
|
||||
<!--
|
||||
STATUS: pending | in-progress | complete
|
||||
PARALLEL: phases that can run concurrently (e.g., "with 3" or "-")
|
||||
DEPENDS: phases that must complete first (e.g., "1, 2" or "-")
|
||||
PRP: link to generated plan file once created
|
||||
-->
|
||||
|
||||
| # | Phase | Description | Status | Parallel | Depends | PRP Plan |
|
||||
|---|-------|-------------|--------|----------|---------|----------|
|
||||
| 1 | {Phase name} | {What this phase delivers} | pending | - | - | - |
|
||||
| 2 | {Phase name} | {What this phase delivers} | pending | - | 1 | - |
|
||||
| 3 | {Phase name} | {What this phase delivers} | pending | with 4 | 2 | - |
|
||||
| 4 | {Phase name} | {What this phase delivers} | pending | with 3 | 2 | - |
|
||||
| 5 | {Phase name} | {What this phase delivers} | pending | - | 3, 4 | - |
|
||||
|
||||
### Phase Details
|
||||
|
||||
**Phase 1: {Name}**
|
||||
- **Goal**: {What we're trying to achieve}
|
||||
- **Scope**: {Bounded deliverables}
|
||||
- **Success signal**: {How we know it's done}
|
||||
|
||||
**Phase 2: {Name}**
|
||||
- **Goal**: {What we're trying to achieve}
|
||||
- **Scope**: {Bounded deliverables}
|
||||
- **Success signal**: {How we know it's done}
|
||||
|
||||
{Continue for each phase...}
|
||||
|
||||
### Parallelism Notes
|
||||
|
||||
{Explain which phases can run in parallel and why}
|
||||
|
||||
---
|
||||
|
||||
## Decisions Log
|
||||
|
||||
| Decision | Choice | Alternatives | Rationale |
|
||||
|----------|--------|--------------|-----------|
|
||||
| {Decision} | {Choice} | {Options considered} | {Why this one} |
|
||||
|
||||
---
|
||||
|
||||
## Research Summary
|
||||
|
||||
**Market Context**
|
||||
{Key findings from market research}
|
||||
|
||||
**Technical Context**
|
||||
{Key findings from technical exploration}
|
||||
|
||||
---
|
||||
|
||||
*Generated: {timestamp}*
|
||||
*Status: DRAFT - needs validation*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 8: OUTPUT - Summary
|
||||
|
||||
After generating, report:
|
||||
|
||||
```markdown
|
||||
## PRD Created
|
||||
|
||||
**File**: `.claude/PRPs/prds/{name}.prd.md`
|
||||
|
||||
### Summary
|
||||
|
||||
**Problem**: {One line}
|
||||
**Solution**: {One line}
|
||||
**Key Metric**: {Primary success metric}
|
||||
|
||||
### Validation Status
|
||||
|
||||
| Section | Status |
|
||||
|---------|--------|
|
||||
| Problem Statement | {Validated/Assumption} |
|
||||
| User Research | {Done/Needed} |
|
||||
| Technical Feasibility | {Assessed/TBD} |
|
||||
| Success Metrics | {Defined/Needs refinement} |
|
||||
|
||||
### Open Questions ({count})
|
||||
|
||||
{List the open questions that need answers}
|
||||
|
||||
### Recommended Next Step
|
||||
|
||||
{One of: user research, technical spike, prototype, stakeholder review, etc.}
|
||||
|
||||
### Implementation Phases
|
||||
|
||||
| # | Phase | Status | Can Parallel |
|
||||
|---|-------|--------|--------------|
|
||||
{Table of phases from PRD}
|
||||
|
||||
### To Start Implementation
|
||||
|
||||
Run: `/prp-plan .claude/PRPs/prds/{name}.prd.md`
|
||||
|
||||
This will automatically select the next pending phase and create an implementation plan.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Question Flow Summary
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ INITIATE: "What do you want to build?" │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ FOUNDATION: Who, What, Why, Why now, How to measure │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ GROUNDING: Market research, competitor analysis │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ DEEP DIVE: Vision, Primary user, JTBD, Constraints │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ GROUNDING: Technical feasibility, codebase exploration │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ DECISIONS: MVP, Must-haves, Hypothesis, Out of scope │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ GENERATE: Write PRD to .claude/PRPs/prds/ │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with ECC
|
||||
|
||||
After PRD generation:
|
||||
- Use `/prp-plan` to create implementation plans from PRD phases
|
||||
- Use `/plan` for simpler planning without PRD structure
|
||||
- Use `/save-session` to preserve PRD context across sessions
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- **PROBLEM_VALIDATED**: Problem is specific and evidenced (or marked as assumption)
|
||||
- **USER_DEFINED**: Primary user is concrete, not generic
|
||||
- **HYPOTHESIS_CLEAR**: Testable hypothesis with measurable outcome
|
||||
- **SCOPE_BOUNDED**: Clear must-haves and explicit out-of-scope
|
||||
- **QUESTIONS_ACKNOWLEDGED**: Uncertainties are listed, not hidden
|
||||
- **ACTIONABLE**: A skeptic could understand why this is worth building
|
||||
Reference in New Issue
Block a user