Back to Details

grace-multiagent-execute

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Execute a GRACE development plan with multiple agents while keeping planning artifacts and shared context consistent.
在保持规划工件和共享上下文一致性的同时，使用多个Agent执行GRACE开发计划。

Prerequisites

前提条件

  • docs/development-plan.xml
    must exist with module contracts and implementation order
  • docs/knowledge-graph.xml
    must exist
  • If either is missing, tell the user to run 
    $grace-plan
    first
  • If the shell does not already have GRACE worker/reviewer presets, use 
    $grace-setup-subagents
    before dispatching a large wave
  • Prefer this skill only when module-local verification commands already exist or can be defined clearly
  • docs/development-plan.xml
    必须存在，且包含模块契约和实现顺序
  • docs/knowledge-graph.xml
    必须存在
  • 如果其中任意一个缺失，告知用户先运行 
    $grace-plan
  • 如果Shell尚未配置GRACE工作者/评审者预设，在调度大型批次前使用 
    $grace-setup-subagents
  • 仅当模块本地验证命令已存在或可以明确定义时，才优先使用此技能

Core Principle

核心原则

Parallelize module implementation, not architectural truth.
  • One controller owns shared artifacts: 
    docs/development-plan.xml
    , 
    docs/knowledge-graph.xml
    , phase status, and execution queue
  • Worker agents own only their assigned module files and module-local tests
  • Reviewers validate module outputs before the controller merges graph and plan updates
  • Speed should come from better context packaging, batched shared-artifact work, and scoped reviews - not from letting workers invent architecture
If multiple agents edit the same module, the same shared XML file, or the same tightly coupled slice, this is not a multi-agent wave. Use 
$grace-execute
instead.
并行化模块实现，而非架构逻辑。
  • 一个控制器拥有共享工件：
    docs/development-plan.xml
    、
    docs/knowledge-graph.xml
    、阶段状态和执行队列
  • 工作者Agent仅拥有其分配的模块文件和模块本地测试
  • 评审者Agent在控制器合并图谱和计划更新前验证模块输出
  • 速度应来自更优的上下文打包、共享工件的批量处理和范围化评审——而非让工作者自行设计架构
如果多个Agent编辑同一模块、同一共享XML文件或同一紧耦合代码片段，则不属于多Agent批次场景，应改用 
$grace-execute
。

Execution Profiles

执行配置文件

Default to 
balanced
unless the user asks otherwise.
除非用户另有要求，默认使用
balanced
配置。

safe

safe

  • Ask for approval on the proposed waves before dispatch
  • Run contract review and verification review for every module output
  • Run targeted graph sync after each wave and a full refresh at each phase boundary
  • Use when modules are novel, risky, or touch poorly understood integration surfaces
  • 调度前请求用户批准拟议的批次
  • 对每个模块输出执行契约评审和验证评审
  • 每个批次后运行定向图谱同步，每个阶段边界执行全量刷新
  • 适用于模块新颖、存在风险或涉及理解不足的集成面的场景

balanced
(default)

balanced
（默认）

  • Parse plan and graph once at the start of the run
  • Ask for one approval on the execution schedule up front unless the plan changes mid-run
  • Give workers compact execution packets instead of making each worker reread full XML artifacts
  • Run module-local verification per worker, scoped gate reviews per module, and batched integrity checks per wave or phase
  • Run targeted graph sync after each wave and full refresh only at phase boundaries, when drift is suspected, or at final wrap-up
  • 在运行开始时解析一次计划和图谱
  • 除非计划在运行中途变更，否则仅需提前获取一次执行计划的批准
  • 为工作者提供紧凑的执行数据包，而非让每个工作者重新读取完整的XML工件
  • 每个工作者执行模块本地验证，每个模块执行范围化网关评审，每个批次或阶段执行批量完整性检查
  • 每个批次后运行定向图谱同步，仅在阶段边界、怀疑存在漂移或最终收尾时执行全量刷新

fast

fast

  • Use only for mature codebases with strong verification and stable architecture
  • Ask for one approval for the whole run unless a blocker or plan change appears
  • Keep worker packets compact and require only the minimum context needed for exact scope execution
  • Block only on critical scoped review issues during a wave, then batch the deeper integrity audit at phase end or final wrap-up
  • Reserve full refresh for phase completion or final reconciliation
