ado-plan-build

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Azure Boards work item → shipped feature

Azure Boards工作项 → 已交付功能

Take an Azure Boards work item all the way to PR open, Pipelines green, review comments addressed, and the work item updated. There is exactly one explicit checkpoint — plan approval — and even that is conditional: routine changes run straight through.

It is stack-agnostic — .NET repositories are one case it handles, not what it assumes.

Read
references/build-loop.md
now. It is the body of this skill, not optional background. This file supplies the Azure DevOps bindings it asks for.

将Azure Boards工作项全程推进至PR已打开、Pipelines运行正常、评审意见已处理、工作项已更新状态。仅存在一个明确的检查点——计划批准，且该检查点为可选：常规变更可直接跳过。

它与技术栈无关——.NET仓库是它能处理的场景之一，但并非预设场景。

请立即阅读
references/build-loop.md
。这是该技能的核心内容，并非可选背景资料。此文件提供了它所需的Azure DevOps绑定配置。

Autonomy contract

自主操作协议

Act and self-verify by default. No option menus, no "should I proceed?" on green.
Work-item writes on this item are pre-authorized — its state and its discussion comments. Never ask permission for those, and never write anything else in Boards.
This skill pushes branches and opens pull requests without asking. It never completes a PR, never sets auto-complete, never bypasses a branch policy, and never deploys.
Escalate only for the cases listed in
```
references/build-loop.md
```
§ Escalation.

默认主动执行并自我验证。无选项菜单，流水线正常时无需询问“是否继续？”。
预授权对该工作项的写入操作——包括其状态和讨论评论。无需为此类操作请求许可，且绝不在Boards中写入其他内容。
该技能无需询问即可推送分支并打开拉取请求（PR）。但它绝不会完成PR、设置自动完成、绕过分支策略或进行部署。
仅在
references/build-loop.md
§ 升级处理中列出的情况才会升级问题。

Arguments

参数

Parse

$ARGUMENTS

Work item id — bare digits (
```
2
```
), digits with a leading
```
#
```
(
```
#2
```
), or an Azure DevOps work item URL (
```
.../_workitems/edit/2
```
). Extract the integer id. If absent, ask for one.
skip-checkpoint
— or freeform "skip the plan checkpoint" / "run straight to PR". Forces the Step E skip for routine items. Honor it only when explicitly given, and never over a user who asked to see a plan.

There is no brief-file or inline-description path. This skill starts from a work item.

解析

$ARGUMENTS

：

工作项ID——纯数字（
```
2
```
）、带前缀
```
#
```
的数字（
```
#2
```
）或Azure DevOps工作项URL（
```
.../_workitems/edit/2
```
）。提取整数ID。若未提供，则询问用户获取。
skip-checkpoint
——或自由表述的“跳过计划检查点”/“直接运行至PR”。强制跳过常规变更的步骤E。仅在明确指定时生效，且绝不违背用户查看计划的请求。

该技能不支持通过简要文件或内联描述启动，必须从工作项开始。

Phase 0 — Resolve the access path

阶段0 — 确定访问路径

Azure DevOps is reachable two ways, and this skill supports both. Detect in order:

MCP — the session exposes
```
mcp__azure-devops__*
```
tools.
CLI — otherwise,
```
az
```
is installed, the
```
azure-devops
```
extension is present, and
```
az account show
```
succeeds.
Neither — stop and report both setup options.

Say which path you took, and use it for the whole run.

references/ado-access.md

holds the operation-by-operation mapping, the discovery steps for the two operations the CLI has no first-class command for, and the auth troubleshooting for both paths. Read it before your first Azure DevOps call.

Azure DevOps有两种访问方式，该技能均支持。按以下顺序检测：

MCP——会话暴露
```
mcp__azure-devops__*
```
工具。
CLI——若未检测到MCP，则检查是否已安装
```
az
```
、是否存在
```
azure-devops
```
扩展，且
```
az account show
```
执行成功。
均不支持——停止操作并报告两种设置选项。

告知用户所采用的访问路径，并在整个运行过程中使用该路径。

references/ado-access.md

包含了逐操作的映射、CLI无原生命令支持的两项操作的发现步骤，以及两种路径的身份验证故障排除方法。在首次调用Azure DevOps前请阅读此文件。

Phase 1 — Read the work item

阶段1 — 读取工作项

Fetch the item and its discussion. The project is never hardcoded: use the one the caller names, the one configured for the repo, or the one auto-detected from the git remote — and if you can't determine it, ask before fetching.

Read

System.Title

System.Description

System.State

System.WorkItemType

, and

System.Tags

, then the comments — requirements are often negotiated in the discussion rather than written in a field.

Two things that bite, both worth getting right:

