track-management

track-management

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

• 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             | Impact          | Mitigation          |
| ---------------- | --------------- | ------------------- |
| 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   | Checkpoint SHA | Date | Status  |
| ------- | -------------- | ---- | ------- |
| 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

| Track ID                                         | Type    | Status      | Phase | Started    | Assignee   |
| ------------------------------------------------ | ------- | ----------- | ----- | ---------- | ---------- |
| [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

| Track ID                                       | Type  | Completed  | Duration |
| ---------------------------------------------- | ----- | ---------- | -------- |
| [setup-ci_20250110](tracks/setup-ci_20250110/) | chore | 2025-01-12 | 2 days   |

## Archived Tracks

| Track ID                                             | Reason     | Archived   |
| ---------------------------------------------------- | ---------- | ---------- |
| [old-feature_20241201](tracks/old-feature_20241201/) | Superseded | 2025-01-05 |

Metadata (metadata.json) Fields

{
  "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

• Run /conductor:new-track

• Answer interactive questions

• Review generated spec.md

• Review generated plan.md

• Confirm track creation

Starting Implementation

• Read spec.md and plan.md

• Verify context artifacts are current

• Mark first task as [~]

• Begin TDD workflow

Completing a Phase

• Ensure all phase tasks are [x]

• Complete verification tasks

• Wait for checkpoint approval

• Record checkpoint SHA

• Proceed to next phase

Completing a Track

• Verify all phases complete

• Verify all acceptance criteria met

• Update product.md if needed

• Mark track completed in tracks.md

• Update metadata.json

Reverting a Track

• Run /conductor:revert

• Select track to revert

• Choose granularity (track/phase/task)

• Confirm revert operation

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

• Mark blocked tasks with [!] and reason

• Update tracks.md status

• Document blocker in metadata.json

• 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

Phase 3: Cleanup
- Remove dead code
- Update documentation

Best Practices

• One track, one concern: Keep tracks focused on a single logical change

• Small phases: Break work into phases of 3-5 tasks maximum

• Verification after phases: Always include verification tasks

• Update markers immediately: Mark task status as you work

• Record SHAs: Always note commit SHAs for completed tasks

• Review specs before planning: Ensure spec is complete before creating plan

• Link dependencies: Explicitly note track dependencies

• Archive, don't delete: Preserve completed tracks for reference

• Size appropriately: Keep tracks between 1-5 days of work

• Clear acceptance criteria: Every requirement must be testable

Weekly Installs2.9KRepositorywshobson/agentsGitHub Stars31.5KFirst SeenJan 20, 2026Security AuditsGen Agent Trust HubPassSocketPassSnykPassInstalled onclaude-code2.3Kgemini-cli2.1Kopencode2.1Kcursor2.1Kcodex2.0Kgithub-copilot1.7K