Every module still gets a fresh worker. Do not optimize this workflow by reusing worker sessions across modules.
  • 仅适用于具备强验证机制和稳定架构的成熟代码库
  • 除非出现阻塞问题或计划变更，否则仅需获取一次整个运行的批准
  • 为工作者提供紧凑的数据包，仅包含精确范围执行所需的最小上下文
  • 批次执行期间仅在发现关键范围化评审问题时阻塞，然后在阶段结束或最终收尾时批量执行深度完整性审计
  • 仅在阶段完成或最终协调时执行全量刷新
每个模块仍需分配新的工作者Agent。请勿通过跨模块复用工作者会话来优化此工作流。

Process

执行流程

Step 1: Build the Execution Waves Once

步骤1：一次性构建执行批次

Read 
docs/development-plan.xml
and 
docs/knowledge-graph.xml
once per run, then build the controller view of the execution queue.
  1. Parse pending 
    Phase-N
    and 
    step-N
    entries
  2. Group steps into parallel-safe waves
  3. A step is parallel-safe only if:
    • all of its dependencies are already complete
    • it has a disjoint write scope from every other step in the wave
    • it does not require shared edits to the same integration surface
  4. Choose the execution profile: 
    safe
    , 
    balanced
    , or 
    fast
  5. For each wave, prepare a compact execution packet for every module containing:
    • module ID and purpose
    • target file paths and exact write scope
    • module contract excerpt from 
      docs/development-plan.xml
    • module graph entry excerpt from 
      docs/knowledge-graph.xml
    • dependency contract summaries for every module in 
      DEPENDS
    • module-local verification commands
    • wave-level integration checks that will run after merge
    • expected graph delta fields: imports, exports, annotations, and CrossLinks
Present the proposed waves, selected profile, and packet scopes to the user. In 
safe
, wait for approval before each dispatch. In 
balanced
and 
fast
, one up-front approval is enough unless the plan changes.
每次运行时读取一次
docs/development-plan.xml
和
docs/knowledge-graph.xml
，然后构建控制器视角的执行队列。
  1. 解析待处理的
    Phase-N
    和
    step-N
    条目
  2. 将步骤分组为可并行的安全批次
  3. 仅当满足以下条件时，步骤才是可并行的：
    • 其所有依赖项已完成
    • 与批次中其他步骤的写入范围不重叠
    • 无需对同一集成面进行共享编辑
  4. 选择执行配置文件：
    safe
    、
    balanced
    或
    fast
  5. 为每个批次中的每个模块准备一个紧凑的执行数据包，包含：
    • 模块ID和用途
    • 目标文件路径和精确写入范围
    • 来自
      docs/development-plan.xml
      的模块契约节选
    • 来自
      docs/knowledge-graph.xml
      的模块图谱条目节选
    • DEPENDS
      中每个模块的依赖契约摘要
    • 模块本地验证命令
    • 合并后将运行的批次级集成检查
    • 预期的图谱增量字段：导入、导出、注释和CrossLinks
向用户展示拟议的批次、选定的配置文件和数据包范围。在
safe
模式下，每次调度前需等待批准。在
balanced
和
fast
模式下，除非计划变更，否则仅需提前一次批准即可。

Step 2: Assign Ownership

步骤2：明确所有权分配

Before dispatching, define ownership explicitly:
  • Controller:
    • owns 
      docs/development-plan.xml
    • owns 
      docs/knowledge-graph.xml
    • owns wave packets, phase completion, and commits that touch shared artifacts
  • Worker agent:
    • owns one module or one explicitly bounded slice
    • may edit only that module's source files and module-local tests
    • must not change shared planning artifacts directly
  • Reviewer agent:
    • read-only validation of contract compliance, GRACE markup, imports, graph delta accuracy, and verification evidence
If a worker discovers that a missing module or new dependency is required, stop that worker and ask the user to revise the plan before proceeding. Do not allow silent architectural drift.
调度前，明确定义所有权：
  • 控制器：
    • 拥有
      docs/development-plan.xml
    • 拥有
      docs/knowledge-graph.xml
    • 拥有批次数据包、阶段完成状态，以及涉及共享工件的提交
  • 工作者Agent：
    • 拥有一个模块或一个明确界定的代码片段
    • 仅可编辑该模块的源文件和模块本地测试
    • 不得直接修改共享规划工件
  • 评审者Agent：
    • 只读验证契约合规性、GRACE标记、导入、图谱增量准确性和验证证据
