maestro-new-track

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

New Track -- Specification & Planning

新追踪项 -- 规格说明与规划

This skill is CLI-agnostic. It works with Claude Code, Codex, Amp, or any AI coding assistant.

Validate the result of every operation. If any step fails, halt and report the failure before continuing.

Create a new development track with a requirements specification and phased implementation plan. Every feature, bug fix, or chore gets its own track.

该Skill与CLI无关，可与Claude Code、Codex、Amp或任何AI编码助手配合使用。

验证每一步操作的结果。如果任何步骤失败，停止操作并报告失败情况后再继续。

创建包含需求规格说明和分阶段实施计划的新开发追踪项。每个功能、缺陷修复或杂项任务都对应单独的追踪项。

Arguments

参数

$ARGUMENTS

The track description. Examples:

"Add dark mode support"

"Fix login timeout"

"Refactor connection pooling"

$ARGUMENTS

追踪项描述。示例：

"添加深色模式支持"

"修复登录超时问题"

"重构连接池"

Step 1: Validate Prerequisites

步骤1：验证前置条件

Check

.maestro/context/product.md

exists. If not: "Run

/maestro:setup

first." Stop.

Check

.maestro/tracks.md

exists. If missing, create it with registry header.

检查

.maestro/context/product.md

是否存在。若不存在："请先运行

/maestro:setup

"，然后停止操作。

检查

.maestro/tracks.md

是否存在。若缺失，创建该文件并添加注册表头部信息。

Step 2: Parse Input

步骤2：解析输入

Extract track description from

$ARGUMENTS

. If empty, ask user for type (feature/bug/chore) and description.

从

$ARGUMENTS

中提取追踪项描述。若为空，询问用户任务类型（功能/缺陷/杂项）及描述。

Step 3: Generate Track ID

步骤3：生成追踪项ID

Format:

{shortname}_{YYYYMMDD}

(2-4 words, snake_case + date). Example:

dark_mode_20260225

格式：

{shortname}_{YYYYMMDD}

（2-4个单词，蛇形命名法+日期）。示例：

dark_mode_20260225

Step 4: Duplicate Check

步骤4：重复项检查

Scan

