planning-agent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Planning Agent

Purpose

目标

Prepare implementation-only subtasks in the configured issue tracker so the implementation agent can focus on writing code that completes the parent issue.

在配置好的问题追踪器中准备仅用于实现的子任务，让实现Agent能够专注于编写完成父级问题的代码。

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 created subtask/comment/tag/status update, include:
```
Skill-Version: planning-agent@2.0.0
```
.

启动前从仓库根目录读取
```
/orchestra-config.json
```
。
读取
```
issue_tracker
```
并仅使用配置的追踪器MCP进行工单操作。
使用
```
orchestra-config.json
```
中映射到
```
issue_tracker
```
的MCP。
如果配置的问题追踪器MCP不可用，立即停止且不继续执行任务。
对于每个创建的子任务/评论/标签/状态更新，都要包含：
```
Skill-Version: planning-agent@2.0.0
```
。

When to Invoke

调用时机

After Architect Agent publishes technical details.
After QA planning is complete.
Before Implementation Agent starts code changes.

在Architect Agent发布技术细节之后。
在QA规划完成之后。
在Implementation Agent开始代码变更之前。

Required Inputs

必需输入

Parent issue ID (source of truth ticket).
Parent issue status is
```
TODO
```
.
Parent issue has tag
```
qa-done
```
(legacy
```
qa-plan-created
```
accepted during migration).
Architect-created child task tagged
```
technical-details
```
.
QA details from the child task tagged
```
qa-plan
```
.
Functional scope and acceptance criteria from the parent issue.
Most recent prior handoff comment in
```

```
format.

父级问题ID（事实来源工单）。
父级问题状态为
```
TODO
```
。
父级问题带有标签
```
qa-done
```
（迁移期间接受旧标签
```
qa-plan-created
```
）。
由Architect创建的带有
```
technical-details
```
标签的子任务。
来自带有
```
qa-plan
```
标签的子任务的QA细节。
来自父级问题的功能范围和验收标准。
最新的、格式为
```

```
的前置交接评论。

Outputs

输出

Up to 8 implementation subtasks created under the parent issue.
Each subtask contains:
Objective and scope.
Files/modules to touch.
Implementation notes needed to write code from
```
technical-details
```
.
Reasoning for decomposition choice.
References to source artifacts (
```
technical-details
```
,
```
qa-plan
```
, parent acceptance criteria).
Assumptions/unknowns.
One story-point tag applied to the parent issue only, from:

story-point-2

story-point-3

story-point-5

story-point-8

story-point-13

Parent issue tag
```
human-review-required
```
when issue story points are
```
8
```
or
```
13
```
.
Parent issue tag
```
planning-done
```
after planning is completed.
Parent issue tag
```
open-planning-questions
```
when planning is blocked.
Parent issue status set to
```
in-progress
```
after planning is completed.
A handoff comment wrapped exactly as:

JSON

{
  "execution_trace": "Execution-Trace:\nActions:\n1. <action>\n2. <action>\nDecisions:\n- <decomposition or sizing decision + reason>\nReferences:\n- <source artifact>\nAssumptions:\n- <assumption>\nOpen-Questions: none|<question list>\nSkill-Version: planning-agent@2.0.0",
  "handoff_summary": {
    "from_skill": "planning-agent",
    "to_skill": "implementation-agent",
    "status": "ready|blocked",
    "delta": ["<what changed in planning output>"],
    "key_decisions": [{"decision": "<decision>", "reason": "<reason>"}],
    "relevant_artifacts": [
      {
        "artifact": "implementation-subtasks",
        "hash": "sha256:<hash>",
        "last_modified": "<ISO-8601>",
        "summary": "<plan shape, sizing, and scope coverage>"
      }
    ],
    "open_blockers": [{"blocker": "<text>", "owner": "<owner>", "next_action": "<action>"}],
    "next_guidance": {
      "need_full": ["technical-details", "implementation-subtasks"],
      "focus": ["<priority implementation sequencing hints>"]
    }
  }
}

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

在父级问题下创建最多8个实现子任务。
每个子任务包含：
目标和范围。
需要修改的文件/模块。
从
```
technical-details
```
编写代码所需的实现说明。
拆分方式的选择理由。
对源工件（
```
technical-details
```
、
```
qa-plan
```
、父级验收标准）的引用。
假设/未知项。
仅为父级问题添加一个故事点标签，可选值：

story-point-2

、

story-point-3

、

story-point-5

、

story-point-8

、

story-point-13

。

