v1.0.0 to v1.0.0

2 added, 559 removed. Audit A to A.

---

name: track-management

description: Use this skill when creating, managing, or working with Conductor tracks - the logical work units for features, bugs, and refactors. Applies to spec.md, plan.md, and track lifecycle operations.

version: 1.0.0

---

# 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_20250115`

- - `fix-login-error_20250115`

- - `upgrade-deps_20250115`

- - `refactor-api-client_20250115`

- ## Track Lifecycle

- ### 1. Creation (newTrack)

- **Define Requirements**

- 1. Gather requirements through interactive Q&A

- 2. Identify acceptance criteria

- 3. Determine scope boundaries

- 4. Identify dependencies

- **Generate Specification**

- 1. Create `spec.md` with structured requirements

- 2. Document functional and non-functional requirements

- 3. Define acceptance criteria

- 4. List dependencies and constraints

- **Generate Plan**

- 1. Create `plan.md` with phased task breakdown

- 2. Organize tasks into logical phases

- 3. Add verification tasks after phases

- 4. Estimate effort and complexity

- **Register Track**

- 1. Add entry to `tracks.md` registry

- 2. Create track directory structure

- 3. Generate `metadata.json`

- 4. Create track `index.md`

- ### 2. Implementation

- **Execute Tasks**

- 1. Select next pending task from plan

- 2. Mark task as in-progress

- 3. Implement following workflow (TDD)

- 4. Mark task complete with commit SHA

- **Update Status**

- 1. Update task markers in plan.md

- 2. Record commit SHAs for traceability

- 3. Update phase progress

- 4. Update track status in tracks.md

- **Verify Progress**

- 1. Complete verification tasks

- 2. Wait for checkpoint approval

- 3. Record checkpoint commits

- ### 3. Completion

- **Sync Documentation**

- 1. Update product.md if features added

- 2. Update tech-stack.md if dependencies changed

- 3. Verify all acceptance criteria met

- **Archive or Delete**

- 1. Mark track as completed in tracks.md

- 2. Record completion date

- 3. Archive or retain track directory

- ## Specification (spec.md) Structure

- ```markdown

- # {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 | Impact | Mitigation |

- | ---------------- | --------------- | ------------------- |

- | Risk description | High/Medium/Low | Mitigation strategy |

- ## Open Questions

- - [ ] Question that needs resolution

- - [x] Resolved question - Answer

- ```

- ## Plan (plan.md) Structure

- ```markdown

- # 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

- - [ ] **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

- | ------- | -------------- | ---- | ------- |

- ```

- ## 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:

- ```markdown

- - [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

- ```markdown

- # Track Registry

- ## Active Tracks

- | ------------------------------------------------ | ------- | ----------- | ----- | ---------- | ---------- |

- | [user-auth_20250115](tracks/user-auth_20250115/) | feature | in-progress | 2/3 | 2025-01-15 | @developer |

- | [fix-login_20250114](tracks/fix-login_20250114/) | bug | pending | 0/2 | 2025-01-14 | - |

- ## Completed Tracks

- | ---------------------------------------------- | ----- | ---------- | -------- |

- ## Archived Tracks

- | Track ID | Reason | Archived |

- | ---------------------------------------------------- | ---------- | ---------- |

- | [old-feature_20241201](tracks/old-feature_20241201/) | Superseded | 2025-01-05 |

- ```

- ## Metadata (metadata.json) Fields

- ```json

- {

- "id": "user-auth_20250115",

- "title": "User Authentication System",

- "type": "feature",

- "status": "in-progress",

- "priority": "high",

- "created": "2025-01-15T10:30:00Z",

- "updated": "2025-01-15T14:45:00Z",

- "started": "2025-01-15T11:00:00Z",

- "completed": null,

- "assignee": "@developer",

- "phases": {

- "total": 3,

- "current": 2,

- "completed": 1

- },

- "tasks": {

- "total": 12,

- "completed": 5,

- "in_progress": 1,

- "pending": 6

- },

- "checkpoints": [

- {

- "phase": 1,

- "sha": "abc1234",

- "date": "2025-01-15T13:00:00Z"

- }

- ],

- "dependencies": [],

- "tags": ["auth", "security"]

- }

