eve-plan-implementation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Eve Plan Implementation (Jobs)

Eve计划执行（任务）

Translate a plan document into Eve jobs, parallelize work, and drive review/verification through job phases and dependencies.

Orchestration model: The root epic is the orchestrator — it plans, delegates, and coordinates but does not execute heavy work itself. Phase jobs are sub-orchestrators that break a phase into tasks. Task jobs are workers — each one receives a self-contained description and executes independently with no access to the parent's context.

将计划文档转换为Eve任务，实现工作并行化，并通过任务阶段和依赖关系推动审核/验证。

Orchestration model：根史诗任务是orchestrator——它负责规划、委派和协调，但自身不执行繁重工作。阶段任务是sub-orchestrators，负责将一个阶段拆分为多个任务。任务级任务是workers——每个worker都会收到一份独立完整的描述，并独立执行，无法访问父级上下文。

When to Use

使用场景

A plan/spec exists and the work should be orchestrated as Eve jobs.
The initial job says "use eve-plan-implementation to implement the plan."

已有计划/规范，且工作需要以Eve任务的形式编排执行。
初始任务要求“使用eve-plan-implementation来执行计划”。

Workflow

工作流程

1) Load context (orchestrator)

1) 加载上下文（orchestrator）

Read the plan doc and extract phases, deliverables, and blockers.
If present, read
```
AGENTS.md
```
for repo-specific rules.
Fetch current job context:
bash
```
eve job current --json
```
Stay lightweight: the orchestrator reads just enough to plan the breakdown. Delegate deep analysis (reading large files, exploring code) to worker jobs.

读取计划文档，提取阶段、交付物和阻塞项。
如果存在
```
AGENTS.md
```
文件，读取其中的仓库特定规则。
获取当前任务上下文：
bash
```
eve job current --json
```
保持轻量化：orchestrator仅读取足够信息来规划拆分，将深度分析（读取大文件、探索代码）委派给worker任务。

2) Create or confirm the root epic (orchestrator)

2) 创建或确认根史诗任务（orchestrator）

If the root job does not exist, create one:

bash

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

If a root job already exists, use it as the orchestrator. The root epic never executes implementation work — it creates phase jobs, wires up dependencies, and waits.

如果根任务不存在，则创建一个：

bash

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

如果根任务已存在，则将其用作orchestrator。根史诗任务从不执行具体实现工作——它负责创建阶段任务、关联依赖关系并等待。

3) Break down into phase jobs (sub-orchestrators)

3) 拆分为阶段任务（sub-orchestrators）

Create one child job per plan phase. Each phase job acts as a sub-orchestrator: it breaks its scope into task jobs and coordinates them.

bash

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

Add dependencies so the parent waits on each phase:

bash

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

为每个计划阶段创建一个子任务。每个阶段任务充当sub-orchestrator：将自身范围拆分为任务级任务并进行协调。

bash

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

添加依赖关系，使父任务等待每个阶段完成：

bash

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

4) Create task jobs under each phase (workers)

4) 在每个阶段下创建任务级任务（workers）

Split each phase into 2-6 atomic tasks with clear deliverables.

If a phase has only one task, execute it directly in the phase job rather than creating a child — avoid unnecessary orchestration overhead.

For multi-task phases, create child worker jobs. Each worker description must be self-contained: the executing agent has no access to the parent's context, the plan document, or prior conversation. Include in the description:

The objective and deliverable
Relevant file paths and module names
Any constraints, conventions, or context the worker needs to succeed

bash

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

Make the phase wait on its tasks:

bash

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

将每个阶段拆分为2-6个具有明确交付物的原子任务。

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

对于多任务阶段，创建子worker任务。每个worker的描述必须独立完整：执行agent无法访问父级上下文、计划文档或之前的对话。描述中需包含：

目标和交付物
相关文件路径和模块名称
worker成功执行所需的任何约束、约定或上下文信息

bash

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

设置阶段任务等待其下所有任务完成：

bash

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

5) Parallelize by default

5) 默认并行化

Independent tasks should have no dependencies and run in parallel.
Use
```
blocks
```
only for true sequencing requirements.

独立任务不应有依赖关系，应并行运行。
仅在确实需要顺序执行时使用
```
blocks
```
。

6) Execute tasks and update phases

6) 执行任务并更新阶段状态

Workers pick up task jobs and execute them independently. Each worker:

Reads its own job description for scope and context.
Does the work (reads files, writes code, runs tests).
Reports completion.

bash

eve job update $TASK_JOB_ID --phase active

Workers接收任务级任务并独立执行。每个worker会：

读取自身任务描述以了解范围和上下文。
执行工作（读取文件、编写代码、运行测试）。
报告完成状态。

bash

eve job update $TASK_JOB_ID --phase active

do the work

eve job submit $TASK_JOB_ID --summary "Completed <deliverable>"


If no review is required:
```bash
eve job close $TASK_JOB_ID --reason "Done"

eve job submit $TASK_JOB_ID --summary "Completed <deliverable>"


如果无需审核：
```bash
eve job close $TASK_JOB_ID --reason "Done"

7) Verification and review

7) 验证与审核

Add a dedicated verification job (tests, manual checks) gated after implementation tasks.
Submit the phase job when all tasks are complete.
When all phases complete, submit the root epic for review.

在实现任务之后添加一个专门的验证任务（测试、人工检查）作为关卡。
当所有任务完成后，提交阶段任务。
当所有阶段完成后，提交根史诗任务进行审核。

8) Orchestrator waiting signal

8) Orchestrator等待信号

After an orchestrator (root or phase) creates its child jobs and wires dependencies, it should return a waiting signal. This frees the orchestrator's resources while children execute in parallel:

json

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

当orchestrator（根或阶段级）创建完子任务并关联依赖关系后，应返回一个等待信号。这会在子任务并行执行时释放orchestrator的资源：

json

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

Context Management

上下文管理

Orchestrators should stay lightweight:

Read just enough to plan the decomposition — don't analyze entire codebases.
Push context into child descriptions — file paths, conventions, constraints.
Delegate reading and analysis to workers. A worker that needs to understand a module should read it itself.
Avoid duplicating work — if two tasks need the same context, mention the shared source in both descriptions rather than summarizing it for them.

Orchestrators应保持轻量化：

仅读取必要信息以规划拆分——不要分析整个代码库。
将上下文推入子任务描述——包括文件路径、约定、约束。
将读取和分析工作委派给workers。需要了解某个模块的worker应自行读取该模块。
避免重复工作——如果两个任务需要相同的上下文，在两个描述中都提及共享来源，而不是为它们汇总信息。

Minimal Mapping from Beads to Eve Jobs

Beads到Eve任务的最小映射

Epic -> root job (issue_type via
```
--type
```
if available).
Phase -> child job under the epic.
Task -> child job under the 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 ...

Epic -> 根任务（若支持，可通过
```
--type
```
指定issue_type）。
Phase -> 史诗任务下的子任务。
Task -> 阶段任务下的子任务。

bd dep add

eve job dep add <parent> <child> --type waits_for

bd ready/blocked

eve job dep list <id>

eve job list --phase ...

Optional: Git controls template

可选：Git控制模板

If tasks require code changes on a shared branch:

bash

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

Keep git controls consistent across tasks so all changes land in one PR.

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

bash

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中。