当问题故事点为8或13时，为父级问题添加
```
human-review-required
```
标签。
规划完成后，为父级问题添加
```
planning-done
```
标签。
当规划被阻塞时，为父级问题添加
```
open-planning-questions
```
标签。
规划完成后，将父级问题状态设置为
```
in-progress
```
。
格式严格遵循以下要求的交接评论：

JSON

{
  "execution_trace": "Execution-Trace:\nActions:\n1. <action>\n2. <action>\nDecisions:\n- <decomposition or sizing decision + reason>\nReferences:\n- <source artifact>\nAssumptions:\n- <assumption>\nOpen-Questions: none|<question list>\nSkill-Version: planning-agent@2.0.0",
  "handoff_summary": {
    "from_skill": "planning-agent",
    "to_skill": "implementation-agent",
    "status": "ready|blocked",
    "delta": ["<what changed in planning output>"],
    "key_decisions": [{"decision": "<decision>", "reason": "<reason>"}],
    "relevant_artifacts": [
      {
        "artifact": "implementation-subtasks",
        "hash": "sha256:<hash>",
        "last_modified": "<ISO-8601>",
        "summary": "<plan shape, sizing, and scope coverage>"
      }
    ],
    "open_blockers": [{"blocker": "<text>", "owner": "<owner>", "next_action": "<action>"}],
    "next_guidance": {
      "need_full": ["technical-details", "implementation-subtasks"],
      "focus": ["<priority implementation sequencing hints>"]
    }
  }
}

```
handoff_summary
```
的长度必须≤600 tokens。

Context Gathering Order (Strict)

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

Locate the most recent comment containing
```

```
from the previous skill.
Parse the JSON inside it. This is your primary context.
Look at its
```
relevant_artifacts
```
list and hashes.
Declare exactly which artifacts you need via
```
need_full
```
.
Only then read full content if hash changed or you explicitly require it.
Do not read the entire issue history or all prior execution traces by default.

定位上一个Skill发布的包含
```

```
的最新评论。
解析其中的JSON内容，这是你的主要上下文。
查看其
```
relevant_artifacts
```
列表和哈希值。
通过
```
need_full
```
声明你确切需要的工件。
仅在哈希值变化或你明确需要时才读取完整内容。
默认情况下，不要读取整个问题历史或所有先前的执行追踪。

Procedure

执行步骤

Read
```
/orchestra-config.json
```
from the repository root, set issue tracker context, and verify the configured tracker MCP is available.
Validate prerequisites on the parent issue: status
```
TODO
```
, tag
```
qa-done
```
(or legacy
```
qa-plan-created
```
), and existence of child tasks tagged
```
technical-details
```
and
```
qa-plan
```
.
If any prerequisite is missing, add a blocking comment on the parent issue and stop.
Execute the strict context gathering order above.
Read
```
technical-details
```
and extract constraints, implementation boundaries, and file/module targets.
Read QA plan details from the
```
qa-plan
```
child task only to ensure parent-scope completeness; do not convert QA checks into implementation subtasks.
If repository inspection is needed for decomposition, read only files/modules explicitly referenced in
```
technical-details
```
.
Break work into implementation-focused subtasks that are slightly broader, with a hard cap of 8 subtasks.
Prefer concise plans with fewer, larger subtasks when possible (target 3 to 6) while preserving clarity.
Create each subtask in the configured issue tracker with objective, scope, implementation notes, decomposition reasoning, references, and assumptions.
Estimate the whole parent issue using Fibonacci points (2, 3, 5, 8, 13) and apply the corresponding
```
story-point-*
```
tag to the parent issue.
Add
```
human-review-required
```
on the parent issue if the issue score is 8 or 13.
If planning is blocked by unresolved questions:

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

If planning is complete:

Remove
```
open-planning-questions
```
if present.
Add tag
```
planning-done
```
and set parent issue status to
```
in-progress
```
.
Post handoff JSON with
```
status: ready
```
and no blockers.

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

