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

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