implementation-agent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementation Agent

Purpose

用途

Implement the parent issue by executing planned implementation subtasks and handling PR publication in the same run with token-efficient context loading and auditable stage handoff.

通过执行规划好的实现子任务，并在同一运行流程中处理PR发布，同时采用高效利用token的上下文加载和可审计的阶段交接机制，来实现父级需求。

Runtime Configuration

运行时配置

Read
```
/orchestra-config.json
```
from the repository root before starting.
Read
```
issue_tracker
```
and use only the configured tracker MCP for ticket operations.
Use the MCP mapped to
```
issue_tracker
```
in
```
orchestra-config.json
```
.
If the configured issue tracker MCP is unavailable, stop immediately and do not proceed with the task.
For every task/comment/status update written to the tracker, include:
```
Skill-Version: implementation-agent@2.1.0
```
.
Immediately stop if
```
gh
```
CLI is unavailable.

启动前从仓库根目录读取
```
/orchestra-config.json
```
文件。
读取
```
issue_tracker
```
配置，仅使用已配置的跟踪器MCP进行工单操作。
使用
```
orchestra-config.json
```
中与
```
issue_tracker
```
对应的MCP。
如果配置的问题跟踪器MCP不可用，立即停止任务，不继续执行。
对于写入跟踪器的每一条任务/评论/状态更新，都需包含：
```
Skill-Version: implementation-agent@2.1.0
```
。
如果
```
gh
```
CLI不可用，立即停止任务。

When to Invoke

调用时机

After planning is complete on the parent issue.
After PR review requests implementation rework.

父级需求的规划工作完成后。
PR评审要求对实现进行返工后。

Required Inputs

必要输入

Parent issue ID.
Parent issue status is
```
In-progress
```
.
Parent issue has tag
```
planning-done
```
.
Child subtasks tagged
```
implement
```
.
Most recent prior handoff comment in
```

```
format.

父级需求ID。
父级需求状态为
```
In-progress
```
。
父级需求带有
```
planning-done
```
标签。
子任务带有
```
implement
```
标签。
最新的前置交接评论格式为
```

```
。

Outputs

输出结果

Code changes implementing all completable
```
implement
```
subtasks.
Git branch created as:
```
codex/<issue-id>-<short-description>
```
.
Each completed subtask marked done in the configured issue tracker.
Comment on each incomplete subtask explaining why it was not completed.
Build and lint outcomes recorded in the configured issue tracker as command + pass/fail, with short error excerpts only when failing.
Branch pushed to remote when work is complete.
Pull request created (first pass) or updated (rework pass) and linked to the configured tracker issue.
Parent issue status moved to
```
In review
```
after successful publish/update.
Parent issue tags:
```
implementation-done
```
when implementation is complete.
```
pr-published
```
when PR is created or updated and linked.
```
open-implementation-questions
```
when implementation is blocked.
A handoff comment wrapped exactly as:

JSON

{
  "execution_trace": "Execution-Trace:\nActions:\n1. <action>\n2. <action>\nDecisions:\n- <decision + reason>\nReferences:\n- <source artifact or command>\nAssumptions:\n- <assumption>\nOpen-Questions: none|<question list>\nSkill-Version: implementation-agent@2.1.0",
  "handoff_summary": {
    "from_skill": "implementation-agent",
    "to_skill": "pr-review-agent",
    "status": "ready|blocked",
    "delta": ["<what changed in this implementation pass>"],
    "key_decisions": [{"decision": "<decision>", "reason": "<reason>"}],
    "relevant_artifacts": [
      {
        "artifact": "<artifact name>",
        "hash": "sha256:<hash>",
        "last_modified": "<ISO-8601>",
        "summary": "<short relevance summary>"
      }
    ],
    "open_blockers": [{"blocker": "<text>", "owner": "<owner>", "next_action": "<next action>"}],
    "next_guidance": {
      "need_full": ["<artifact names needed by next skill>"],
      "focus": ["<highest-priority checks for next skill>"],
      "findings": [{"id": "<finding-id>", "file": "<path>", "action": "<required fix/check>"}]
    }
  }
}

```
handoff_summary
```
must be <= 600 tokens.

