Track Management
Guide for creating, managing, and completing Conductor tracks - the logical work units that organize features, bugs, and refactors through specification, planning, and implementation phases.
When to Use This Skill
- Creating new feature, bug, or refactor tracks
- Writing or reviewing spec.md files
- Creating or updating plan.md files
- Managing track lifecycle from creation to completion
- Understanding track status markers and conventions
- Working with the tracks.md registry
- Interpreting or updating track metadata
Track Concept
A track is a logical work unit that encapsulates a complete piece of work. Each track has:
- A unique identifier
- A specification defining requirements
- A phased plan breaking work into tasks
- Metadata tracking status and progress
Tracks provide semantic organization for work, enabling:
- Clear scope boundaries
- Progress tracking
- Git-aware operations (revert by track)
- Team coordination
Track Types
feature
New functionality or capabilities. Use for:
- New user-facing features
- New API endpoints
- New integrations
- Significant enhancements
bug
Defect fixes. Use for:
- Incorrect behavior
- Error conditions
- Performance regressions
- Security vulnerabilities
chore
Maintenance and housekeeping. Use for:
- Dependency updates
- Configuration changes
- Documentation updates
- Cleanup tasks
refactor
Code improvement without behavior change. Use for:
- Code restructuring
- Pattern adoption
- Technical debt reduction
- Performance optimization (same behavior, better performance)
Track ID Format
Track IDs follow the pattern: {shortname}_{YYYYMMDD}
- shortname: 2-4 word kebab-case description (e.g.,
user-auth, api-rate-limit)
- YYYYMMDD: Creation date in ISO format
Examples:
user-auth_20250115fix-login-error_20250115upgrade-deps_20250115refactor-api-client_20250115
Track Lifecycle
1. Creation (newTrack)
Define Requirements
- Gather requirements through interactive Q&A
- Identify acceptance criteria
- Determine scope boundaries
- Identify dependencies
Generate Specification
- Create
spec.md with structured requirements
- Document functional and non-functional requirements
- Define acceptance criteria
- List dependencies and constraints
Generate Plan
- Create
plan.md with phased task breakdown
- Organize tasks into logical phases
- Add verification tasks after phases
- Estimate effort and complexity
Register Track
- Add entry to
tracks.md registry
- Create track directory structure
- Generate
metadata.json
- Create track
index.md
2. Implementation
Execute Tasks
- Select next pending task from plan
- Mark task as in-progress
- Implement following workflow (TDD)
- Mark task complete with commit SHA
Update Status
- Update task markers in plan.md
- Record commit SHAs for traceability
- Update phase progress
- Update track status in tracks.md
Verify Progress
- Complete verification tasks
- Wait for checkpoint approval
- Record checkpoint commits
3. Completion
Sync Documentation
- Update product.md if features added
- Update tech-stack.md if dependencies changed
- Verify all acceptance criteria met
Archive or Delete
- Mark track as completed in tracks.md
- Record completion date
- Archive or retain track directory
Specification (spec.md) Structure
# {Track Title}
## Overview
Brief description of what this track accomplishes and why.
## Functional Requirements
### FR-1: {Requirement Name}
Description of the functional requirement.
- Acceptance: How to verify this requirement is met
### FR-2: {Requirement Name}
...
## Non-Functional Requirements
### NFR-1: {Requirement Name}
Description of the non-functional requirement (performance, security, etc.)
- Target: Specific measurable target
- Verification: How to test
## Acceptance Criteria
- [ ] Criterion 1: Specific, testable condition
- [ ] Criterion 2: Specific, testable condition
- [ ] Criterion 3: Specific, testable condition
## Scope
### In Scope
- Explicitly included items
- Features to implement
- Components to modify
### Out of Scope
- Explicitly excluded items
- Future considerations
- Related but separate work
## Dependencies
### Internal
- Other tracks or components this depends on
- Required context artifacts
### External
- Third-party services or APIs
- External dependencies
## Risks and Mitigations
| ---------------- | --------------- | ------------------- |
| Risk description | High/Medium/Low | Mitigation strategy |
## Open Questions
- [ ] Question that needs resolution
- [x] Resolved question - Answer
Plan (plan.md) Structure
# Implementation Plan: {Track Title}
Track ID: `{track-id}`
Created: YYYY-MM-DD
Status: pending | in-progress | completed
## Overview
Brief description of implementation approach.
## Phase 1: {Phase Name}
### Tasks
- [ ] **Task 1.1**: Task description
- Sub-task or detail
- Sub-task or detail
- [ ] **Task 1.2**: Task description
- [ ] **Task 1.3**: Task description
### Verification
- [ ] **Verify 1.1**: Verification step for phase
## Phase 2: {Phase Name}
### Tasks
- [ ] **Task 2.1**: Task description
- [ ] **Task 2.2**: Task description
### Verification
- [ ] **Verify 2.1**: Verification step for phase
## Phase 3: Finalization
### Tasks
- [ ] **Task 3.1**: Update documentation
- [ ] **Task 3.2**: Final integration test
### Verification
- [ ] **Verify 3.1**: All acceptance criteria met
## Checkpoints
| ------- | -------------- | ---- | ------- |
| Phase 1 | | | pending |
| Phase 2 | | | pending |
| Phase 3 | | | pending |
Status Marker Conventions
Use consistent markers in plan.md:
| Marker |
Meaning |
Usage |
[ ] |
Pending |
Task not started |
[~] |
In Progress |
Currently being worked |
[x] |
Complete |
Task finished (include SHA) |
[-] |
Skipped |
Intentionally not done |
[!] |
Blocked |
Waiting on dependency |
Example:
- [x] **Task 1.1**: Set up database schema `abc1234`
- [~] **Task 1.2**: Implement user model
- [ ] **Task 1.3**: Add validation logic
- [!] **Task 1.4**: Integrate auth service (blocked: waiting for API key)
- [-] **Task 1.5**: Legacy migration (skipped: not needed)
Track Registry (tracks.md) Format
# Track Registry
## Active Tracks
| ------------------------------------------------ | ------- | ----------- | ----- | ---------- | ---------- |
| [user-auth_20250115](tracks/user-auth_202
