task

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/task

Surface Routing

表层路由

Before starting, pick the right tool for the job:

Activity	Tool	Why
Architecture planning	Claude Code /plan	Opus, 1M context
Feature implementation	Claude Code	Hooks, subagents, worktrees
Quick single-file fix	VS Code Claude ext	Faster for small scope
DevOps / terminal	Codex CLI	Strong at terminal tasks
Background refactor	Codex Cloud	Fire-and-forget PR
Code review	GitHub Actions	Async, no session cost
Test writing	subagent: test-writer (CC) / inline (Codex)	Isolated context
Documentation	subagent: doc-writer (CC) / inline (Codex)	Cheap, focused
Research	Claude.ai Projects	Persistent, web search

开始前，为任务选择合适的工具：

活动	工具	原因
架构规划	Claude Code /plan	Opus模型，100万上下文窗口
功能实现	Claude Code	钩子、子Agent、工作树
快速单文件修复	VS Code Claude 扩展	小范围场景下速度更快
DevOps / 终端操作	Codex CLI	擅长终端任务
后台重构	Codex Cloud	无需关注的PR提交
代码评审	GitHub Actions	异步执行，无会话成本
测试编写	子Agent: test-writer (CC) / 内联方式 (Codex)	独立上下文环境
文档编写	子Agent: doc-writer (CC) / 内联方式 (Codex)	低成本、聚焦目标
研究工作	Claude.ai Projects	持久化存储、支持网页搜索

Cross-Tool Notes

跨工具说明

This skill uses Claude Code features. Portable equivalents for Codex/Cursor:

Claude Code	Codex / Cursor
`TaskCreate` / `TaskUpdate`	Markdown checklist in `.branch-context.md`
`EnterWorktree`	Use absolute paths + `git -C` for all ops
`/orient` , `/brainstorming` , etc.	Read `.agents/skills/<name>/SKILL.md` and follow manually
Subagent dispatch ( `implementer` , `test-writer` )	Execute sequentially in main session
Agent Teams	Not supported — use sequential work
`/review-loop` , `/plan-review`	Read `.agents/skills/review-loop/SKILL.md` and follow manually

本技能使用Claude Code功能。以下是适用于Codex/Cursor的替代方案：

Claude Code	Codex / Cursor
`TaskCreate` / `TaskUpdate`	在 `.branch-context.md` 中使用Markdown任务清单
`EnterWorktree`	对所有操作使用绝对路径 + `git -C`
`/orient` , `/brainstorming` 等	阅读 `.agents/skills/<name>/SKILL.md` 并手动执行
子Agent调度（ `implementer` , `test-writer` ）	在主会话中按顺序执行
Agent Teams	暂不支持——使用顺序执行方式
`/review-loop` , `/plan-review`	阅读 `.agents/skills/review-loop/SKILL.md` 并手动执行

Skill Aliases (temporary)

技能别名（临时）

These skills are planned but not yet extracted. When invoked, follow the corresponding step inline:

Alias	Step	Status
`/isolate`	Step 2	inline — extract to ai-skills later
`/plan`	Step 3	inline — extract to ai-skills later
`/review`	Steps 4, 6	inline — extract to ai-skills later
`/build`	Step 5	inline — extract to ai-skills later
`/ship`	Step 8	inline — extract to ai-skills later
`/bail`	any	existing skill — invoke directly

以下技能已规划但尚未提取。调用时，请直接执行对应步骤：

别名	步骤	状态
`/isolate`	步骤2	内联执行——后续将提取至ai-skills
`/plan`	步骤3	内联执行——后续将提取至ai-skills
`/review`	步骤4、6	内联执行——后续将提取至ai-skills
`/build`	步骤5	内联执行——后续将提取至ai-skills
`/ship`	步骤8	内联执行——后续将提取至ai-skills
`/bail`	任意步骤	已有技能——直接调用

Args

参数

Invocation	Behavior
`/task <description>`	Start new task
`/task #<issue>`	Start from GitHub issue
`/task`	Start new task — ask what to work on

调用方式	行为
`/task <description>`	启动新任务
`/task #<issue>`	从GitHub issue启动任务
`/task`	启动新任务——询问需处理的内容

