zhongwei/gh-rjmoggach-claude-plugins-plugins-spec
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:51:52 +08:00
commit 7886816c48
15 changed files with 1327 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

174
skills/spec-workflow/SKILL.md Normal file
View File

@@ -0,0 +1,174 @@
---
name: Spec Workflow
description: Create complete product feature specifications with requirements, design, and tasks documents. Use when the user wants to create a spec, generate specifications, or mentions "spec workflow". Handles validation and iterative refinement.
---
You are the spec-driven development workflow assistant.
## Your Role
You help users create and validate product feature specifications using a systematic, agent-driven workflow.
## Intent Detection
Analyze the user's request to determine intent:
### Intent: Create New Specification
Patterns:
- "use spec workflow to create [feature]"
- "create spec for [feature]"
- "generate specification for [feature]"
- "spec workflow for [feature]"
Action: Invoke the **spec-orchestrator** agent
### Intent: Validate Existing Document
Patterns:
- "validate [document]"
- "check the [requirements/design/tasks]"
- "review spec for [feature]"
Action: Invoke the appropriate validator agent
### Intent: Unclear
Action: Ask user to clarify what they want to do
## Workflow: Create New Specification
When the user wants to create a new specification:
1. **Extract feature details** from user request:
- Feature name
- Feature description
- Any specific requirements or context
- Target location (default: `.claude/specs/{feature-name}/`)
2. **Invoke spec-orchestrator agent** using the Task tool:
```
Create a complete specification for the following feature:
Feature Name: {extracted feature name}
Description: {user's description}
Additional Context:
{any other context provided by user}
Follow the complete spec-driven workflow:
1. Setup: Create directory .claude/specs/{feature-name}/
2. Phase 1: Generate requirements.md following template
3. Phase 2: Validate requirements using spec-requirements-validator
4. Phase 3: Generate design.md following template and leveraging existing code
5. Phase 4: Validate design using spec-design-validator
6. Phase 5: Generate tasks.md following template with detailed prompts
7. Phase 6: Validate tasks using spec-tasks-validator
8. Iterate on validation feedback until all documents achieve PASS rating (max 2 iterations per phase)
9. Provide completion summary
IMPORTANT:
- Search codebase for existing code to leverage in design and tasks
- Ensure all acceptance criteria are testable
- Include detailed implementation prompts in every task
- Map tasks to specific requirements
- Generate Mermaid diagrams in design document
```
3. **Monitor orchestrator progress** and present results to user
4. **Upon completion**, show user:
```markdown
## Specification Created Successfully
I've created a complete specification for **{feature-name}** using the spec-driven workflow.
### Documents Created
- 📋 Requirements: .claude/specs/{feature-name}/requirements.md
- 🏗️ Design: .claude/specs/{feature-name}/design.md
- ✅ Tasks: .claude/specs/{feature-name}/tasks.md
### Validation Status
All documents have been validated and passed quality checks.
### Next Steps
You can:
1. Review the specification documents
2. Request modifications to any document
3. Begin implementation by executing the tasks
4. Export the spec to share with your team
What would you like to do next?
```
## Workflow: Validate Existing Document
When the user wants to validate a document:
1. **Identify document type and path**:
- Ask user if not clear from request
- Validate path exists
2. **Invoke appropriate validator**:
For **requirements**:
```
Use spec-requirements-validator agent to validate {path}
```
For **design**:
```
Use spec-design-validator agent to validate {path}
```
For **tasks**:
```
Use spec-tasks-validator agent to validate {path}
```
3. **Present validation results**:
```markdown
## Validation Results for {document-type}
**Rating**: {PASS/NEEDS_IMPROVEMENT/MAJOR_ISSUES}
### Issues Found
{list of issues from validator}
### Improvement Suggestions
{suggestions from validator}
### Strengths
{what was done well}
Would you like me to help address any of these issues?
```
## Templates
This Skill includes templates for consistent specification structure:
- [requirements-template.md](templates/requirements-template.md) - User stories and acceptance criteria
- [design-template.md](templates/design-template.md) - Architecture and component design
- [tasks-template.md](templates/tasks-template.md) - Implementation task breakdown
Templates are loaded automatically by the orchestrator and validators.
## Error Handling
If issues arise:
- **Template not found**: Guide user to create templates or use defaults
- **Directory creation fails**: Suggest manual creation or permission check
- **Validation fails repeatedly**: Present issues to user and offer to help fix
- **Agent invocation fails**: Provide fallback guidance
## Key Principles
1. **Systematic**: Follow the workflow phases in order
2. **Validated**: Every document must pass validation
3. **Leveraged**: Always identify and reuse existing code
4. **Actionable**: Tasks must be implementation-ready
5. **Traceable**: Link tasks to requirements and design
## Example Interactions
### Example 1: New Spec Creation
```
User: use spec workflow to create our user authentication feature

22
skills/spec-workflow/scripts/get-content.ps1 Normal file
View File

@@ -0,0 +1,22 @@
# Script: get-content.ps1
# Purpose: Helper script for spec-workflow agents to load template and spec files (Windows)
# Usage: get-content.ps1 "C:\path\to\file.md"
param(
[Parameter(Mandatory=$true)]
[string]$FilePath
)
# Check if file exists
if (-not (Test-Path -Path $FilePath -PathType Leaf)) {
Write-Error "Error: File not found: $FilePath"
Write-Host "Please check the path and try again."
exit 1
}
# Output file content with header for clarity
Write-Host "=== Content of: $FilePath ===" -ForegroundColor Cyan
Write-Host ""
Get-Content -Path $FilePath
Write-Host ""
Write-Host "=== End of file ===" -ForegroundColor Cyan

28
skills/spec-workflow/scripts/get-content.sh Executable file
View File

@@ -0,0 +1,28 @@
#!/bin/bash
# Script: get-content.sh
# Purpose: Helper script for spec-workflow agents to load template and spec files
# Usage: get-content.sh "/path/to/file.md"
# Check if file path argument is provided
if [ -z "$1" ]; then
echo "Error: No file path provided"
echo "Usage: $0 \"/path/to/file.md\""
exit 1
fi
FILE_PATH="$1"
# Check if file exists
if [ ! -f "$FILE_PATH" ]; then
echo "Error: File not found: $FILE_PATH"
echo "Please check the path and try again."
exit 1
fi
# Output file content with header for clarity
echo "=== Content of: $FILE_PATH ==="
echo ""
cat "$FILE_PATH"
echo ""
echo "=== End of file ==="

96
skills/spec-workflow/templates/design-template.md Normal file
View File

@@ -0,0 +1,96 @@
# Design Document
## Overview
[High-level description of the feature and its place in the overall system]
## Steering Document Alignment
### Technical Standards (tech.md)
[How the design follows documented technical patterns and standards]
### Project Structure (structure.md)
[How the implementation will follow project organization conventions]
## Code Reuse Analysis
[What existing code will be leveraged, extended, or integrated with this feature]
### Existing Components to Leverage
- **[Component/Utility Name]**: [How it will be used]
- **[Service/Helper Name]**: [How it will be extended]
### Integration Points
- **[Existing System/API]**: [How the new feature will integrate]
- **[Database/Storage]**: [How data will connect to existing schemas]
## Architecture
[Describe the overall architecture and design patterns used]
### Modular Design Principles
- **Single File Responsibility**: Each file should handle one specific concern or domain
- **Component Isolation**: Create small, focused components rather than large monolithic files
- **Service Layer Separation**: Separate data access, business logic, and presentation layers
- **Utility Modularity**: Break utilities into focused, single-purpose modules
```mermaid
graph TD
A[Component A] --> B[Component B]
B --> C[Component C]
```
## Components and Interfaces
### Component 1
- **Purpose:** [What this component does]
- **Interfaces:** [Public methods/APIs]
- **Dependencies:** [What it depends on]
- **Reuses:** [Existing components/utilities it builds upon]
### Component 2
- **Purpose:** [What this component does]
- **Interfaces:** [Public methods/APIs]
- **Dependencies:** [What it depends on]
- **Reuses:** [Existing components/utilities it builds upon]
## Data Models
### Model 1
```
[Define the structure of Model1 in your language]
- id: [unique identifier type]
- name: [string/text type]
- [Additional properties as needed]
```
### Model 2
```
[Define the structure of Model2 in your language]
- id: [unique identifier type]
- [Additional properties as needed]
```
## Error Handling
### Error Scenarios
1. **Scenario 1:** [Description]
- **Handling:** [How to handle]
- **User Impact:** [What user sees]
2. **Scenario 2:** [Description]
- **Handling:** [How to handle]
- **User Impact:** [What user sees]
## Testing Strategy
### Unit Testing
- [Unit testing approach]
- [Key components to test]
### Integration Testing
- [Integration testing approach]
- [Key flows to test]
### End-to-End Testing
- [E2E testing approach]
- [User scenarios to test]

50
skills/spec-workflow/templates/requirements-template.md Normal file
View File

@@ -0,0 +1,50 @@
# Requirements Document
## Introduction
[Provide a brief overview of the feature, its purpose, and its value to users]
## Alignment with Product Vision
[Explain how this feature supports the goals outlined in product.md]
## Requirements
### Requirement 1
**User Story:** As a [role], I want [feature], so that [benefit]
#### Acceptance Criteria
1. WHEN [event] THEN [system] SHALL [response]
2. IF [precondition] THEN [system] SHALL [response]
3. WHEN [event] AND [condition] THEN [system] SHALL [response]
### Requirement 2
**User Story:** As a [role], I want [feature], so that [benefit]
#### Acceptance Criteria
1. WHEN [event] THEN [system] SHALL [response]
2. IF [precondition] THEN [system] SHALL [response]
## Non-Functional Requirements
### Code Architecture and Modularity
- **Single Responsibility Principle**: Each file should have a single, well-defined purpose
- **Modular Design**: Components, utilities, and services should be isolated and reusable
- **Dependency Management**: Minimize interdependencies between modules
- **Clear Interfaces**: Define clean contracts between components and layers
### Performance
- [Performance requirements]
### Security
- [Security requirements]
### Reliability
- [Reliability requirements]
### Usability
- [Usability requirements]

139
skills/spec-workflow/templates/tasks-template.md Normal file
View File

@@ -0,0 +1,139 @@
# Tasks Document
- [ ] 1. Create core interfaces in src/types/feature.ts
- File: src/types/feature.ts
- Define TypeScript interfaces for feature data structures
- Extend existing base interfaces from base.ts
- Purpose: Establish type safety for feature implementation
- _Leverage: src/types/base.ts_
- _Requirements: 1.1_
- _Prompt: Role: TypeScript Developer specializing in type systems and interfaces | Task: Create comprehensive TypeScript interfaces for the feature data structures following requirements 1.1, extending existing base interfaces from src/types/base.ts | Restrictions: Do not modify existing base interfaces, maintain backward compatibility, follow project naming conventions | Success: All interfaces compile without errors, proper inheritance from base types, full type coverage for feature requirements_
- [ ] 2. Create base model class in src/models/FeatureModel.ts
- File: src/models/FeatureModel.ts
- Implement base model extending BaseModel class
- Add validation methods using existing validation utilities
- Purpose: Provide data layer foundation for feature
- _Leverage: src/models/BaseModel.ts, src/utils/validation.ts_
- _Requirements: 2.1_
- _Prompt: Role: Backend Developer with expertise in Node.js and data modeling | Task: Create a base model class extending BaseModel and implementing validation following requirement 2.1, leveraging existing patterns from src/models/BaseModel.ts and src/utils/validation.ts | Restrictions: Must follow existing model patterns, do not bypass validation utilities, maintain consistent error handling | Success: Model extends BaseModel correctly, validation methods implemented and tested, follows project architecture patterns_
- [ ] 3. Add specific model methods to FeatureModel.ts
- File: src/models/FeatureModel.ts (continue from task 2)
- Implement create, update, delete methods
- Add relationship handling for foreign keys
- Purpose: Complete model functionality for CRUD operations
- _Leverage: src/models/BaseModel.ts_
- _Requirements: 2.2, 2.3_
- _Prompt: Role: Backend Developer with expertise in ORM and database operations | Task: Implement CRUD methods and relationship handling in FeatureModel.ts following requirements 2.2 and 2.3, extending patterns from src/models/BaseModel.ts | Restrictions: Must maintain transaction integrity, follow existing relationship patterns, do not duplicate base model functionality | Success: All CRUD operations work correctly, relationships are properly handled, database operations are atomic and efficient_
- [ ] 4. Create model unit tests in tests/models/FeatureModel.test.ts
- File: tests/models/FeatureModel.test.ts
- Write tests for model validation and CRUD methods
- Use existing test utilities and fixtures
- Purpose: Ensure model reliability and catch regressions
- _Leverage: tests/helpers/testUtils.ts, tests/fixtures/data.ts_
- _Requirements: 2.1, 2.2_
- _Prompt: Role: QA Engineer with expertise in unit testing and Jest/Mocha frameworks | Task: Create comprehensive unit tests for FeatureModel validation and CRUD methods covering requirements 2.1 and 2.2, using existing test utilities from tests/helpers/testUtils.ts and fixtures from tests/fixtures/data.ts | Restrictions: Must test both success and failure scenarios, do not test external dependencies directly, maintain test isolation | Success: All model methods are tested with good coverage, edge cases covered, tests run independently and consistently_
- [ ] 5. Create service interface in src/services/IFeatureService.ts
- File: src/services/IFeatureService.ts
- Define service contract with method signatures
- Extend base service interface patterns
- Purpose: Establish service layer contract for dependency injection
- _Leverage: src/services/IBaseService.ts_
- _Requirements: 3.1_
- _Prompt: Role: Software Architect specializing in service-oriented architecture and TypeScript interfaces | Task: Design service interface contract following requirement 3.1, extending base service patterns from src/services/IBaseService.ts for dependency injection | Restrictions: Must maintain interface segregation principle, do not expose internal implementation details, ensure contract compatibility with DI container | Success: Interface is well-defined with clear method signatures, extends base service appropriately, supports all required service operations_
- [ ] 6. Implement feature service in src/services/FeatureService.ts
- File: src/services/FeatureService.ts
- Create concrete service implementation using FeatureModel
- Add error handling with existing error utilities
- Purpose: Provide business logic layer for feature operations
- _Leverage: src/services/BaseService.ts, src/utils/errorHandler.ts, src/models/FeatureModel.ts_
- _Requirements: 3.2_
- _Prompt: Role: Backend Developer with expertise in service layer architecture and business logic | Task: Implement concrete FeatureService following requirement 3.2, using FeatureModel and extending BaseService patterns with proper error handling from src/utils/errorHandler.ts | Restrictions: Must implement interface contract exactly, do not bypass model validation, maintain separation of concerns from data layer | Success: Service implements all interface methods correctly, robust error handling implemented, business logic is well-encapsulated and testable_
- [ ] 7. Add service dependency injection in src/utils/di.ts
- File: src/utils/di.ts (modify existing)
- Register FeatureService in dependency injection container
- Configure service lifetime and dependencies
- Purpose: Enable service injection throughout application
- _Leverage: existing DI configuration in src/utils/di.ts_
- _Requirements: 3.1_
- _Prompt: Role: DevOps Engineer with expertise in dependency injection and IoC containers | Task: Register FeatureService in DI container following requirement 3.1, configuring appropriate lifetime and dependencies using existing patterns from src/utils/di.ts | Restrictions: Must follow existing DI container patterns, do not create circular dependencies, maintain service resolution efficiency | Success: FeatureService is properly registered and resolvable, dependencies are correctly configured, service lifetime is appropriate for use case_
- [ ] 8. Create service unit tests in tests/services/FeatureService.test.ts
- File: tests/services/FeatureService.test.ts
- Write tests for service methods with mocked dependencies
- Test error handling scenarios
- Purpose: Ensure service reliability and proper error handling
- _Leverage: tests/helpers/testUtils.ts, tests/mocks/modelMocks.ts_
- _Requirements: 3.2, 3.3_
- _Prompt: Role: QA Engineer with expertise in service testing and mocking frameworks | Task: Create comprehensive unit tests for FeatureService methods covering requirements 3.2 and 3.3, using mocked dependencies from tests/mocks/modelMocks.ts and test utilities | Restrictions: Must mock all external dependencies, test business logic in isolation, do not test framework code | Success: All service methods tested with proper mocking, error scenarios covered, tests verify business logic correctness and error handling_
- [ ] 4. Create API endpoints
- Design API structure
- _Leverage: src/api/baseApi.ts, src/utils/apiUtils.ts_
- _Requirements: 4.0_
- _Prompt: Role: API Architect specializing in RESTful design and Express.js | Task: Design comprehensive API structure following requirement 4.0, leveraging existing patterns from src/api/baseApi.ts and utilities from src/utils/apiUtils.ts | Restrictions: Must follow REST conventions, maintain API versioning compatibility, do not expose internal data structures directly | Success: API structure is well-designed and documented, follows existing patterns, supports all required operations with proper HTTP methods and status codes_
- [ ] 4.1 Set up routing and middleware
- Configure application routes
- Add authentication middleware
- Set up error handling middleware
- _Leverage: src/middleware/auth.ts, src/middleware/errorHandler.ts_
- _Requirements: 4.1_
- _Prompt: Role: Backend Developer with expertise in Express.js middleware and routing | Task: Configure application routes and middleware following requirement 4.1, integrating authentication from src/middleware/auth.ts and error handling from src/middleware/errorHandler.ts | Restrictions: Must maintain middleware order, do not bypass security middleware, ensure proper error propagation | Success: Routes are properly configured with correct middleware chain, authentication works correctly, errors are handled gracefully throughout the request lifecycle_
- [ ] 4.2 Implement CRUD endpoints
- Create API endpoints
- Add request validation
- Write API integration tests
- _Leverage: src/controllers/BaseController.ts, src/utils/validation.ts_
- _Requirements: 4.2, 4.3_
- _Prompt: Role: Full-stack Developer with expertise in API development and validation | Task: Implement CRUD endpoints following requirements 4.2 and 4.3, extending BaseController patterns and using validation utilities from src/utils/validation.ts | Restrictions: Must validate all inputs, follow existing controller patterns, ensure proper HTTP status codes and responses | Success: All CRUD operations work correctly, request validation prevents invalid data, integration tests pass and cover all endpoints_
- [ ] 5. Add frontend components
- Plan component architecture
- _Leverage: src/components/BaseComponent.tsx, src/styles/theme.ts_
- _Requirements: 5.0_
- _Prompt: Role: Frontend Architect with expertise in React component design and architecture | Task: Plan comprehensive component architecture following requirement 5.0, leveraging base patterns from src/components/BaseComponent.tsx and theme system from src/styles/theme.ts | Restrictions: Must follow existing component patterns, maintain design system consistency, ensure component reusability | Success: Architecture is well-planned and documented, components are properly organized, follows existing patterns and theme system_
- [ ] 5.1 Create base UI components
- Set up component structure
- Implement reusable components
- Add styling and theming
- _Leverage: src/components/BaseComponent.tsx, src/styles/theme.ts_
- _Requirements: 5.1_
- _Prompt: Role: Frontend Developer specializing in React and component architecture | Task: Create reusable UI components following requirement 5.1, extending BaseComponent patterns and using existing theme system from src/styles/theme.ts | Restrictions: Must use existing theme variables, follow component composition patterns, ensure accessibility compliance | Success: Components are reusable and properly themed, follow existing architecture, accessible and responsive_
- [ ] 5.2 Implement feature-specific components
- Create feature components
- Add state management
- Connect to API endpoints
- _Leverage: src/hooks/useApi.ts, src/components/BaseComponent.tsx_
- _Requirements: 5.2, 5.3_
- _Prompt: Role: React Developer with expertise in state management and API integration | Task: Implement feature-specific components following requirements 5.2 and 5.3, using API hooks from src/hooks/useApi.ts and extending BaseComponent patterns | Restrictions: Must use existing state management patterns, handle loading and error states properly, maintain component performance | Success: Components are fully functional with proper state management, API integration works smoothly, user experience is responsive and intuitive_
- [ ] 6. Integration and testing
- Plan integration approach
- _Leverage: src/utils/integrationUtils.ts, tests/helpers/testUtils.ts_
- _Requirements: 6.0_
- _Prompt: Role: Integration Engineer with expertise in system integration and testing strategies | Task: Plan comprehensive integration approach following requirement 6.0, leveraging integration utilities from src/utils/integrationUtils.ts and test helpers | Restrictions: Must consider all system components, ensure proper test coverage, maintain integration test reliability | Success: Integration plan is comprehensive and feasible, all system components work together correctly, integration points are well-tested_
- [ ] 6.1 Write end-to-end tests
- Set up E2E testing framework
- Write user journey tests
- Add test automation
- _Leverage: tests/helpers/testUtils.ts, tests/fixtures/data.ts_
- _Requirements: All_
- _Prompt: Role: QA Automation Engineer with expertise in E2E testing and test frameworks like Cypress or Playwright | Task: Implement comprehensive end-to-end tests covering all requirements, setting up testing framework and user journey tests using test utilities and fixtures | Restrictions: Must test real user workflows, ensure tests are maintainable and reliable, do not test implementation details | Success: E2E tests cover all critical user journeys, tests run reliably in CI/CD pipeline, user experience is validated from end-to-end_
- [ ] 6.2 Final integration and cleanup
- Integrate all components
- Fix any integration issues
- Clean up code and documentation
- _Leverage: src/utils/cleanup.ts, docs/templates/_
- _Requirements: All_
- _Prompt: Role: Senior Developer with expertise in code quality and system integration | Task: Complete final integration of all components and perform comprehensive cleanup covering all requirements, using cleanup utilities and documentation templates | Restrictions: Must not break existing functionality, ensure code quality standards are met, maintain documentation consistency | Success: All components are fully integrated and working together, code is clean and well-documented, system meets all requirements and quality standards_