.maestro/tracks/*

directories. Warn if any starts with the same short name prefix.

扫描

.maestro/tracks/*

目录。如果存在以相同短名称前缀开头的追踪项，发出警告。

Step 4.5: BR Bootstrap Check

步骤4.5：BR引导检查

Ensure the beads workspace exists for task tracking integration:

bash

[ -d ".beads" ] || br init --prefix maestro --json

br

is not installed, skip silently -- beads integration is optional.

确保用于任务追踪集成的beads工作区已存在：

bash

[ -d ".beads" ] || br init --prefix maestro --json

若未安装

br

，则静默跳过——beads集成是可选的。

Step 5: Create Track Directory

步骤5：创建追踪项目录

bash

mkdir -p .maestro/tracks/{track_id}

bash

mkdir -p .maestro/tracks/{track_id}

Step 6: Auto-Infer Track Type

步骤6：自动推断追踪项类型

Analyze description keywords to classify as

feature

bug

, or

chore

. Only confirm with user if ambiguous.

Inference rules:

feature: add, build, create, implement, support, introduce
bug: fix, broken, error, crash, incorrect, regression, timeout, fail
chore: refactor, cleanup, migrate, upgrade, rename, reorganize, extract

分析描述中的关键词，将其分类为

feature

（功能）、

bug

（缺陷）或

chore

（杂项）。仅当分类不明确时，才与用户确认。

推断规则：

feature：包含add、build、create、implement、support、introduce等关键词
bug：包含fix、broken、error、crash、incorrect、regression、timeout、fail等关键词
chore：包含refactor、cleanup、migrate、upgrade、rename、reorganize、extract等关键词

Step 7: Specification Interview

步骤7：规格说明访谈

Run the type-specific interview to gather requirements. See

reference/interview-questions.md

for all questions per type (feature/bug/chore).

运行对应类型的访谈以收集需求。详情请参考

reference/interview-questions.md

中针对不同类型（功能/缺陷/杂项）的所有问题。

Step 8: Draft Specification

步骤8：起草规格说明

Compose spec from interview answers. See

reference/interview-questions.md

for the spec template and approval loop.

Present full draft for approval. Max 3 revision loops. Write to

.maestro/tracks/{track_id}/spec.md

根据访谈答案撰写规格说明。规格说明模板及审批流程请参考

reference/interview-questions.md

。

提交完整草稿供审批。最多允许3次修订循环。将最终版本写入

.maestro/tracks/{track_id}/spec.md

。

Step 9: Generate Implementation Plan

步骤9：生成实施计划

Read context:

workflow.md

tech-stack.md

guidelines.md

. Use

reference/plan-template.md

for structure and rules.

Present full plan for approval. Max 3 revision loops. Write to

.maestro/tracks/{track_id}/plan.md

读取上下文文件：

workflow.md

、

tech-stack.md

、

guidelines.md

。使用

reference/plan-template.md

的结构和规则。

提交完整计划供审批。最多允许3次修订循环。将最终版本写入

.maestro/tracks/{track_id}/plan.md

。

Step 9.5: Detect Relevant Skills

步骤9.5：检测相关Skills

Scan the runtime's installed skill list. Record skills whose description matches this track's domain/tech. Store names + relevance in metadata.json

skills

array. Skip if none match.

扫描运行时已安装的Skill列表。记录描述与当前追踪项领域/技术匹配的Skills。将名称及相关性存储在

metadata.json

的

skills

数组中。若无匹配项则跳过。

Step 9.7: Plan-to-BR Sync

步骤9.7：计划与BR同步

.beads/

directory exists AND

command -v br

succeeds: run plan-to-BR sync per

reference/plan-to-br-sync.md

(in the

maestro:implement

skill). Otherwise skip entirely.

若

.beads/

目录存在且

command -v br

执行成功：根据

maestro:implement

Skill中的

reference/plan-to-br-sync.md

执行计划与BR的同步。否则完全跳过此步骤。

Step 10-12: Write Metadata and Registry

步骤10-12：写入元数据与注册表

Write

metadata.json

, update

tracks.md

. See

reference/metadata-and-registry.md

for all schemas, templates, commit message, and summary format.

写入

metadata.json

，更新

tracks.md

。所有模式、模板、提交消息及摘要格式请参考

reference/metadata-and-registry.md

。

Step 13: Commit

步骤13：提交代码

bash

git add .maestro/tracks/{track_id} .maestro/tracks.md

bash

git add .maestro/tracks/{track_id} .maestro/tracks.md

Include beads state if BR sync was performed

若执行了BR同步，则包含beads状态

[ -d ".beads" ] && git add .beads/ git commit -m "chore(maestro:new-track): add track {track_id}"

undefined

[ -d ".beads" ] && git add .beads/ git commit -m "chore(maestro:new-track): add track {track_id}"

undefined

Step 14: Summary

步骤14：总结

Display track creation summary with ID, type, phase/task counts, file paths, and next step (

/maestro:implement

显示追踪项创建总结，包含ID、类型、阶段/任务数量、文件路径及下一步操作（

/maestro:implement

）。

Relationship to Other Commands

与其他命令的关系

Recommended workflow:

```
/maestro:setup
```
-- Scaffold project context (run first)
```
/maestro:new-track
```
-- You are here. Create a feature/bug track with spec and plan
```
/maestro:implement
```
-- Execute the implementation
```
/maestro:review
```
-- Verify implementation correctness
```
/maestro:status
```
-- Check progress across all tracks
```
/maestro:revert
```
-- Undo implementation if needed
```
/maestro:note
```
-- Capture decisions and context to persistent notepad

A track created here produces

spec.md

and

plan.md

that

/maestro:implement

consumes. The spec also serves as the baseline for

/maestro:review

to validate against. Good specs lead to good implementations -- be thorough in the interview.

推荐工作流：

```
/maestro:setup
```
-- 搭建项目上下文（首先运行）
```
/maestro:new-track
```
-- 当前所在步骤：创建包含规格说明和计划的功能/缺陷追踪项
```
/maestro:implement
```
-- 执行实施计划
```
/maestro:review
```
-- 验证实施正确性
```
/maestro:status
```
-- 检查所有追踪项的进度
```
/maestro:revert
```
-- 若需要，撤销实施操作
```
/maestro:note
```
-- 将决策和上下文记录到持久记事本中

在此创建的追踪项会生成

spec.md

和

plan.md

，供

/maestro:implement

使用。规格说明同时作为

/maestro:review

验证的基准。完善的规格说明有助于实现高质量的开发——请在访谈环节做到详尽全面。