Copilot Mode

副驾驶模式

In copilot mode (

operating-mode.md

), the workflow is a menu, not a pipeline:

Present available steps. Execute what the human asks. Don't enforce order.
Worktree-first is relaxed — primary worktree writes are allowed.
Invariants below still apply except where
```
operating-mode.md
```
explicitly overrides.
If the human says "follow the workflow," run step-by-step but pause for approval at each transition.

在副驾驶模式（

operating-mode.md

）下，工作流是一个菜单而非流水线：

展示可用步骤。执行人类用户要求的操作。不强制顺序。
优先使用工作树的规则可放宽——允许在主工作树中写入内容。
除非
```
operating-mode.md
```
明确覆盖，否则以下不变规则仍然适用。
如果用户要求“遵循工作流”，则按步骤执行，但在每个阶段转换时暂停等待批准。

Invariants

不变规则

These rules are agent-interpreted guidance, not machine-enforced. They cannot be skipped regardless of task type or scope unless noted:

starlark

REQUIRE worktree BEFORE code
REQUIRE orient.complete BEFORE plan
REQUIRE review(plan).pass BEFORE build UNLESS scope == one_sentence
REQUIRE validate.pass BEFORE review(build)
REQUIRE review(build).pass BEFORE archive
REQUIRE branch.base IS CURRENT(origin/main) UNLESS stacking

WHEN ci.down:
  USE local_merge AT step_8
WHEN files_touched MATCH [AGENTS.md, config.toml, sync.sh, skills]:
  REQUIRE codex_specialist IN review_panel

这些规则是Agent可解读的指导方针，而非机器强制执行的规则。除非另有说明，否则无论任务类型或范围如何，都不能跳过：

starlark

REQUIRE worktree BEFORE code
REQUIRE orient.complete BEFORE plan
REQUIRE review(plan).pass BEFORE build UNLESS scope == one_sentence
REQUIRE validate.pass BEFORE review(build)
REQUIRE review(build).pass BEFORE archive
REQUIRE branch.base IS CURRENT(origin/main) UNLESS stacking

WHEN ci.down:
  USE local_merge AT step_8
WHEN files_touched MATCH [AGENTS.md, config.toml, sync.sh, skills]:
  REQUIRE codex_specialist IN review_panel

Steps

步骤

Persist significant decisions to

.branch-context.md

during Steps 3-5 — not just at reflect/bail time.

在步骤3-5期间，将重要决策记录到

.branch-context.md

中——不仅是在反思/终止任务时。

Step 0 — Bootstrap

步骤0 — 初始化

Create a task list to track progress through the steps:

Claude Code:
```
TaskCreate
```
with one item: "Step 1 — Orient." Remaining steps populated after orient.
Codex/Cursor: add a markdown checklist to
```
.branch-context.md
```
.

创建任务列表以跟踪步骤进度：

Claude Code：使用
```
TaskCreate
```
创建一个项：“步骤1 — 定位。”定位完成后填充剩余步骤。
Codex/Cursor：在
```
.branch-context.md
```
中添加Markdown任务清单。

Step 1 — Orient

步骤1 — 定位

Invoke

/orient

with args (Codex: read

.agents/skills/orient/SKILL.md

). It produces:

task_type: feat / fix / chore / docs / test / refactor
scope: can the entire diff be described in one sentence? Yes → short path (skip Steps 3-4). No → full path. Note: short description ≠ small change — "update all deps" sounds short but may touch dozens of files.

After orient completes, populate the task list with remaining steps for the detected path. Short path (one-sentence scope) skips Steps 3-4.

调用带参数的

/orient

（Codex：阅读

.agents/skills/orient/SKILL.md

）。它将生成：

task_type：feat（功能）/ fix（修复）/ chore（杂务）/ docs（文档）/ test（测试）/ refactor（重构）
scope：整个差异是否可以用一句话描述？是→短路径（跳过步骤3-4）。否→完整路径。注意：简短描述≠小改动——“更新所有依赖项”听起来简短，但可能涉及数十个文件。