如果工作者发现需要缺失的模块或新的依赖项，停止该工作者并要求用户修订计划后再继续。不允许出现无记录的架构漂移。

Step 3: Dispatch Fresh Worker Agents Per Wave

步骤3：为每个批次调度新的工作者Agent

For each approved wave:
  1. Dispatch one fresh worker agent per module
  2. Give each worker only the execution packet and the files inside its write scope
  3. Require the worker to:
    • generate or update code using the 
      $grace-generate
      protocol
    • preserve MODULE_CONTRACT, MODULE_MAP, CHANGE_SUMMARY, function contracts, and semantic blocks
    • add or update module-local tests only
    • run module-local verification only
    • commit their work after module-local verification passes with format: 
      grace(MODULE_ID): short description

Wave N, Phase M
    • return a result packet with changed files, verification evidence, graph delta proposal, commit hash, and any integration assumptions
对于每个已批准的批次：
  1. 为每个模块调度一个新的工作者Agent
  2. 仅向每个工作者提供执行数据包及其写入范围内的文件
  3. 要求工作者：
    • 使用
      $grace-generate
      协议生成或更新代码
    • 保留MODULE_CONTRACT、MODULE_MAP、CHANGE_SUMMARY、函数契约和语义块
    • 仅添加或更新模块本地测试
    • 仅运行模块本地验证
    • 模块本地验证通过后提交工作，提交格式如下： 
      grace(MODULE_ID): 简短描述

Wave N, Phase M
    • 返回包含已更改文件、验证证据、图谱增量提案、提交哈希和任何集成假设的结果数据包

Step 4: Review with the Smallest Safe Scope

步骤4：以最小安全范围执行评审

After each worker finishes:
  1. Run a scoped contract review against the changed files and execution packet
  2. Run a scoped verification review against the module-local tests and verification evidence
  3. Escalate to a full 
    $grace-reviewer
    audit only when:
    • cross-module drift is suspected
    • the graph delta contradicts the packet or actual imports
    • verification is too weak for the chosen profile
    • a phase boundary audit is due
  4. If issues are found:
    • send the same worker back to fix them
    • re-run only the affected reviews unless escalation is required
  5. Only approved module outputs may move to controller integration
每个工作者完成后：
  1. 针对已更改文件和执行数据包运行范围化契约评审
  2. 针对模块本地测试和验证证据运行范围化验证评审
  3. 仅在以下情况下升级为完整的
    $grace-reviewer
    审计：
    • 怀疑存在跨模块漂移
    • 图谱增量与数据包或实际导入矛盾
    • 验证强度不符合所选配置文件的要求
    • 阶段边界审计到期
  4. 如果发现问题：
    • 将同一工作者派回修复问题
    • 除非需要升级，否则仅重新运行受影响的评审
  5. 仅经过批准的模块输出才可进入控制器集成环节

Step 5: Controller Integration and Batch Graph Sync

步骤5：控制器集成和批量图谱同步

After all modules in the wave are approved:
  1. Integrate the accepted module outputs
  2. Apply graph delta proposals once, centrally, to 
    docs/knowledge-graph.xml
  3. Update 
    docs/development-plan.xml
    step status once per wave
  4. Run targeted 
    $grace-refresh
    against the changed modules and touched dependency surfaces
  5. If targeted refresh reports wider drift, escalate to a full refresh before the next wave
  6. If the wave reveals weak or missing automated checks, use 
    $grace-verification
    before continuing
批次中所有模块均获批准后：
  1. 集成已接受的模块输出
  2. 集中应用一次图谱增量提案到
    docs/knowledge-graph.xml
  3. 每个批次更新一次
    docs/development-plan.xml
    的步骤状态
  4. 针对已更改的模块和涉及的依赖面运行定向
    $grace-refresh
  5. 如果定向刷新报告存在更广泛的漂移，在下一个批次前升级为全量刷新
  6. 如果批次暴露出自动化检查薄弱或缺失的问题，在继续前使用
    $grace-verification

Step 6: Verify by Level

步骤6：分层次验证

Run verification at the smallest level that still protects correctness.
  • Worker level: module-local typecheck, lint, unit tests, and deterministic local assertions
  • Wave level: integration checks only for the merged surfaces touched by the wave
  • Phase level: full suite, full integrity audit, and final graph reconciliation before marking the phase done
