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

14
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,14 @@
{
"name": "prd-skills",
"description": "Complete PRD workflow: plan features with intelligent context loading, implement with automatic testing and code review, and ship with well-formatted commits and PRs. Supports core features, expansions, and tasks.",
"version": "1.1.0",
"author": {
"name": "Navid Emad",
"email": "design.navid@gmail.com"
},
"skills": [
"./skills/plan-prd",
"./skills/code-prd",
"./skills/publish"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# prd-skills
Complete PRD workflow: plan features with intelligent context loading, implement with automatic testing and code review, and ship with well-formatted commits and PRs. Supports core features, expansions, and tasks.

57
plugin.lock.json Normal file
View File

@@ -0,0 +1,57 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:navidemad/claude-code-plugins:prd-plugin",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "457139313795ad68571e8510f3f4518063ea5e8e",
"treeHash": "ba1f2c9dce5fccbb2c70341d16f9dc6c94099d693f670662165c1954d7350def",
"generatedAt": "2025-11-28T10:27:17.162054Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "prd-skills",
"description": "Complete PRD workflow: plan features with intelligent context loading, implement with automatic testing and code review, and ship with well-formatted commits and PRs. Supports core features, expansions, and tasks.",
"version": "1.1.0"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "50d33093063c723ead0277ac9bb05510509877031aba09857facf8edae7f331c"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "c0b6f60e3dea933895fe4ee7e46a7360ca864ed6055f8a57524beaef59a48234"
},
{
"path": "skills/code-prd/SKILL.md",
"sha256": "ad6c0e758f3555db679fb13383feec93cc2e675782f8c8345f590b30b54c888b"
},
{
"path": "skills/code-prd/references/ux-enhancements.md",
"sha256": "232e12f38ca352bb1fa66cd021630d7f7fea522d78d8ae410962c10eb3f6d339"
},
{
"path": "skills/publish/SKILL.md",
"sha256": "7ede07da302298ea6d1538e0f751def4eef77571d4b6015f193b11c6a3978a73"
},
{
"path": "skills/plan-prd/SKILL.md",
"sha256": "7ad9833770c93913340b5d7049455658d497e406c274857f5e548ccac16fcd16"
}
],
"dirSha256": "ba1f2c9dce5fccbb2c70341d16f9dc6c94099d693f670662165c1954d7350def"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

1590
skills/code-prd/SKILL.md Normal file
View File

File diff suppressed because it is too large Load Diff

646
skills/code-prd/references/ux-enhancements.md Normal file
View File

