track-management

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Track Management

Track管理

Guide for creating, managing, and completing Conductor tracks - the logical work units that organize features, bugs, and refactors through specification, planning, and implementation phases.

本指南介绍如何创建、管理和完成Conductor track——这是一种逻辑工作单元，通过需求定义、规划和实施阶段来组织功能开发、Bug修复和代码重构工作。

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

创建新的功能、Bug修复或代码重构track
编写或审核spec.md文件
创建或更新plan.md文件
管理从创建到完成的track生命周期
了解track状态标记和约定
操作tracks.md注册表
解读或更新track元数据

Track Concept

Track概念

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是一个封装了完整工作内容的逻辑工作单元。每个track包含：

唯一标识符
定义需求的规格文档
将工作拆分为任务的阶段性计划
跟踪状态和进度的元数据

Track为工作提供语义化组织，支持：

清晰的范围边界
进度跟踪
感知Git的操作（按track回滚）
团队协作

Track Types

Track类型

feature

New functionality or capabilities. Use for:

New user-facing features
New API endpoints
New integrations
Significant enhancements

新功能或能力。适用于：

面向用户的新功能
新API端点
新集成功能
重大功能增强

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 ID格式

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 ID遵循以下格式：

{shortname}_{YYYYMMDD}

shortname：2-4个单词的短横线分隔描述（例如：
```
user-auth
```
,
```
api-rate-limit
```
）
YYYYMMDD：ISO格式的创建日期

示例：

```
user-auth_20250115
```
```
fix-login-error_20250115
```
```
upgrade-deps_20250115
```
```
refactor-api-client_20250115
```

Track Lifecycle

Track生命周期

1. Creation (newTrack)

