plan-graph

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Plan Graph

Plan Graph（计划图谱）

Turn plan markdown into a concrete graph instead of hand-waving over the document structure. This skill is for plan-driven orchestration, not for live steering once workers are already moving.

将计划 Markdown 转换为具体的图结构，而不是在文档结构上含糊其辞。该 skill 用于基于计划的编排，而非在 worker 已经开始运行后进行实时引导。

Handoff Contract

交接契约

For plan-backed orchestration, treat this as the canonical handoff bundle:

the exact plan selection: explicit
```
--plan
```
paths, or
```
--plans-root
```
plus
```
--glob
```
any explicit
```
--depends source:target
```
edges
the resolved
```
graph_id
```
```
selection_hash
```
```
snapshot_path
```
and
```
state_dir
```
when a snapshot exists on disk

Carry the same selection when auto-managed reuse is acceptable. Carry the explicit

graph_id

when downstream work must attach to one exact saved slot regardless of selection context.

对于基于计划的编排，应将以下内容视为标准交接包：

精确的计划选择：显式
```
--plan
```
路径，或
```
--plans-root
```
加
```
--glob
```
所有显式
```
--depends source:target
```
边
解析出的
```
graph_id
```
```
selection_hash
```
磁盘上存在 snapshot 时的
```
snapshot_path
```
和
```
state_dir
```

如果允许自动管理并复用状态，请沿用相同的选择。如果下游工作必须附加到一个精确的已保存 slot，无论选择上下文如何，都请沿用显式

graph_id

。

Canonical Inputs

标准输入

Default search root:

```
./.codex/plans
```
in the current working directory
override with
```
--plans-root
```
or set
```
CODEX_PLANS_ROOT
```
or
```
CODEX_HOME
```

Expected frontmatter shape:

```
name
```
```
overview
```
```
todos
```
```
isProject
```

Expected todo shape:

```
id
```
```
content
```
```
status
```

Expected todo statuses in the current local corpus:

```
pending
```
```
in_progress
```
```
completed
```

The parser is intentionally tolerant of imperfect plans such as empty names, empty overviews, and

todos: []

. Treat those as warnings unless the calling task explicitly wants strict validation.

Recommended file shape below the frontmatter:

repeat the plan name as the top-level heading

add short markdown sections such as

Execution Notes

Constraints

References

, or

Operator Guidance

keep the body focused on narrative guidance that frontmatter cannot express cleanly
write the body as something a subagent can read end-to-end to understand intent, boundaries, success criteria, and implementation guidance without relying only on the frontmatter

Do not duplicate the overview paragraph or the todo list in the markdown body unless a caller explicitly wants that redundancy. The frontmatter remains the machine-readable source of truth for graphing and status.

When creating new plan files, start from

references/plan-template.plan.md

and adapt it instead of inventing the body structure ad hoc.

默认搜索根目录：

当前工作目录中的
```
./.codex/plans
```
使用
```
--plans-root
```
覆盖
或设置
```
CODEX_PLANS_ROOT
```
或
```
CODEX_HOME
```

预期的 frontmatter 结构：

```
name
```
```
overview
```
```
todos
```
```
isProject
```

预期的 todo 结构：

```
id
```
```
content
```
```
status
```

当前本地语料中的预期 todo 状态：

```
pending
```
```
in_progress
```
```
completed
```

解析器有意容忍不完整的计划，例如名称为空、概述为空以及

todos: []

。除非调用任务明确要求严格验证，否则应将其视为警告。

frontmatter 下推荐的正文结构：

将计划名称重复为顶级标题

添加简短的 Markdown 章节，例如

Execution Notes

、

Constraints

、

References

或

Operator Guidance

让正文专注于 frontmatter 无法清晰表达的叙述性指导
将正文写成 subagent 能够从头读到尾的内容，使其可以理解意图、边界、成功标准和实施指导，而不必只依赖 frontmatter

除非调用方明确需要这种冗余，否则不要在 Markdown 正文中重复概述段落或 todo 列表。对于图构建和状态跟踪，frontmatter 仍然是机器可读的事实来源。

创建新计划文件时，应从

references/plan-template.plan.md

开始并进行调整，而不是临时臆造正文结构。

Durable State

持久化状态

Do not rely on implicit thread or agent metadata for cross-agent persistence.

