track-management

Track Management

Tracks are coordination scaffolding for agentic team development. Each track owns a durable outcome, not a tiny implementation step. The mode determines workflow.

When to Use This Skill

• Creating new tracks (any mode)
• Updating track spec / plan / metadata
• Managing track lifecycle from scoping to closure
• Choosing between modes when work could fit multiple
• Writing handoff artifacts between sessions/agents

Track Shape

Every substantive track defines:

• Outcome — what durable result this track owns
• Scope — what's included
• Non-goals — what should NOT be pulled in
• Dependencies — what must exist or be decided first
• Blocks — what this track unlocks
• Handoff artifacts — files / reports / PRs / scripts / datasets / decisions another agent will consume
• Verification — what proves the work is trustworthy (mode-appropriate)
• Risks — known failure modes, unresolved questions, operational hazards

For important / risky / multi-week work, also include an Outcome Contract:

• Success condition
• Non-negotiable invariants
• Unacceptable failure modes
• Quality bar and tradeoffs
• How a human/operator will know it worked

For small focused work (1-3 days, single concern, low risk), the basic Track Shape is enough — skip the Outcome Contract.

Track Modes

Mode	Use for	Verification weight
Implementation	Code, schema, API, UI, behavior, infrastructure, automation	Focused tests + typecheck + lint; TDD when practical for behavior changes
Audit / Research	Investigation, data review, source-truth comparison, system mapping	Evidence (sources, queries, files, confidence levels); no tests
Decision / Planning	Architecture choices, sequencing, scope/ownership, tradeoffs	Decision artifact with options + recommendation + reasoning
Execution / Batch Ops	Migrations, data writes, imports, backfills, bulk edits	Dry run + sample inspection + final counts + anomaly report; explicit confirmation for irreversible writes
Publishing / PR	Preparing/pushing/opening work for review	Verification appropriate to the change being shipped; intentional file scoping

Pick the mode at track creation. The mode is captured in metadata.json (mode: implementation | audit | decision | batch | publishing) and surfaces in the dashboard.

Track ID Format

{shortname}_{YYYYMMDD}

• shortname: 2-4 word kebab-case derived from outcome (e.g., user-auth, api-rate-limit)
• YYYYMMDD: creation date in ISO format

If collision: append _2, _3, etc.

Track Status Values

Status	Meaning
scoping	Spec being authored; not ready to implement
ready	Spec + plan complete; no tasks started
in_progress	Tasks actively being worked
blocked	Track is paused awaiting resolution of blocker
shipped	Final PR merged; outcome delivered
superseded	Replaced by another track or DEC; not delivered
absorbed	Merged into a different track's scope; not delivered as named

Closure is a commit, not a ceremony. Flip status and update shipped_at (or superseded_by / absorbed_into) when the terminal state is real.

Plan Markers

Use consistently in plan.md:

Marker	Meaning
[ ]	Pending
[~]	In progress
[x]	Complete (include short SHA or PR ref for Implementation tracks)
[!]	Blocked (with reason)
[-]	Skipped (intentionally not done)

Example:

- [x] Task 1.1: Set up database schema  abc1234
- [~] Task 1.2: Implement user model
- [!] Task 1.3: Integrate auth service  (blocked: waiting for API key)
- [ ] Task 1.4: Add validation logic
- [-] Task 1.5: Legacy migration  (skipped: not needed)

If the plan no longer matches reality, revise the plan. Don't mechanically follow stale tasks.

Track Files

conductor/tracks/{trackId}/
├── spec.md              # Track Shape (outcome, scope, non-goals, etc.) + optional Outcome Contract
├── plan.md              # Phased task list with markers
├── metadata.json        # Per-track state (status, mode, current_task, commits, blockers)
├── RESUME-*.md          # Cold-start handoff for paused/multi-day tracks (optional)
└── decisions/           # Track-scoped decision memos (optional, for tracks producing multiple decisions)

Templates for each file live in templates/ next to this skill.

Lifecycle

Creation

/conductor:new-track [mode] [shortname] walks through:

1. Pick the mode
2. Capture Track Shape fields
3. Optional Outcome Contract for important work
4. Generate trackId, files, register in dashboard

