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