完成所有可执行
```
implement
```
子任务的代码变更。
创建Git分支，命名格式为：
```
codex/<issue-id>-<short-description>
```
。
在配置的问题跟踪器中标记已完成的子任务为“已完成”。
对每个未完成的子任务添加评论，说明未完成原因。
在配置的问题跟踪器中记录构建和代码检查结果，包含命令及通过/失败状态，仅在失败时添加简短错误片段。
工作完成后将分支推送到远程仓库。
创建（首次提交）或更新（返工提交）Pull Request，并关联到配置的跟踪器需求。
成功发布/更新PR后，将父级需求状态改为
```
In review
```
。
父级需求标签：
实现完成时添加
```
implementation-done
```
标签。
PR创建或更新并关联后添加
```
pr-published
```
标签。
实现被阻塞时添加
```
open-implementation-questions
```
标签。
格式严格符合以下要求的交接评论：

JSON

{
  "execution_trace": "Execution-Trace:\nActions:\n1. <action>\n2. <action>\nDecisions:\n- <decision + reason>\nReferences:\n- <source artifact or command>\nAssumptions:\n- <assumption>\nOpen-Questions: none|<question list>\nSkill-Version: implementation-agent@2.1.0",
  "handoff_summary": {
    "from_skill": "implementation-agent",
    "to_skill": "pr-review-agent",
    "status": "ready|blocked",
    "delta": ["<what changed in this implementation pass>"],
    "key_decisions": [{"decision": "<decision>", "reason": "<reason>"}],
    "relevant_artifacts": [
      {
        "artifact": "<artifact name>",
        "hash": "sha256:<hash>",
        "last_modified": "<ISO-8601>",
        "summary": "<short relevance summary>"
      }
    ],
    "open_blockers": [{"blocker": "<text>", "owner": "<owner>", "next_action": "<next action>"}],
    "next_guidance": {
      "need_full": ["<artifact names needed by next skill>"],
      "focus": ["<highest-priority checks for next skill>"],
      "findings": [{"id": "<finding-id>", "file": "<path>", "action": "<required fix/check>"}]
    }
  }
}

```
handoff_summary
```
的token数必须≤600。

Context Gathering Order (Strict)

上下文收集顺序（严格执行）

Locate the most recent comment containing
```

```
from the previous skill.
Parse the JSON inside it; treat
```
handoff_summary
```
as primary context.
Review
```
relevant_artifacts
```
and hashes first.
Declare exactly which artifacts require full reads with
```
need_full
```
.
Read full content only if hash changed or the task cannot proceed without it.
Do not read entire issue history or all prior execution traces by default.

定位来自上一个skill的最新包含
```

```
的评论。
解析其中的JSON；将
```
handoff_summary
```
作为主要上下文。
优先查看
```
relevant_artifacts
```
和哈希值。
明确声明哪些工件需要通过
```
need_full
```
进行完整读取。
仅当哈希值变化或任务无法继续时，才读取完整内容。
默认情况下，不要读取整个需求历史或所有先前的执行跟踪记录。

Procedure

执行流程

Read
```
/orchestra-config.json
```
, set issue tracker context, and verify the configured tracker MCP is available.
Execute the strict context gathering order above.
Validate prerequisites: parent issue status is
```
In-progress
```
and parent has
```
planning-done
```
.
Determine mode:

```
standard_mode
```
: previous handoff is from planning/earlier implementation stage.

rework_mode

: previous handoff is from

pr-review-agent

and includes

next_guidance.findings

In
```
rework_mode
```
, read only:

```
next_guidance.findings
```
from the review handoff.
affected
```
implement
```
subtasks referenced by those findings.
additional artifacts only if explicitly declared in
```
need_full
```
.

Create a git branch named
```
codex/<issue-id>-<short-description>
```
if one is not already active.
Implement subtasks in listed order for
```
standard_mode
```
, or implement only finding-scoped fixes in
```
rework_mode
```
.
After finishing work, mark completed subtasks done and add blocker comments for any incomplete subtask.
Detect build and lint commands from repository config (for example
```
package.json
```
,
```
Makefile
```
, or equivalent).
Run build and lint commands and record concise results.
If implementation is blocked:

Add
```
open-implementation-questions
```
.
Post handoff JSON with
```
status: blocked
```
and concrete
```
open_blockers
```
.
Stop and wait for clarifications.

If implementation is complete:

Remove
```
open-implementation-questions
```
if present.
Add tag
```
implementation-done
```
.
Optionally keep legacy tag
```
implemented
```
during migration windows.
Push branch to origin (
```
git push -u origin <branch>
```
).
If linked PR already exists (typical
```
rework_mode
```
), update the existing PR context/comments.
Otherwise create a PR targeting the base branch and include tracker issue ID/URL.
Ensure parent issue tag
```
pr-published
```
is present.
Add concise parent issue comment with PR URL and short review request.
Move parent issue status to
```
In review
```
.
Post handoff JSON with
```
to_skill: pr-review-agent
```
and
```
status: ready
```
.

