mb-execute

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

mb-execute — Execution loop (plan → build → gates → verify → MB-SYNC)

mb-execute — 执行循环（规划 → 构建 → 门禁 → 验证 → MB-SYNC）

What it does: implements one scoped task and records the run in protocol files.
Use it when:
```
TASK-*
```
already exists and you want a clean, resumable implementation flow.
Input:
```
TASK_ID
```
plus links to the driving feature, requirement, and backlog entry.
Output: code changes, protocol artifacts, verification inputs, and synchronized Memory Bank state.

功能说明：实现单个限定范围的任务，并将运行记录存入协议文件。
适用场景：
```
TASK-*
```
已存在，你需要一套清晰、可中断恢复的实现流程。
输入：
```
TASK_ID
```
以及对应的关联功能、需求和待办条目链接。
输出：代码变更、协议产物、验证输入，以及同步后的 Memory Bank 状态。

Goal

目标

Turn a backlog item into a reproducible, verifiable change:

clear plan
bounded implementation
deterministic gates
recorded verification
synchronized Memory Bank

将待办事项转化为 可复现、可验证的变更：

清晰的规划
边界明确的实现
确定性的质量门禁
可追溯的验证记录
同步完成的 Memory Bank

Inputs

输入

Orchestrator must provide:

```
TASK_ID
```
(e.g.
```
TASK-123
```
)

link to the driving spec(s):

```
.memory-bank/features/FT-*/...
```
and/or
```
.memory-bank/requirements.md
```
(REQ IDs)
```
.memory-bank/tasks/backlog.md
```
entry

编排器必须提供：

```
TASK_ID
```
（例如
```
TASK-123
```
）

驱动规范的链接：

```
.memory-bank/features/FT-*/...
```
和/或
```
.memory-bank/requirements.md
```
（需求ID）
```
.memory-bank/tasks/backlog.md
```
对应条目

Required artifacts

必需产物

Create:

```
.protocols/<TASK_ID>/context.md
```
```
.protocols/<TASK_ID>/plan.md
```
```
.protocols/<TASK_ID>/progress.md
```
```
.protocols/<TASK_ID>/verification.md
```
```
.protocols/<TASK_ID>/handoff.md
```

And a runtime folder:

```
.tasks/<TASK_ID>/
```

Use templates from:

./references/shared-protocols-context-template.md

./references/shared-protocols-plan-template.md

./references/shared-protocols-progress-template.md

./references/shared-protocols-verification-template.md

./references/shared-protocols-handoff-template.md

创建以下文件：

```
.protocols/<TASK_ID>/context.md
```
```
.protocols/<TASK_ID>/plan.md
```
```
.protocols/<TASK_ID>/progress.md
```
```
.protocols/<TASK_ID>/verification.md
```
```
.protocols/<TASK_ID>/handoff.md
```

以及一个运行时文件夹：

```
.tasks/<TASK_ID>/
```

使用以下路径的模板：

./references/shared-protocols-context-template.md

./references/shared-protocols-plan-template.md

./references/shared-protocols-progress-template.md

./references/shared-protocols-verification-template.md

./references/shared-protocols-handoff-template.md

Process

流程

1) Prime context (cheap-to-prime)

1) 准备上下文（低开销初始化）

Read only what you need:

```
AGENTS.md
```
```
.memory-bank/index.md
```
the specific
```
FT-*
```
/
```
REQ-*
```
relevant to
```
TASK_ID
```

仅读取你需要的内容：

```
AGENTS.md
```
```
.memory-bank/index.md
```
与
```
TASK_ID
```
相关的特定
```
FT-*
```
/
```
REQ-*
```
文件

2) Write the plan (before touching code)

2) 编写规划（修改代码前完成）

.protocols/<TASK_ID>/plan.md

goal + non-goals
touched files/modules (hypotheses allowed, mark as such)
constraints/invariants
quality gates to run
MB-SYNC step is mandatory (link to
```
.memory-bank/workflows/mb-sync.md
```
)

写入

.protocols/<TASK_ID>/plan.md

：

目标 + 非目标
涉及的文件/模块（允许假设，需明确标注）
约束/不变量
需要运行的质量门禁
MB-SYNC 步骤为必填项（链接到
```
.memory-bank/workflows/mb-sync.md
```
）