Acceptance criteria live in different places per process. The Basic process
```
Issue
```
type has no acceptance-criteria field — the whole requirement is in
```
System.Description
```
. Only Agile/Scrum types (
```
User Story
```
,
```
Product Backlog Item
```
) define
```
Microsoft.VSTS.Common.AcceptanceCriteria
```
. Read
```
System.WorkItemType
```
first and ask for that field only when the type defines it. Never assume it exists, and never treat its absence as an empty requirement.
System.Description
comes back as HTML, not Markdown — and so do acceptance criteria where present. Render to text before reasoning over them, and don't let stray tags leak into the plan.

Two failure modes to handle rather than paper over. If the fetch fails, stop and report the error verbatim — do not invent a requirement from the id, and do not proceed on a partially-read item. If the description is empty (and there's no acceptance-criteria field, or it's empty too), say so and ask: an id is a pointer, not a specification.

获取工作项及其讨论内容。项目绝不能硬编码：使用用户指定的项目、仓库配置的项目，或从git远程仓库自动检测到的项目——若无法确定项目，则在获取前询问用户。

读取

System.Title

、

System.Description

、

System.State

、

System.WorkItemType

和

System.Tags

，然后读取评论——需求通常在讨论中协商确定，而非写入字段。

有两个容易出错的点，务必处理正确：

验收标准的位置因流程而异。Basic流程的
```
Issue
```
类型没有验收标准字段——所有需求都在
```
System.Description
```
中。只有Agile/Scrum类型（
```
User Story
```
、
```
Product Backlog Item
```
）定义了
```
Microsoft.VSTS.Common.AcceptanceCriteria
```
。先读取
```
System.WorkItemType
```
，仅当该类型定义了验收标准字段时才请求读取该字段。绝不假设该字段存在，也绝不将其缺失视为需求为空。
System.Description
返回的是HTML而非Markdown——验收标准（若存在）也是如此。在进行推理前先转换为文本，不要让多余的标签混入计划中。

有两种失败模式需要处理而非掩盖。若获取失败，立即停止并如实报告错误——不要根据ID编造需求，也不要在工作项读取不完整的情况下继续操作。若描述为空（且无验收标准字段，或该字段也为空），则告知用户并询问：ID只是一个指针，而非规范说明。

Phase 2 — Prepare the git environment

阶段2 — 准备Git环境

Default branch:

git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@'

```
git fetch origin
```
.
If the working tree is dirty, stop and report. Do not stash, do not discard.

git checkout <default-branch> && git pull --ff-only origin <default-branch>

Create
```
feature/<id>-<short-slug>
```
. The branch name must contain the work item id. If you are already on that branch with prior work on it, stay on it.

默认分支：执行

git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@'

获取。

执行
```
git fetch origin
```
。
若工作树未干净，停止操作并报告。不要暂存，不要丢弃更改。

执行

git checkout <default-branch> && git pull --ff-only origin <default-branch>

。

创建分支
```
feature/<id>-<short-slug>
```
。分支名称必须包含工作项ID。若已在该分支上进行过前期工作，则保留在该分支。

Phase 3 — Present the work item summary

阶段3 — 展示工作项摘要

Print a concise summary: title, type, state, assignee, area and iteration path, tags, branch name, linked and child items, and the decisions buried in the discussion.

Board state is not authoritative. Flag every linked blocker that isn't done, and before treating a dependency as met, confirm it against

git log

and the code rather than against a column on a board.

打印简洁的摘要：标题、类型、状态、经办人、区域和迭代路径、标签、分支名称、关联和子项，以及讨论中隐含的决策。

看板状态不具备权威性。标记所有未完成的关联阻塞项，在将依赖项视为已满足前，需对照

git log

和代码确认，而非仅依赖看板上的列状态。

Phase 4 — Run the build loop

阶段4 — 运行构建循环

references/build-loop.md

, Steps A → J, with these bindings. Exact commands per access path are in

references/ado-access.md

Binding	Azure DevOps
`TICKET`	the work item, plus any child items you work
`STATUS→IN-PROGRESS`	set the item's in-progress state — see States below
`STATUS→IN-REVIEW`	set the item's review state — see States below
`COMMENT`	add to the item's discussion
`BRANCH`	the Phase 2 branch
`LINK-TOKEN`	`AB#<id>` in the commit message — that exact syntax is what makes Boards attach the commit; a bare `#2` does nothing
`OPEN-PR`	`az repos pr create … --work-items <id>` , or the MCP equivalent
`CI`	Azure Pipelines runs for the branch — `az pipelines runs list --branch <b>` , then `az pipelines runs show --id <run>`
`PR-COMMENTS`	the PR's comment threads — `az repos pr show` , plus thread discovery per `references/ado-access.md`

States are per-process, so read them, don't assume. Basic uses

To Do

Doing

Done

; Agile uses

New

Active

Resolved

Closed

; Scrum uses

New

Approved

Committed

Done

. Read the item's current