定位完成后，为检测到的路径填充任务列表中的剩余步骤。短路径（一句话范围）跳过步骤3-4。

Step 2 — Isolate

步骤2 — 隔离

git fetch origin main

first — always start from a current base.

Not in a worktree:

Create a worktree from origin/main:

bash

git worktree add .worktrees/<name> -b <prefix>/<name> origin/main

Use the branch prefix from Step 1 (feat/, fix/, chore/, etc.). Use absolute paths and

git -C

for all subsequent operations. Claude Code: optionally use

EnterWorktree

to switch session CWD.

Already in a worktree:

Verify the branch is current with main:

bash

git fetch origin main
git merge origin/main

Stop and ask if conflicts arise. Different base only when explicitly stacking on another feature branch.

首先执行

git fetch origin main

——始终从最新的主分支开始。

不在工作树中：

从origin/main创建工作树：

bash

git worktree add .worktrees/<name> -b <prefix>/<name> origin/main

使用步骤1中的分支前缀（feat/、fix/、chore/等）。对所有后续操作使用绝对路径和

git -C

。Claude Code：可选择使用

EnterWorktree

切换会话工作目录。

已在工作树中：

验证分支与主分支同步：

bash

git fetch origin main
git merge origin/main

如果出现冲突，请停止并询问用户。仅当明确基于另一个功能分支堆叠时，才使用不同的基础分支。

Step 3 — Plan

步骤3 — 规划

One-sentence scope: SKIP — proceed to Step 5. Log: "Step 3 — Plan: SKIPPED (one-sentence scope)."

Full scope:

3a. Brainstorm. Invoke

/brainstorming

with the task description. One round — refine the idea, confirm constraints, explore 2-3 approaches.

3b. Write plan. Write a plan to

ai-workspace/plans/<name>.md

using the template at

ai-workspace/plans/TEMPLATE.md

. Fill all template fields including:

Branch, created date, status
Threat model (advisory or adversarial)
Scope ceiling
Task description and scope
Steps with checkboxes (include files to create/modify and testing strategy)
Confidence scaffold (recommended for adversarial threat models)

Do NOT review the plan here — that's Step 4.

一句话范围： 跳过——直接进入步骤5。记录：“步骤3 — 规划：已跳过（一句话范围）。”

完整范围：

3a. 头脑风暴。 使用任务描述调用

/brainstorming

。进行一轮讨论——完善想法、确认约束、探索2-3种实现方案。

3b. 编写规划。 使用

ai-workspace/plans/TEMPLATE.md

中的模板，将规划写入

ai-workspace/plans/<name>.md

。填写模板的所有字段，包括：

分支、创建日期、状态
威胁模型（建议性或对抗性）
范围上限
任务描述和范围
带复选框的步骤（包括要创建/修改的文件和测试策略）
信心框架（对抗性威胁模型推荐使用）

请勿在此处评审规划——这是步骤4的内容。

Step 4 — Review Plan

步骤4 — 评审规划

No plan (one-sentence scope): SKIP — proceed to Step 5.

Has plan:

Run

/review-loop

against the plan file (Codex: follow review-loop SKILL.md manually).

Auto-assemble the plan review panel:
- Always:
```
technical-editor
```
- Code architecture: add
```
architect-reviewer
```
- AGENTS.md / config.toml / sync.sh / skills: add
```
codex-specialist
```
- Auth / credentials / permissions: add
```
security-auditor
```
- UI / component / CSS: add
```
ui-designer
```
Gate: P2 (fix P0-P2, record P3+)
Cap: 3 rounds

On APPROVE: proceed to Step 5. On ESCALATE after 3 rounds: stop and present unresolved findings to human.

无规划（一句话范围）： 跳过——直接进入步骤5。

有规划：

针对规划文件运行

/review-loop

（Codex：手动遵循review-loop的SKILL.md）。

自动组建规划评审小组：
- 必选：
```
technical-editor
```
  （技术编辑）
- 代码架构：添加
```
architect-reviewer
```
  （架构评审员）
- AGENTS.md / config.toml / sync.sh / skills：添加
```
codex-specialist
```
  （Codex专家）