3) Implementation (fan-out allowed)

3) 实现阶段（允许拆分任务）

If work is non-trivial:

spawn subagents (max depth=2)
give each worker a narrow scope (≤3–5 files)
workers write details to
```
.tasks/<TASK_ID>/...
```

Recommended role split (optional):

Implementer: changes code/tests —
```
./agents/shared-implementer.md
```
Secretary: keeps
```
progress.md
```
updated —
```
./agents/shared-secretary.md
```

如果工作量较大：

生成子Agent（最大深度为2）
给每个执行Agent分配窄范围任务（≤3-5个文件）
执行Agent将细节写入
```
.tasks/<TASK_ID>/...
```

推荐角色拆分（可选）：

实现者：修改代码/测试 —— 参考
```
./agents/shared-implementer.md
```
记录员：持续更新
```
progress.md
```
—— 参考
```
./agents/shared-secretary.md
```

3.1) Fresh Codex session per task (optional, clean context)

3.1) 每个任务使用全新 Codex 会话（可选，上下文更干净）

If you want the implementation to run in a fresh Codex session (clean context), run it via shell:

bash

codex exec --ephemeral --full-auto -m gpt-5.2-high \
  'TASK_ID=TASK-123. Read AGENTS.md, .protocols/TASK-123/context.md, .protocols/TASK-123/plan.md, .protocols/TASK-123/progress.md. Keep context.md updated. Implement only scoped changes. Write report to .tasks/TASK-123/TASK-123-S-IMPL-final-report-code-01.md. Update .protocols/TASK-123/progress.md.'

Then run verification in another fresh session:

bash

codex exec --ephemeral --full-auto -m gpt-5.2-high \
  'TASK_ID=TASK-123. Read .protocols/TASK-123/context.md, .protocols/TASK-123/plan.md and progress.md + acceptance criteria. Keep context.md updated. Fill .protocols/TASK-123/verification.md and put evidence in .tasks/TASK-123/. VERDICT: PASS/FAIL.'

如果你需要在 全新 Codex 会话（干净上下文）中运行实现，可通过shell执行：

bash

codex exec --ephemeral --full-auto -m gpt-5.2-high \
  'TASK_ID=TASK-123. Read AGENTS.md, .protocols/TASK-123/context.md, .protocols/TASK-123/plan.md, .protocols/TASK-123/progress.md. Keep context.md updated. Implement only scoped changes. Write report to .tasks/TASK-123/TASK-123-S-IMPL-final-report-code-01.md. Update .protocols/TASK-123/progress.md.'

然后在另一个全新会话中运行验证：

bash

codex exec --ephemeral --full-auto -m gpt-5.2-high \
  'TASK_ID=TASK-123. Read .protocols/TASK-123/context.md, .protocols/TASK-123/plan.md and progress.md + acceptance criteria. Keep context.md updated. Fill .protocols/TASK-123/verification.md and put evidence in .tasks/TASK-123/. VERDICT: PASS/FAIL.'

3.2) Fresh Claude session per task (required when working in Claude Code)

3.2) 每个任务使用全新 Claude 会话（在 Claude Code 中工作时必填）

If you are running inside Claude Code, enforce clean context by executing each

TASK-XXX

in a fresh Claude session:

Run implementer in a fresh session via shell (new session, clean context):

bash

claude -p --no-session-persistence --permission-mode acceptEdits --model opus \
  'TASK_ID=TASK-123. Read AGENTS.md, .protocols/TASK-123/context.md, .protocols/TASK-123/plan.md, .protocols/TASK-123/progress.md, and acceptance criteria docs. Keep context.md updated. Implement only scoped changes. Update .protocols/TASK-123/progress.md. Write report to .tasks/TASK-123/TASK-123-S-IMPL-final-report-code-01.md.'

Then run verifier in another fresh session:

bash

claude -p --no-session-persistence --permission-mode acceptEdits --model opus \
  'TASK_ID=TASK-123. Read .protocols/TASK-123/context.md, .protocols/TASK-123/plan.md + progress.md + acceptance criteria docs. Keep context.md updated. Fill .protocols/TASK-123/verification.md and store evidence in .tasks/TASK-123/. VERDICT: PASS/FAIL/NEEDS-CLARIFICATION.'

如果你在 Claude Code 中运行，需为每个