Implementation

/conductor:implement <trackId> walks through:

1. Mode detection (REQUIRED before execution)
2. Task selection
3. Mode-appropriate workflow:
   • Implementation: TDD when practical → focused verification → commit → mark complete
   • Audit: read-only investigation → evidence capture → produce artifact
   • Decision: define decision → list options → recommend → author memo
   • Batch: dry run → sample inspection → confirm → apply → record
   • Publishing: scoped diff → verify → commit → push → PR
4. Worktree hygiene throughout
5. Handoff doc if pausing

Closure

When the final PR (or final artifact for non-Implementation tracks) lands:

1. Confirm artifact landed (PR merged / decision ratified / data applied)
2. Update metadata.json: status, shipped_at (or terminal state field), final SHA in commits[]
3. Regenerate dashboard if auto-generator script exists
4. Commit closure: conductor({trackId}): close — status=shipped

Dependencies

Identify at track creation:

• Hard dependencies: must complete before this track can start. Surface in Dependencies field.
• Soft dependencies: can proceed in parallel; may affect integration. Surface in Dependencies field with note.
• External dependencies: third-party services / APIs / team decisions. Surface in Dependencies with owner / contact.

When a track is blocked: mark blocked tasks [!] with reason; update metadata.status to blocked; document blocker in metadata.blockers[].

Sizing Guidelines

Right-sized tracks complete in 1-5 days, deliver a coherent + testable unit, have 2-4 phases (or fewer for non-Implementation).

Too large signs: >5 phases, >25 tasks, multiple unrelated outcomes, estimated >1 week. Solution: split.

Too small signs: single phase with 1-2 tasks, no meaningful verification needed, less than a few hours of work. Solution: skip the track and just do the work, or fold into an existing track.

For Decision / Audit modes: sizing is about artifact scope, not task count. A 1-page decision artifact may be the entire track.

Common Patterns

Implementation track

Phase 1: Foundation        — data models / migrations / API skeleton
Phase 2: Core logic        — business logic / validation / error handling
Phase 3: Integration       — UI / API docs / E2E

Bug fix track

Phase 1: Reproduction      — failing test capturing bug
Phase 2: Fix               — implementation + test passes + regression check
Phase 3: Verification      — manual verify + docs update if needed

Audit track

Phase 1: Source survey     — list primary sources, queries, files
Phase 2: Evidence capture  — confirmed facts vs assumptions
Phase 3: Findings + recs   — recommendation artifact + follow-up actions

Decision track

Phase 1: Problem framing   — what decision, what's at stake
Phase 2: Options + tradeoffs
Phase 3: Recommendation + memo authoring
Phase 4: Promotion         — to canonical doc / DEC entry / cross-link

Batch ops track

Phase 1: Cohort definition + dry run
Phase 2: Sample inspection + stop rules
Phase 3: Apply (with explicit confirmation)
Phase 4: Final counts + anomaly report

Best Practices

1. Pick the mode first. Workflow depends on it.
2. One track, one outcome. If scope sprawls, split.
3. Update markers immediately. Don't batch a week of plan updates into one cleanup commit.
4. Record SHAs (Implementation tracks). Helps cold-start for the next agent.
5. Handoff docs for paused work. A RESUME-*.md saves the next session 30 minutes.
6. Right-size for the work, not the format. A 1-day chore doesn't need a 5-phase plan.
7. Outcome Contract only for important work. Don't ceremony-tax small tracks.
8. Surface blockers explicitly. [!] markers + metadata.blockers[] + dashboard visibility.
9. Closure is a commit. Don't let shipped tracks linger as in_progress on the dashboard.
10. Trust the mode. If the work doesn't fit any mode, the work is probably the wrong shape.

Reference

• templates/track-spec.md — spec.md template (mode-aware)
• templates/track-plan.md — plan.md template
• templates/track-metadata.json — metadata.json schema
• templates/workflow.md — project-level workflow doc template (mode-aware framework)
• commands/new-track.md — creation command
• commands/implement.md — execution command (mode-detecting)
• commands/status.md — dashboard summary (groups by mode + blockers)
• commands/revert.md — git-aware undo (always requires explicit confirmation)