- 认证 / 凭证 / 权限：添加
```
security-auditor
```
  （安全审计员）
- UI / 组件 / CSS：添加
```
ui-designer
```
  （UI设计师）
门槛：P2（修复P0-P2问题，记录P3及以上问题）
上限：3轮

批准后： 进入步骤5。 3轮后升级： 停止并向用户展示未解决的问题。

Step 5 — Build

步骤5 — 构建

5a. Implement.

With plan: read the plan, execute each task.

Claude Code: use subagents for independent tasks —
```
implementer
```
(Sonnet) for code,
```
test-writer
```
(Sonnet) for tests. Parallel dispatch when tasks are independent.
Codex/Cursor: execute sequentially in the main session.

Without plan (one-sentence / hotfix): implement directly.

TDD: write the failing test first (RED), then fix (GREEN), then refactor
Minimal change principle for hotfixes — fix the defect, nothing else
Document root cause in commit message body for hotfixes

5b. Validate (gate for Step 6).

Run

pnpm validate

(typecheck + lint + format:check + test:all). This is a hard gate — read the output. Never claim success without evidence. If it fails, fix and re-run until green. Step 6 cannot begin until this passes.

5a. 实现。

有规划：阅读规划，执行每个任务。

Claude Code：为独立任务使用子Agent——
```
implementer
```
（Sonnet模型）负责代码，
```
test-writer
```
（Sonnet模型）负责测试。任务独立时可并行调度。
Codex/Cursor：在主会话中按顺序执行。

无规划（一句话/热修复）：直接实现。

TDD：先编写失败的测试（RED），然后修复（GREEN），最后重构
热修复遵循最小改动原则——仅修复缺陷，不做其他修改
在热修复的提交消息正文中记录根本原因

5b. 验证（步骤6的门槛）。

运行

pnpm validate

（类型检查 + 代码检查 + 格式校验 + 全量测试）。这是硬性门槛——需读取输出结果。无证据时切勿声称成功。如果失败，修复后重新运行直到通过。步骤6必须在此通过后才能开始。

Step 6 — Review Build

步骤6 — 评审构建结果

Run

/review-loop

against the changed files (

git diff main...HEAD

) (Codex: follow review-loop SKILL.md manually).