Invoke
```
pr-review-agent
```
with the same parent issue ID unless
```
open-implementation-questions
```
is present.

读取
```
/orchestra-config.json
```
，设置问题跟踪器上下文，验证配置的跟踪器MCP是否可用。
严格执行上述上下文收集顺序。
验证前置条件：父级需求状态为
```
In-progress
```
且带有
```
planning-done
```
标签。
确定运行模式：

```
standard_mode
```
：前置交接来自规划阶段或早期实现阶段。

rework_mode

：前置交接来自

pr-review-agent

且包含

next_guidance.findings

。

在
```
rework_mode
```
下，仅读取：

评审交接中的
```
next_guidance.findings
```
。
这些问题涉及的
```
implement
```
子任务。
仅当
```
need_full
```
中明确声明时，才读取额外工件。

如果不存在对应分支，创建名为
```
codex/<issue-id>-<short-description>
```
的Git分支。
```
standard_mode
```
下按列表顺序实现子任务，
```
rework_mode
```
下仅实现问题范围的修复。
工作完成后，标记已完成的子任务为“已完成”，并为每个未完成的子任务添加阻塞原因评论。
从仓库配置中检测构建和代码检查命令（例如
```
package.json
```
、
```
Makefile
```
或等效文件）。
运行构建和代码检查命令，并记录简洁结果。
如果实现被阻塞：

添加
```
open-implementation-questions
```
标签。
发布状态为
```
blocked
```
的交接JSON，并包含具体的
```
open_blockers
```
。
停止任务，等待澄清。

如果实现完成：

若存在
```
open-implementation-questions
```
标签则移除。
添加
```
implementation-done
```
标签。
在迁移窗口期可保留旧标签
```
implemented
```
。
将分支推送到远程仓库（
```
git push -u origin <branch>
```
）。
如果已存在关联PR（常见于
```
rework_mode
```
），更新现有PR的上下文/评论。
否则创建针对基准分支的PR，并包含跟踪器需求ID/链接。
确保父级需求带有
```
pr-published
```
标签。
在父级需求中添加简洁评论，包含PR链接和简短评审请求。
将父级需求状态改为
```
In review
```
。
发布目标skill为
```
pr-review-agent
```
、状态为
```
ready
```
的交接JSON。

除非存在
```
open-implementation-questions
```
标签，否则使用同一父级需求ID调用
```
pr-review-agent
```
。

Guardrails

约束规则

Do not start implementation unless parent issue has
```
planning-done
```
and status
```
In-progress
```
.
Do not execute subtasks that are not tagged
```
implement
```
.
Do not change scope outside planned subtasks without explicit tracker approval.
Do not leave incomplete subtasks without a blocker comment.
Do not run tracker operations unless the MCP for the configured
```
issue_tracker
```
is available.
Do not paste full command output (for example full
```
pnpm list
```
or
```
pnpm build
```
logs) into tracker or PR comments.
Do not reconstruct state by reading full comment history; use handoff summary first, then lazy-load only required artifacts.
Do not create or update a PR if there are no committed changes from this implementation pass.
Do not move issue status to
```
In review
```
until PR creation/update succeeds.
Ensure the PR references the correct tracker issue ID and URL.

除非父级需求带有
```
planning-done
```
标签且状态为
```
In-progress
```
，否则不启动实现工作。
不执行未标记
```
implement
```
的子任务。
未经跟踪器明确批准，不得超出规划子任务的范围。
不得留下未添加阻塞原因评论的未完成子任务。
配置的
```
issue_tracker
```
对应的MCP不可用时，不执行跟踪器操作。
不得将完整命令输出（例如完整的
```
pnpm list
```
或
```
pnpm build
```
日志）粘贴到跟踪器或PR评论中。
不得通过读取完整评论历史来重建状态；优先使用交接摘要，仅延迟加载必要的工件。
如果本次实现没有提交任何变更，不得创建或更新PR。
除非PR创建/更新成功，否则不得将需求状态改为
```
In review
```
。
确保PR关联正确的跟踪器需求ID和链接。

Handoff

交接对象

Primary consumer:

pr-review-agent

(auto-invoke when unblocked).

主要消费方：

pr-review-agent

（未阻塞时自动调用）。