If you pass
```
--graph-id <id>
```
or set
```
GRAPH_ID
```
, the tool uses that explicit graph slot.
If you omit
```
GRAPH_ID
```
, the tool reuses the latest slot for the same resolved plan selection and rewrites that snapshot from current plan files before reporting.
A plan selection means both the resolved absolute plan paths and any explicit
```
--depends
```
edges.
If no saved snapshot matches, it creates a managed graph slot automatically from that selection and writes a snapshot for later reuse.

Persist shared state under

./.codex/plan-graphs/<resolved-graph-id>/

by default.

Override the snapshot root with

--state-dir

CODEX_PLAN_GRAPHS_ROOT

, or

CODEX_HOME

```
--write-state
```
forces persistence for an explicit graph id.
If you use an explicit
```
--graph-id
```
without
```
--write-state
```
, only treat
```
snapshot_path
```
as real when the command output actually includes it.

This survives across root agent work, spawned workers, explorers, and later resumptions far better than thread-local context.

不要依赖隐式 thread 或 agent metadata 实现跨 Agent 持久化。

如果传入
```
--graph-id <id>
```
或设置
```
GRAPH_ID
```
，工具将使用该显式 graph slot。
如果省略
```
GRAPH_ID
```
，工具会复用同一已解析计划选择对应的最新 slot，并在输出报告前根据当前计划文件重写该 snapshot。
计划选择同时包含解析后的绝对计划路径和所有显式
```
--depends
```
边。
如果没有匹配的已保存 snapshot，工具会根据该选择自动创建一个受管理的 graph slot，并写入 snapshot 供后续复用。

默认在

./.codex/plan-graphs/<resolved-graph-id>/

下持久化共享状态。

使用

--state-dir

、

CODEX_PLAN_GRAPHS_ROOT

或

CODEX_HOME

覆盖 snapshot 根目录。

```
--write-state
```
会强制为显式 graph id 持久化状态。
如果使用显式
```
--graph-id
```
但未指定
```
--write-state
```
，只有在命令输出实际包含
```
snapshot_path
```
时，才应将其视为真实存在。

与 thread-local context 相比，这种方式能更好地跨 root Agent 工作、派生 worker、explorer 以及后续恢复而持续存在。

Workflow

工作流

Choose the plan set.
- Use explicit
```
--plan
```
  paths when the task already points at specific plans.
- Otherwise search the default or overridden plans root with
```
--glob
```
  .
- If you need to author new plan files first, copy
```
references/plan-template.plan.md
```
  and then fill in the frontmatter plus the detailed markdown body.
- Or use
```
scripts/plan_graph.py generate --breadth N --depth M
```
  to scaffold a plan set and persisted graph state automatically.
Validate the plan corpus first.
- Run
```
scripts/plan_graph.py validate
```
  .

Validation covers both parse quality and graph integrity: duplicate plan names or slugs, duplicate todo ids, empty todo content, self-dependencies, dependency cycles, and orphaned plan nodes.
In a multi-plan selection, every selected plan should participate in at least one dependency edge. If a plan is documentation-only or an umbrella wrapper, either link it explicitly or leave it out of the active graph selection.
Because inter-plan edges connect the source plan's final todo to the target plan's first todo, wrapper or project-summary plans usually work best as downstream rollup nodes unless their todo sequence is intentionally written to gate all child work.
- Use
```
--strict
```
  only when malformed plans should fail the workflow.

Start with a quick summary when you need orientation.
- Run
```
scripts/plan_graph.py summary
```
  .
- This gives the per-plan status plus handoff state without flooding the operator with the full DAG.
Build the graph when structure matters.
- Run
```
scripts/plan_graph.py dag
```
  for a full text or JSON DAG.
- Run a visual pass with
```
--format mermaid
```
  whenever you need to confirm roots, parallel branches, blocked lanes, or whether the umbrella project plan is incorrectly acting like an execution node.
- Mermaid output intentionally omits the plain-text handoff footer, so pair it with a text or JSON
```
dag
```
  /
```
frontier
```
  run when you also need the resolved graph id, blockers, or handoff state.
- Add
```
--depends source:target
```
  edges when plan-to-plan sequencing is known but not stored in frontmatter.
- In text mode, this command prints
```
handoff state
```
  lines for downstream handoff.
Surface launchable work.
- Run
```
scripts/plan_graph.py frontier --lanes N --max-depth M
```
  .