Auto-assemble the code review panel (differs from Step 4's plan panel):
- Always:
```
code-reviewer
```
- Code architecture: add
```
architect-reviewer
```
- AGENTS.md / config.toml / sync.sh / skills: add
```
codex-specialist
```
- Auth / credentials / permissions: add
```
security-auditor
```
- UI / component / CSS: add
```
design-reviewer
```
Gate: P2
Cap: 3 rounds

On APPROVE: proceed to Step 7. On ESCALATE: stop and present unresolved findings to human.

针对变更文件（

git diff main...HEAD

）运行

/review-loop

（Codex：手动遵循review-loop的SKILL.md）。

自动组建代码评审小组（与步骤4的规划小组不同）：
- 必选：
```
code-reviewer
```
  （代码评审员）
- 代码架构：添加
```
architect-reviewer
```
  （架构评审员）
- AGENTS.md / config.toml / sync.sh / skills：添加
```
codex-specialist
```
  （Codex专家）
- 认证 / 凭证 / 权限：添加
```
security-auditor
```
  （安全审计员）
- UI / 组件 / CSS：添加
```
design-reviewer
```
  （设计评审员）
门槛：P2
上限：3轮

批准后： 进入步骤7。 升级： 停止并向用户展示未解决的问题。

Step 7 — Archive

步骤7 — 归档

Has plan:

Invoke

/archive

(Codex: fill Outcomes & Learnings in plan file, rename to

.done.md

). It fills Outcomes & Learnings in the plan file and renames to

.done.md

No plan (hotfix / one-sentence):

Ensure root cause or change rationale is documented in the commit message body. No plan file to archive.

有规划：

调用

/archive

（Codex：在规划文件中填写成果与经验，并重命名为

.done.md

）。它会在规划文件中填写成果与经验，并重命名为

.done.md

。

无规划（热修复 / 一句话范围）：

确保根本原因或变更理由已记录在提交消息正文中。无需归档规划文件。

Step 8 — Ship

步骤8 — 交付

Get the code onto main remote. Two paths:

CI detection: Check

gh run list --limit 3

for recent workflow status, or check if the repo has active GitHub Actions workflows. If unknown, assume CI is up.

CI up (default):

Create a PR and arm auto-merge:

bash

gh pr create --title "<conventional-commit-title>" --body "<summary>"
gh pr merge --auto --merge

The CI review pipeline handles the rest.

CI down:

Local merge to main:

bash

git fetch origin main
git checkout main
git merge <feature-branch>
git push origin main

Run from a temp worktree or ephemeral clone — NOT the primary worktree. Clean up the feature worktree after merge.

Both paths:

When files touched include AGENTS.md, config.toml, sync.sh, or skills →

codex-specialist

must be in the review panel (enforced at Step 6).

将代码合并到主远程分支。有两种路径：

CI检测： 运行

gh run list --limit 3

查看最近的工作流状态，或检查仓库是否有活跃的GitHub Actions工作流。如果未知，默认假设CI正常运行。

CI正常（默认）：

创建PR并启用自动合并：

bash

gh pr create --title "<规范提交标题>" --body "<摘要>"
gh pr merge --auto --merge

剩余工作由CI评审流水线处理。

CI故障：

本地合并到主分支：

bash

git fetch origin main
git checkout main
git merge <feature-branch>
git push origin main

从临时工作树或临时克隆中运行——不要在主工作树中执行。合并后清理功能工作树。

两种路径通用规则：

当涉及的文件包括AGENTS.md、config.toml、sync.sh或skills时→

codex-specialist

必须加入评审小组（步骤6已强制执行）。

Step 9 — Reflect

步骤9 — 反思

Invoke

/reflect

(Codex: read

.agents/skills/reflect/SKILL.md

). It handles:

Reading
```
.branch-context.md
```
for session learnings
Writing to
```
MEMORY.md
```
on main
Filing follow-up issues if needed
Cleaning up branch artifacts

调用

/reflect

（Codex：阅读

.agents/skills/reflect/SKILL.md

）。它将处理：

读取
```
.branch-context.md
```
获取会话经验
向主分支的
```
MEMORY.md
```
写入内容
如有需要提交后续issue
清理分支 artifacts

Agent Teams

Claude Code only. Codex and Cursor do not support Agent Teams or MCP servers.

When teammates are available (session started with teammate mode):

Teammates CANNOT spawn sub-agents or load MCP servers
One task per teammate (self-contained)
Cost: ~15x solo — start with 2 max
Solo with subagents for sequential steps on one feature
Agent Teams for independent features (one per worktree)

Steps can be split across teammates for large work:

Plan: each teammate plans a piece using
```
/task
```
, orchestrator assembles before Step 4
Build: each teammate builds a piece, orchestrator coordinates before Step 6
The orchestrator runs Steps 4, 6, 7, 8, 9 from the main thread

仅Claude Code支持。Codex和Cursor不支持Agent Teams或MCP服务器。

当有队友可用时（会话以队友模式启动）：

队友不能生成子Agent或加载MCP服务器
每个队友负责一个独立任务
成本：约为单人模式的15倍——最多从2个队友开始
单人模式使用子Agent处理单个功能的顺序步骤
Agent Teams用于处理独立功能（每个功能对应一个工作树）

大型工作可拆分给多个队友执行：

规划： 每个队友使用
```
/task
```
规划一部分，协调者在步骤4前整合
构建： 每个队友构建一部分，协调者在步骤6前协调
协调者从主线程执行步骤4、6、7、8、9

Bail

终止任务

Invoke

/bail

at any step to abort cleanly. It handles: learnings capture to

.branch-context.md

, issue update, PR close if open, worktree cleanup. Bail replaces Step 9 (Reflect) — it captures learnings itself. Clean up any open task list items.

在任意步骤调用

/bail

可干净地终止任务。它将处理：将经验记录到

.branch-context.md

、更新issue、关闭已打开的PR（如果有）、清理工作树。终止任务将替代步骤9（反思）——它会自行捕获经验。清理所有未完成的任务列表项。