Track Management

What Is Track Management?

Track Management is the systematic process of creating, maintaining, and completing "tracks" in the Conductor system. A track is a logical work unit that encapsulates a feature, bug, or refactor task, and is managed through discrete phases such as specification, planning, and implementation. Each track is uniquely identified and documented, with clear metadata and lifecycle stages. The Track Management skill is essential for anyone who needs to create, update, or track the lifecycle of work units in projects using the Conductor workflow.

Tracks are more than just tasks or issues; they are structured entities that promote semantic organization of work, enforce scope boundaries, and enable effective progress tracking. This skill enables practitioners to efficiently organize, coordinate, and deliver work by leveraging standardized conventions and files such as spec.md, plan.md, and the tracks.md registry.

Why Use Track Management?

Track Management is crucial in complex projects where multiple features, bugs, and refactors are handled concurrently. Its benefits include:

• Clarity and Scope Control: Tracks enforce well-defined scopes, reducing ambiguity and preventing scope creep.
• Lifecycle Visibility: The status and progress of each work unit are tracked through metadata and status markers, making it easy to see what is in progress, under review, or completed.
• Documentation: By mandating spec.md and plan.md files, every track maintains rich documentation for requirements and execution strategy.
• Team Coordination: Tracks act as coordination points for teams, ensuring that everyone is aligned on what needs to be done and who is responsible.
• Git Integration: Tracks are designed for Git-aware operations, allowing actions like reverting changes by track, which simplifies change management and auditing.

How to Use Track Management

1. Creating a New

Track

To initiate a new track, determine whether it is a feature, bug, or refactor. Each track should have:

• A unique identifier (e.g., track-1234)
• A directory containing at minimum:
  • spec.md: The specification of requirements
  • plan.md: The phased breakdown of tasks and deliverables
  • Metadata indicating status and progress

Example: Creating a new feature track

mkdir tracks/track-1234-feature-awesome-login
cd tracks/track-1234-feature-awesome-login
touch spec.md plan.md

Populate spec.md with requirements and objectives:

## spec.md

## Objective
Implement a secure, user-friendly login system.

## Requirements
- Support for email/password authentication
- Password reset workflow
- Error handling for failed logins

Define the phased plan in plan.md:

## plan.md

## Phase 1:

UI Implementation
- Create login form
- Add input validation

## Phase 2:

Backend Integration
- Connect form to authentication API
- Handle authentication tokens

## Phase 3:

Error Handling & Testing
- Implement error messages
- Write unit and integration tests

2. Managing Track

Lifecycle

As work progresses, update the track's status and metadata within tracks.md or the track's own metadata file.

Example: Updating track status

## tracks/track-1234-feature-awesome-login/track.yaml

id: track-1234
type: feature
status: in-progress
assignee: alice
created: 2024-06-01
updated: 2024-06-03

Statuses typically include: proposed, in-progress, under-review, completed, and archived.

3. Registry and

Conventions

The tracks.md file acts as a registry and index of all tracks in the project. Each entry should reference the track's identifier, title, type, status, and location.

Example: tracks.md entry

- id: track-1234
  title: Implement Awesome Login
  type: feature
  status: in-progress
  path: tracks/track-1234-feature-awesome-login

4. Reviewing and Completing

Tracks

Upon completion of all tasks in plan.md, update the track's status to completed and ensure all documentation is up to date. Reviewers may verify the implementation against spec.md and plan.md before closing the track.

When to Use Track Management

• When initiating new work that requires specification and planning, such as features, bugfixes, or refactors
• While writing or reviewing spec.md files to establish requirements
• During creation or updates of plan.md files to define execution strategy
• Throughout the track lifecycle, from creation and assignment to completion and archival
• When interpreting or updating track metadata for project status reporting
• While referencing or updating the tracks.md registry for project-wide work visibility

Important Notes

• Always assign a unique identifier to each track for traceability.
• Ensure that both spec.md and plan.md are present and maintained throughout the lifecycle.
• Use clear and consistent status markers to facilitate team communication and progress tracking.
• Leverage the tracks.md registry to maintain a project-wide overview of all active and completed tracks.
• Metadata should be kept current to accurately reflect the state and history of each track.
• Tracks should encapsulate logically complete work units to maximize clarity and minimize dependencies.
• Adhere strictly to conventions for naming, documentation, and status updates to ensure smooth team operations and future maintenance.