Do not run full-repository tests and full-repository graph scans after every successful module unless the risk profile requires it.
在仍能保障正确性的最小层级上运行验证。
  • 工作者层级：模块本地类型检查、代码规范检查、单元测试和确定性本地断言
  • 批次层级：仅对批次涉及的合并面执行集成检查
  • 阶段层级：完整套件、完整完整性审计，以及标记阶段完成前的最终图谱协调
除非风险配置文件要求，否则不要在每个成功模块后运行全仓库测试和全仓库图谱扫描。

Step 7: Controller Shared-Artifact Commits and Report

步骤7：控制器共享工件提交和报告

After each wave, the controller commits only shared artifacts that changed:
  • Update 
    docs/knowledge-graph.xml
    and 
    docs/development-plan.xml
    with wave results
  • Commit with format: 
    grace(graph): sync after wave N

Modules: M-xxx, M-yyy
Worker implementation commits are already done per module in Step 3. Controller commits are only for shared planning artifacts.
After each wave, report:
text
=== WAVE COMPLETE ===
Wave: N
Profile: safe / balanced / fast
Modules: M-xxx, M-yyy
Approved: count/count
Graph sync: targeted passed / targeted fixed / escalated to full refresh
Verification: module-local passed / wave checks passed / follow-up required
Remaining waves: count
每个批次后，控制器仅提交已更改的共享工件：
  • 使用批次结果更新
    docs/knowledge-graph.xml
    和
    docs/development-plan.xml
  • 提交格式如下： 
    grace(graph): sync after wave N

Modules: M-xxx, M-yyy
工作者的实现提交已在步骤3中按模块完成。控制器仅提交共享规划工件。
每个批次后，生成报告：
text
=== 批次完成 ===
Wave: N
Profile: safe / balanced / fast
Modules: M-xxx, M-yyy
Approved: count/count
Graph sync: targeted passed / targeted fixed / escalated to full refresh
Verification: module-local passed / wave checks passed / follow-up required
Remaining waves: count

Dispatch Rules

调度规则

  • Parse shared XML artifacts once per run unless the plan changes
  • Prefer controller-built execution packets over repeated raw XML reads by workers
  • Parallelize only across independent modules, never across unknown coupling
  • Do not let workers invent new architecture
  • Do not let workers edit the same XML planning artifacts in parallel
  • Do not reuse worker sessions across modules; keep workers fresh and packets compact
  • Give every worker exact file ownership and exact success criteria
  • Workers must commit their implementation after verification passes - do not wait for controller
  • Controller commits only shared artifacts (graph, plan), not implementation files
  • Prefer targeted refresh and scoped review during active waves
  • Reserve full reviewer audits and full refresh scans for phase boundaries, drift suspicion, or critical failures
  • If verification is weak, slow down and move to 
    safe
    rather than pretending 
    fast
    is safe
  • 除非计划变更，否则每次运行仅解析一次共享XML工件
  • 优先使用控制器构建的执行数据包，而非让工作者重复读取原始XML
  • 仅在独立模块间并行，绝不在未知耦合的模块间并行
  • 不允许工作者自行设计新架构
  • 不允许工作者并行编辑同一XML规划工件
  • 不跨模块复用工作者会话；保持工作者为新实例，数据包紧凑
  • 为每个工作者明确指定精确的文件所有权和成功标准
  • 工作者必须在验证通过后提交其实现——不要等待控制器
  • 控制器仅提交共享工件（图谱、计划），不提交实现文件
  • 活跃批次执行期间优先使用定向刷新和范围化评审
  • 仅在阶段边界、怀疑存在漂移或出现关键故障时，才进行完整的评审者审计和全量刷新扫描
  • 如果验证机制薄弱，应放缓速度并切换到
    safe
    配置，而非假装
    fast
    配置是安全的

When NOT to Use

不适用场景

  • Only one module remains
  • Steps are tightly coupled and share the same files
  • The plan is still changing frequently
  • The team has not defined reliable module-local verification yet
Use 
$grace-execute
for sequential execution when dependency risk is higher than the parallelism gain.
  • 仅剩一个模块
  • 步骤紧密耦合且共享同一文件
  • 计划仍在频繁变更
  • 团队尚未定义可靠的模块本地验证机制
当依赖风险高于并行收益时，使用
$grace-execute
进行顺序执行。