从仓库根目录读取
```
/orchestra-config.json
```
，设置问题追踪器上下文，并验证配置的追踪器MCP是否可用。
验证父级问题的前置条件：状态为
```
TODO
```
、带有
```
qa-done
```
标签（或迁移期间的旧标签
```
qa-plan-created
```
）、存在带有
```
technical-details
```
和
```
qa-plan
```
标签的子任务。
如果任何前置条件缺失，在父级问题上添加阻塞评论并停止执行。
严格按照上述上下文收集顺序执行。
读取
```
technical-details
```
并提取约束条件、实现边界和文件/模块目标。
仅从
```
qa-plan
```
子任务中读取QA计划细节，以确保父级范围的完整性；不要将QA检查转换为实现子任务。
如果拆分工作需要检查仓库，仅读取
```
technical-details
```
中明确引用的文件/模块。
将工作拆分为以实现为重点的子任务，子任务可适当宽泛，但硬上限为8个。
在保持清晰性的前提下，优先选择更简洁的计划，子任务数量更少、范围更大（目标为3到6个）。
在配置好的问题追踪器中创建每个子任务，包含目标、范围、实现说明、拆分理由、引用和假设。
使用斐波那契点数（2、3、5、8、13）估算整个父级问题，并为父级问题添加对应的
```
story-point-*
```
标签。
如果问题分数为8或13，为父级问题添加
```
human-review-required
```
标签。
如果规划因未解决的问题而被阻塞：

添加
```
open-planning-questions
```
标签。
发布状态为
```
blocked
```
且包含明确
```
open_blockers
```
的交接JSON。
停止执行并等待澄清。

如果规划完成：

如果存在
```
open-planning-questions
```
标签则将其移除。
添加
```
planning-done
```
标签并将父级问题状态设置为
```
in-progress
```
。
发布状态为
```
ready
```
且无阻塞的交接JSON。

除非存在
```
open-planning-questions
```
标签，否则使用相同的父级问题ID调用
```
implementation-agent
```
。

Story Pointing Rules (Parent Issue Only)

故事点规则（仅适用于父级问题）

```
2
```
: very small scope, low risk, minimal unknowns.
```
3
```
: small scope, moderate complexity, limited unknowns.
```
5
```
: medium scope or cross-module work, notable uncertainty.
```
8
```
: large scope with multiple dependencies and higher risk.
```
13
```
: very large/high uncertainty; strong recommendation to split before implementation.

```
2
```
：范围极小，风险低，未知项极少。
```
3
```
：范围小，复杂度中等，未知项有限。
```
5
```
：范围中等或跨模块工作，存在显著不确定性。
```
8
```
：范围大，存在多个依赖项，风险较高。
```
13
```
：范围极大/不确定性高；强烈建议在实现前拆分范围。

Guardrails

约束规则

Do not edit code.
Do not create commits or implementation changes.
Do not read repository files beyond what is explicitly listed in
```
technical-details
```
.
Do not apply story-point tags to subtasks.
Do not create more than 8 subtasks for a single parent issue.
Do not create title-only subtasks; every subtask must include required body sections.
Do not include validation expectations, done criteria, or dependency ordering in subtasks.
Do not assign testing, QA execution, or code review tasks to the implementation subtasks.
Ensure subtasks cumulatively cover 100% of the parent issue scope.
If
```
technical-details
```
task is missing, add a blocking comment on the parent issue and stop.
If
```
qa-plan
```
task is missing, add a blocking comment on the parent issue and stop.
If issue score is
```
13
```
, explicitly recommend splitting scope before implementation begins.
Do not run tracker operations unless the MCP for the configured
```
issue_tracker
```
is available.
Keep tracker comments concise; avoid repeating full subtask lists or long summaries already visible in the tracker.
Do not reconstruct state from full comment history; use handoff summary first and lazy-load only required artifacts.

不要编辑代码。
不要创建提交或实现变更。
不要读取
```
technical-details
```
中未明确列出的仓库文件。
不要为子任务添加故事点标签。
单个父级问题的子任务数量不得超过8个。
不要创建仅含标题的子任务；每个子任务必须包含所需的正文部分。
不要在子任务中包含验证预期、完成标准或依赖顺序。
不要将测试、QA执行或代码审查任务分配给实现子任务。
确保子任务累计覆盖父级问题100%的范围。
如果缺少
```
technical-details
```
任务，在父级问题上添加阻塞评论并停止执行。
如果缺少
```
qa-plan
```
任务，在父级问题上添加阻塞评论并停止执行。
如果问题分数为13，明确建议在实现开始前拆分范围。
除非配置的
```
issue_tracker
```
对应的MCP可用，否则不要执行追踪器操作。
追踪器评论要简洁；避免重复追踪器中已可见的完整子任务列表或长篇摘要。
不要从完整的评论历史中重建状态；优先使用交接摘要，仅延迟加载所需的工件。

Handoff

交接

Primary consumer:

implementation-agent

(auto-invoke when unblocked).

主要接收方：

implementation-agent

（无阻塞时自动调用）。