540 lines
12 KiB
Markdown
540 lines
12 KiB
Markdown
# 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*
|