TASK-XXX

启动 全新 Claude 会话 来保证上下文干净：

在全新会话中通过shell运行实现者（新会话，干净上下文）：

bash

claude -p --no-session-persistence --permission-mode acceptEdits --model opus \
  'TASK_ID=TASK-123. Read AGENTS.md, .protocols/TASK-123/context.md, .protocols/TASK-123/plan.md, .protocols/TASK-123/progress.md, and acceptance criteria docs. Keep context.md updated. Implement only scoped changes. Update .protocols/TASK-123/progress.md. Write report to .tasks/TASK-123/TASK-123-S-IMPL-final-report-code-01.md.'

然后在另一个全新会话中运行验证器：

bash

claude -p --no-session-persistence --permission-mode acceptEdits --model opus \
  'TASK_ID=TASK-123. Read .protocols/TASK-123/context.md, .protocols/TASK-123/plan.md + progress.md + acceptance criteria docs. Keep context.md updated. Fill .protocols/TASK-123/verification.md and store evidence in .tasks/TASK-123/. VERDICT: PASS/FAIL/NEEDS-CLARIFICATION.'

3.3) Sequencing rule (dependencies)

3.3) 排序规则（依赖处理）

If tasks are independent (no dependency and no shared files), you MAY run them in separate clean sessions in parallel.
If tasks have a dependency chain (TASK-B requires outputs from TASK-A), run them sequentially, one after another, each in its own clean session.
If tasks touch the same files, treat them as dependent unless you isolate via worktrees/branches.

如果任务 相互独立（无依赖且无共享文件），你可以在独立的干净会话中并行运行。
如果任务存在 依赖链（TASK-B 需要 TASK-A 的输出），需 顺序执行，逐个运行，每个任务使用独立的干净会话。
如果任务修改相同文件，视为存在依赖，除非你通过工作树/分支进行了隔离。

4) Quality gates (deterministic)

4) 质量门禁（确定性校验）

Run the repo’s canonical gates (from

AGENTS.md

). Minimum:

lint / typecheck
unit tests
integration/e2e when relevant

If any gate is flaky, record it in

progress.md

and (if needed) file a bug doc in

.memory-bank/bugs/

运行代码库的标准门禁（定义在

AGENTS.md

中），最低要求：

代码检查 / 类型校验
单元测试
符合场景的集成/端到端测试

如果任何门禁结果不稳定，记录到

progress.md

中，必要时在

.memory-bank/bugs/

下提交缺陷文档。

5) Verification handoff

5) 验证交接

Do not self-validate beyond sanity checks.

Hand off to
```
mb-verify
```
(fresh-ish context) to fill
```
verification.md
```
.

除了合理性检查外不要自行验证。

交接给
```
mb-verify
```
（相对干净的上下文）填写
```
verification.md
```
。

6) MB-SYNC (required, last step)

6) MB-SYNC（必填，最后一步）

After verification is complete:

update
```
.memory-bank/
```
docs (only WHY/WHERE + navigation)
update
```
.memory-bank/index.md
```
routers if needed
update
```
.memory-bank/requirements.md
```
RTM status (if used)
mark the backlog task with the correct state (
```
done
```
/
```
failed
```
/
```
blocked
```
)
append a record to
```
.memory-bank/changelog.md
```

验证完成后：

更新
```
.memory-bank/
```
文档（仅更新原因/位置 + 导航信息）
必要时更新
```
.memory-bank/index.md
```
导航路由
更新
```
.memory-bank/requirements.md
```
需求跟踪矩阵状态（如果使用）
标记待办任务的正确状态（
```
已完成
```
/
```
失败
```
/
```
阻塞
```
）
在
```
.memory-bank/changelog.md
```
中追加变更记录

Definition of done

完成定义

Protocol folder exists with all 5 required files.
Gates pass (or failures are explicitly recorded + bug filed).
```
verification.md
```
contains evidence links to
```
.tasks/<TASK_ID>/
```
.
Memory Bank is synced + changelog updated.

协议文件夹存在，包含全部5个必需文件。
门禁通过（或已明确记录失败原因 + 提交缺陷）。
```
verification.md
```
包含指向
```
.tasks/<TASK_ID>/
```
的证据链接。
Memory Bank 已同步 + 变更日志已更新。