Initial commit
This commit is contained in:
12
.claude-plugin/plugin.json
Normal file
12
.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,12 @@
|
|||||||
|
{
|
||||||
|
"name": "spec-driven",
|
||||||
|
"description": "Transform specifications into executable code with automated analysis, validation checkpoints, and incremental delivery",
|
||||||
|
"version": "0.1.0",
|
||||||
|
"author": {
|
||||||
|
"name": "Nick Nisi",
|
||||||
|
"email": "nick@nisi.org"
|
||||||
|
},
|
||||||
|
"commands": [
|
||||||
|
"./commands"
|
||||||
|
]
|
||||||
|
}
|
||||||
3
README.md
Normal file
3
README.md
Normal file
@@ -0,0 +1,3 @@
|
|||||||
|
# spec-driven
|
||||||
|
|
||||||
|
Transform specifications into executable code with automated analysis, validation checkpoints, and incremental delivery
|
||||||
77
commands/check-prp.md
Normal file
77
commands/check-prp.md
Normal file
@@ -0,0 +1,77 @@
|
|||||||
|
# Validate PRP Quality
|
||||||
|
|
||||||
|
## PRP File: $ARGUMENTS
|
||||||
|
|
||||||
|
Review a PRP (Pre-Requirements Plan) file for completeness and implementation readiness.
|
||||||
|
|
||||||
|
## Validation Checklist
|
||||||
|
|
||||||
|
### Research and Context
|
||||||
|
|
||||||
|
- [ ] All research context included with URLs
|
||||||
|
- [ ] Tech stack properly identified (framework, build tools, testing)
|
||||||
|
- [ ] External documentation links provided
|
||||||
|
- [ ] Code examples from codebase referenced
|
||||||
|
|
||||||
|
### Implementation Planning
|
||||||
|
|
||||||
|
- [ ] Implementation phases clearly defined
|
||||||
|
- [ ] Each phase has specific deliverables
|
||||||
|
- [ ] Validation commands match project setup
|
||||||
|
- [ ] Manual testing steps provided for each phase
|
||||||
|
|
||||||
|
### Technical Details
|
||||||
|
|
||||||
|
- [ ] Error handling strategy documented
|
||||||
|
- [ ] Existing patterns properly referenced
|
||||||
|
- [ ] Incremental milestones defined
|
||||||
|
- [ ] Edge cases considered
|
||||||
|
|
||||||
|
### Execution Readiness
|
||||||
|
|
||||||
|
- [ ] All TODOs and placeholders resolved
|
||||||
|
- [ ] Dependencies clearly listed
|
||||||
|
- [ ] Environment setup documented
|
||||||
|
- [ ] Success criteria measurable
|
||||||
|
|
||||||
|
## Analysis Process
|
||||||
|
|
||||||
|
1. **Structural Review**
|
||||||
|
- Check for all required PRP sections
|
||||||
|
- Verify phase breakdown is logical
|
||||||
|
- Ensure validation points are clear
|
||||||
|
|
||||||
|
2. **Technical Assessment**
|
||||||
|
- Validate that tech stack matches project
|
||||||
|
- Check if referenced patterns exist in codebase
|
||||||
|
- Confirm validation commands will work
|
||||||
|
|
||||||
|
3. **Completeness Check**
|
||||||
|
- Scan for missing implementation details
|
||||||
|
- Identify any ambiguous requirements
|
||||||
|
- Flag incomplete research areas
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
### Quality Score (1-10)
|
||||||
|
|
||||||
|
Rate the PRP's readiness for execution:
|
||||||
|
|
||||||
|
- **1-3**: Major gaps, needs significant work
|
||||||
|
- **4-6**: Good foundation, some areas need completion
|
||||||
|
- **7-8**: Well-defined, minor improvements possible
|
||||||
|
- **9-10**: Comprehensive and execution-ready
|
||||||
|
|
||||||
|
### Feedback Report
|
||||||
|
|
||||||
|
- **Strengths**: What the PRP does well
|
||||||
|
- **Missing Elements**: Critical gaps to address
|
||||||
|
- **Research Gaps**: Areas needing more documentation
|
||||||
|
- **Implementation Concerns**: Potential execution challenges
|
||||||
|
|
||||||
|
### Recommended Actions
|
||||||
|
|
||||||
|
- **Ready to execute**: Proceed with `/execute-prp`
|
||||||
|
- **Needs completion**: Specific sections to enhance
|
||||||
|
- **Requires validation**: Commands to verify first
|
||||||
|
- **Research needed**: External resources to gather
|
||||||
85
commands/check-spec.md
Normal file
85
commands/check-spec.md
Normal file
@@ -0,0 +1,85 @@
|
|||||||
|
# Validate Specification Quality
|
||||||
|
|
||||||
|
## Spec File: $ARGUMENTS
|
||||||
|
|
||||||
|
Review a feature specification for completeness and implementation readiness.
|
||||||
|
|
||||||
|
## Validation Checklist
|
||||||
|
|
||||||
|
### Requirements Clarity
|
||||||
|
|
||||||
|
- [ ] Feature purpose and goals clearly defined
|
||||||
|
- [ ] Target users and use cases identified
|
||||||
|
- [ ] Success criteria measurable and specific
|
||||||
|
- [ ] Core functionality well-described
|
||||||
|
|
||||||
|
### User Experience
|
||||||
|
|
||||||
|
- [ ] User stories cover main workflows
|
||||||
|
- [ ] Edge cases and error states considered
|
||||||
|
- [ ] User interface requirements specified
|
||||||
|
- [ ] Accessibility considerations included
|
||||||
|
|
||||||
|
### Technical Specifications
|
||||||
|
|
||||||
|
- [ ] Data requirements clearly defined
|
||||||
|
- [ ] Integration points with existing systems identified
|
||||||
|
- [ ] Performance and scalability requirements specified
|
||||||
|
- [ ] Security and authentication needs addressed
|
||||||
|
|
||||||
|
### Implementation Readiness
|
||||||
|
|
||||||
|
- [ ] Acceptance criteria are testable
|
||||||
|
- [ ] Technical constraints documented
|
||||||
|
- [ ] Dependencies and external services noted
|
||||||
|
- [ ] Out-of-scope items clearly defined
|
||||||
|
|
||||||
|
### Project Management
|
||||||
|
|
||||||
|
- [ ] MVP vs future enhancements distinguished
|
||||||
|
- [ ] Relative priority/importance indicated
|
||||||
|
- [ ] Potential risks or challenges flagged
|
||||||
|
- [ ] Scope is reasonable for single implementation
|
||||||
|
|
||||||
|
## Analysis Process
|
||||||
|
|
||||||
|
1. **Completeness Check**
|
||||||
|
- Scan for missing critical sections
|
||||||
|
- Identify vague or ambiguous requirements
|
||||||
|
- Flag areas needing more detail
|
||||||
|
|
||||||
|
2. **Feasibility Assessment**
|
||||||
|
- Check against existing codebase patterns
|
||||||
|
- Identify potential technical challenges
|
||||||
|
- Estimate implementation complexity
|
||||||
|
|
||||||
|
3. **Quality Review**
|
||||||
|
- Ensure requirements are specific and measurable
|
||||||
|
- Verify user stories follow good practices
|
||||||
|
- Check that acceptance criteria are testable
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
### Quality Score (1-10)
|
||||||
|
|
||||||
|
Rate the specification's readiness for implementation:
|
||||||
|
|
||||||
|
- **1-3**: Major gaps, needs significant work
|
||||||
|
- **4-6**: Good foundation, some areas need clarification
|
||||||
|
- **7-8**: Well-defined, minor improvements possible
|
||||||
|
- **9-10**: Comprehensive and implementation-ready
|
||||||
|
|
||||||
|
### Feedback Report
|
||||||
|
|
||||||
|
- **Strengths**: What the spec does well
|
||||||
|
- **Missing Elements**: Critical gaps to address
|
||||||
|
- **Clarification Needed**: Vague or ambiguous areas
|
||||||
|
- **Suggestions**: Ways to improve the specification
|
||||||
|
- **Risk Assessment**: Potential implementation challenges
|
||||||
|
|
||||||
|
### Recommended Actions
|
||||||
|
|
||||||
|
- **Ready to implement**: Proceed with `/execute-spec`
|
||||||
|
- **Needs revision**: Specific areas to improve first
|
||||||
|
- **Requires research**: External factors to investigate
|
||||||
|
- **Scope adjustment**: Recommendations for MVP vs full feature
|
||||||
190
commands/execute-prp.md
Normal file
190
commands/execute-prp.md
Normal file
@@ -0,0 +1,190 @@
|
|||||||
|
# Execute PRP with Incremental Validation
|
||||||
|
|
||||||
|
## PRP File: $ARGUMENTS
|
||||||
|
|
||||||
|
Execute a PRP (Pre-Requirements Plan) in phases with validation points between each step for controlled, incremental implementation.
|
||||||
|
|
||||||
|
## Execution Process
|
||||||
|
|
||||||
|
### 1. Load and Plan
|
||||||
|
|
||||||
|
- Read the PRP file completely to understand all requirements
|
||||||
|
- Extract research context, tech stack, and validation commands
|
||||||
|
- Create implementation plan using TodoWrite tool
|
||||||
|
- Identify the phases and validation points from the PRP
|
||||||
|
|
||||||
|
### 2. Phase-by-Phase Execution
|
||||||
|
|
||||||
|
For each phase in the PRP:
|
||||||
|
|
||||||
|
1. **Announce Phase Start**
|
||||||
|
- Clear statement of which phase is beginning
|
||||||
|
- List the specific deliverables for this phase
|
||||||
|
- Estimate time/complexity for the phase
|
||||||
|
|
||||||
|
2. **Implement Phase Requirements**
|
||||||
|
- Follow the PRP's instructions for this phase
|
||||||
|
- Use referenced patterns from the codebase
|
||||||
|
- Apply the documented error handling strategy
|
||||||
|
- Create only the code specified for this phase
|
||||||
|
|
||||||
|
3. **Run Validation**
|
||||||
|
- Execute phase-specific validation commands from PRP
|
||||||
|
- Run any automated tests defined
|
||||||
|
- Check for compilation/syntax errors
|
||||||
|
- Verify the phase deliverables are complete
|
||||||
|
|
||||||
|
4. **User Checkpoint**
|
||||||
|
- Show what was implemented with file paths
|
||||||
|
- Provide manual testing steps from PRP
|
||||||
|
- Report validation results clearly
|
||||||
|
- Wait for user feedback before proceeding
|
||||||
|
|
||||||
|
### 3. Phase Structure
|
||||||
|
|
||||||
|
Standard progression (from PRP template):
|
||||||
|
|
||||||
|
- **Setup Phase**: File structure, types, interfaces, configuration
|
||||||
|
- **Core Phase**: Main functionality implementation
|
||||||
|
- **Integration Phase**: Connect with existing systems
|
||||||
|
- **Testing Phase**: Unit and integration tests
|
||||||
|
- **Polish Phase**: Error handling, edge cases, documentation
|
||||||
|
|
||||||
|
Each phase should:
|
||||||
|
|
||||||
|
- Output working, testable code
|
||||||
|
- Have clear success criteria
|
||||||
|
- Include manual testing instructions
|
||||||
|
- Build incrementally on previous phases
|
||||||
|
|
||||||
|
### 4. Validation Protocol
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Run validation commands from PRP
|
||||||
|
npm run type-check # or project-specific command
|
||||||
|
npm run lint
|
||||||
|
npm run test
|
||||||
|
|
||||||
|
# Report results clearly
|
||||||
|
echo "✓ Type checking passed"
|
||||||
|
echo "✓ Linting passed"
|
||||||
|
echo "⚠ 2 tests pending implementation"
|
||||||
|
|
||||||
|
# Fix any failures before proceeding
|
||||||
|
# If validation fails, stop and fix before continuing
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. User Checkpoints
|
||||||
|
|
||||||
|
After completing each phase:
|
||||||
|
|
||||||
|
- **Implementation Summary**: List all files created/modified
|
||||||
|
- **Validation Results**: Show output from validation commands
|
||||||
|
- **Manual Testing**: Provide specific steps for user to test
|
||||||
|
- **Next Phase Preview**: Brief description of what comes next
|
||||||
|
|
||||||
|
Wait for user response:
|
||||||
|
|
||||||
|
- "continue" → Proceed to next phase
|
||||||
|
- "fix [issue]" → Address specific problem
|
||||||
|
- Other feedback → Incorporate before continuing
|
||||||
|
|
||||||
|
## Control Commands During Execution
|
||||||
|
|
||||||
|
### Navigation Commands
|
||||||
|
|
||||||
|
- `continue` - Proceed to next phase
|
||||||
|
- `pause` - Stop for manual intervention
|
||||||
|
- `status` - Show current phase and progress
|
||||||
|
- `restart phase` - Redo current phase from beginning
|
||||||
|
- `skip to [phase]` - Jump to specific phase (with warning)
|
||||||
|
|
||||||
|
### Correction Commands
|
||||||
|
|
||||||
|
- `fix [issue]` - Address specific problem
|
||||||
|
- `rollback` - Undo current phase changes
|
||||||
|
- `validate` - Re-run validation commands
|
||||||
|
- `debug` - Show detailed error information
|
||||||
|
|
||||||
|
### Information Commands
|
||||||
|
|
||||||
|
- `show plan` - Display full implementation plan
|
||||||
|
- `show prp` - Display relevant PRP section
|
||||||
|
- `progress` - Show overall completion status
|
||||||
|
- `help` - Show available commands
|
||||||
|
|
||||||
|
## Execution Modes
|
||||||
|
|
||||||
|
### Standard Mode (Default)
|
||||||
|
|
||||||
|
- Stop at each checkpoint for user confirmation
|
||||||
|
- Show all validation results
|
||||||
|
- Require explicit "continue" to proceed
|
||||||
|
|
||||||
|
### Auto Mode (When specified)
|
||||||
|
|
||||||
|
- Continue automatically if validation passes
|
||||||
|
- Stop only on errors or warnings
|
||||||
|
- Still show progress updates
|
||||||
|
|
||||||
|
### Debug Mode
|
||||||
|
|
||||||
|
- Extra verbose output
|
||||||
|
- Show all command executions
|
||||||
|
- Detailed error traces
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
### Validation Failures
|
||||||
|
|
||||||
|
1. Stop execution immediately
|
||||||
|
2. Show clear error message
|
||||||
|
3. Suggest fix if possible
|
||||||
|
4. Wait for user instruction
|
||||||
|
|
||||||
|
### Missing Dependencies
|
||||||
|
|
||||||
|
1. Identify what's missing
|
||||||
|
2. Suggest installation command
|
||||||
|
3. Pause for user to install
|
||||||
|
4. Retry after installation
|
||||||
|
|
||||||
|
### Ambiguous Requirements
|
||||||
|
|
||||||
|
1. Flag the ambiguity
|
||||||
|
2. Show PRP section in question
|
||||||
|
3. Ask for clarification
|
||||||
|
4. Update understanding and proceed
|
||||||
|
|
||||||
|
## Completion
|
||||||
|
|
||||||
|
### Final Validation
|
||||||
|
|
||||||
|
- Run complete test suite
|
||||||
|
- Verify all PRP requirements met
|
||||||
|
- Check success criteria achieved
|
||||||
|
- Generate coverage report if applicable
|
||||||
|
|
||||||
|
### Deliverables
|
||||||
|
|
||||||
|
- Summary of all changes made
|
||||||
|
- Documentation updates completed
|
||||||
|
- Usage examples created
|
||||||
|
- Any remaining TODOs noted
|
||||||
|
|
||||||
|
### Handoff
|
||||||
|
|
||||||
|
- Provide clear usage documentation
|
||||||
|
- List any manual steps needed
|
||||||
|
- Note any deferred items
|
||||||
|
- Suggest next steps
|
||||||
|
|
||||||
|
## Important Notes
|
||||||
|
|
||||||
|
- **Always wait for user confirmation between phases** unless explicitly told to continue automatically
|
||||||
|
- **Never skip validation** even if it seems unnecessary
|
||||||
|
- **Document any deviations** from the PRP with clear reasoning
|
||||||
|
- **Preserve existing code** unless PRP specifically says to modify
|
||||||
|
- **Test incrementally** rather than waiting until the end
|
||||||
|
|
||||||
|
The goal is controlled, validated, incremental delivery that builds confidence at each step.
|
||||||
304
commands/execute-spec.md
Normal file
304
commands/execute-spec.md
Normal file
@@ -0,0 +1,304 @@
|
|||||||
|
# Execute Feature Specification
|
||||||
|
|
||||||
|
## Spec File: $ARGUMENTS
|
||||||
|
|
||||||
|
Execute feature specifications with intelligent automation, comprehensive validation, and progress tracking.
|
||||||
|
|
||||||
|
## Pre-Execution Setup
|
||||||
|
|
||||||
|
### 1. Load and Validate Specification
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Load specification
|
||||||
|
SPEC_FILE="$ARGUMENTS"
|
||||||
|
SPEC_NAME=$(basename "$SPEC_FILE" .md)
|
||||||
|
PRP_FILE="PRPs/${SPEC_NAME}.md"
|
||||||
|
|
||||||
|
# Auto-generate or update PRP if needed
|
||||||
|
if [ ! -f "$PRP_FILE" ] || [ "$SPEC_FILE" -nt "$PRP_FILE" ]; then
|
||||||
|
echo "Generating PRP from spec..."
|
||||||
|
/generate-prp "$SPEC_FILE"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Extract metadata from spec
|
||||||
|
COMPLEXITY_SCORE=$(grep "Complexity Score:" "$SPEC_FILE" | cut -d: -f2)
|
||||||
|
ESTIMATED_EFFORT=$(grep "Estimated Effort:" "$SPEC_FILE" | cut -d: -f2)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Project Context Discovery
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Discover project structure and conventions
|
||||||
|
find . -maxdepth 3 -name "*.config.*" -o -name "*rc.*" -o -name "Makefile"
|
||||||
|
|
||||||
|
# Identify test patterns
|
||||||
|
find . -type f -name "*test*" -o -name "*spec*" | head -5
|
||||||
|
|
||||||
|
# Check for existing similar features
|
||||||
|
grep -r "similar_pattern" --include="*.ts" --include="*.js" --include="*.py"
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Execution Plan Generation
|
||||||
|
|
||||||
|
Based on spec complexity score:
|
||||||
|
|
||||||
|
- **1-3 (Simple)**: Direct implementation with minimal checkpoints
|
||||||
|
- **4-6 (Medium)**: Phased approach with validation points
|
||||||
|
- **7-10 (Complex)**: Incremental delivery with extensive validation
|
||||||
|
|
||||||
|
## Spec-Driven Execution Phases
|
||||||
|
|
||||||
|
### Phase 1: Foundation
|
||||||
|
|
||||||
|
**From Spec Section: Technical Architecture**
|
||||||
|
|
||||||
|
1. **Database Changes** (if specified in spec)
|
||||||
|
- Create/modify schema as defined
|
||||||
|
- Add migrations if project uses them
|
||||||
|
- Update models/entities
|
||||||
|
|
||||||
|
2. **API Structure** (if specified in spec)
|
||||||
|
- Create endpoint definitions
|
||||||
|
- Add request/response types
|
||||||
|
- Set up routing
|
||||||
|
|
||||||
|
3. **Core Data Structures**
|
||||||
|
- Implement interfaces from spec
|
||||||
|
- Create types/classes as defined
|
||||||
|
- Set up state management
|
||||||
|
|
||||||
|
**Validation Checkpoint:**
|
||||||
|
|
||||||
|
- Verify all foundation elements exist
|
||||||
|
- Check that types/interfaces compile
|
||||||
|
- Confirm database changes applied
|
||||||
|
|
||||||
|
### Phase 2: Core Implementation
|
||||||
|
|
||||||
|
**From Spec Section: Implementation Checklist**
|
||||||
|
|
||||||
|
Work through each item in the spec's implementation checklist:
|
||||||
|
|
||||||
|
1. Read the specific requirement
|
||||||
|
2. Implement exactly as specified
|
||||||
|
3. Validate implementation works
|
||||||
|
4. Mark item complete in tracking
|
||||||
|
|
||||||
|
**Continuous Validation:**
|
||||||
|
|
||||||
|
- After each file modification
|
||||||
|
- Check for syntax errors
|
||||||
|
- Verify imports resolve
|
||||||
|
- Ensure no breaking changes
|
||||||
|
|
||||||
|
### Phase 3: Integration
|
||||||
|
|
||||||
|
**From Spec Section: Dependencies and Integration**
|
||||||
|
|
||||||
|
1. **Connect Components**
|
||||||
|
- Wire up services as specified
|
||||||
|
- Integrate with existing systems
|
||||||
|
- Add configuration as needed
|
||||||
|
|
||||||
|
2. **Data Flow**
|
||||||
|
- Implement data pipelines
|
||||||
|
- Connect frontend to backend
|
||||||
|
- Set up event handlers
|
||||||
|
|
||||||
|
**Validation Checkpoint:**
|
||||||
|
|
||||||
|
- Test integration points work
|
||||||
|
- Verify data flows correctly
|
||||||
|
- Check error handling
|
||||||
|
|
||||||
|
### Phase 4: Testing & Validation
|
||||||
|
|
||||||
|
**From Spec Section: Testing Strategy**
|
||||||
|
|
||||||
|
Execute test plan from specification:
|
||||||
|
|
||||||
|
1. Create tests for acceptance criteria
|
||||||
|
2. Implement test scenarios from spec
|
||||||
|
3. Validate success metrics
|
||||||
|
|
||||||
|
**Coverage Areas:**
|
||||||
|
|
||||||
|
- Unit tests for new functions
|
||||||
|
- Integration tests for workflows
|
||||||
|
- Manual testing checklist items
|
||||||
|
|
||||||
|
### Phase 5: Documentation & Polish
|
||||||
|
|
||||||
|
**From Spec Section: User Stories**
|
||||||
|
|
||||||
|
1. **Code Documentation**
|
||||||
|
- Add comments for complex logic
|
||||||
|
- Document public APIs
|
||||||
|
- Update type definitions
|
||||||
|
|
||||||
|
2. **User Documentation**
|
||||||
|
- Create usage examples
|
||||||
|
- Document configuration options
|
||||||
|
- Add troubleshooting notes
|
||||||
|
|
||||||
|
## Progress Tracking
|
||||||
|
|
||||||
|
### Implementation Checklist Tracking
|
||||||
|
|
||||||
|
Track progress through spec requirements:
|
||||||
|
|
||||||
|
```
|
||||||
|
[✓] Database schema created
|
||||||
|
[✓] API endpoints defined
|
||||||
|
[⏳] Frontend components built
|
||||||
|
[ ] Integration complete
|
||||||
|
[ ] Tests passing
|
||||||
|
[ ] Documentation updated
|
||||||
|
```
|
||||||
|
|
||||||
|
### Execution Report Template
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## Implementation Progress
|
||||||
|
|
||||||
|
### Completed
|
||||||
|
|
||||||
|
- [List completed spec requirements]
|
||||||
|
|
||||||
|
### In Progress
|
||||||
|
|
||||||
|
- [Current work items]
|
||||||
|
|
||||||
|
### Remaining
|
||||||
|
|
||||||
|
- [Outstanding spec requirements]
|
||||||
|
|
||||||
|
### Issues & Blockers
|
||||||
|
|
||||||
|
- [Any problems encountered]
|
||||||
|
|
||||||
|
### Validation Results
|
||||||
|
|
||||||
|
- [Test results if available]
|
||||||
|
- [Manual testing outcomes]
|
||||||
|
```
|
||||||
|
|
||||||
|
## Control Commands
|
||||||
|
|
||||||
|
### During Execution
|
||||||
|
|
||||||
|
- `continue` - Proceed to next phase
|
||||||
|
- `status` - Show current progress
|
||||||
|
- `validate` - Run validation checks
|
||||||
|
- `pause` - Stop for manual work
|
||||||
|
- `skip` - Skip current item (with warning)
|
||||||
|
- `retry` - Retry failed operation
|
||||||
|
|
||||||
|
### Validation Commands
|
||||||
|
|
||||||
|
- `check-spec` - Verify against specification
|
||||||
|
- `test` - Run relevant tests
|
||||||
|
- `lint` - Check code quality
|
||||||
|
|
||||||
|
### Reporting
|
||||||
|
|
||||||
|
- `report` - Generate progress report
|
||||||
|
- `checklist` - Show implementation checklist
|
||||||
|
- `metrics` - Display execution metrics
|
||||||
|
|
||||||
|
## Smart Checkpoints
|
||||||
|
|
||||||
|
### Automatic Progression
|
||||||
|
|
||||||
|
Continue automatically when:
|
||||||
|
|
||||||
|
- Current phase implementation complete
|
||||||
|
- No errors detected
|
||||||
|
- Spec requirements met for phase
|
||||||
|
|
||||||
|
### Manual Checkpoint Required
|
||||||
|
|
||||||
|
Pause for confirmation when:
|
||||||
|
|
||||||
|
- Complexity score > 7
|
||||||
|
- Errors or warnings detected
|
||||||
|
- Spec has explicit "manual review" notes
|
||||||
|
- Major architectural changes made
|
||||||
|
|
||||||
|
## Error Recovery
|
||||||
|
|
||||||
|
### Common Recovery Actions
|
||||||
|
|
||||||
|
1. **Missing Dependencies**: Note what's needed
|
||||||
|
2. **Type/Syntax Errors**: Attempt fixes
|
||||||
|
3. **Test Failures**: Isolate and document
|
||||||
|
4. **Integration Issues**: Rollback and retry
|
||||||
|
|
||||||
|
### Manual Intervention
|
||||||
|
|
||||||
|
Required for:
|
||||||
|
|
||||||
|
- Spec ambiguities
|
||||||
|
- Architectural decisions
|
||||||
|
- Security concerns
|
||||||
|
- Performance issues
|
||||||
|
|
||||||
|
## Spec Compliance Validation
|
||||||
|
|
||||||
|
### Continuous Checks
|
||||||
|
|
||||||
|
- Are we following the spec's Technical Architecture?
|
||||||
|
- Have we completed Implementation Checklist items?
|
||||||
|
- Do changes match the API Design?
|
||||||
|
- Are Success Metrics being met?
|
||||||
|
|
||||||
|
### Final Validation
|
||||||
|
|
||||||
|
1. **Spec Requirements**: Check all requirements implemented
|
||||||
|
2. **Acceptance Criteria**: Verify all criteria met
|
||||||
|
3. **Test Coverage**: Ensure test scenarios covered
|
||||||
|
4. **Documentation**: Confirm docs updated
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
### Project-Specific Settings
|
||||||
|
|
||||||
|
The command adapts to project conventions:
|
||||||
|
|
||||||
|
- Reads existing config files
|
||||||
|
- Follows established patterns
|
||||||
|
- Uses project's test framework
|
||||||
|
- Respects code style rules
|
||||||
|
|
||||||
|
### Execution Modes
|
||||||
|
|
||||||
|
- **Guided**: Step-by-step with confirmations
|
||||||
|
- **Auto**: Automatic progression where safe
|
||||||
|
- **Review**: Implementation with detailed review points
|
||||||
|
- **Fast**: Minimal checkpoints for simple features
|
||||||
|
|
||||||
|
## Usage Examples
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Execute a specification
|
||||||
|
/execute-spec specs/user-auth-spec.md
|
||||||
|
|
||||||
|
# Execute with auto-progression
|
||||||
|
/execute-spec specs/feature-spec.md --auto
|
||||||
|
|
||||||
|
# Execute specific phase
|
||||||
|
/execute-spec specs/api-spec.md --phase=3
|
||||||
|
|
||||||
|
# Dry run to preview changes
|
||||||
|
/execute-spec specs/new-feature.md --dry-run
|
||||||
|
```
|
||||||
|
|
||||||
|
## Key Principles
|
||||||
|
|
||||||
|
1. **Follow the Spec Literally**: Implement exactly what's specified
|
||||||
|
2. **Validate Continuously**: Check work at each step
|
||||||
|
3. **Track Progress**: Maintain clear status of implementation
|
||||||
|
4. **Adapt to Project**: Use project's patterns and conventions
|
||||||
|
5. **Fail Safely**: Pause when uncertain rather than guess
|
||||||
|
|
||||||
|
The execution is driven entirely by the specification document, ensuring that implementation matches requirements exactly while adapting to each project's unique structure and conventions.
|
||||||
74
commands/generate-prp.md
Normal file
74
commands/generate-prp.md
Normal file
@@ -0,0 +1,74 @@
|
|||||||
|
# Create PRP
|
||||||
|
|
||||||
|
## Feature file: $ARGUMENTS
|
||||||
|
|
||||||
|
Generate a complete PRP for feature implementation with thorough research. Read the feature file first to understand requirements and context.
|
||||||
|
|
||||||
|
## Research Process
|
||||||
|
|
||||||
|
1. **Codebase Analysis**
|
||||||
|
- Search for similar patterns in the codebase
|
||||||
|
- Identify TypeScript/JavaScript conventions
|
||||||
|
- Check existing test patterns (Jest, Vitest, etc.)
|
||||||
|
- Note build tools and package manager (npm, yarn, pnpm)
|
||||||
|
|
||||||
|
2. **External Research**
|
||||||
|
- Library documentation with specific URLs
|
||||||
|
- TypeScript implementation examples
|
||||||
|
- Best practices for the tech stack
|
||||||
|
- Common integration patterns
|
||||||
|
|
||||||
|
3. **Project Context**
|
||||||
|
- Framework being used (React, Next.js, Node.js, etc.)
|
||||||
|
- Testing strategy and tools
|
||||||
|
- Build and deployment processes
|
||||||
|
|
||||||
|
## PRP Generation
|
||||||
|
|
||||||
|
Using PRPs/templates/prp_base.md as template:
|
||||||
|
|
||||||
|
### Critical Context
|
||||||
|
|
||||||
|
- **Documentation URLs**: Specific sections for libraries/frameworks
|
||||||
|
- **Code Examples**: Real patterns from the codebase
|
||||||
|
- **Tech Stack**: Framework, build tools, testing setup
|
||||||
|
- **Patterns**: Existing approaches to mirror
|
||||||
|
|
||||||
|
### Implementation Blueprint
|
||||||
|
|
||||||
|
- Pseudocode showing the approach
|
||||||
|
- Reference files for patterns to follow
|
||||||
|
- Error handling strategy
|
||||||
|
- **Incremental milestones** for step-by-step validation
|
||||||
|
|
||||||
|
### Validation Gates (Tech Stack Specific)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# TypeScript/Build validation
|
||||||
|
npm run type-check
|
||||||
|
npm run lint
|
||||||
|
npm run build
|
||||||
|
|
||||||
|
# Testing
|
||||||
|
npm run test
|
||||||
|
|
||||||
|
# Custom validation commands based on project
|
||||||
|
Implementation Phases
|
||||||
|
Break implementation into phases:
|
||||||
|
|
||||||
|
Setup Phase: File structure, types, interfaces
|
||||||
|
Core Phase: Main functionality implementation
|
||||||
|
Integration Phase: Connect with existing systems
|
||||||
|
Testing Phase: Unit and integration tests
|
||||||
|
Polish Phase: Error handling, edge cases
|
||||||
|
|
||||||
|
Each phase should have:
|
||||||
|
|
||||||
|
Clear deliverables
|
||||||
|
Validation commands
|
||||||
|
Manual testing instructions
|
||||||
|
|
||||||
|
Output
|
||||||
|
Save as: PRPs/{feature-name}.md
|
||||||
|
Score the PRP on confidence level (1-10) for successful incremental implementation.
|
||||||
|
```
|
||||||
277
commands/generate-spec.md
Normal file
277
commands/generate-spec.md
Normal file
@@ -0,0 +1,277 @@
|
|||||||
|
# Generate Feature Specification
|
||||||
|
|
||||||
|
## Feature description: $ARGUMENTS
|
||||||
|
|
||||||
|
Create a comprehensive, actionable feature specification with automated codebase analysis.
|
||||||
|
|
||||||
|
## Phase 1: Automated Discovery
|
||||||
|
|
||||||
|
### Codebase Pattern Analysis
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Find similar features
|
||||||
|
rg -l "similar_feature_keywords" --type ts --type tsx
|
||||||
|
# Identify existing patterns
|
||||||
|
find . -name "*.spec.ts" -path "*/features/*" | head -5
|
||||||
|
# Check authentication patterns
|
||||||
|
rg "useAuth|requireAuth|withAuth" --type ts -A 2
|
||||||
|
# Database schema patterns
|
||||||
|
find . -name "*.prisma" -o -name "*.sql" -o -name "*migration*"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Dependency Mapping
|
||||||
|
|
||||||
|
- Search for related imports: `rg "import.*{feature_related}" --type ts`
|
||||||
|
- Check existing API endpoints: `rg "router\.(get|post|put|delete)" --type ts`
|
||||||
|
- Find UI components: `find ./src/components -name "*.tsx" | grep -i feature_area`
|
||||||
|
|
||||||
|
## Phase 2: Requirements Analysis
|
||||||
|
|
||||||
|
### User Story Mining
|
||||||
|
|
||||||
|
**Format**: As a [user_type], I want [capability] so that [business_value]
|
||||||
|
|
||||||
|
**Required Classifications**:
|
||||||
|
|
||||||
|
- Critical path (blocks other features)
|
||||||
|
- Core functionality (MVP)
|
||||||
|
- Enhancement (can ship without)
|
||||||
|
- Future consideration (v2)
|
||||||
|
|
||||||
|
### Technical Complexity Scoring
|
||||||
|
|
||||||
|
Calculate automatically:
|
||||||
|
|
||||||
|
- Files to modify: `git ls-files | xargs grep -l "pattern" | wc -l`
|
||||||
|
- New dependencies: Check against package.json
|
||||||
|
- Database changes: Schema modifications needed
|
||||||
|
- API surface: New endpoints required
|
||||||
|
|
||||||
|
**Complexity Score**:
|
||||||
|
|
||||||
|
- 1-3: Simple (< 5 files, no deps, no DB)
|
||||||
|
- 4-6: Medium (5-15 files, deps OR DB)
|
||||||
|
- 7-10: Complex (> 15 files, deps AND DB)
|
||||||
|
|
||||||
|
## Phase 3: Specification Generation
|
||||||
|
|
||||||
|
### 1. Executive Summary
|
||||||
|
|
||||||
|
- **Feature Name**: [Descriptive, searchable name]
|
||||||
|
- **Business Value**: [Specific metric improvement expected]
|
||||||
|
- **Complexity Score**: [Auto-calculated from above]
|
||||||
|
- **Estimated Effort**: [Based on complexity and similar features]
|
||||||
|
|
||||||
|
### 2. Technical Architecture
|
||||||
|
|
||||||
|
#### Database Schema
|
||||||
|
|
||||||
|
```sql
|
||||||
|
-- Required changes
|
||||||
|
ALTER TABLE existing_table ADD COLUMN new_field TYPE;
|
||||||
|
CREATE TABLE IF NOT EXISTS new_table (...);
|
||||||
|
```
|
||||||
|
|
||||||
|
#### API Design
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// New endpoints
|
||||||
|
POST /api/feature
|
||||||
|
GET /api/feature/:id
|
||||||
|
PUT /api/feature/:id
|
||||||
|
DELETE /api/feature/:id
|
||||||
|
|
||||||
|
// Request/Response types
|
||||||
|
interface FeatureRequest { ... }
|
||||||
|
interface FeatureResponse { ... }
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Frontend Components
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// Component hierarchy
|
||||||
|
<FeatureContainer>
|
||||||
|
<FeatureList />
|
||||||
|
<FeatureDetail />
|
||||||
|
<FeatureForm />
|
||||||
|
</FeatureContainer>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Implementation Checklist
|
||||||
|
|
||||||
|
#### Pre-Implementation
|
||||||
|
|
||||||
|
- [ ] Review existing patterns in: [list similar files]
|
||||||
|
- [ ] Confirm database migrations approach
|
||||||
|
- [ ] Validate API design with team
|
||||||
|
- [ ] Check accessibility requirements
|
||||||
|
|
||||||
|
#### Core Implementation
|
||||||
|
|
||||||
|
- [ ] Database schema and migrations
|
||||||
|
- [ ] API endpoints with validation
|
||||||
|
- [ ] Frontend components with tests
|
||||||
|
- [ ] Integration with existing auth/permissions
|
||||||
|
- [ ] Error handling and logging
|
||||||
|
|
||||||
|
#### Validation
|
||||||
|
|
||||||
|
- [ ] Unit tests (minimum 80% coverage)
|
||||||
|
- [ ] Integration tests for API
|
||||||
|
- [ ] E2E tests for critical paths
|
||||||
|
- [ ] Performance benchmarks met
|
||||||
|
- [ ] Security review completed
|
||||||
|
|
||||||
|
### 4. Risk Analysis
|
||||||
|
|
||||||
|
#### Technical Risks
|
||||||
|
|
||||||
|
- **Breaking Changes**: [List any backward compatibility issues]
|
||||||
|
- **Performance Impact**: [Database queries, API load]
|
||||||
|
- **Security Concerns**: [Data exposure, permission gaps]
|
||||||
|
|
||||||
|
#### Mitigation Strategies
|
||||||
|
|
||||||
|
- Feature flags for gradual rollout
|
||||||
|
- Database indexes for performance
|
||||||
|
- Rate limiting for API endpoints
|
||||||
|
- Audit logging for sensitive operations
|
||||||
|
|
||||||
|
### 5. Dependencies and Integration
|
||||||
|
|
||||||
|
#### External Dependencies
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"new-package": "^1.0.0",
|
||||||
|
"existing-upgrade": "^2.0.0 -> ^3.0.0"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Internal Dependencies
|
||||||
|
|
||||||
|
- Services: [List services that need updates]
|
||||||
|
- Shared components: [List reusable components]
|
||||||
|
- Configuration: [Environment variables needed]
|
||||||
|
|
||||||
|
### 6. Testing Strategy
|
||||||
|
|
||||||
|
#### Unit Tests
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
describe('Feature', () => {
|
||||||
|
test('core functionality', () => { ... });
|
||||||
|
test('edge cases', () => { ... });
|
||||||
|
test('error handling', () => { ... });
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Integration Tests
|
||||||
|
|
||||||
|
- API endpoint testing with supertest
|
||||||
|
- Database transaction testing
|
||||||
|
- Authentication/authorization flows
|
||||||
|
|
||||||
|
#### Manual Testing Checklist
|
||||||
|
|
||||||
|
- [ ] Happy path user flow
|
||||||
|
- [ ] Error state handling
|
||||||
|
- [ ] Mobile responsiveness
|
||||||
|
- [ ] Accessibility (keyboard nav, screen readers)
|
||||||
|
- [ ] Performance under load
|
||||||
|
|
||||||
|
### 7. Rollout Plan
|
||||||
|
|
||||||
|
#### Phase 1: Internal Testing
|
||||||
|
|
||||||
|
- Deploy behind feature flag
|
||||||
|
- Limited access to internal users
|
||||||
|
- Monitor error rates and performance
|
||||||
|
|
||||||
|
#### Phase 2: Beta Release
|
||||||
|
|
||||||
|
- Enable for % of users
|
||||||
|
- Gather feedback and metrics
|
||||||
|
- Fix critical issues
|
||||||
|
|
||||||
|
#### Phase 3: General Availability
|
||||||
|
|
||||||
|
- Full rollout
|
||||||
|
- Documentation updates
|
||||||
|
- Support team training
|
||||||
|
|
||||||
|
### 8. Success Metrics
|
||||||
|
|
||||||
|
#### Quantitative
|
||||||
|
|
||||||
|
- Feature adoption rate: [target %]
|
||||||
|
- Performance metrics: [response time targets]
|
||||||
|
- Error rate: [< threshold]
|
||||||
|
|
||||||
|
#### Qualitative
|
||||||
|
|
||||||
|
- User satisfaction score
|
||||||
|
- Support ticket reduction
|
||||||
|
- Developer experience feedback
|
||||||
|
|
||||||
|
## Phase 4: PRP Preparation
|
||||||
|
|
||||||
|
### Research Links
|
||||||
|
|
||||||
|
Collect during analysis:
|
||||||
|
|
||||||
|
- API documentation: [urls]
|
||||||
|
- Library docs: [urls]
|
||||||
|
- Design patterns: [urls]
|
||||||
|
- Security best practices: [urls]
|
||||||
|
|
||||||
|
### Code References
|
||||||
|
|
||||||
|
- Similar implementations: `path/to/file.ts:line`
|
||||||
|
- Pattern examples: `path/to/example.ts:line`
|
||||||
|
- Test examples: `path/to/test.spec.ts:line`
|
||||||
|
|
||||||
|
### Outstanding Questions
|
||||||
|
|
||||||
|
- [ ] Technical decisions needed
|
||||||
|
- [ ] Architecture review required
|
||||||
|
- [ ] Performance optimization approach
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
### Primary Spec
|
||||||
|
|
||||||
|
Save to: `docs/specs/{feature-name}-spec.md`
|
||||||
|
|
||||||
|
### Supporting Artifacts
|
||||||
|
|
||||||
|
- `docs/specs/{feature-name}-api.yaml` - OpenAPI spec
|
||||||
|
- `docs/specs/{feature-name}-db.sql` - Database changes
|
||||||
|
- `docs/specs/{feature-name}-tests.md` - Test plan
|
||||||
|
|
||||||
|
### Validation
|
||||||
|
|
||||||
|
Run after generation:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Validate spec completeness
|
||||||
|
grep -c "TODO\|TBD\|FIXME" docs/specs/{feature-name}-spec.md
|
||||||
|
# Check for broken references
|
||||||
|
grep -o "path/to/.*\.ts:[0-9]*" docs/specs/{feature-name}-spec.md | while read ref; do
|
||||||
|
file=$(echo $ref | cut -d: -f1)
|
||||||
|
[ -f "$file" ] || echo "Missing: $file"
|
||||||
|
done
|
||||||
|
```
|
||||||
|
|
||||||
|
## Usage Notes
|
||||||
|
|
||||||
|
This command now:
|
||||||
|
|
||||||
|
1. Automatically analyzes your codebase for patterns
|
||||||
|
2. Calculates complexity scores
|
||||||
|
3. Generates actionable, specific specifications
|
||||||
|
4. Prepares for PRP generation
|
||||||
|
5. Includes validation and rollout planning
|
||||||
|
6. Provides testable success criteria
|
||||||
|
|
||||||
|
The spec is no longer just documentation - it's a blueprint for implementation.
|
||||||
65
plugin.lock.json
Normal file
65
plugin.lock.json
Normal file
@@ -0,0 +1,65 @@
|
|||||||
|
{
|
||||||
|
"$schema": "internal://schemas/plugin.lock.v1.json",
|
||||||
|
"pluginId": "gh:nicknisi/claude-plugins:plugins/spec-driven",
|
||||||
|
"normalized": {
|
||||||
|
"repo": null,
|
||||||
|
"ref": "refs/tags/v20251128.0",
|
||||||
|
"commit": "5685647d61e429f9a4d7abf2007bf08e858dc09c",
|
||||||
|
"treeHash": "f976c3ae1afab870c59b4cfda58f98d4de77eb5ef11c7929323568f0daa52de1",
|
||||||
|
"generatedAt": "2025-11-28T10:27:22.508738Z",
|
||||||
|
"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": "spec-driven",
|
||||||
|
"description": "Transform specifications into executable code with automated analysis, validation checkpoints, and incremental delivery",
|
||||||
|
"version": "0.1.0"
|
||||||
|
},
|
||||||
|
"content": {
|
||||||
|
"files": [
|
||||||
|
{
|
||||||
|
"path": "README.md",
|
||||||
|
"sha256": "cf423ea00090d7a285ce66f0cd571bd935e95f136185bb09d81fcd1f8a02f05a"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": ".claude-plugin/plugin.json",
|
||||||
|
"sha256": "bcd7c00f52656fa9571188319e91fb58b7c41fa9de767238f3afc791a5f60e63"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "commands/execute-spec.md",
|
||||||
|
"sha256": "89f2ef13ef5c140efd5adbaa4698c39c06bad8a033e7fb983bcf2b264bfab5be"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "commands/generate-prp.md",
|
||||||
|
"sha256": "d26a61573521db79a7952fb9af70aa8f78c69e7de454878d67a37ee0f9817409"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "commands/execute-prp.md",
|
||||||
|
"sha256": "0fcf06c5d84da87b8d6dcfb774ae8ca3622a4e90c66966cd4d2dbe017df96fb6"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "commands/generate-spec.md",
|
||||||
|
"sha256": "f5f33293560e6f39855f2e2f9cff4d6c9c29fdb82ad913c79e9fb2e69d6b1014"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "commands/check-prp.md",
|
||||||
|
"sha256": "5e5a5ab1088b922946786a37652a4b4d61a24c373412172ada7ee70b61a23fda"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "commands/check-spec.md",
|
||||||
|
"sha256": "da0ade906ab9f011dde4506657419528d8dd9f2ab01707b701b5a91109b0aa39"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"dirSha256": "f976c3ae1afab870c59b4cfda58f98d4de77eb5ef11c7929323568f0daa52de1"
|
||||||
|
},
|
||||||
|
"security": {
|
||||||
|
"scannedAt": null,
|
||||||
|
"scannerVersion": null,
|
||||||
|
"flags": []
|
||||||
|
}
|
||||||
|
}
|
||||||
Reference in New Issue
Block a user