- This gives the next executable lane per plan after accounting for completed todos and explicit upstream plan dependencies.
- In text mode, this command also includes the same
```
handoff state
```
  footer.
Visually check the graph before handing it off.
- Render the graph with
```
scripts/plan_graph.py dag --format mermaid
```
  .
- Confirm the critical path, any parallel lanes, and every
```
blocked_by
```
  relationship shown by the matching text
```
dag
```
  or
```
frontier
```
  run.
- If the visual graph shows a documentation-only wrapper plan acting like a runnable lane, either remove it from the active selection or add explicit dependencies so it is no longer an orphaned node.
Inspect what already exists before minting new work.
- Run
```
scripts/plan_graph.py plans
```
  to see existing plan files.
- Run
```
scripts/plan_graph.py graphs
```
  to see saved graph snapshots.
- Run
```
scripts/plan_graph.py delete-plan
```
  to preview matched plan-file deletion, then rerun with
```
--yes
```
  to actually delete them.
- Use
```
--format json
```
  when you need machine-readable
```
graph_id
```
  ,
```
selection_hash
```
  ,
```
snapshot_path
```
  ,
```
state_dir
```
  ,
```
plan_count
```
  ,
```
edge_count
```
  , or
```
selected_plan_paths
```
  for downstream operators.
Preserve exact targeting across subagents.
- Rerun any
```
--plan
```
  /
```
--glob
```
  selection plus the same
```
--depends
```
  edges to resolve the same auto-managed graph slot.
- For strict targeting, pass an explicit
```
--graph-id
```
  (or reuse the resolved one from prior output).
- Prefer
```
--format json
```
  or
```
graphs --format json
```
  whenever you need the exact
```
graph_id
```
  ,
```
selection_hash
```
  ,
```
state_dir
```
  , or
```
snapshot_path
```
  .
Persist or reuse the shared snapshot when the graph will feed other skills.
- In the common case, rerun the same plan selection and let the tool auto-reuse the saved slot.
- Hand the resolved
```
GRAPH_ID
```
  to
```
subagent-graph
```
  ,
```
dag
```
  , or
```
helm
```
  only when another tool or agent truly needs that exact slot.

选择计划集合。
- 当任务已经指向特定计划时，使用显式
```
--plan
```
  路径。
- 否则，使用
```
--glob
```
  搜索默认或覆盖后的 plans root。
- 如果需要先编写新的计划文件，请复制
```
references/plan-template.plan.md
```
  ，然后填写 frontmatter 和详细的 Markdown 正文。
- 或使用
```
scripts/plan_graph.py generate --breadth N --depth M
```
  自动生成计划集合和持久化的图状态。
首先验证计划集合。
- 运行
```
scripts/plan_graph.py validate
```
  。

验证同时涵盖解析质量和图完整性：重复的计划名称或 slug、重复的 todo id、todo 内容为空、自依赖、依赖环，以及孤立的计划节点。
在多计划选择中，每个选中的计划都应至少参与一条依赖边。如果某个计划仅用于文档或是 umbrella wrapper，要么显式链接它，要么将其排除在活动图选择之外。
由于计划间的边会将源计划的最后一个 todo 连接到目标计划的第一个 todo，wrapper 或 project-summary 计划通常最适合作为下游 rollup 节点，除非其 todo 序列有意被编写为 gate 所有子项工作。
- 仅当格式错误的计划应导致工作流失败时，才使用
```
--strict
```
  。

需要快速掌握整体情况时，先获取摘要。
- 运行
```
scripts/plan_graph.py summary
```
  。
- 它会提供每个计划的状态和 handoff state，而不会用完整 DAG 淹没操作者。
当结构很重要时构建图。
- 运行
```
scripts/plan_graph.py dag
```
  获取完整的文本或 JSON DAG。
- 每当需要确认根节点、并行分支、阻塞通道，或 umbrella project plan 是否错误地充当执行节点时，都使用
```
--format mermaid
```
  进行可视化检查。
- Mermaid 输出有意省略纯文本 handoff footer，因此当还需要解析后的 graph id、blockers 或 handoff state 时，请配合文本或 JSON 格式的
```
dag
```
  /
```
frontier
```
  运行。
- 当已知计划间的执行顺序但尚未存储在 frontmatter 中时，添加
```
--depends source:target
```
  边。
- 在文本模式下，该命令会为下游交接打印
```
handoff state
```
  行。
