12 KiB
12 KiB
Specification Integration & Tracking
This file describes how to integrate with Quaestor's specification system for tracking implementation progress.
Specification Folder Structure
.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
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:
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:
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:
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:
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:
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:
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:
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:
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:
---
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
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:
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:
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:
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:
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:
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
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
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
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