@@ -0,0 +1,646 @@
# UX Enhancements Reference
**Purpose:** Detailed implementation specifications for all UX enhancements in the code-prd skill.
**Location:** `skills/code-prd/references/ux-enhancements.md`
**How to use this reference:**
- Main workflow is in `SKILL.md` with callout markers (📚 🧪 📋 💾 🔍 🎯)
- When you see a callout, read the corresponding section here for full implementation
- See "UX Enhancement Reference Map" in `SKILL.md` for quick navigation
**File Type:** Reference documentation (loaded as needed, not executed directly)
---
## Section 1: Learning Mode (Step 4.0 - Before each substory)
**When enabled**, show explanation before implementing:
```markdown
💡 Learning Mode: ON
About to implement: Substory 1.2 - OAuth callback handler
📚 My Approach:
**What I'll build:**
Create `/auth/callback` endpoint to handle OAuth provider redirects
**Why this pattern:**
- Follows RESTful routing (established in Substory 1.1)
- Separates concerns: Controller handles HTTP, Service handles OAuth logic
- Pattern from CLAUDE.md: Thin controller pattern
**Key decisions:**
1. Use OAuthService (created in 1.1) for token exchange
2. Store tokens in encrypted format (Security best practice)
3. Handle errors with custom OAuthError class (Consistent error handling)
**Files I'll create/modify:**
- `app/controllers/auth_controller.rb` - Add callback action
- `app/services/oauth_service.rb` - Add token_exchange method
- `spec/controllers/auth_controller_spec.rb` - Test callback flow
**Estimated complexity:** Medium (involves external API calls)
Ready to proceed? [yes/explain-more/adjust-approach]
```
**Smart mode** (only explain new patterns):
- Only shows explanation when introducing a pattern not seen in prior substories
- Skips explanation for repetitive patterns
**Disabled mode:**
- Proceeds directly to implementation without explanation
## Section 2: Dependency Warnings (Step 4.1 - Before substory execution)
Before implementing each substory, check for dependencies:
```bash
# Detect dependencies from substory description and acceptance criteria
dependencies=()
# Check for API keys/credentials
if grep -qi "api\|oauth\|key\|secret\|credential" <<< "$substory_text"; then
# Check environment or config files
if ! grep -q "GOOGLE_CLIENT_ID\|GITHUB_CLIENT_ID" .env 2>/dev/null; then
dependencies+=("oauth_credentials")
fi
fi
# Check for database migrations
if grep -qi "database\|migration\|schema\|table" <<< "$substory_text"; then
# Check if migrations are pending
if [[ $(rails db:migrate:status 2>/dev/null | grep -c "down") -gt 0 ]]; then
dependencies+=("pending_migrations")
fi
fi
# Check for external services
if grep -qi "redis\|elasticsearch\|postgres\|mysql" <<< "$substory_text"; then
# Check if services are running
if ! pgrep -x "redis-server" > /dev/null 2>&1; then
dependencies+=("redis_not_running")
fi
fi
# Check for package dependencies
if grep -qi "npm install\|bundle install\|pip install" <<< "$substory_text"; then
# Check if lock file is newer than node_modules
if [[ package-lock.json -nt node_modules ]]; then
dependencies+=("packages_outdated")
fi
fi
```
**Show dependency warnings:**
```markdown
⚠️ Dependency Check: Substory 1.3 - Token encryption
Found 2 potential blockers:
1. 🔑 OAuth Credentials Required
- Need: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET
- Status: ❌ Not found in .env file
Options:
a. Set up credentials now (I'll guide you)
b. Skip this substory for now (mark as blocked)
c. Use mock credentials for testing
2. 📦 Package Dependencies
- Package 'jose' (JWT library) not installed
- Required for token encryption
Options:
a. Install now: npm install jose
b. Use alternative library
c. Skip encryption for now (not recommended)
How would you like to proceed? [resolve-all/skip/continue-anyway]
```
**If user chooses "resolve-all":**
Guide through each dependency setup step-by-step.
**If user chooses "skip":**
Mark substory as blocked, move to next unblocked substory.
**If user chooses "continue-anyway":**
Warn about potential failures, proceed with implementation.
## Section 3: Rollback Protection (Step 4.9 - Phase boundaries)
Before starting each new phase, create automatic checkpoint:
```bash
# Create rollback checkpoint before Phase start
phase_number="$1"
checkpoint_dir=".claude/checkpoints"
checkpoint_name="phase-${phase_number}-$(date +%Y%m%d-%H%M%S)"
checkpoint_path="${checkpoint_dir}/${checkpoint_name}"
mkdir -p "$checkpoint_path"
# Note: checkpoints directory and gitignore are created in Phase 0/Step 1
# Save git state
git diff > "${checkpoint_path}/git-diff.patch"
git diff --cached > "${checkpoint_path}/git-diff-staged.patch"
git status --porcelain > "${checkpoint_path}/git-status.txt"
git rev-parse HEAD > "${checkpoint_path}/git-commit.txt"
# Save PRD state
cp "$prd_file" "${checkpoint_path}/prd.md"
cp "$context_file" "${checkpoint_path}/context.json"
# Save file list
find . -type f -newer "${checkpoint_path}/../last-checkpoint" 2>/dev/null > "${checkpoint_path}/modified-files.txt" || true
# Create rollback script
cat > "${checkpoint_path}/rollback.sh" <<'ROLLBACK'
#!/bin/bash
echo "🔄 Rolling back to checkpoint: ${checkpoint_name}"
echo ""
echo "This will:"
echo "- Restore PRD and context files"
echo "- Undo all uncommitted changes since checkpoint"
echo "- Restore modified files"
echo ""
read -p "Continue with rollback? [yes/no]: " confirm
if [[ "$confirm" == "yes" ]]; then
git apply --reverse git-diff.patch 2>/dev/null || true
git apply --reverse git-diff-staged.patch 2>/dev/null || true
cp prd.md "$prd_file"
cp context.json "$context_file"
echo "✅ Rollback complete"
else
echo "Rollback cancelled"
fi
ROLLBACK
chmod +x "${checkpoint_path}/rollback.sh"
# Update last checkpoint marker
touch "${checkpoint_dir}/last-checkpoint"
```
**Show checkpoint confirmation:**
```markdown
💾 Checkpoint Created: Phase 2 Start
Saved current state before beginning Phase 2
Checkpoint includes:
- Current code state (3 files modified)
- PRD status (Phase 1 complete, 66% overall)
- Context data (patterns, decisions, files)
If something goes wrong during Phase 2:
- Type "rollback" to undo Phase 2 changes
- Run: .claude/checkpoints/phase-2-20251026-143022/rollback.sh
Checkpoint expires: 24 hours (auto-cleanup)
Proceeding to Phase 2...
```
## Section 4: Smart Test Suggestions (Step 5a - Test writing)
Analyze code complexity before writing tests:
```bash
# Analyze code complexity for smart test suggestions
analyze_code_complexity() {
local file="$1"
# Cyclomatic complexity (count branches: if, case, for, while, &&, ||)
complexity=$(grep -c "if\|case\|for\|while\|&&\|||" "$file" 2>/dev/null || echo 0)
# Count public methods/functions
public_methods=$(grep -c "def \|function \|export function" "$file" 2>/dev/null || echo 0)
# Count edge cases (null checks, empty checks, error handling)
edge_cases=$(grep -c "nil?\|null\|undefined\|empty?\|rescue\|catch\|raise\|throw" "$file" 2>/dev/null || echo 0)
# Lines of code
loc=$(wc -l < "$file" 2>/dev/null || echo 0)
# Determine complexity level
if [[ $complexity -lt 3 ]] && [[ $loc -lt 50 ]]; then
echo "low"
elif [[ $complexity -lt 8 ]] && [[ $loc -lt 150 ]]; then
echo "medium"
else
echo "high"
fi
}
```
**Show test strategy suggestion:**
```markdown
🧪 Test Strategy: Substory 1.3 - OAuth token encryption
📊 Code Complexity Analysis:
- Complexity score: Medium (cyclomatic complexity: 5)
- Public API: 3 methods (encrypt_token, decrypt_token, validate_token)
- Edge cases detected: 4 (nil token, invalid format, expired token, encryption error)
- Lines of code: 87 lines
🎯 Recommended Test Coverage:
Unit Tests (Recommended: 10 tests)
✅ Happy paths: 3 tests
- encrypt_token with valid data
- decrypt_token with valid encrypted token
- validate_token with valid token
✅ Error handling: 4 tests
- nil/empty token input
- malformed encrypted data
- expired token validation
- encryption key missing
✅ Edge cases: 3 tests
- Very long tokens (>4KB)
- Special characters in tokens
- Concurrent encryption requests
Integration Tests (Optional: 1 test)
⚡ Full OAuth flow with token encryption/decryption
E2E Tests (Skip)
⏭️ Not needed - no direct user interaction
📋 Test Plan Summary:
- Total tests: 10-11
- Estimated coverage: 95%+
- Focus: Error handling (high risk area)
Proceed with this test plan? [yes/add-more/minimal/custom]
```
**If user chooses "minimal":**
Only write happy path tests (3 tests).
**If user chooses "add-more":**
Ask what additional scenarios to cover.
**If user chooses "custom":**
Let user specify exact test cases.
## Section 5: Code Review Insights Summary (Step 5b - After review)
Enhanced review output with trends and gamification:
```markdown
📋 Code Review Complete: Substory 1.3
🎯 Quality Score: 89/100 (Excellent ✅)
📈 Trend Analysis:
Security: ██████████ 95% (+5% from last substory ⬆️)
Performance: ████████░░ 85% (+2% ⬆️)
Readability: █████████░ 92% (same)
Testability: ████████░░ 88% (+8% ⬆️)
Maintainability: ████████░░ 87% (+3% ⬆️)
🏆 Achievements Unlocked:
✨ Security Champion - 3 substories in a row with 90%+ security score
🎯 Test Master - Achieved 95%+ test coverage
📚 Pattern Consistency - 100% adherence to established patterns
✅ Top Wins:
• Excellent error handling with custom exception hierarchy
• Clear naming conventions throughout
• Comprehensive test coverage (96%)
• Good documentation in complex methods
💡 Focus Areas for Next Substory:
• Consider extracting magic constants (found 2 instances)
• Add database index for oauth_tokens.user_id (performance optimization)
• Document the encryption algorithm choice (maintainability)
🔄 Iteration History:
• Iteration 1: Found 2 major issues → Auto-fixed
• Iteration 2: Clean ✅
All critical and major issues resolved!
```
## Section 6: Parallel Work Detection (Step 6.5 - Before continuing to next phase)
Check for concurrent changes on main branch:
```bash
# Detect parallel work that might conflict
current_branch=$(git rev-parse --abbrev-ref HEAD)
base_branch=$(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@')
# Get files changed in current branch
our_files=$(git diff --name-only $base_branch...HEAD)
# Fetch latest from remote
git fetch origin $base_branch --quiet 2>/dev/null
# Get files changed on base branch since we branched off
their_files=$(git diff --name-only HEAD...origin/$base_branch)
# Find overlapping files
conflicts=$(comm -12 <(echo "$our_files" | sort) <(echo "$their_files" | sort))
if [[ -n "$conflicts" ]]; then
# Analyze conflict risk
conflict_count=$(echo "$conflicts" | wc -l)
# Get commit authors
for file in $conflicts; do
author=$(git log -1 --format='%an <%ae>' origin/$base_branch -- "$file")
timestamp=$(git log -1 --format='%ar' origin/$base_branch -- "$file")
done
fi
```
**Show parallel work warning:**
```markdown
⚠️ Parallel Work Detected
While working on this PRD, changes were made to ${base_branch}:
Potentially Conflicting Files:
1. src/services/oauth_service.rb
- Modified by: Sarah Chen <sarah@example.com>
- When: 2 hours ago
- Commit: "refactor: extract token validation logic"
2. app/controllers/auth_controller.rb
- Modified by: Mike Johnson <mike@example.com>
- When: 45 minutes ago
- Commit: "feat: add rate limiting to auth endpoints"
Risk Level: 🟡 MEDIUM
- 2 files overlap with your changes
- Affects Substories: 1.2, 1.3
📊 Impact Analysis:
- Both files are in your current phase
- oauth_service.rb: Moderate overlap (refactored same methods)
- auth_controller.rb: Minor overlap (different endpoints)
Options:
1. 🔄 Merge ${base_branch} now (recommended)
- Pauses PRD implementation
- Resolves conflicts immediately
- Continues with updated code
2. ⏭️ Continue and merge later
- Higher risk of complex conflicts
- May require rework
3. 📞 Coordinate with team
- Notify Sarah and Mike
- Discuss approach before proceeding
4. 🔍 Show detailed diff
- Review exactly what changed
What would you like to do? [1/2/3/4]
```
## Section 7: Context-Aware Expansion Suggestions (Step 7 - Core PRD completion)
Analyze codebase to suggest smart expansions:
```bash
# Analyze core implementation for expansion suggestions
analyze_for_expansions() {
local prd_file="$1"
local context_file="$2"
suggestions=()
# Strategy 1: Analyze "Out of Scope" section from PRD
out_of_scope=$(sed -n '/Out of Scope/,/^##/p' "$prd_file")
# Strategy 2: Find TODO comments in implemented files
files_created=$(jq -r '.files_created[]' "$context_file")
todos=$(grep -rh "TODO\|FIXME\|ENHANCEMENT" $files_created 2>/dev/null || true)
# Strategy 3: Analyze data model for missing relationships
# Look for foreign keys without inverse relationships
# Strategy 4: Check CLAUDE.md for planned features
planned_features=$(sed -n '/Planned Features\|Roadmap/,/^##/p' CLAUDE.md 2>/dev/null || true)
# Strategy 5: Analyze usage patterns (if analytics/logs available)
# Find commonly accessed fields that don't exist yet
# Rank suggestions by:
# - Effort (lines of code, complexity)
# - Impact (usage frequency, business value from comments)
# - Dependencies (what else is needed)
}
```
**Show smart expansion suggestions:**
```markdown
🎯 Smart Expansion Suggestions
Based on your core implementation, here are natural next steps:
┌─────────────────────────────────────────────────────────┐
│ 1. 🔥 Customer Details (HIGH PRIORITY) │
├─────────────────────────────────────────────────────────┤
│ Why recommended: │
│ • Found 73% of invoices reference 'customer_id' in DB │
│ • Listed in "Out of Scope" section of core PRD │
│ • 5 TODO comments mention customer information │
│ │
│ Effort: ██████░░░░ Medium (2-3 substories) │
│ Impact: ██████████ Very High (critical for production) │
│ Builds on: Invoice model, InvoiceService pattern │
│ │
│ Would add: │
│ • Customer model with name, email, address │
│ • Invoice-Customer association │
│ • Customer selection in invoice forms │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│ 2. 💡 Line Items (QUICK WIN) │
├─────────────────────────────────────────────────────────┤
│ Why recommended: │
│ • Follows same service pattern as InvoiceService │
│ • Mentioned in CLAUDE.md planned features │
│ • Low complexity, high value │
│ │
│ Effort: ████░░░░░░ Small (1-2 substories) │
│ Impact: ████████░░ High (enables itemized invoices) │
│ Builds on: Invoice model, existing CRUD patterns │
│ │
│ Would add: │
│ • LineItem model (description, quantity, unit_price) │
│ • Has-many relationship with Invoice │
│ • Automatic total calculation │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│ 3. 🚀 Tax Calculations (HIGH IMPACT) │
├─────────────────────────────────────────────────────────┤
│ Why recommended: │
│ • TODO comment: "Add tax calculation for compliance" │
│ • Required for production use │
│ • Blocked until Line Items implemented │
│ │
│ Effort: ████████░░ Large (4-5 substories) │
│ Impact: ██████████ Critical (regulatory requirement) │
│ Depends on: Line Items expansion │
│ Complexity: Tax rules, multi-jurisdiction support │
│ │
│ Would add: │
│ • TaxRule model with regional rates │
│ • Tax calculation service │
│ • Tax line items in invoices │
└─────────────────────────────────────────────────────────┘
📊 Recommended Order:
1st: Customer Details (unblocks other features)
2nd: Line Items (enables Tax Calculations)
3rd: Tax Calculations (compliance requirement)
Which expansion interests you? [1/2/3/custom/plan-all]:
```
**If user selects number:**
Trigger plan-prd skill with pre-filled expansion context.
**If user chooses "plan-all":**
Create PRDs for all three expansions in sequence.
**If user chooses "custom":**
Let user describe their own expansion idea.
## Section 8: Adaptive Difficulty (Phase 0 - Session configuration)
Track user progress and adapt workflow:
```bash
# Calculate user skill level based on history
calculate_skill_level() {
local prds_completed=$(find .claude/prds/context -name "*.json" -exec jq -r 'select(.status=="complete") | .prd_name' {} \; | wc -l)
local avg_quality=$(find .claude/prds/context -name "*.json" -exec jq -r '.code_quality_scores[]' {} \; | awk '{sum+=$1; n++} END {if (n>0) print sum/n; else print 0}')
local avg_coverage=$(find .claude/prds/context -name "*.json" -exec jq -r '.test_coverage' {} \; | awk '{sum+=$1; n++} END {if (n>0) print sum/n; else print 0}')
# Determine level
if [[ $prds_completed -ge 10 ]] && [[ $(echo "$avg_quality > 90" | bc) -eq 1 ]]; then
echo "advanced"
elif [[ $prds_completed -ge 5 ]] && [[ $(echo "$avg_quality > 80" | bc) -eq 1 ]]; then
echo "intermediate"
else
echo "beginner"
fi
}
```
**Advanced mode unlocked message:**
```markdown
🎓 Level Up! Advanced Mode Unlocked
Based on your track record:
- ✅ PRDs completed: 12
- ✅ Avg code quality: 94/100
- ✅ Test coverage: Consistently 92%+
- ✅ Pattern consistency: Excellent
You've unlocked Advanced Mode features:
🚀 Speed Optimizations:
• Auto-approve low-risk changes (skip simple confirmations)
• Skip repetitive explanations in Learning Mode
• Parallel substory execution where possible
• Fast-track phase approvals for clean code
🎯 Advanced Features:
• Custom code review rules
• Configurable test thresholds
• Advanced refactoring suggestions
• Performance profiling integration
⚙️ Customization:
• Define your own quality gates
• Set preferred patterns per project
• Custom commit message templates
Enable Advanced Mode? [yes/not-yet/customize]
(You can always change this in .claude/user-preferences.json)
```
**Adaptive behaviors by level:**
**Beginner:**
- Learning Mode ON by default
- Detailed explanations
- All confirmations required
- Guided dependency resolution
- Thorough code review
**Intermediate:**
- Learning Mode Smart by default
- Condensed explanations
- Skip trivial confirmations
- Suggested fixes with approval
- Standard code review
**Advanced:**
- Learning Mode OFF by default
- Minimal explanations
- Auto-approve safe changes
- Auto-fix simple issues
- Streamlined code review with trends
---
## Implementation Notes
All these features integrate seamlessly into the existing code-prd workflow:
1. **Learning Mode**: Triggered before each substory if enabled (Step 4.0)
2. **Dependency Warnings**: Checked before substory execution (Step 4.1)
3. **Rollback Protection**: Created at phase boundaries (Step 4.9)
4. **Smart Test Suggestions**: Integrated into test writing step (Step 5a)
5. **Code Review Insights**: Enhanced review output format (Step 5b)
6. **Parallel Work Detection**: Checked at phase boundaries before continuing (Step 6.5)
7. **Context-Aware Suggestions**: Shown at PRD completion (Step 7)
8. **Adaptive Difficulty**: Calculated at session start, influences all steps (Phase 0)
User preferences stored in `.claude/user-preferences.json` (auto-gitignored):
```json
{
"skill_level": "intermediate",
"learning_mode": true,
"auto_approve_safe_changes": false,
"last_updated": "2025-10-26T14:30:22Z"
}
```
**Important:** This file is automatically added to `.gitignore` to prevent:
- Merge conflicts between developers
- Accidentally committing personal preferences
- Team preferences overwriting individual settings
The skill automatically ensures `.gitignore` contains:
```gitignore
# Claude Code user-specific files (do not commit)
.claude/user-preferences.json
.claude/checkpoints/
```

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
```

1006
skills/publish/SKILL.md Normal file
View File

File diff suppressed because it is too large Load Diff