System.State

and its type, pick the state that actually means in-progress or in review for that process, and name the one you picked. A state write is never worth blocking the work over — if nothing fits, say so and carry on.

Branch policies matter here. An Azure Repos PR often can't complete without CI green plus a reviewer approval. That's the point: this skill drives CI to green and addresses the review comments, then leaves the completion to a human.

遵循

references/build-loop.md

中的步骤A→J，并使用以下绑定配置。各访问路径的具体命令见

references/ado-access.md

。

绑定项	Azure DevOps对应内容
`TICKET`	工作项，以及您处理的所有子项
`STATUS→IN-PROGRESS`	设置工作项的进行中状态——见下方状态说明
`STATUS→IN-REVIEW`	设置工作项的评审中状态——见下方状态说明
`COMMENT`	添加至工作项的讨论
`BRANCH`	阶段2创建的分支
`LINK-TOKEN`	提交消息中的 `AB#<id>` ——正是这种语法让Boards关联提交；纯 `#2` 无效
`OPEN-PR`	执行 `az repos pr create … --work-items <id>` ，或使用MCP等效操作
`CI`	针对该分支的Azure Pipelines运行——执行 `az pipelines runs list --branch <b>` ，然后执行 `az pipelines runs show --id <run>`
`PR-COMMENTS`	PR的评论线程——执行 `az repos pr show` ，并根据 `references/ado-access.md` 中的方法发现线程

状态因流程而异，请读取状态而非假设。Basic流程使用

To Do

Doing

Done

；Agile流程使用

New

Active

Resolved

Closed

；Scrum流程使用

New

Approved

Committed

Done

。读取工作项当前的

System.State

及其类型，选择对应流程中实际表示“进行中”或“评审中”的状态，并明确说明所选状态。状态写入操作绝不应阻碍工作推进——若没有合适的状态，告知用户并继续操作。

分支策略至关重要。Azure Repos PR通常需要CI运行正常且获得评审者批准才能完成。这正是该技能的作用：推动CI至正常状态，处理评审意见，然后将PR完成操作留给人工处理。

Notes

注意事项

What this skill is pre-approved to do. Read and write files in the repo, run the repo's own build/test commands, write to this work item, push its branch, and open a PR. It will not complete a PR, bypass a policy, deploy, or touch anything else in Boards. If that is more autonomy than you want on a given item, run it without
```
skip-checkpoint
```
and stop it at the Step E checkpoint.
No architecture is assumed. This skill does not check for, recommend, or plan against Clean Architecture, hexagonal, MVC, or any other named pattern. Step B reads what the repository actually does and the plan follows it.
Migrations. If the change needs a schema migration, use the repo's own migration command — whatever
```
AGENTS.md
```
, the
```
Makefile
```
, or the toolchain defines. Don't assume migrations run on startup.
Keep secrets out of the shell and the commit. Don't stage
```
.env
```
files, keys, or tokens, and never echo a PAT into a command, a commit message, or a PR body.
Gate commands. The mainstream runners (
```
make
```
,
```
npm
```
/
```
pnpm
```
/
```
yarn
```
,
```
pytest
```
,
```
go
```
,
```
cargo
```
,
```
dotnet
```
,
```
mvn
```
/
```
gradle
```
,
```
bundle
```
,
```
composer
```
) are pre-approved. If your repo's gate isn't among them, run it and approve the prompt — never skip or fake a gate to avoid a permission dialog.

该技能预授权的操作。读取和写入仓库中的文件，运行仓库自带的构建/测试命令，写入该工作项，推送其分支，打开PR。它不会完成PR、绕过策略、部署，也不会触碰Boards中的其他任何内容。如果您不希望某个工作项拥有如此高的自主性，请不带
```
skip-checkpoint
```
参数运行它，并在步骤E检查点处停止。
不预设架构。该技能不会检查、推荐或针对Clean Architecture、六边形架构、MVC或任何其他命名模式制定计划。步骤B会读取仓库的实际架构，计划将遵循该架构。
迁移操作。若变更需要架构迁移，请使用仓库自带的迁移命令——无论
```
AGENTS.md
```
、
```
Makefile
```
或工具链如何定义。不要假设迁移会在启动时自动运行。
避免泄露机密。不要暂存
```
.env
```
文件、密钥或令牌，绝不要在命令、提交消息或PR正文中回显PAT（个人访问令牌）。
门控命令。主流运行工具（
```
make
```
、
```
npm
```
/
```
pnpm
```
/
```
yarn
```
、
```
pytest
```
、
```
go
```
、
```
cargo
```
、
```
dotnet
```
、
```
mvn
```
/
```
gradle
```
、
```
bundle
```
、
```
composer
```
）已获预授权。若仓库的门控工具不在其中，运行它并批准提示——绝不要跳过或伪造门控以避免权限对话框。