Initial commit
This commit is contained in:
Zhongwei Li
432
skills/implement/SKILL.md
Normal file
432
skills/implement/SKILL.md
Normal file
@@ -0,0 +1,432 @@
|
||||
---
|
||||
name: implement
|
||||
description: Use when spec exists and is validated - generates implementation plan FROM spec, executes with TDD, and verifies spec compliance throughout
|
||||
---
|
||||
|
||||
# Spec-Driven Implementation
|
||||
|
||||
## Overview
|
||||
|
||||
Implement features from validated specifications using Test-Driven Development, with continuous spec compliance checking throughout.
|
||||
|
||||
This is the core SDD implementation workflow: Spec → Plan → TDD → Verify.
|
||||
|
||||
**Critical Rule:** Implementation MUST match spec. Any deviation triggers spec evolution workflow.
|
||||
|
||||
## When to Use
|
||||
|
||||
**Use this skill when:**
|
||||
- Spec exists and is validated
|
||||
- Ready to write code
|
||||
- Starting implementation of new feature
|
||||
|
||||
**Don't use this skill when:**
|
||||
- No spec exists → Use `sdd:spec` or `sdd:brainstorm` first
|
||||
- Spec/code mismatch exists → Use `sdd:evolve`
|
||||
- Debugging existing code → Use `systematic-debugging`
|
||||
|
||||
## Technical Prerequisites
|
||||
|
||||
Ensure spec-kit is initialized:
|
||||
|
||||
{Skill: spec-kit}
|
||||
|
||||
If spec-kit prompts for restart, pause this workflow and resume after restart.
|
||||
|
||||
## Workflow Prerequisites
|
||||
|
||||
**Before starting implementation:**
|
||||
- [ ] Spec exists in `specs/features/[feature-name].md`
|
||||
- [ ] Spec validated for soundness (`sdd:review-spec`)
|
||||
- [ ] Spec validated against constitution (if exists)
|
||||
- [ ] No open questions in spec that block implementation
|
||||
|
||||
**If prerequisites not met:** Stop and address them first.
|
||||
|
||||
## The Process
|
||||
|
||||
### 1. Read and Understand Spec
|
||||
|
||||
**Load the spec:**
|
||||
```bash
|
||||
cat specs/features/[feature-name].md
|
||||
```
|
||||
|
||||
**Extract key information:**
|
||||
- Functional requirements (what to build)
|
||||
- Success criteria (how to verify)
|
||||
- Error handling (what can go wrong)
|
||||
- Dependencies (what's needed)
|
||||
- Constraints (limitations)
|
||||
|
||||
**Validate understanding:**
|
||||
- Summarize spec back to user
|
||||
- Confirm no ambiguities remain
|
||||
- Identify any implementation questions
|
||||
|
||||
### 2. Generate Implementation Plan FROM Spec
|
||||
|
||||
**Use `sdd:writing-plans` skill** to create plan.
|
||||
|
||||
**The plan MUST:**
|
||||
- Derive directly from spec requirements
|
||||
- Include all functional requirements
|
||||
- Cover all error cases
|
||||
- Address all edge cases
|
||||
- Reference spec sections explicitly
|
||||
|
||||
**Plan structure:**
|
||||
```markdown
|
||||
# Implementation Plan: [Feature Name]
|
||||
|
||||
**Source Spec:** specs/features/[feature-name].md
|
||||
**Date:** YYYY-MM-DD
|
||||
|
||||
## Requirements Coverage
|
||||
|
||||
### Functional Requirement 1: [From spec]
|
||||
**Implementation approach:**
|
||||
- [ ] Task 1
|
||||
- [ ] Task 2
|
||||
...
|
||||
|
||||
[Repeat for all functional requirements]
|
||||
|
||||
## Error Handling Implementation
|
||||
|
||||
[For each error case in spec]
|
||||
- **Error:** [From spec]
|
||||
- **Implementation:** [How to handle]
|
||||
|
||||
## Test Strategy
|
||||
|
||||
[How we'll verify each requirement]
|
||||
|
||||
## Files to Create/Modify
|
||||
|
||||
[List with file paths]
|
||||
|
||||
## Verification Steps
|
||||
|
||||
- [ ] All tests pass
|
||||
- [ ] Spec compliance check passes
|
||||
- [ ] Code review against spec
|
||||
```
|
||||
|
||||
**Save plan:** `docs/plans/[date]-[feature]-implementation.md`
|
||||
|
||||
### 3. Set Up Isolated Workspace
|
||||
|
||||
**Use `using-git-worktrees`** (optional but recommended):
|
||||
|
||||
```bash
|
||||
git worktree add ../feature-[name] -b feature/[name]
|
||||
cd ../feature-[name]
|
||||
```
|
||||
|
||||
**Or work in current branch:**
|
||||
- Ensure clean working directory
|
||||
- Create feature branch if needed
|
||||
|
||||
### 4. Implement with Test-Driven Development
|
||||
|
||||
**Use `test-driven-development` skill.**
|
||||
|
||||
**For each requirement in spec:**
|
||||
|
||||
1. **Write test first** (based on spec requirement)
|
||||
- Test validates spec requirement directly
|
||||
- Include error cases from spec
|
||||
- Include edge cases from spec
|
||||
|
||||
2. **Watch it fail**
|
||||
- Confirms test is testing the right thing
|
||||
- Red phase of TDD
|
||||
|
||||
3. **Write minimal code to pass**
|
||||
- Implement spec requirement
|
||||
- Don't add features not in spec
|
||||
- Green phase of TDD
|
||||
|
||||
4. **Refactor**
|
||||
- Clean up while keeping tests green
|
||||
- Refactor phase of TDD
|
||||
|
||||
5. **Verify spec compliance**
|
||||
- Does code match spec requirement?
|
||||
- Check implementation against spec section
|
||||
- Document any necessary deviations
|
||||
|
||||
**Track progress with TodoWrite:**
|
||||
- Mark requirements as in_progress/completed
|
||||
- One requirement at a time
|
||||
- Don't skip or batch
|
||||
|
||||
### 5. Continuous Spec Compliance Checking
|
||||
|
||||
**During implementation, regularly check:**
|
||||
|
||||
```bash
|
||||
# Compare implementation to spec
|
||||
# For each functional requirement:
|
||||
# - ✓ Implemented as specified
|
||||
# - ✗ Deviation detected → document reason
|
||||
```
|
||||
|
||||
**If deviation needed:**
|
||||
- Document WHY spec cannot be followed
|
||||
- Note what changed and reason
|
||||
- Will trigger `sdd:evolve` during review
|
||||
|
||||
### 6. Code Review Against Spec
|
||||
|
||||
**Use `sdd:review-code` skill.**
|
||||
|
||||
**Review checks:**
|
||||
- Code implements all spec requirements
|
||||
- No extra features beyond spec
|
||||
- Error handling matches spec
|
||||
- Edge cases covered per spec
|
||||
- Tests validate spec requirements
|
||||
|
||||
**Output:**
|
||||
- Compliance score (% of requirements met)
|
||||
- List of deviations with reasons
|
||||
- Recommendations: approve or evolve
|
||||
|
||||
### 7. Verification Before Completion
|
||||
|
||||
**Use `sdd:verification-before-completion` skill.**
|
||||
|
||||
**Verification steps:**
|
||||
1. All tests pass
|
||||
2. Spec compliance validation passes
|
||||
3. No unaddressed deviations
|
||||
4. All success criteria met (from spec)
|
||||
|
||||
**If verification fails:** Fix issues before claiming completion.
|
||||
|
||||
## Checklist
|
||||
|
||||
Use TodoWrite to track:
|
||||
|
||||
- [ ] Read and understand spec
|
||||
- [ ] Generate implementation plan from spec
|
||||
- [ ] Set up workspace (worktree or branch)
|
||||
- [ ] For each requirement: TDD cycle (test, fail, implement, pass, refactor)
|
||||
- [ ] Check spec compliance continuously
|
||||
- [ ] Request code review against spec
|
||||
- [ ] Run verification (tests + spec compliance)
|
||||
- [ ] Address any deviations (evolve spec or fix code)
|
||||
- [ ] Commit implementation
|
||||
- [ ] Clean up workspace
|
||||
|
||||
## Example Flow
|
||||
|
||||
```
|
||||
User: Let's implement the user profile API from the spec
|
||||
|
||||
You: I'm using sdd:implement to build this feature from the spec.
|
||||
|
||||
Reading spec: specs/features/user-profile-api.md
|
||||
|
||||
The spec defines:
|
||||
- PUT /api/users/:id/profile endpoint
|
||||
- Fields: name (2-50 chars), bio (max 500), avatar_url
|
||||
- Auth: JWT required
|
||||
- Errors: 401, 403, 404, 422
|
||||
- Success criteria: authenticated users can update profiles
|
||||
|
||||
Generating implementation plan from spec...
|
||||
[Uses sdd:writing-plans]
|
||||
|
||||
Plan created: docs/plans/2025-11-10-user-profile-api-implementation.md
|
||||
|
||||
Plan includes:
|
||||
1. Create route handler (src/api/users/profile.ts)
|
||||
2. Add validation middleware (src/middleware/validate-profile.ts)
|
||||
3. Update service layer (src/services/user.ts)
|
||||
4. Add tests (tests/api/users/profile.test.ts)
|
||||
|
||||
Ready to implement with TDD. Starting...
|
||||
|
||||
[Uses test-driven-development]
|
||||
|
||||
Test 1: Should reject unauthenticated requests (Spec: Error Handling)
|
||||
|
||||
Writing test...
|
||||
```typescript
|
||||
test('PUT /api/users/:id/profile returns 401 without JWT', async () => {
|
||||
const response = await request(app)
|
||||
.put('/api/users/123/profile')
|
||||
.send({ name: 'Test' });
|
||||
|
||||
expect(response.status).toBe(401);
|
||||
expect(response.body.error).toBe('Authentication required');
|
||||
});
|
||||
```
|
||||
|
||||
Running test... ❌ FAIL (expected - no auth implemented yet)
|
||||
|
||||
Implementing auth middleware...
|
||||
[Adds JWT validation]
|
||||
|
||||
Running test... ✅ PASS
|
||||
|
||||
Spec compliance check:
|
||||
✓ Matches spec requirement: "User must be authenticated with valid JWT"
|
||||
✓ Error message matches spec: "Authentication required"
|
||||
|
||||
---
|
||||
|
||||
Test 2: Should validate name length (Spec: Functional Requirements #2)
|
||||
|
||||
Writing test...
|
||||
```typescript
|
||||
test('PUT /api/users/:id/profile validates name length', async () => {
|
||||
const token = generateTestJWT({ sub: '123' });
|
||||
|
||||
// Too short
|
||||
let response = await request(app)
|
||||
.put('/api/users/123/profile')
|
||||
.set('Authorization', `Bearer ${token}`)
|
||||
.send({ name: 'A' });
|
||||
|
||||
expect(response.status).toBe(422);
|
||||
|
||||
// Too long
|
||||
response = await request(app)
|
||||
.put('/api/users/123/profile')
|
||||
.set('Authorization', `Bearer ${token}`)
|
||||
.send({ name: 'A'.repeat(51) });
|
||||
|
||||
expect(response.status).toBe(422);
|
||||
|
||||
// Valid
|
||||
response = await request(app)
|
||||
.put('/api/users/123/profile')
|
||||
.set('Authorization', `Bearer ${token}`)
|
||||
.send({ name: 'Valid Name' });
|
||||
|
||||
expect(response.status).toBe(200);
|
||||
});
|
||||
```
|
||||
|
||||
Running test... ❌ FAIL
|
||||
|
||||
Implementing validation...
|
||||
[Adds name length validation]
|
||||
|
||||
Running test... ✅ PASS
|
||||
|
||||
Spec compliance check:
|
||||
✓ Matches spec: "name: string, 2-50 characters"
|
||||
|
||||
---
|
||||
|
||||
[Continues through all requirements...]
|
||||
|
||||
All requirements implemented ✓
|
||||
|
||||
Requesting code review against spec...
|
||||
[Uses sdd:review-code]
|
||||
|
||||
Code Review Results:
|
||||
✓ All functional requirements implemented (6/6)
|
||||
✓ All error cases handled (4/4)
|
||||
✓ All edge cases covered (3/3)
|
||||
✓ Tests validate spec requirements
|
||||
|
||||
Spec Compliance: 100%
|
||||
|
||||
Deviations detected: 1
|
||||
- Added `updated_at` field to response (not in spec)
|
||||
Reason: Standard practice for update endpoints
|
||||
Recommendation: Update spec (minor addition)
|
||||
|
||||
Running verification...
|
||||
[Uses sdd:verification-before-completion]
|
||||
|
||||
✅ All tests passing (24/24)
|
||||
✅ Spec compliance validated
|
||||
⚠️ Minor deviation: updated_at field
|
||||
|
||||
Recommendation: Use sdd:evolve to update spec with updated_at field
|
||||
|
||||
You: Should I update the spec to include the updated_at field?
|
||||
```
|
||||
|
||||
## Handling Deviations
|
||||
|
||||
**When code deviates from spec:**
|
||||
|
||||
1. **Document the deviation** during implementation
|
||||
2. **Note the reason** (technical constraint, better approach, etc.)
|
||||
3. **Continue implementation** (don't block on it)
|
||||
4. **Trigger evolution** during review
|
||||
5. **Use `sdd:evolve`** to reconcile
|
||||
|
||||
**Never:**
|
||||
- Silently deviate without documentation
|
||||
- Force-fit code to incorrect spec
|
||||
- Skip spec compliance checks
|
||||
|
||||
## Integration with Superpowers Skills
|
||||
|
||||
**This skill orchestrates:**
|
||||
- `sdd:writing-plans` - Generate plan from spec
|
||||
- `test-driven-development` - TDD implementation
|
||||
- `sdd:review-code` - Spec compliance review
|
||||
- `sdd:verification-before-completion` - Tests + spec validation
|
||||
- `sdd:evolve` - If deviations need reconciliation
|
||||
|
||||
**Also compatible with:**
|
||||
- `using-git-worktrees` - Isolated workspace
|
||||
- `systematic-debugging` - If bugs found during implementation
|
||||
|
||||
## Success Criteria
|
||||
|
||||
**Implementation is complete when:**
|
||||
- [ ] All spec requirements implemented
|
||||
- [ ] All tests passing
|
||||
- [ ] Spec compliance 100% (or deviations reconciled)
|
||||
- [ ] Code review passed
|
||||
- [ ] Verification passed
|
||||
- [ ] All success criteria from spec met
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
**Avoid:**
|
||||
- Implementing features not in spec
|
||||
- Skipping TDD (spec doesn't mean no tests!)
|
||||
- Ignoring error cases from spec
|
||||
- Deviating without documentation
|
||||
- Claiming completion before verification
|
||||
|
||||
**Instead:**
|
||||
- Implement only what's in spec (YAGNI)
|
||||
- TDD for every requirement
|
||||
- Test all error cases from spec
|
||||
- Document all deviations
|
||||
- Verify before completing
|
||||
|
||||
## Remember
|
||||
|
||||
**The spec is your contract.**
|
||||
|
||||
- Don't add features not in spec
|
||||
- Don't skip requirements from spec
|
||||
- Don't ignore error cases in spec
|
||||
- Don't deviate silently
|
||||
|
||||
**If spec is wrong or incomplete:**
|
||||
- Document the issue
|
||||
- Continue implementation
|
||||
- Use `sdd:evolve` to fix spec
|
||||
|
||||
**Quality gates exist for a reason:**
|
||||
- TDD ensures testability
|
||||
- Code review ensures compliance
|
||||
- Verification ensures correctness
|
||||
|
||||
**Follow the process. Ship quality code that matches the spec.**
|
||||
Reference in New Issue
Block a user