- ```

- ## Track Operations

- ### Creating a Track

- 1. Run `/conductor:new-track`

- 2. Answer interactive questions

- 3. Review generated spec.md

- 4. Review generated plan.md

- 5. Confirm track creation

- ### Starting Implementation

- 1. Read spec.md and plan.md

- 2. Verify context artifacts are current

- 3. Mark first task as `[~]`

- 4. Begin TDD workflow

- ### Completing a Phase

- 1. Ensure all phase tasks are `[x]`

- 2. Complete verification tasks

- 3. Wait for checkpoint approval

- 4. Record checkpoint SHA

- 5. Proceed to next phase

- ### Completing a Track

- 1. Verify all phases complete

- 2. Verify all acceptance criteria met

- 3. Update product.md if needed

- 4. Mark track completed in tracks.md

- 5. Update metadata.json

- ### Reverting a Track

- 1. Run `/conductor:revert`

- 2. Select track to revert

- 3. Choose granularity (track/phase/task)

- 4. Confirm revert operation

- 5. Update status markers

- ## Handling Track Dependencies

- ### Identifying Dependencies

- During track creation, identify:

- - **Hard dependencies**: Must complete before this track can start

- - **Soft dependencies**: Can proceed in parallel but may affect integration

- - **External dependencies**: Third-party services, APIs, or team decisions

- ### Documenting Dependencies

- In spec.md, list dependencies with:

- - Dependency type (hard/soft/external)

- - Current status (available/pending/blocked)

- - Resolution path (what needs to happen)

- ### Managing Blocked Tracks

- When a track is blocked:

- 1. Mark blocked tasks with `[!]` and reason

- 2. Update tracks.md status

- 3. Document blocker in metadata.json

- 4. Consider creating dependency track if needed

- ## Track Sizing Guidelines

- ### Right-Sized Tracks

- Aim for tracks that:

- - Complete in 1-5 days of work

- - Have 2-4 phases

- - Contain 8-20 tasks total

- - Deliver a coherent, testable unit

- ### Too Large

- Signs a track is too large:

- - More than 5 phases

- - More than 25 tasks

- - Multiple unrelated features

- - Estimated duration > 1 week

- Solution: Split into multiple tracks with clear boundaries.

- ### Too Small

- Signs a track is too small:

- - Single phase with 1-2 tasks

- - No meaningful verification needed

- - Could be a sub-task of another track

- - Less than a few hours of work

- Solution: Combine with related work or handle as part of existing track.

- ## Specification Quality Checklist

- Before finalizing spec.md, verify:

- ### Requirements Quality

- - [ ] Each requirement has clear acceptance criteria

- - [ ] Requirements are testable

- - [ ] Requirements are independent (can verify separately)

- - [ ] No ambiguous language ("should be fast" → "response < 200ms")

- ### Scope Clarity

- - [ ] In-scope items are specific

- - [ ] Out-of-scope items prevent scope creep

- - [ ] Boundaries are clear to implementer

- ### Dependencies Identified

- - [ ] All internal dependencies listed

- - [ ] External dependencies have owners/contacts

- - [ ] Dependency status is current

- ### Risks Addressed

- - [ ] Major risks identified

- - [ ] Impact assessment realistic

- - [ ] Mitigations are actionable

- ## Plan Quality Checklist

- Before starting implementation, verify plan.md:

- ### Task Quality

- - [ ] Tasks are atomic (one logical action)

- - [ ] Tasks are independently verifiable

- - [ ] Task descriptions are clear

- - [ ] Sub-tasks provide helpful detail

- ### Phase Organization

- - [ ] Phases group related tasks

- - [ ] Each phase delivers something testable

- - [ ] Verification tasks after each phase

- - [ ] Phases build on each other logically

- ### Completeness

- - [ ] All spec requirements have corresponding tasks

- - [ ] Documentation tasks included

- - [ ] Testing tasks included

- - [ ] Integration tasks included

- ## Common Track Patterns

- ### Feature Track Pattern

- ```

- Phase 1: Foundation

- - Data models

- - Database migrations

- - Basic API structure

- Phase 2: Core Logic

- - Business logic implementation

- - Input validation

- - Error handling

- Phase 3: Integration

- - UI integration

- - API documentation

- - End-to-end tests

- ```

- ### Bug Fix Track Pattern

- ```

- Phase 1: Reproduction

- - Write failing test capturing bug

- - Document reproduction steps

- Phase 2: Fix

- - Implement fix

- - Verify test passes

- - Check for regressions

- Phase 3: Verification

- - Manual verification

- - Update documentation if needed

- ```

- ### Refactor Track Pattern

- ```

- Phase 1: Preparation

- - Add characterization tests

- - Document current behavior

- Phase 2: Refactoring

- - Apply changes incrementally

- - Maintain green tests throughout

+ ## Detailed patterns and worked examples

- Phase 3: Cleanup

- - Remove dead code

- - Update documentation

- ```

+ Detailed pattern documentation lives in `references/details.md`. Read that file when the navigation tier above is insufficient.

## Best Practices

1. **One track, one concern**: Keep tracks focused on a single logical change

2. **Small phases**: Break work into phases of 3-5 tasks maximum

3. **Verification after phases**: Always include verification tasks

4. **Update markers immediately**: Mark task status as you work

5. **Record SHAs**: Always note commit SHAs for completed tasks

6. **Review specs before planning**: Ensure spec is complete before creating plan

7. **Link dependencies**: Explicitly note track dependencies

8. **Archive, don't delete**: Preserve completed tracks for reference

9. **Size appropriately**: Keep tracks between 1-5 days of work

10. **Clear acceptance criteria**: Every requirement must be testable