找出可启动的工作。
- 运行
```
scripts/plan_graph.py frontier --lanes N --max-depth M
```
  。
- 在考虑已完成的 todo 和显式上游计划依赖后，它会给出每个计划的下一条可执行通道。
- 在文本模式下，该命令还会包含相同的
```
handoff state
```
  footer。
在交接前对图进行可视化检查。
- 使用
```
scripts/plan_graph.py dag --format mermaid
```
  渲染图。
- 确认关键路径、所有并行通道，以及匹配的文本
```
dag
```
  或
```
frontier
```
  结果中显示的每条
```
blocked_by
```
  关系。
- 如果可视化图显示仅用于文档的 wrapper plan 表现得像可运行通道，则将其从活动选择中移除，或添加显式依赖，使其不再是孤立节点。
在创建新工作之前检查已有内容。
- 运行
```
scripts/plan_graph.py plans
```
  查看现有计划文件。
- 运行
```
scripts/plan_graph.py graphs
```
  查看已保存的 graph snapshot。
- 运行
```
scripts/plan_graph.py delete-plan
```
  预览匹配的计划文件删除操作，然后使用
```
--yes
```
  重新运行以实际删除。
- 当下游操作需要机器可读的
```
graph_id
```
  、
```
selection_hash
```
  、
```
snapshot_path
```
  、
```
state_dir
```
  、
```
plan_count
```
  、
```
edge_count
```
  或
```
selected_plan_paths
```
  时，使用
```
--format json
```
  。
在 subagent 之间保持精确目标。
- 重新运行任何
```
--plan
```
  /
```
--glob
```
  选择以及相同的
```
--depends
```
  边，以解析同一个自动管理的 graph slot。
- 对于严格定位，请传入显式
```
--graph-id
```
  ，或复用之前输出中解析出的 graph id。
- 每当需要精确的
```
graph_id
```
  、
```
selection_hash
```
  、
```
state_dir
```
  或
```
snapshot_path
```
  时，优先使用
```
--format json
```
  或
```
graphs --format json
```
  。
当图将提供给其他 skills 时，持久化或复用共享 snapshot。
- 在常见情况下，重新运行相同的选择计划，并让工具自动复用已保存的 slot。
- 仅当另一个工具或 Agent 确实需要该精确 slot 时，才将解析出的
```
GRAPH_ID
```
  交给
```
subagent-graph
```
  、
```
dag
```
  或
```
helm
```
  。

Commands

命令

Use the bundled CLI instead of re-parsing plan files ad hoc:

bash

python /Users/zackjackson/.codex/skills/plan-graph/scripts/plan_graph.py generate --plans-root ./.codex/plans --graph-id example-graph --title-prefix "Example Plan" --slug-prefix example-plan --breadth 2 --depth 2 --todo-count 3
python /Users/zackjackson/.codex/skills/plan-graph/scripts/plan_graph.py generate --plans-root ./.codex/plans --state-dir ./.codex/plan-graphs --title-prefix "Migration Plan" --slug-prefix migration-plan --breadth 3 --depth 2 --format json
python /Users/zackjackson/.codex/skills/plan-graph/scripts/plan_graph.py plans --glob '*.plan.md'
python /Users/zackjackson/.codex/skills/plan-graph/scripts/plan_graph.py graphs
python /Users/zackjackson/.codex/skills/plan-graph/scripts/plan_graph.py delete-plan --plan "$PLAN_PATH"
python /Users/zackjackson/.codex/skills/plan-graph/scripts/plan_graph.py delete-plan --plan "$PLAN_PATH" --yes
python /Users/zackjackson/.codex/skills/plan-graph/scripts/plan_graph.py validate --glob '*.plan.md'
python /Users/zackjackson/.codex/skills/plan-graph/scripts/plan_graph.py summary --plan "$PLAN_PATH"
python /Users/zackjackson/.codex/skills/plan-graph/scripts/plan_graph.py summary --glob '*subagent*.plan.md' --format json
python /Users/zackjackson/.codex/skills/plan-graph/scripts/plan_graph.py dag --plan "$PLAN_PATH" --format mermaid
python /Users/zackjackson/.codex/skills/plan-graph/scripts/plan_graph.py dag --plans-root ./.codex/plans --glob '*subagent*.plan.md' --depends source:target --format mermaid
python /Users/zackjackson/.codex/skills/plan-graph/scripts/plan_graph.py dag --plan "$PLAN_PATH"
python /Users/zackjackson/.codex/skills/plan-graph/scripts/plan_graph.py frontier --glob '*subagent*.plan.md' --lanes 3 --max-depth 2 --format json
python /Users/zackjackson/.codex/skills/plan-graph/scripts/plan_graph.py frontier --glob '*subagent*.plan.md' --lanes 3 --max-depth 2 --graph-id subagents-v1 --write-state

