eve-plan-implementation

Eve 计划实施（Jobs）

将计划文档转换为 Eve jobs，并行开展工作，并通过 job 阶段和依赖关系推进审查与验证。

编排模型：根 epic 是编排者——负责规划、分派和协调，但不亲自执行繁重工作。阶段 job 是子编排者，负责将阶段拆分为任务。任务 job 是执行者——每个任务都会收到一份自包含的说明，并在无法访问父级上下文的情况下独立执行。

适用场景

• 已有计划／规范，需要将工作编排为 Eve jobs。
• 初始 job 指示“使用 eve-plan-implementation 实施计划”。

工作流

1) 加载上下文（编排者）

• 阅读计划文档，提取阶段、交付成果和阻塞项。
• 如果存在，阅读 AGENTS.md，了解仓库专属规则。
• 获取当前 job 上下文：

  eve job current --json
  

• 保持轻量：编排者只需阅读足够的信息来规划拆分即可。 将深入分析（阅读大型文件、探索代码）委派给执行 job。

2) 创建或确认根 epic（编排者）

如果根 job 尚不存在，则创建一个：

eve job create \
  --project $EVE_PROJECT_ID \
  --description "Implement <plan name>" \
  --review human \
  --phase backlog

如果根 job 已存在，则将其用作编排者。根 epic 绝不执行实施工作——它负责创建阶段 job、设置依赖关系并等待。

3) 拆分为阶段 job（子编排者）

为计划中的每个阶段创建一个子 job。每个阶段 job 都充当子编排者： 将其范围拆分为任务 job 并协调这些任务。

eve job create \
  --project $EVE_PROJECT_ID \
  --parent $EVE_JOB_ID \
  --description "Phase: <name>. Deliverable: <artifact/result>" \
  --phase ready

添加依赖关系，让父级等待各个阶段：

eve job dep add $EVE_JOB_ID $PHASE_JOB_ID --type waits_for

4) 在每个阶段下创建任务 job（执行者）

将每个阶段拆分为 2-6 个边界明确、交付成果清晰的原子任务。

如果某个阶段只有一个任务，则直接在阶段 job 中执行，而不要创建子 job——避免不必要的编排开销。

对于包含多个任务的阶段，创建子执行 job。每个执行者说明都必须 自包含：执行 Agent 无法访问父级上下文、计划文档或之前的对话。说明中应包含：

• 目标和交付成果
• 相关文件路径和模块名称
• 执行者成功完成任务所需的约束、约定或上下文

eve job create \
  --project $EVE_PROJECT_ID \
  --parent $PHASE_JOB_ID \
  --description "Task: <objective>. Deliverable: <result>. Files: <paths>. Context: <anything the worker needs>" \
  --phase ready

让阶段等待其任务完成：

eve job dep add $PHASE_JOB_ID $TASK_JOB_ID --type waits_for

5) 默认并行执行

• 独立任务之间不应设置依赖关系，应并行运行。
• 仅在确实需要按顺序执行时使用 blocks。

6) 执行任务并更新阶段

执行者领取任务 job 后独立执行。每个执行者：

1. 阅读自己的 job 说明，了解范围和上下文。
2. 开展工作（阅读文件、编写代码、运行测试）。
3. 报告完成情况。

eve job update $TASK_JOB_ID --phase active
# do the work
eve job submit $TASK_JOB_ID --summary "Completed <deliverable>"

如果不需要审查：

eve job close $TASK_JOB_ID --reason "Done"

7) 验证与审查

• 添加专门的验证 job（测试、手动检查），并设置为在实施任务之后执行。
• 所有任务完成后，提交阶段 job。
• 所有阶段完成后，提交根 epic 以供审查。

8) 编排者等待信号

编排者（根级或阶段级）创建子 job 并设置依赖关系后，应返回等待信号。这样可以释放编排者的资源，让子 job 并行执行：

{
  "eve": {
    "status": "waiting",
    "summary": "Spawned child jobs and added waits_for relations"
  }
}

上下文管理

编排者应保持轻量：

• 只阅读足以规划拆分的信息——不要分析整个代码库。
• 将上下文写入子 job 说明——包括文件路径、约定和约束。
• 将阅读和分析工作委派给执行者。需要了解某个模块的执行者应自行阅读该模块。
• 避免重复劳动——如果两个任务需要相同的上下文，应在两份说明中注明共同的信息来源，而不是替它们总结。

Beads 到 Eve Jobs 的最简映射

• Epic → 根作业（如果可用，通过 --type 设置 issue_type）。
• Phase → Epic 下的子作业。
• Task → Phase 下的子作业。
• bd dep add → eve job dep add <parent> <child> --type waits_for
• bd ready/blocked → eve job dep list <id> + eve job list --phase ...

可选：Git 控制模板

如果任务需要在共享分支上进行代码更改：

eve job create \
  --project $EVE_PROJECT_ID \
  --description "Task: <objective>" \
  --git-ref main \
  --git-ref-policy explicit \
  --git-branch feature/<name> \
  --git-create-branch if_missing \
  --git-commit required \
  --git-push on_success

在所有任务中保持 Git 控制一致，确保所有更改都进入同一个 PR。