zhongwei/gh-navidemad-claude-code-plugins-prd-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:42:25 +08:00
commit c0a5a7e86d
7 changed files with 4112 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

796
skills/plan-prd/SKILL.md Normal file
View File

@@ -0,0 +1,796 @@
---
name: plan-prd
description: Create product requirement documents when user wants to plan features, write specs, or document new functionality. Supports minimal core features, focused expansions, and task-based changes. Automatically loads context from related PRDs to maintain consistency.
---
# Plan PRD
Create structured PRDs using the **"land then expand"** approach with automatic context management for consistency.
**Communication Style**: In all interactions and commit messages, be extremely concise and sacrifice grammar for the sake of concision.
## Philosophy: Land Then Expand
Modern Claude models work best when they establish patterns first, then layer complexity. This skill creates:
1. **Core PRDs**: Minimal foundation with essential fields only (2-4 substories max)
2. **Expansion PRDs**: Focused enhancements building on completed core with auto-loaded context
**Why**: Large comprehensive PRDs lead to incorrect assumptions, token inefficiency, and inconsistent results.
## Activation Context
Use when user says things like:
- "plan a feature for..."
- "write a PRD for..."
- "I want to build..."
- "document requirements for..."
- "create a spec for..."
- "plan [feature name]"
- Any request to plan, design, or document new functionality
## Workflow
### Phase 0: Validate Prerequisites
**FIRST: Check for CLAUDE.md**
```bash
if [[ ! -f "CLAUDE.md" ]]; then
cat <<EOF
❌ ERROR: CLAUDE.md file not found in project root
This workflow requires a CLAUDE.md file documenting your project conventions.
To create one, start a new Claude Code session and type:
/init
Then describe your project, and Claude will help create CLAUDE.md.
Exiting...
EOF
exit 1
fi
```
**Show confirmation:**
```
✅ CLAUDE.md found
📋 Ready to plan PRD
```
### Phase 1: Determine PRD Type and Load Context
**Step 1: Ask PRD Type**
**CRITICAL**: Ask user to determine the PRD type:
```
Is this:
1. 🌱 A new core feature (minimal foundation to establish patterns)
2. 🔧 An expansion of existing feature (builds on completed core)
3. ⚡ A task-based change (infrastructure, migration, optimization, refactor, etc.)
Choose [1/2/3]:
```
**If user chooses "1 - Core Feature":**
- Create minimal foundation PRD
- Max 2-4 substories in single phase
- Essential fields only
- File: `.claude/prds/YYYY-MM-DD-{feature}-core.md`
- Goal: Establish patterns and working code, NOT completeness
- Initialize context: `.claude/prds/context/YYYY-MM-DD-{feature}-core.json`
**If user chooses "2 - Expansion":**
- Ask: "Which core feature does this expand?" or auto-detect from `.claude/prds/`
- **VALIDATE CORE PRD EXISTS AND IS COMPLETE:**
```bash
# Check core PRD exists
if [[ ! -f "$core_prd_file" ]]; then
echo "❌ ERROR: Core PRD not found"
exit 1
fi
# Check core PRD is marked complete
if ! grep -q "Status.*Complete" "$core_prd_file"; then
echo "⚠️ WARNING: Core PRD not marked complete"
echo "Expansion PRDs should build on completed cores."
echo "Continue anyway? [yes/no]"
fi
# Check context file exists
if [[ ! -f ".claude/prds/context/{core-prd-name}.json" ]]; then
echo "⚠️ WARNING: No context file found for core PRD"
echo "Context may be limited. Continue? [yes/no]"
fi
```
- **AUTOMATICALLY LOAD CORE CONTEXT:**
1. Read core PRD file (parse frontmatter, substories, acceptance criteria)
2. Load `.claude/prds/context/{core-prd-name}.json` (structured context)
3. Extract files_created, patterns, libraries, architectural_decisions
4. Read actual core implementation files (analyze code patterns)
5. Document established patterns with examples
6. Present findings to user before asking questions
- Create focused expansion PRD building on core
- File: `.claude/prds/YYYY-MM-DD-{feature}-{expansion-name}.md`
- Goal: Add ONE focused aspect using established patterns
**If user chooses "3 - Task-based Change":**
- Use task-oriented format instead of substories
- File: `.claude/prds/YYYY-MM-DD-{task-name}-task.md`
- Format: Checklist of concrete steps instead of phases/substories
- Examples: Database migration, CI/CD setup, performance optimization, refactoring, security patch
- Goal: Complete specific technical task with clear acceptance criteria
**Step 2: Understand Feature Scope**
Ask scoping question:
```
"Describe the [core feature/expansion] briefly (1-2 sentences):"
```
**For Core PRDs - Enforce Minimalism:**
If user describes complex multi-part feature, push back:
```
🌱 Core PRD Mode: Let's start with the absolute minimum.
You described: [user's description]
What's the simplest version with just essential fields?
Example: If building invoices, start with just number, date, amount.
Everything else (customers, line items, tax) comes later as expansions.
Simplest core version:
```
**For Expansion PRDs:**
Ask specifically what this expansion adds to the core.
**Step 3: Explore Existing Codebase**
**Before asking detailed questions, understand what exists:**
```bash
# Read project conventions from CLAUDE.md in project root
# This file contains project-specific conventions, tech stack, patterns, etc.
# Example: Read CLAUDE.md
```
**For Core PRDs:**
Explore to understand project patterns and conventions from CLAUDE.md and existing codebase.
**For Expansion PRDs (CRITICAL - AUTO-LOAD):**
**Execute comprehensive context loading:**
```bash
# Source context manager
source skills/shared/scripts/context-manager.sh
# 1. Load core PRD file
core_prd_content=$(cat "$core_prd_file")
# 2. Load core context file
core_context=$(read_context "$core_prd_file")
# 3. Extract structured information
core_files=$(echo "$core_context" | jq -r '.files_created[]')
core_patterns=$(echo "$core_context" | jq -r '.patterns')
core_libraries=$(echo "$core_context" | jq -r '.libraries')
core_decisions=$(echo "$core_context" | jq -r '.architectural_decisions[]')
# 4. Read actual implementation files to understand patterns
echo "📖 Reading core implementation files..."
for file in $core_files; do
if [[ -f "$file" ]]; then
# Read file to analyze patterns, naming conventions, structure
# Focus on: class/function naming, code organization, error handling
fi
done
# 5. Analyze patterns from code
# - Identify naming conventions (e.g., *Service, *Repository, *Controller)
# - Detect architectural patterns (e.g., MVC, service layer, repository pattern)
# - Note error handling approaches
# - Identify validation patterns
# - Observe data flow patterns
```
**Document comprehensive findings:**
```
🔍 Context Analysis Complete:
[For Core PRDs:]
Project Conventions (from CLAUDE.md):
- Tech stack: [framework, language, key technologies]
- Architecture: [architectural pattern from CLAUDE.md]
- Testing: [testing framework and approach]
- Code style: [linting, formatting standards]
Existing Patterns (from codebase exploration):
- Similar features found: [list related features]
- Common patterns: [list patterns observed]
- File organization: [describe structure]
- Naming conventions: [describe conventions]
[For Expansion PRDs - AUTO-LOADED:]
✅ Core Context Loaded: docs/prds/YYYY-MM-DD-{feature}-core.md
Implementation Files ([X] files):
[List actual files with brief description of each]
- path/to/file1.ext - [what it does]
- path/to/file2.ext - [what it does]
Established Patterns ([Y] patterns):
[List specific patterns with examples from code]
- Pattern 1: [name] - [where used, how implemented]
- Pattern 2: [name] - [where used, how implemented]
Libraries in Use ([Z] libraries):
[List with purpose]
- library1 - [purpose in core]
- library2 - [purpose in core]
Architectural Decisions ([W] decisions):
[List key decisions with rationale]
1. [Decision 1]: [rationale from context]
2. [Decision 2]: [rationale from context]
Code Analysis Insights:
- Naming convention: [pattern observed, e.g., "FeatureNameService"]
- Error handling: [approach used, e.g., "Custom exception classes"]
- Validation: [approach used, e.g., "Schema validators"]
- Data access: [pattern used, e.g., "Repository pattern"]
✅ Expansion will extend these patterns consistently.
```
### Phase 1: Requirements Gathering
**Adapt questions based on PRD type:**
**CORE PRD MODE** - Ask focused essential questions (5-8 questions):
**Start with understanding:**
1. **Problem & Context:**
- "What problem does this solve?" (User pain point or business need)
- "Who is this for?" (Target users/personas)
2. **Minimal Scope:**
- "What's the simplest version that solves the core problem?" (Essential functionality only)
- "What are the absolute minimum data/fields needed?" (Core data model)
- "What's the ONE primary user flow?" (Single happy path)
3. **Success & Boundaries:**
- "How will we measure success?" (Success criteria, metrics)
- "What's explicitly NOT included in v1?" (Out of scope - becomes expansions)
4. **Technical Constraints:**
- "Any critical dependencies or integrations?" (Required systems/services)
- "Any technical constraints we should know about?" (Performance, security, compliance)
**Approach**: Ask questions conversationally, not as a rigid checklist. If answers suggest complexity, push back:
```
💡 That sounds complex for a core PRD. Core should be minimal (2-4 substories).
You mentioned: [complex features A, B, C]
Simplest core version: [essential feature only]
Future expansions: [B], [C]
Does that work?
```
**EXPANSION PRD MODE** - Ask focused questions about the expansion (6-10 questions):
**First, present loaded context:**
```
✅ Core context loaded from: [core PRD name]
Found:
- [X] implementation files
- [Y] established patterns
- [Z] libraries in use
- [W] architectural decisions
I'll ask questions to understand how this expansion builds on these patterns.
```
**Then ask expansion-specific questions:**
1. **Expansion Goal:**
- "What specific capability does this add to the core?" (Single focused enhancement)
- "What user need or use case does this address?" (Why this expansion)
2. **Data & Integration:**
- "What new data/fields are needed?" (Data model additions)
- "How does this connect to existing core code?" (Integration points)
- "Which core files will be extended vs new files?" (Code changes)
3. **User Experience:**
- "What new or enhanced user flows?" (User interactions)
- "How does this change the existing user experience?" (UX impact)
4. **Success & Constraints:**
- "How will we know this expansion works?" (Acceptance criteria)
- "Any performance or security considerations?" (Non-functional requirements)
- "What's out of scope for THIS expansion?" (Boundaries - next expansion)
**Approach**: Reference loaded patterns explicitly in questions:
```
I see the core uses [Pattern X] for [Purpose]. Should this expansion follow the same pattern?
```
**Important**:
- Expansion PRDs are FOCUSED on ONE aspect (e.g., customer details OR line items, not both)
- Must build on core patterns, not introduce conflicting approaches
- If scope seems large, suggest splitting into multiple expansions
### Phase 2: Document Generation
**CRITICAL**: Structure differs for core vs expansion PRDs.
#### Core PRD Structure
File: `.claude/prds/YYYY-MM-DD-{feature}-core.md`
```markdown
# [Feature Name] - Core
**Type:** Core Feature
**Created:** YYYY-MM-DD
**Status:** Planning
**Context File:** `.claude/prds/context/YYYY-MM-DD-{feature}-core.json`
## Overview
### Problem Statement
[Clear articulation of problem]
### Core Solution
[Minimal viable solution - essential fields/functionality ONLY]
### Users
[Target users]
### Success Criteria
- [Basic measurable criteria]
### SLC Commitment
**This PRD defines an SLC (Simple, Lovable, Complete) - *not* an MVP.** The release must feel complete, polished, and delightful even with a tight scope.
## Core Requirements
### Essential Data/Fields
[ONLY the minimum viable fields - example: invoice number, date, amount]
### Core User Flow
[Single primary happy path only]
### Out of Scope (Future Expansions)
[List everything NOT in core - these become expansion PRDs]
Examples:
- Customer details → expansion PRD
- Line items → expansion PRD
- Tax calculations → expansion PRD
## Implementation
**RULE**: Maximum ONE phase with 2-4 substories
### Phase 1: Core Foundation
**Goal:** Establish minimal working feature with essential patterns
#### Substory 1.1: [Minimal Model/Component]
**Description:** [Create basic entity with essential fields only]
**Acceptance Criteria:**
- [ ] [Essential field 1] works
- [ ] [Essential field 2] works
- [ ] Basic CRUD operations
**Status:** ⏳ Not Started
#### Substory 1.2: [Basic Interface/API]
**Description:** [Simple create/read operations]
**Acceptance Criteria:**
- [ ] Can create with essential fields
- [ ] Can retrieve
**Status:** ⏳ Not Started
[2-4 substories maximum]
## Project-Specific Notes
[Minimal project-specific details for core only - reference CLAUDE.md]
## Next Expansions
After core is complete, consider these expansion PRDs:
1. [Expansion 1 name]
2. [Expansion 2 name]
3. [Expansion 3 name]
## Context
This PRD has an associated context file at `.claude/prds/context/YYYY-MM-DD-{feature}-core.json` which tracks:
- Architectural decisions
- Patterns established
- Libraries chosen
- Files created
This context is automatically loaded when creating expansion PRDs.
```
#### Expansion PRD Structure
File: `.claude/prds/YYYY-MM-DD-{feature}-{expansion-name}.md`
```markdown
# [Feature Name] - [Expansion Name]
**Type:** Expansion
**Builds On:** [Link to core PRD: .claude/prds/YYYY-MM-DD-{feature}-core.md]
**Created:** YYYY-MM-DD
**Status:** Planning
**Context File:** `.claude/prds/context/YYYY-MM-DD-{feature}-{expansion}.json` (inherits from core)
## Overview
### What This Expansion Adds
[Specific enhancement to core]
### Core Implementation Reference (AUTO-LOADED)
**Core PRD:** `.claude/prds/YYYY-MM-DD-{feature}-core.md`
**Files created in core:**
[AUTO-POPULATED from context file - actual file paths from your project]
**Patterns established in core:**
[AUTO-POPULATED from context file - actual patterns used in your codebase]
**Libraries in use:**
[AUTO-POPULATED from context file - actual libraries chosen during core implementation]
**Architectural decisions:**
[AUTO-POPULATED from context file - actual decisions made during core implementation]
### Success Criteria
- [Measurable criteria for this expansion]
### SLC Commitment
**This PRD defines an SLC (Simple, Lovable, Complete) - *not* an MVP.** The release must feel complete, polished, and delightful even with a tight scope.
## Expansion Requirements
### New Data/Fields
[What's added to the core data model]
### Enhanced/New User Flows
[How this changes or adds to core flows]
### Integration with Core
[How this connects to existing core implementation]
## Implementation
### Phase 1: [Expansion Name]
**Goal:** [Expansion objective]
#### Substory 1.1: [Enhancement 1]
**Description:** [Building on core patterns]
**Core Files to Modify:**
- [existing file from core]
**Core Patterns to Follow:**
- [reference established patterns from auto-loaded context]
**Acceptance Criteria:**
- [ ] [Criterion 1]
**Status:** ⏳ Not Started
[Add substories as needed for focused expansion]
## Testing Strategy
[Test approach following core's testing framework]
## Security Considerations
[Following core's security patterns]
## Performance Considerations
[Optimizations specific to this expansion]
## Dependencies
**Internal:**
- Requires: [Core PRD completion]
**External:**
- [New third-party services if any]
## Context
This expansion inherits context from core and adds expansion-specific context to `.claude/prds/context/YYYY-MM-DD-{feature}-{expansion}.json`.
```
#### Task-Based PRD Structure
File: `.claude/prds/YYYY-MM-DD-{task-name}-task.md`
```markdown
# [Task Name]
**Type:** Task
**Created:** YYYY-MM-DD
**Status:** Planning
**Context File:** `.claude/prds/context/YYYY-MM-DD-{task-name}-task.json`
## Overview
### Problem/Goal
[Clear description of what needs to be done and why]
### Success Criteria
- [Measurable criteria for completion]
## Technical Approach
[Describe the approach, technology choices, and reasoning]
## Implementation Checklist
**Each checkbox represents a concrete step:**
### Preparation
- [ ] [Step 1: e.g., Backup database, review current config]
- [ ] [Step 2: e.g., Set up test environment]
### Execution
- [ ] [Step 3: e.g., Create migration scripts]
- [ ] [Step 4: e.g., Update configuration files]
- [ ] [Step 5: e.g., Deploy changes]
### Validation
- [ ] [Step 6: e.g., Run integration tests]
- [ ] [Step 7: e.g., Verify monitoring/alerts]
- [ ] [Step 8: e.g., Document changes]
**Status:** ⏳ Not Started
## Testing Strategy
[How to verify this task is complete]
## Rollback Plan
[How to revert if something goes wrong]
## Dependencies
**Internal:** [Other PRDs or systems affected]
**External:** [Third-party services, tools required]
## Project-Specific Notes
[Any project-specific details from CLAUDE.md]
## Context
Task-based PRDs use simplified context tracking focused on steps completed rather than phases/substories.
```
### Phase 3: Context Initialization
**After creating PRD:**
```bash
# Source context manager
source skills/shared/scripts/context-manager.sh
# Initialize context file
context_file=$(init_context "$prd_file")
# For expansions: inherit core context
if [[ "$prd_type" == "expansion" ]]; then
# Copy core context as base
core_context=$(read_context "$core_prd_file")
# Add expansion-specific fields
# Update context with expansion name
fi
# For tasks: simpler context structure
if [[ "$prd_type" == "task" ]]; then
# Task-based context focuses on checklist completion
# No phases/substories tracking needed
fi
```
### Phase 4: Validation and Next Steps
**After Core PRD creation:**
- Verify it's truly minimal (2-4 substories max)
- Confirm essential fields only
- Suggest expansion PRDs for excluded features
- Confirm context file created
- Output message:
```
✅ Core PRD created: .claude/prds/YYYY-MM-DD-{feature}-core.md
📋 Context file: .claude/prds/context/YYYY-MM-DD-{feature}-core.json
📋 Core includes: [brief summary]
🚫 Out of scope (future expansions): [list]
💡 Next steps:
1. "implement" - Build core foundation with auto-testing and review
2. After core is complete, use "plan" again for expansions:
- Customer details expansion
- Line items expansion
- [etc]
```
**After Expansion PRD creation:**
- Verify it builds on completed core
- Confirm focused on ONE aspect
- Reference core implementation patterns
- Confirm context inherited and extended
- Output message:
```
✅ Expansion PRD created: .claude/prds/YYYY-MM-DD-{feature}-{expansion}.md
📋 Context file: .claude/prds/context/YYYY-MM-DD-{feature}-{expansion}.json
🔧 Expands: {core feature name}
📋 Adds: [brief summary]
🎯 Auto-loaded from core:
- [X] files created
- [Y] patterns
- [Z] libraries
- [W] architectural decisions
💡 Next: "implement" to build this expansion following core patterns
```
**After Task-Based PRD creation:**
- Verify checklist is concrete and actionable
- Confirm rollback plan is included
- Confirm success criteria are measurable
- Output message:
```
✅ Task PRD created: .claude/prds/YYYY-MM-DD-{task-name}-task.md
📋 Context file: .claude/prds/context/YYYY-MM-DD-{task-name}-task.json
⚡ Task: [brief summary]
📋 Steps: [X] concrete steps defined
✅ Success criteria: [brief list]
🔄 Rollback plan: Included
💡 Next: "implement" to execute this task checklist
```
## Guidelines
**Critical Rules:**
- **ALWAYS ask core vs expansion first** - This determines everything
- **For Core: Enforce minimalism** - Push back on complexity, max 2-4 substories
- **For Expansion: AUTO-LOAD core context** - Read core PRD and context file automatically
- **Initialize context files** - Always create/update `.claude/prds/context/{prd-name}.json`
- **Naming convention**:
- Core: `.claude/prds/YYYY-MM-DD-{feature}-core.md`
- Expansion: `.claude/prds/YYYY-MM-DD-{feature}-{expansion-name}.md`
**Project Conventions:**
- Read `CLAUDE.md` from project root for project-specific conventions
- Use project-defined terminology and patterns from CLAUDE.md
- Follow tech stack, architecture, and coding standards documented in CLAUDE.md
**Context Management:**
- Create context file on PRD creation
- For expansions: inherit core context automatically
- Store: patterns, libraries, architectural decisions from CLAUDE.md and codebase
- Used by `implement` skill for consistency
**Quality Checks:**
- Ensure acceptance criteria are testable
- Document assumptions explicitly
- Reference project patterns from CLAUDE.md and existing codebase
- For expansions: explicitly reference and auto-load core implementation patterns
- Verify context files are created and populated
## Auto-Loading Core Context (Expansion Mode)
When creating an expansion PRD, the skill **automatically**:
1. **Validates core PRD**:
- Checks core PRD file exists
- Warns if core is not marked complete
- Checks context file exists
- Verifies context file is valid JSON
2. **Loads core information**:
- Reads core PRD file content (parse frontmatter, substories)
- Reads `.claude/prds/context/{core-prd-name}.json` file
- Extracts structured data (files, patterns, libraries, decisions)
3. **Analyzes implementation**:
- Reads actual implementation files from `files_created`
- Analyzes code patterns: naming conventions, structure, error handling
- Identifies architectural patterns in use
- Documents specific examples from code
4. **Presents findings before questions**:
```
✅ Core context loaded successfully
Implementation files analyzed:
- src/models/invoice.rb - Core data model with validations
- src/services/invoice_service.rb - Business logic service
- src/api/invoices_controller.rb - RESTful API endpoints
Patterns identified:
- Service objects for business logic (InvoiceService)
- ActiveRecord models with validations
- RESTful API with JSON serialization
- RSpec for testing
Libraries in use:
- ActiveRecord (ORM)
- ActiveModel::Serializers (JSON API)
Now I'll ask how this expansion builds on these patterns...
```
5. **Uses context during PRD creation**:
- Auto-fills "Core Implementation Reference" section with real data
- References specific patterns in substory descriptions
- Suggests extending existing files vs creating new ones
- Inherits architectural decisions
6. **Creates expansion context**:
- Expansion context starts with core context as base
- Adds expansion-specific patterns, files, decisions
- Maintains link to core PRD
**This ensures expansions are consistent with core through automated context awareness.**
## Directory Structure
The skill maintains this directory structure:
```
.claude/prds/
├── YYYY-MM-DD-feature-core.md # Active PRD files
├── YYYY-MM-DD-feature-expansion.md
├── context/ # Active context files
│ ├── YYYY-MM-DD-feature-core.json
│ └── YYYY-MM-DD-feature-expansion.json
└── archive/ # Manual archival (user responsibility)
├── old-feature.md # Archived PRD
└── context/
└── old-feature.json # Archived context
```
**Archive Usage:**
- The `archive/` folder is created but managed by users
- When archiving a completed PRD, move **both** files:
- `.claude/prds/feature.md` → `.claude/prds/archive/feature.md`
- `.claude/prds/context/feature.json` → `.claude/prds/archive/context/feature.json`
- This keeps PRD and context paired together
- Only archive PRDs that are fully complete, shipped, and no longer actively referenced
## Directory Initialization
Before creating any PRD, validate and create required directories:
```bash
# Ensure .claude directory structure exists
mkdir -p .claude/prds/context
mkdir -p .claude/prds/archive/context
mkdir -p .claude/checkpoints
# Ensure checkpoints are gitignored (created by code-prd skill)
if [[ -f ".gitignore" ]]; then
if ! grep -q "\.claude/checkpoints" .gitignore; then
echo ".claude/checkpoints/" >> .gitignore
fi
fi
# Note: archive/ is for user manual archival only
# Users should move both .md and corresponding .json to archive/
# to keep PRD and context paired together
```