zhongwei/gh-rhuss-cc-superpowers-sdd
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:44 +08:00
commit a0be4de7ac
22 changed files with 5124 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

500
skills/writing-plans/SKILL.md Normal file
View File

@@ -0,0 +1,500 @@
---
name: writing-plans
description: Generate implementation plans FROM specifications - reads spec as input, extracts requirements, creates step-by-step tasks with validation against spec
---
# Writing Implementation Plans from Specifications
## Overview
Generate detailed implementation plans derived FROM specifications, not from scratch.
The spec is the source of truth. The plan translates spec requirements into concrete, actionable implementation tasks.
**Key Difference from Standard Writing-Plans:**
- **Input is SPEC** (not blank slate)
- Plan MUST cover all spec requirements
- Plan validates against spec for completeness
- Tasks reference spec sections explicitly
## When to Use
**Use this skill when:**
- Spec exists and is validated
- Ready to create implementation plan
- Called by `sdd:implement` workflow
- Need to break spec into tasks
**Don't use this skill when:**
- No spec exists → Create spec first
- Plan already exists → Review/update existing plan
- Just clarifying approach → Use brainstorming
## Prerequisites
- [ ] Spec exists and is complete
- [ ] Spec validated for soundness
- [ ] No blocking open questions in spec
- [ ] Ready to start implementation
## The Process
### 1. Read and Parse Specification
**Load the spec:**
```bash
cat specs/features/[feature-name].md
```
**Extract all elements:**
- **Functional requirements** (what to build)
- **Non-functional requirements** (how it should perform)
- **Success criteria** (how to verify)
- **Error handling** (what can go wrong)
- **Edge cases** (boundary conditions)
- **Dependencies** (what's needed)
- **Constraints** (limitations)
**Create requirements checklist:**
- Number each requirement
- Reference spec section
- Mark coverage status
### 2. Understand Project Context
**Check existing codebase:**
```bash
# Find related files
rg "[relevant-terms]"
# Check architecture
ls -la src/
# Review dependencies
cat package.json # or requirements.txt, go.mod, etc.
```
**Identify:**
- Where new code should live
- Existing patterns to follow
- Components to reuse
- Integration points
### 3. Design Implementation Strategy
**For each functional requirement, determine:**
**Approach:**
- How will this be implemented?
- What components are needed?
- What patterns apply?
**Files:**
- What files to create?
- What files to modify?
- Full file paths
**Dependencies:**
- What needs to exist first?
- What can be done in parallel?
- What's the critical path?
**Testing:**
- How will this be tested?
- What test files needed?
- What edge cases to cover?
### 4. Create Implementation Plan
**Use this structure:**
```markdown
# Implementation Plan: [Feature Name]
**Source Spec:** specs/features/[feature-name].md
**Date:** YYYY-MM-DD
**Estimated Effort:** [time estimate if relevant]
## Overview
[Brief summary of what we're implementing and why]
## Requirements Coverage
### Functional Requirement 1: [Quote from spec]
**Spec Reference:** specs/features/[feature].md#[section]
**Implementation Approach:**
[How we'll implement this requirement]
**Tasks:**
- [ ] [Specific actionable task]
- [ ] [Another task]
**Files to Create/Modify:**
- `path/to/file.ext` - [What changes]
**Tests:**
- [ ] [Test case for this requirement]
---
### Functional Requirement 2: [Quote from spec]
[Repeat structure]
---
[Continue for ALL functional requirements]
## Non-Functional Requirements
[For each non-functional requirement from spec]
### [Requirement Name]: [Quote from spec]
**Spec Reference:** specs/features/[feature].md#[section]
**Implementation:**
[How we'll achieve this]
**Validation:**
[How we'll measure/verify this]
## Error Handling Implementation
[For each error case in spec]
### Error: [From spec]
**Spec Reference:** specs/features/[feature].md#error-handling
**Implementation:**
```
[Code approach or pseudocode]
```
**Test Cases:**
- [ ] [Test for this error case]
## Edge Cases Implementation
[For each edge case in spec]
### Edge Case: [From spec]
**Expected Behavior:** [From spec]
**Implementation:**
[How we'll handle this]
**Test:**
- [ ] [Test for edge case]
## Dependencies
**Required Before Implementation:**
- [ ] [Dependency 1 from spec]
- [ ] [Dependency 2 from spec]
**Integration Points:**
- [Component/service 1]: [How we integrate]
- [Component/service 2]: [How we integrate]
## Implementation Order
**Phase 1: Foundation**
1. [Task]
2. [Task]
**Phase 2: Core Functionality**
1. [Task]
2. [Task]
**Phase 3: Error Handling**
1. [Task]
2. [Task]
**Phase 4: Edge Cases & Polish**
1. [Task]
2. [Task]
## Test Strategy
**Unit Tests:**
- [ ] [Component/function to test]
- [ ] [Another component/function]
**Integration Tests:**
- [ ] [Integration scenario]
- [ ] [Another scenario]
**Spec Compliance Tests:**
- [ ] [Verify requirement 1]
- [ ] [Verify requirement 2]
## Files to Create
- `path/to/new/file1.ext` - [Purpose]
- `path/to/new/file2.ext` - [Purpose]
## Files to Modify
- `path/to/existing/file1.ext` - [What changes]
- `path/to/existing/file2.ext` - [What changes]
## Success Criteria
[From spec, repeated here for reference]
- [ ] [Criterion 1]
- [ ] [Criterion 2]
## Spec Validation Checklist
**All requirements covered:**
- [ ] All functional requirements have tasks
- [ ] All non-functional requirements addressed
- [ ] All error cases have implementation approach
- [ ] All edge cases have handling strategy
- [ ] All dependencies identified
- [ ] All success criteria have verification plan
**Plan completeness:**
- [ ] All tasks are specific and actionable
- [ ] All file paths are complete (not "TBD")
- [ ] All requirements reference spec sections
- [ ] Test strategy covers all requirements
- [ ] Implementation order is logical
## Notes
[Any additional context, decisions, or considerations]
```
### 5. Validate Plan Against Spec
**Completeness check:**
For each requirement in spec:
- [ ] Plan has implementation approach
- [ ] Plan has specific tasks
- [ ] Plan has test coverage
- [ ] Plan references spec section
**Coverage matrix:**
```
Requirement 1 → Tasks [1,2,3], Tests [A,B] ✓
Requirement 2 → Tasks [4,5], Tests [C,D] ✓
Requirement 3 → Tasks [6], Tests [E,F,G] ✓
...
```
**If any requirement uncovered:** Add tasks before proceeding.
### 6. Review for Implementability
**Check that plan:**
- Has concrete file paths (not "somewhere")
- Has specific tasks (not vague "implement X")
- Has realistic order (dependencies respected)
- Has test coverage (every requirement tested)
**Red flags:**
- "Figure out how to..."
- "Implement [vague concept]"
- "TBD"
- Missing file paths
- No test strategy
### 7. Save and Commit Plan
**Save plan:**
```bash
# Location
docs/plans/[date]-[feature]-implementation.md
```
**Commit plan:**
```bash
git add docs/plans/[date]-[feature]-implementation.md
git commit -m "Add implementation plan for [feature]
Generated from spec: specs/features/[feature].md
Coverage:
- [N] functional requirements
- [N] error cases
- [N] edge cases
Estimated [N] tasks
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>"
```
## Checklist
Use TodoWrite to track:
- [ ] Read and parse specification completely
- [ ] Extract all requirements, errors, edge cases
- [ ] Understand project context and codebase
- [ ] Design implementation strategy
- [ ] Create implementation plan with all sections
- [ ] Validate plan coverage against spec (100%)
- [ ] Review plan for implementability
- [ ] Ensure all file paths are complete
- [ ] Ensure all tasks are specific and actionable
- [ ] Save plan to docs/plans/
- [ ] Commit plan to git
## Example
```
[Called from sdd:implement]
You: Generating implementation plan from spec...
Reading spec: specs/features/user-profile-api.md
Extracting requirements:
- Functional: 6 requirements
- Non-functional: 3 requirements
- Error cases: 4
- Edge cases: 3
- Dependencies: 2
Understanding project context...
- Existing API routes in: src/api/
- Validation middleware in: src/middleware/
- User service in: src/services/user.ts
- Tests in: tests/api/
Creating implementation plan...
# Implementation Plan: User Profile Update API
**Source Spec:** specs/features/user-profile-api.md
**Date:** 2025-11-10
## Overview
Implement REST API endpoint for authenticated users to update their profiles.
Includes validation, error handling, and partial update support.
## Requirements Coverage
### Functional Requirement 1: PUT endpoint accepts requests
**Spec Reference:** specs/features/user-profile-api.md#functional-requirements
**Implementation Approach:**
Create Express route handler at PUT /api/users/:id/profile using
existing route structure in src/api/users/
**Tasks:**
- [ ] Create route file at src/api/users/profile.ts
- [ ] Register route in src/api/users/index.ts
- [ ] Add route handler function
**Files to Create/Modify:**
- `src/api/users/profile.ts` - New route handler
- `src/api/users/index.ts` - Register route
**Tests:**
- [ ] Test route responds to PUT requests
- [ ] Test route path is /api/users/:id/profile
---
### Functional Requirement 2: Validate request body
**Spec Reference:** specs/features/user-profile-api.md#functional-requirements
**Implementation Approach:**
Create validation middleware using existing validation pattern.
Validate: name (2-50 chars), bio (max 500), avatar_url (URL format).
**Tasks:**
- [ ] Create validation schema in src/middleware/validation/profile.ts
- [ ] Add validation middleware to route
- [ ] Return 422 on validation errors
**Files to Create/Modify:**
- `src/middleware/validation/profile.ts` - Validation schema
- `src/api/users/profile.ts` - Apply middleware
**Tests:**
- [ ] Test name length validation (too short)
- [ ] Test name length validation (too long)
- [ ] Test bio length validation
- [ ] Test avatar_url format validation
[... continues for all requirements ...]
## Spec Validation Checklist
**All requirements covered:**
- [x] All 6 functional requirements have tasks
- [x] All 3 non-functional requirements addressed
- [x] All 4 error cases have implementation
- [x] All 3 edge cases handled
- [x] All 2 dependencies identified
- [x] All 5 success criteria have verification
Plan validated against spec ✓
Coverage: 100%
Saving plan to: docs/plans/2025-11-10-user-profile-api-implementation.md
Plan created ✓
Committed to git ✓
Plan has 24 tasks across 4 phases.
Ready to implement with TDD?
```
## Quality Standards
**Every plan MUST have:**
- Complete file paths (no "TBD")
- Specific tasks (not vague)
- Test coverage (every requirement)
- Error handling (every error case)
- Edge case coverage (every edge case)
- Spec references (every requirement linked)
**Every task MUST be:**
- Actionable (clear what to do)
- Testable (can verify completion)
- Atomic (one clear outcome)
- Ordered (dependencies respected)
## Common Pitfalls
**Avoid:**
- Creating plan before spec exists
- Missing spec requirements in plan
- Vague tasks ("implement feature")
- Missing file paths
- No test strategy
- Skipping error cases
- Ignoring edge cases
**Instead:**
- Always start from spec
- Cover 100% of spec requirements
- Make tasks concrete and specific
- Provide complete file paths
- Test every requirement
- Handle every error case
- Cover every edge case
## Remember
**The plan is a bridge from spec to code.**
- Spec says WHAT
- Plan says HOW and WHERE and WHEN
- Code implements the plan
**A good plan makes implementation smooth.**
**A poor plan causes confusion and rework.**
**Validate against spec before proceeding.**
**100% coverage is non-negotiable.**