1. 创建（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
```

定义需求

通过交互式问答收集需求
确定验收标准
明确范围边界
识别依赖项

生成需求规格

创建包含结构化需求的
```
spec.md
```
记录功能性和非功能性需求
定义验收标准
列出依赖项和约束条件

生成计划

创建包含阶段性任务拆分的
```
plan.md
```
将任务组织为逻辑阶段
在每个阶段后添加验证任务
评估工作量和复杂度

注册Track

在
```
tracks.md
```
注册表中添加条目
创建track目录结构
生成
```
metadata.json
```
创建track的
```
index.md
```

2. Implementation

2. 实施

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

执行任务

从计划中选择下一个待处理任务
将任务标记为进行中
遵循TDD工作流实施
标记任务完成并记录提交SHA

更新状态

更新plan.md中的任务标记
记录提交SHA以实现可追溯性
更新阶段进度
更新tracks.md中的track状态

验证进度

完成验证任务
等待检查点审批
记录检查点提交记录

3. Completion

3. 完成

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

同步文档

若添加了新功能，更新product.md
若依赖项有变更，更新tech-stack.md
验证所有验收标准均已满足

归档或删除

在tracks.md中将track标记为已完成
记录完成日期
归档或保留track目录

Specification (spec.md) Structure

需求规格（spec.md）结构

markdown

undefined

markdown

undefined

{Track Title}

{Track标题}

Overview

概述

Brief description of what this track accomplishes and why.

简述本track要完成的工作及其意义。

Functional Requirements

功能性需求

FR-1: {Requirement Name}

FR-1: {需求名称}

Description of the functional requirement.

Acceptance: How to verify this requirement is met

功能性需求描述。

验收标准：如何验证该需求已满足

FR-2: {Requirement Name}

FR-2: {需求名称}

...

Non-Functional Requirements

非功能性需求

NFR-1: {Requirement Name}

NFR-1: {需求名称}

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

标准1：具体、可测试的条件
标准2：具体、可测试的条件
标准3：具体、可测试的条件

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

本track依赖的其他track或组件
所需的上下文工件

External

外部依赖

Third-party services or APIs
External dependencies

第三方服务或API
外部依赖项

Risks and Mitigations

风险与缓解措施

Risk	Impact	Mitigation
Risk description	High/Medium/Low	Mitigation strategy

风险	影响程度	缓解措施
风险描述	高/中/低	缓解策略

Open Questions

待解决问题

Question that needs resolution
Resolved question - Answer

undefined

需要解决的问题
已解决问题 - 答案

undefined

Plan (plan.md) Structure

计划（plan.md）结构

markdown

undefined

markdown

undefined

Implementation Plan: {Track Title}

实施计划: {Track标题}

Track ID:

{track-id}

Created: YYYY-MM-DD Status: pending | in-progress | completed

Track ID:

{track-id}

创建日期: YYYY-MM-DD 状态: pending | in-progress | completed

Overview

概述

Brief description of implementation approach.

简述实施方法。

Phase 1: {Phase Name}

阶段1: {阶段名称}

Tasks

任务

Task 1.1: Task description
- Sub-task or detail
- Sub-task or detail
Task 1.2: Task description
Task 1.3: Task description

任务1.1: 任务描述
- 子任务或细节
- 子任务或细节
任务1.2: 任务描述
任务1.3: 任务描述

Verification

验证

Verify 1.1: Verification step for phase

验证1.1: 阶段验证步骤

Phase 2: {Phase Name}

阶段2: {阶段名称}

Tasks

任务

Task 2.1: Task description
Task 2.2: Task description

任务2.1: 任务描述
任务2.2: 任务描述

Verification

验证

Verify 2.1: Verification step for phase

验证2.1: 阶段验证步骤

Phase 3: Finalization

阶段3: 收尾

Tasks

任务

Task 3.1: Update documentation
Task 3.2: Final integration test

任务3.1: 更新文档
任务3.2: 最终集成测试

Verification

验证

Verify 3.1: All acceptance criteria met

验证3.1: 所有验收标准均已满足

Checkpoints

检查点

Phase	Checkpoint SHA	Date	Status
Phase 1			pending
Phase 2			pending
Phase 3			pending

undefined

阶段	检查点SHA	日期	状态
阶段1			pending
阶段2			pending
阶段3			pending

undefined

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)

在plan.md中使用统一的标记：

标记	含义	使用场景
`[ ]`	待处理	任务未开始
`[~]`	进行中	当前正在处理
`[x]`	已完成	任务已完成（需包含SHA）
`[-]`	已跳过	有意不执行的任务
`[!]`	已阻塞	等待依赖项完成

示例：

markdown

- [x] **任务1.1**: 设置数据库架构 `abc1234`
- [~] **任务1.2**: 实现用户模型
- [ ] **任务1.3**: 添加验证逻辑
- [!] **任务1.4**: 集成认证服务（阻塞原因：等待API密钥）
- [-] **任务1.5**: 遗留系统迁移（已跳过：无需执行）

Track Registry (tracks.md) Format

Track注册表（tracks.md）格式

markdown

undefined

markdown

undefined

Track Registry

Track注册表

Active Tracks

活跃Track

Track ID	Type	Status	Phase	Started	Assignee
user-auth_20250115	feature	in-progress	2/3	2025-01-15	@developer
fix-login_20250114	bug	pending	0/2	2025-01-14	-

Track ID	类型	状态	阶段	开始日期	负责人
user-auth_20250115	feature	in-progress	2/3	2025-01-15	@developer
fix-login_20250114	bug	pending	0/2	2025-01-14	-

Completed Tracks

已完成Track

Track ID	Type	Completed	Duration
setup-ci_20250110	chore	2025-01-12	2 days

Track ID	类型	完成日期	耗时
setup-ci_20250110	chore	2025-01-12	2天

Archived Tracks

已归档Track

Track ID	Reason	Archived
old-feature_20241201	Superseded	2025-01-05

undefined

Track ID	归档原因	归档日期
old-feature_20241201	已被替代	2025-01-05

undefined

Metadata (metadata.json) Fields

元数据（metadata.json）字段

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"]
}

json

{
  "id": "user-auth_20250115",
  "title": "用户认证系统",
  "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

Track操作

Creating a Track

创建Track

Run
```
/conductor:new-track
```
Answer interactive questions
Review generated spec.md
Review generated plan.md
Confirm track creation

运行
```
/conductor:new-track
```
回答交互式问题
审核生成的spec.md
审核生成的plan.md
确认创建track

Starting Implementation

开始实施

Read spec.md and plan.md
Verify context artifacts are current
Mark first task as
```
[~]
```
Begin TDD workflow

阅读spec.md和plan.md
验证上下文工件是最新的
将第一个任务标记为
```
[~]
```
开始TDD工作流

Completing a Phase

完成一个阶段

Ensure all phase tasks are
```
[x]
```
Complete verification tasks
Wait for checkpoint approval
Record checkpoint SHA
Proceed to next phase

确保该阶段所有任务均标记为
```
[x]
```
完成验证任务
等待检查点审批
记录检查点SHA
进入下一阶段

Completing a Track

完成Track

Verify all phases complete
Verify all acceptance criteria met
Update product.md if needed
Mark track completed in tracks.md
Update metadata.json

验证所有阶段均已完成
验证所有验收标准均已满足
必要时更新product.md
在tracks.md中将track标记为已完成
更新metadata.json

Reverting a Track

回滚Track

Run
```
/conductor:revert
```
Select track to revert
Choose granularity (track/phase/task)
Confirm revert operation
Update status markers

运行
```
/conductor:revert
```
选择要回滚的track
选择回滚粒度（整个track/阶段/任务）
确认回滚操作
更新状态标记

Handling Track Dependencies

处理Track依赖项

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

在创建track时，识别以下依赖：

强依赖：必须在本track开始前完成
弱依赖：可并行进行，但可能影响集成
外部依赖：第三方服务、API或团队决策

Documenting Dependencies

记录依赖项

In spec.md, list dependencies with:

Dependency type (hard/soft/external)
Current status (available/pending/blocked)
Resolution path (what needs to happen)

在spec.md中列出依赖项，包含：

依赖类型（强/弱/外部）
当前状态（可用/待处理/阻塞）
解决路径（需要完成的工作）

Managing Blocked Tracks

管理被阻塞的Track

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被阻塞时：

用
```
[!]
```
标记被阻塞的任务并注明原因
更新tracks.md中的状态
在metadata.json中记录阻塞信息
必要时创建依赖track

Track Sizing Guidelines

Track规模指南

Right-Sized Tracks

合适规模的Track

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

理想的Track应满足：

1-5天内完成
包含2-4个阶段
总任务数8-20个
交付一个连贯、可测试的工作单元

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.

Track规模过大的迹象：

超过5个阶段
超过25个任务
包含多个不相关功能
预计耗时超过1周

解决方案：拆分为多个边界清晰的track

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.

Track规模过小的迹象：

单阶段仅包含1-2个任务
无需有意义的验证
可作为其他track的子任务
耗时不足几小时

解决方案：与相关工作合并，或作为现有track的一部分处理

Specification Quality Checklist

需求规格质量检查清单

Before finalizing spec.md, verify:

在最终确定spec.md前，验证以下内容：

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

每个需求都有清晰的验收标准
需求可测试
需求相互独立（可单独验证）
无模糊表述（如将“应快速”改为“响应时间<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

风险应对

Plan Quality Checklist

计划质量检查清单

Before starting implementation, verify plan.md:

在开始实施前，验证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

完整性

Common Track Patterns

常见Track模式

Feature Track Pattern

功能开发Track模式

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

阶段1：基础准备
- 数据模型
- 数据库迁移
- 基础API结构

阶段2：核心逻辑
- 业务逻辑实现
- 输入验证
- 错误处理

阶段3：集成
- UI集成
- API文档
- 端到端测试

Bug Fix Track Pattern

Bug修复Track模式

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

阶段1：复现问题
- 编写捕获Bug的失败测试
- 记录复现步骤

阶段2：修复
- 实施修复
- 验证测试通过
- 检查是否有回退风险

阶段3：验证
- 手动验证
- 必要时更新文档

Refactor Track Pattern

代码重构Track模式

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

阶段1：准备
- 添加特征测试
- 记录当前行为

阶段2：重构
- 逐步应用变更
- 全程保持测试通过

阶段3：清理
- 删除死代码
- 更新文档

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

一个track，一个关注点：保持track聚焦于单一逻辑变更
小阶段拆分：将工作拆分为最多包含3-5个任务的阶段
阶段后必验证：始终包含验证任务
即时更新标记：工作时即时更新任务状态
记录SHA：完成任务时务必记录提交SHA
先审规格再规划：确保spec完整后再创建plan
明确依赖链接：显式标注track依赖项
归档而非删除：保留已完成的track以供参考
规模适中：保持track在1-5天的工作量
清晰的验收标准：每个需求都必须可测试