Initial commit
This commit is contained in:
Zhongwei Li
539
skills/implementing-features/SPECS.md
Normal file
539
skills/implementing-features/SPECS.md
Normal file
@@ -0,0 +1,539 @@
|
||||
# Specification Integration & Tracking
|
||||
|
||||
This file describes how to integrate with Quaestor's specification system for tracking implementation progress.
|
||||
|
||||
## Specification Folder Structure
|
||||
|
||||
```yaml
|
||||
.quaestor/specs/
|
||||
├── draft/ # Planned specifications (not yet started)
|
||||
├── active/ # In-progress implementations (max 3)
|
||||
├── completed/ # Finished implementations
|
||||
└── archived/ # Old/cancelled specifications
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Specification Lifecycle
|
||||
|
||||
### States and Transitions
|
||||
|
||||
```yaml
|
||||
States:
|
||||
draft: "Specification created but not started"
|
||||
active: "Currently being implemented"
|
||||
completed: "Implementation finished and validated"
|
||||
archived: "Old or cancelled"
|
||||
|
||||
Transitions:
|
||||
draft → active: "Start implementation"
|
||||
active → completed: "Finish implementation"
|
||||
active → draft: "Pause work"
|
||||
any → archived: "Cancel or archive"
|
||||
|
||||
Limits:
|
||||
active: "Maximum 3 active specs"
|
||||
draft: "Unlimited"
|
||||
completed: "Unlimited"
|
||||
archived: "Unlimited"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Specification Discovery
|
||||
|
||||
### No Arguments Provided
|
||||
|
||||
**Discovery Protocol:**
|
||||
```yaml
|
||||
Step 1: Check Active Specs
|
||||
Location: .quaestor/specs/active/*.md
|
||||
Purpose: Find in-progress work
|
||||
Output: List of active specifications
|
||||
|
||||
Step 2: Check Draft Specs (if no active)
|
||||
Location: .quaestor/specs/draft/*.md
|
||||
Purpose: Find available work
|
||||
Output: List of draft specifications
|
||||
|
||||
Step 3: Present to User
|
||||
Format:
|
||||
"Found 2 specifications:
|
||||
- [active] spec-feature-001: User Authentication
|
||||
- [draft] spec-feature-002: Data Export API
|
||||
|
||||
Which would you like to work on?"
|
||||
|
||||
Step 4: User Selection
|
||||
User provides: spec ID or description
|
||||
Match: Find corresponding specification
|
||||
Activate: Move draft → active (if needed)
|
||||
```
|
||||
|
||||
### Arguments Provided
|
||||
|
||||
**Match Specification by ID or Description:**
|
||||
```yaml
|
||||
Argument Examples:
|
||||
- "spec-feature-001"
|
||||
- "feature-001"
|
||||
- "001"
|
||||
- "user authentication"
|
||||
- "auth system"
|
||||
|
||||
Matching Strategy:
|
||||
1. Exact ID match: spec-feature-001.md
|
||||
2. Partial ID match: Contains "feature-001"
|
||||
3. Description match: Title contains "user authentication"
|
||||
4. Fuzzy match: Similar words in title
|
||||
|
||||
Result:
|
||||
Match Found:
|
||||
→ Load specification
|
||||
→ Display: "Found: spec-feature-001 - User Authentication System"
|
||||
→ Activate if in draft/
|
||||
|
||||
No Match:
|
||||
→ Display: "No matching specification found"
|
||||
→ Suggest: "Available specs: [list]"
|
||||
→ Ask: "Would you like to create a new spec?"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Specification Activation
|
||||
|
||||
### Pre-Activation Validation
|
||||
|
||||
**Before Moving to Active:**
|
||||
```yaml
|
||||
Validation Checks:
|
||||
1. Spec Location:
|
||||
- If already active: "Already working on this spec"
|
||||
- If in completed: "Spec already completed"
|
||||
- If in draft: Proceed with activation
|
||||
|
||||
2. Active Limit:
|
||||
- Count: Active specs in .quaestor/specs/active/
|
||||
- Limit: Maximum 3 active specs
|
||||
- If at limit: "Active limit reached (3 specs). Complete one before starting another."
|
||||
- If under limit: Proceed with activation
|
||||
|
||||
3. Specification Validity:
|
||||
- Check: Has phases defined
|
||||
- Check: Has acceptance criteria
|
||||
- If invalid: "Specification incomplete. Please update before starting."
|
||||
```
|
||||
|
||||
### Activation Process
|
||||
|
||||
**Move from Draft to Active:**
|
||||
```yaml
|
||||
Atomic Operation:
|
||||
1. Read Specification:
|
||||
Source: .quaestor/specs/draft/spec-feature-001.md
|
||||
Parse: Extract metadata and phases
|
||||
|
||||
2. Update Status:
|
||||
Field: status
|
||||
Change: "draft" → "in_progress"
|
||||
Add: start_date (current date)
|
||||
|
||||
3. Move File:
|
||||
From: .quaestor/specs/draft/spec-feature-001.md
|
||||
To: .quaestor/specs/active/spec-feature-001.md
|
||||
Method: Git mv (preserves history)
|
||||
|
||||
4. Confirm:
|
||||
Display: "✅ Activated: spec-feature-001 - User Authentication"
|
||||
Display: "Status: in_progress"
|
||||
Display: "Phases: 4 total, 0 completed"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Progress Tracking
|
||||
|
||||
### Phase Status Updates
|
||||
|
||||
**During Implementation:**
|
||||
```yaml
|
||||
Phase Tracking:
|
||||
Format in Specification:
|
||||
## Phases
|
||||
|
||||
### Phase 1: Authentication Flow Design
|
||||
- [ ] Task 1
|
||||
- [ ] Task 2
|
||||
Status: ⏳ in_progress
|
||||
|
||||
### Phase 2: JWT Implementation
|
||||
- [ ] Task 1
|
||||
- [ ] Task 2
|
||||
Status: ⏳ pending
|
||||
|
||||
Update Protocol:
|
||||
1. Complete tasks: Mark checkboxes [x]
|
||||
2. Update status: pending → in_progress → completed
|
||||
3. Add notes: Implementation details
|
||||
4. Track blockers: If any issues
|
||||
|
||||
Example Update:
|
||||
### Phase 1: Authentication Flow Design
|
||||
- [x] Design login flow
|
||||
- [x] Design registration flow
|
||||
- [x] Design password reset flow
|
||||
Status: ✅ completed
|
||||
|
||||
Implementation Notes:
|
||||
- Used JWT with 15min access, 7day refresh
|
||||
- Implemented token rotation for security
|
||||
- Added rate limiting on auth endpoints
|
||||
```
|
||||
|
||||
### Acceptance Criteria Tracking
|
||||
|
||||
**Track Progress Against Criteria:**
|
||||
```yaml
|
||||
Acceptance Criteria Format:
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] AC1: Users can register with email/password
|
||||
- [ ] AC2: Users can log in and receive JWT
|
||||
- [ ] AC3: Tokens expire after 15 minutes
|
||||
- [ ] AC4: Refresh tokens work correctly
|
||||
- [ ] AC5: Rate limiting prevents brute force
|
||||
|
||||
Update During Implementation:
|
||||
As Each Criterion Met:
|
||||
- Mark checkbox: [x]
|
||||
- Add evidence: Link to test or code
|
||||
- Validate: Ensure actually working
|
||||
|
||||
Example:
|
||||
- [x] AC1: Users can register with email/password
|
||||
✓ Implemented in auth/registration.py
|
||||
✓ Tests: test_registration_flow.py (8 tests passing)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Completion & Transition
|
||||
|
||||
### Completion Criteria
|
||||
|
||||
**Before Moving to Completed:**
|
||||
```yaml
|
||||
All Must Be True:
|
||||
1. All Phases Completed:
|
||||
- Every phase status: ✅ completed
|
||||
- All phase tasks: [x] checked
|
||||
|
||||
2. All Acceptance Criteria Met:
|
||||
- Every criterion: [x] checked
|
||||
- Evidence provided for each
|
||||
- Tests passing for each
|
||||
|
||||
3. Quality Gates Passed:
|
||||
- All tests passing
|
||||
- Linting clean
|
||||
- Type checking passed
|
||||
- Documentation complete
|
||||
|
||||
4. No Blockers:
|
||||
- All issues resolved
|
||||
- No pending decisions
|
||||
- Ready for review
|
||||
```
|
||||
|
||||
### Move to Completed
|
||||
|
||||
**Atomic Transition:**
|
||||
```yaml
|
||||
Operation:
|
||||
1. Update Specification:
|
||||
Field: status
|
||||
Change: "in_progress" → "completed"
|
||||
Add: completion_date (current date)
|
||||
Add: final_notes (summary of implementation)
|
||||
|
||||
2. Move File:
|
||||
From: .quaestor/specs/active/spec-feature-001.md
|
||||
To: .quaestor/specs/completed/spec-feature-001.md
|
||||
Method: Git mv (preserves history)
|
||||
|
||||
3. Create Commit:
|
||||
Message: "feat: implement spec-feature-001 - User Authentication"
|
||||
Body: Include spec summary and changes
|
||||
Reference: Link to specification
|
||||
|
||||
4. Confirm:
|
||||
Display: "✅ Completed: spec-feature-001 - User Authentication"
|
||||
Display: "Status: completed"
|
||||
Display: "All phases completed, all criteria met"
|
||||
Display: "Ready for review and PR creation"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Specification File Format
|
||||
|
||||
### Markdown Structure
|
||||
|
||||
**Required Sections:**
|
||||
```markdown
|
||||
---
|
||||
id: spec-feature-001
|
||||
title: User Authentication System
|
||||
status: in_progress
|
||||
priority: high
|
||||
type: feature
|
||||
start_date: 2024-01-15
|
||||
---
|
||||
|
||||
# User Authentication System
|
||||
|
||||
## Overview
|
||||
Brief description of what this spec implements.
|
||||
|
||||
## Phases
|
||||
|
||||
### Phase 1: Phase Name
|
||||
- [ ] Task 1
|
||||
- [ ] Task 2
|
||||
Status: ⏳ in_progress
|
||||
|
||||
### Phase 2: Phase Name
|
||||
- [ ] Task 1
|
||||
- [ ] Task 2
|
||||
Status: ⏳ pending
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] AC1: Criterion 1
|
||||
- [ ] AC2: Criterion 2
|
||||
|
||||
## Technical Details
|
||||
Technical implementation notes.
|
||||
|
||||
## Testing Strategy
|
||||
How this will be tested.
|
||||
|
||||
## Implementation Notes
|
||||
Notes added during implementation.
|
||||
```
|
||||
|
||||
### Metadata Fields
|
||||
|
||||
```yaml
|
||||
Required Fields:
|
||||
id: "Unique identifier (spec-feature-001)"
|
||||
title: "Human-readable title"
|
||||
status: "draft|in_progress|completed|archived"
|
||||
priority: "low|medium|high|critical"
|
||||
type: "feature|bugfix|refactor|docs|other"
|
||||
|
||||
Optional Fields:
|
||||
start_date: "When implementation started"
|
||||
completion_date: "When implementation finished"
|
||||
estimated_hours: "Time estimate"
|
||||
actual_hours: "Actual time spent"
|
||||
assignee: "Who implemented it"
|
||||
blockers: "Any blocking issues"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Git
|
||||
|
||||
### Commit Messages
|
||||
|
||||
**Reference Specifications in Commits:**
|
||||
```yaml
|
||||
Format:
|
||||
type(scope): message
|
||||
|
||||
Spec: spec-feature-001
|
||||
Description: Detailed description
|
||||
|
||||
Example:
|
||||
feat(auth): implement JWT authentication
|
||||
|
||||
Spec: spec-feature-001
|
||||
- Add JWT token generation
|
||||
- Implement refresh token rotation
|
||||
- Add authentication middleware
|
||||
|
||||
All acceptance criteria met.
|
||||
Tests: 42 new tests added (100% coverage)
|
||||
```
|
||||
|
||||
### Git History Preservation
|
||||
|
||||
**Using Git MV:**
|
||||
```yaml
|
||||
Benefit:
|
||||
- Preserves file history across moves
|
||||
- Maintains specification evolution
|
||||
- Enables tracking changes over time
|
||||
|
||||
Command:
|
||||
git mv .quaestor/specs/draft/spec-feature-001.md \
|
||||
.quaestor/specs/active/spec-feature-001.md
|
||||
|
||||
History:
|
||||
- See full edit history
|
||||
- Track progress over time
|
||||
- Understand evolution of spec
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Auto-Update Protocol
|
||||
|
||||
### Pre-Implementation
|
||||
|
||||
**When Starting Implementation:**
|
||||
```yaml
|
||||
Actions:
|
||||
1. Find Specification:
|
||||
- Search draft/ and active/
|
||||
- Match by ID or description
|
||||
|
||||
2. Activate Specification:
|
||||
- Move draft → active (if needed)
|
||||
- Update status → in_progress
|
||||
- Add start date
|
||||
|
||||
3. Declare Intent:
|
||||
Output: "🎯 Working on Spec: spec-feature-001 - User Authentication System"
|
||||
Output: "Status: in_progress (moved to active/)"
|
||||
Output: "Phases: 4 total, starting Phase 1"
|
||||
|
||||
4. Present Plan:
|
||||
- Show implementation strategy
|
||||
- Get user approval
|
||||
- Begin implementation
|
||||
```
|
||||
|
||||
### During Implementation
|
||||
|
||||
**Progress Updates:**
|
||||
```yaml
|
||||
After Completing Each Phase:
|
||||
1. Update Specification:
|
||||
- Mark phase tasks complete: [x]
|
||||
- Update phase status: completed
|
||||
- Add implementation notes
|
||||
|
||||
2. Track Progress:
|
||||
Output: "✅ Phase 1 complete (1/4 phases)"
|
||||
Output: " - All tasks finished"
|
||||
Output: " - Implementation notes added"
|
||||
Output: "Starting Phase 2..."
|
||||
|
||||
After Completing Acceptance Criterion:
|
||||
1. Update Specification:
|
||||
- Mark criterion complete: [x]
|
||||
- Add evidence (tests, code references)
|
||||
|
||||
2. Track Progress:
|
||||
Output: "✅ AC1 met: Users can register"
|
||||
Output: " - Tests: test_registration.py (8 passing)"
|
||||
Output: " - Code: auth/registration.py"
|
||||
Output: "Progress: 1/5 criteria met"
|
||||
```
|
||||
|
||||
### Post-Implementation
|
||||
|
||||
**When Implementation Complete:**
|
||||
```yaml
|
||||
Actions:
|
||||
1. Validate Completion:
|
||||
- All phases: ✅ completed
|
||||
- All criteria: [x] met
|
||||
- Quality gates: Passed
|
||||
|
||||
2. Update Specification:
|
||||
- Status → completed
|
||||
- Add completion date
|
||||
- Add final summary
|
||||
|
||||
3. Move to Completed:
|
||||
- From: active/spec-feature-001.md
|
||||
- To: completed/spec-feature-001.md
|
||||
- Method: Git mv
|
||||
|
||||
4. Create Commit:
|
||||
- Reference spec in message
|
||||
- Include summary of changes
|
||||
- Link to relevant files
|
||||
|
||||
5. Declare Complete:
|
||||
Output: "✅ Implementation Complete"
|
||||
Output: "Specification: spec-feature-001"
|
||||
Output: "Status: completed (moved to completed/)"
|
||||
Output: "All 4 phases completed, all 5 criteria met"
|
||||
Output: "Ready for review and PR creation"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Specification Not Found
|
||||
|
||||
```yaml
|
||||
Issue: No matching specification
|
||||
|
||||
Actions:
|
||||
1. Search all folders: draft/, active/, completed/
|
||||
2. Try fuzzy matching on title
|
||||
3. If still no match:
|
||||
Output: "❌ No matching specification found"
|
||||
Output: "Available specifications:"
|
||||
Output: [List active and draft specs]
|
||||
Output: "Would you like to create a new spec?"
|
||||
|
||||
4. If user wants to create:
|
||||
Delegate to spec-writing skill
|
||||
```
|
||||
|
||||
### Active Limit Reached
|
||||
|
||||
```yaml
|
||||
Issue: Already 3 active specs
|
||||
|
||||
Actions:
|
||||
1. Count active specs
|
||||
2. If at limit:
|
||||
Output: "❌ Active limit reached (3 specs)"
|
||||
Output: "Currently active:"
|
||||
Output: [List 3 active specs with progress]
|
||||
Output: "Complete one before starting another"
|
||||
|
||||
3. Suggest:
|
||||
Output: "Would you like to:"
|
||||
Output: "1. Continue one of the active specs"
|
||||
Output: "2. Move one back to draft"
|
||||
```
|
||||
|
||||
### Invalid Specification
|
||||
|
||||
```yaml
|
||||
Issue: Spec missing required fields
|
||||
|
||||
Actions:
|
||||
1. Validate specification structure
|
||||
2. Check required fields: id, title, phases, criteria
|
||||
3. If invalid:
|
||||
Output: "❌ Specification incomplete"
|
||||
Output: "Missing: [list missing fields]"
|
||||
Output: "Please update specification before starting"
|
||||
|
||||
4. Suggest fix:
|
||||
Output: "Use spec-writing skill to update specification"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*Complete specification integration for tracking implementation progress with Quaestor*
|
||||
Reference in New Issue
Block a user