使用随附的 CLI，而不是临时重复解析计划文件：

bash

python /Users/zackjackson/.codex/skills/plan-graph/scripts/plan_graph.py generate --plans-root ./.codex/plans --graph-id example-graph --title-prefix "Example Plan" --slug-prefix example-plan --breadth 2 --depth 2 --todo-count 3
python /Users/zackjackson/.codex/skills/plan-graph/scripts/plan_graph.py generate --plans-root ./.codex/plans --state-dir ./.codex/plan-graphs --title-prefix "Migration Plan" --slug-prefix migration-plan --breadth 3 --depth 2 --format json
python /Users/zackjackson/.codex/skills/plan-graph/scripts/plan_graph.py plans --glob '*.plan.md'
python /Users/zackjackson/.codex/skills/plan-graph/scripts/plan_graph.py graphs
python /Users/zackjackson/.codex/skills/plan-graph/scripts/plan_graph.py delete-plan --plan "$PLAN_PATH"
python /Users/zackjackson/.codex/skills/plan-graph/scripts/plan_graph.py delete-plan --plan "$PLAN_PATH" --yes
python /Users/zackjackson/.codex/skills/plan-graph/scripts/plan_graph.py validate --glob '*.plan.md'
python /Users/zackjackson/.codex/skills/plan-graph/scripts/plan_graph.py summary --plan "$PLAN_PATH"
python /Users/zackjackson/.codex/skills/plan-graph/scripts/plan_graph.py summary --glob '*subagent*.plan.md' --format json
python /Users/zackjackson/.codex/skills/plan-graph/scripts/plan_graph.py dag --plan "$PLAN_PATH" --format mermaid
python /Users/zackjackson/.codex/skills/plan-graph/scripts/plan_graph.py dag --plans-root ./.codex/plans --glob '*subagent*.plan.md' --depends source:target --format mermaid
python /Users/zackjackson/.codex/skills/plan-graph/scripts/plan_graph.py dag --plan "$PLAN_PATH"
python /Users/zackjackson/.codex/skills/plan-graph/scripts/plan_graph.py frontier --glob '*subagent*.plan.md' --lanes 3 --max-depth 2 --format json
python /Users/zackjackson/.codex/skills/plan-graph/scripts/plan_graph.py frontier --glob '*subagent*.plan.md' --lanes 3 --max-depth 2 --graph-id subagents-v1 --write-state

Boundaries

边界

Use
```
subagent-graph
```
after the plan graph is known and you need launch waves, ownership, and merge sequencing.
Use
```
dag
```
when you only need the current frontier, blocked lanes, or plan progress. The
```
dag
```
skill is the frontier/status companion, not the full DAG renderer.
Use
```
helm
```
when workers are already active and the problem is operational steering.
```
delete-plan
```
removes matched plan files only. It does not prune saved graph snapshots.
```
generate
```
is for scaffolding plan files and a matching saved graph slot. It is not a substitute for execution planning after real todo content is known.

Read

references/cursor-plan-format.md

when you need the exact frontmatter assumptions, the on-disk state layout, or the saved-slot matching rules.

在 plan graph 已明确，并且需要启动波次、所有权分配和合并顺序时，使用
```
subagent-graph
```
。
仅需当前 frontier、阻塞通道或计划进度时，使用
```
dag
```
。
```
dag
```
skill 是 frontier/status 的配套工具，而不是完整的 DAG renderer。
当 worker 已经活跃且问题属于操作层面的引导时，使用
```
helm
```
。
```
delete-plan
```
仅删除匹配的计划文件，不会清理已保存的 graph snapshot。
```
generate
```
用于搭建计划文件和匹配的已保存 graph slot，不能替代在明确真实 todo 内容后进行执行规划。

当需要了解确切的 frontmatter 假设、磁盘状态布局或已保存 slot 的匹配规则时，请阅读

references/cursor-plan-format.md

。