beo-planning

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Beo Planning

Beo 规划

Overview

概述

Planning is the research-and-decompose phase. It takes

CONTEXT.md

from exploring and turns locked decisions into a credible implementation strategy and an execution-ready current phase.

规划是调研与拆解阶段，它接收探索阶段产出的

CONTEXT.md

，将已锁定的决策转化为可落地的实现策略和可直接执行的当前阶段方案。

Key Terms

核心术语

current phase: the slice being prepared now for validation and execution
single-phase: one closed loop is enough to deliver the feature safely
multi-phase: the feature needs 2-4 intentional slices, and only the current one should be prepared now
phase plan: the whole-feature sequence for multi-phase work; it is not the same thing as the current-phase contract

current phase（当前阶段）：当前正在准备验证和执行的工作切片
single-phase（单阶段）：只需一个闭环即可安全交付功能
multi-phase（多阶段）：功能需要2-4个明确的工作切片，当前仅需准备当前阶段的内容
phase plan（阶段规划）：多阶段工作的全功能交付序列，和当前阶段契约不是同一概念

Default Planning Loop

默认规划循环

Use this happy-path loop before diving into the deeper operations file:

confirm
```
CONTEXT.md
```
exists and decisions are truly locked
retrieve prior learnings and critical patterns
run focused discovery
write
```
approach.md
```
decide
```
single-phase
```
vs
```
multi-phase
```
write
```
plan.md
```
, and
```
phase-plan.md
```
if needed
define the current phase with
```
phase-contract.md
```
map the current phase into stories
create only the beads needed for the current phase
hand off to validation

Reach for

references/planning-operations.md

when you need the exact artifact order, approval wording, dependency wiring, or high-stakes review procedure.

Outputs:

A
```
discovery.md
```
document with the implementation landscape
An
```
approach.md
```
document with the chosen strategy, alternatives, and risk map
A
```
plan.md
```
summary that explains the plan in human-readable form
An optional
```
phase-plan.md
```
when the feature should unfold across multiple phases
A
```
phase-contract.md
```
defining the current phase as a closed loop with entry/exit state
A
```
story-map.md
```
breaking the current phase into narrative slices
Task beads in the bead graph with dependencies wired and story context embedded
A risk classification for each task

Core principle: Plan once, execute many. Every minute spent shaping the feature and the current phase saves confused implementation later.

在深入查看操作文件前，优先使用这个标准流程：

确认
```
CONTEXT.md
```
已存在且决策确实已锁定
调取历史经验和关键模式
开展针对性调研
编写
```
approach.md
```
判定采用
```
single-phase
```
还是
```
multi-phase
```
编写
```
plan.md
```
，如需要同步编写
```
phase-plan.md
```
通过
```
phase-contract.md
```
定义当前阶段
为当前阶段映射用户故事
仅创建当前阶段所需的bead
移交到验证环节

当你需要明确的产出物顺序、审批措辞、依赖关联或是高风险评审流程时，可查阅

references/planning-operations.md

。

产出物：

包含实现全貌的
```
discovery.md
```
文档
包含选定策略、备选方案和风险地图的
```
approach.md
```
文档
以通俗易懂的语言说明规划内容的
```
plan.md
```
摘要
功能需要跨多阶段交付时可选产出
```
phase-plan.md
```
将当前阶段定义为具备准入/准出状态的闭环的
```
phase-contract.md
```
将当前阶段拆解为叙事切片的
```
story-map.md
```
bead图谱中的任务bead，已关联依赖并嵌入故事上下文
每个任务的风险分类

核心原则：一次规划，多次执行。花在梳理功能和当前阶段上的每一分钟，都能避免后续开发过程中的混乱。

Core Planning Model

核心规划模型

Planning operates at these levels:

text

Whole Feature
  → Discovery
  → Approach
  → Plan Summary
  → Optional Phase Plan
  → Current Phase
  → Stories
  → Beads

Do not jump from research straight to beads.

If one believable closed loop is enough, stay single-phase and prepare that phase directly.

If the full feature is too large, too vague, or too sequential to fit one safe loop, create a

phase-plan.md

and prepare only the current phase for execution.

规划按以下层级开展：

text

全功能
  → 调研
  → 实现方案
  → 规划摘要
  → 可选阶段规划
  → 当前阶段
  → 用户故事
  → Bead

不要直接从调研跳转到bead创建。

如果一个可靠的闭环就足够交付，就采用单阶段模式直接准备该阶段即可。

如果全功能体量太大、太模糊或是顺序性太强，无法适配单个安全闭环，就创建

phase-plan.md

，仅准备当前阶段的执行内容。

Planning Modes

规划模式

Planning supports two modes:

single-phase: one believable closed loop can deliver the feature safely
multi-phase: the feature unfolds across 2-4 meaningful capability slices, and only the current phase should be prepared now

Use the simplest mode that keeps the work understandable and execution-safe.

规划支持两种模式：

single-phase（单阶段）：一个可靠的闭环即可安全交付功能
multi-phase（多阶段）：功能需要拆分为2-4个有实际意义的能力切片交付，当前仅需准备当前阶段的内容

优先使用能保证工作可理解、执行安全的最简单模式。

When a Phase Plan Is Required

何时需要阶段规划

Create

phase-plan.md

when any of these are true:

a single phase would become a vague work bucket
the feature naturally unfolds across multiple capability slices
story count would exceed 4 if forced into one phase
the work has a clear unlock sequence where one slice must become true before later slices matter
the team should prepare only the next slice while intentionally deferring later work

Do not create

phase-plan.md

just because the feature is moderately sized. If one clear closed loop can still explain the work, stay single-phase.

满足以下任意条件时需要创建

phase-plan.md

：

单阶段会变成模糊的工作桶
功能天然需要跨多个能力切片交付
如果强制塞进单个阶段，用户故事数量会超过4个
工作有明确的解锁顺序，必须先完成某个切片，后续切片才有意义
团队只需准备下一个切片，有意推迟后续工作

不要仅仅因为功能体量中等就创建

phase-plan.md

。如果单个清晰的闭环仍能覆盖工作内容，就保持单阶段模式。

Mini Example

简单示例

Single-phase example:

Phase: "A user can submit feedback and the team can review it in the admin panel."

Stories:

Capture feedback submissions reliably
Display submitted feedback for review

Beads:

Create the feedback persistence model and write path
Add submission validation and success/error states
Build the admin read view for submitted feedback

Multi-phase example:

Whole feature: "Inbound messages are received safely, normalized, routed, and made operationally visible."

Phase plan:

Accept inbound payloads safely
Normalize and persist them consistently
Route them into the right workflow and add operational visibility

Current phase contract and story map describe only Phase 1 until that phase is complete.

单阶段示例：

阶段： "用户可以提交反馈，团队可以在管理后台查看反馈。"

用户故事：

可靠采集反馈提交内容
展示已提交的反馈供审核

Bead：

创建反馈持久化模型和写入路径
新增提交校验和成功/错误状态
开发管理后台已提交反馈的查看页

多阶段示例：

全功能： "入站消息可被安全接收、标准化、路由，并具备运营可见性。"

阶段规划：

安全接收入站 payload
统一标准化并持久化
路由到正确工作流并新增运营可见性

当前阶段契约和故事映射仅描述阶段1的内容，直到该阶段完成。

Prerequisites

前置条件

Default checks:

bash

cat .beads/artifacts/<feature-name>/CONTEXT.md 2>/dev/null
br show <EPIC_ID> --json
cat .beads/critical-patterns.md 2>/dev/null

Load

references/planning-operations.md

when you need the exact planning-mode selection rules, artifact order, or handoff details.

<HARD-GATE> If `CONTEXT.md` does not exist, do not invent requirements here. First verify whether the feature was explored under a different slug or path. If no trustworthy context exists, route back to `beo-exploring`. </HARD-GATE>

默认检查项：

bash

cat .beads/artifacts/<feature-name>/CONTEXT.md 2>/dev/null
br show <EPIC_ID> --json
cat .beads/critical-patterns.md 2>/dev/null

当你需要明确的规划模式选择规则、产出物顺序或是移交细节时，可查阅

references/planning-operations.md

。

<HARD-GATE> 如果`CONTEXT.md`不存在，不要在此处虚构需求。首先确认该功能是否在其他别名或路径下完成过探索。如果不存在可信的上下文，退回`beo-exploring`阶段。 </HARD-GATE>

Phase 0: Learnings Retrieval

阶段0：经验调取

Mandatory. Before any research, check institutional memory.

Default retrieval sequence:

query indexed learnings if QMD is available
read
```
.beads/critical-patterns.md
```
if it exists
fall back to flat-file learnings search only when richer retrieval is unavailable or insufficient
write down what actually matters for this plan

If relevant patterns exist:

note them explicitly
embed them into the approach and plan
carry them into affected task descriptions
prevent re-solving known problems

Relevant learnings must influence both the chosen implementation approach and any decision about whether the work stays single-phase or becomes multi-phase.

强制要求。开展任何调研前，先查看团队历史经验。

默认调取顺序：

如果有QMD可查询索引化的历史经验
如果存在
```
.beads/critical-patterns.md
```
则查阅该文件
仅当更丰富的调取方式不可用或不足时，才 fallback 到平文件经验搜索
记录对本次规划实际有用的内容

如果存在相关模式：

明确标注出来
嵌入到实现方案和规划中
同步到受影响的任务描述中
避免重复解决已知问题

相关经验必须同时影响选定的实现方案，以及单阶段/多阶段模式的决策。

Phase 1: Discovery

阶段1：调研

Goal-oriented research to understand the implementation landscape. Launch 2-4 parallel research subagents (Architecture, Pattern, Constraint, External) when the feature is broad enough to benefit from parallel discovery; otherwise research inline. Synthesize findings into

.beads/artifacts/<feature-name>/discovery.md

See

references/discovery-guide.md

for detailed agent descriptions and synthesis format.

Discovery findings are inputs to

approach.md

; they are not the final plan by themselves.

目标导向的调研，用于了解实现全貌。如果功能覆盖面足够广，可启动2-4个并行调研子Agent（架构、模式、约束、外部依赖）来提升效率，否则直接 inline 调研。将结论整理到

.beads/artifacts/<feature-name>/discovery.md

。

查看

references/discovery-guide.md

获取详细的Agent说明和结论整理格式。

调研结论是

approach.md

的输入，本身不是最终规划。

Phase 2: Approach Synthesis

阶段2：实现方案整合

Write

.beads/artifacts/<feature-name>/approach.md

This artifact explains:

what the feature needs to make true
what the codebase already provides
what is missing or risky
the recommended implementation strategy
alternatives considered
the risk map
whether the work should stay single-phase or become multi-phase

Use

references/approach-template.md

approach.md

is the strategy artifact.

plan.md

remains the human-readable planning summary.

编写

.beads/artifacts/<feature-name>/approach.md

。

该产出物需要说明：

功能需要达成的目标
代码库已提供的能力
缺失的能力或存在的风险
推荐的实现策略
考虑过的备选方案
风险地图
工作应采用单阶段还是多阶段模式

使用

references/approach-template.md

模板。

approach.md

是策略类产出物，

plan.md

是通俗易懂的规划摘要。

Phase 3: Whole-Feature Phase Planning (Optional but Required for Multi-Phase Work)

阶段3：全功能阶段规划（可选，但多阶段工作必须提供）

If the feature is multi-phase, write

.beads/artifacts/<feature-name>/phase-plan.md

The phase plan must explain:

the whole-feature goal
why one phase is not enough
the 2-4 meaningful phases
what becomes true after each phase
why the order makes sense
which phase should be prepared now

Use

references/phase-plan-template.md

<HARD-GATE> If the work is clearly multi-phase, do not skip `phase-plan.md`. Do not prepare the current phase as if it were the whole feature. If you are unsure whether it is truly multi-phase, resolve that uncertainty in `approach.md` before creating current-phase beads. </HARD-GATE>

如果功能是多阶段交付，编写

.beads/artifacts/<feature-name>/phase-plan.md

。

阶段规划必须说明：

全功能目标
单阶段不足以交付的原因
2-4个有实际意义的阶段
每个阶段完成后达成的目标
阶段顺序的合理性
当前需要准备的阶段

使用

references/phase-plan-template.md

模板。

<HARD-GATE> 如果工作明确是多阶段，不要跳过`phase-plan.md`。不要把当前阶段当作全功能来准备。如果你不确定是否真的是多阶段，先在`approach.md`中解决这个不确定性，再创建当前阶段的bead。 </HARD-GATE>

Phase 3.5: Multi-Phase Planning Approval

阶段3.5：多阶段规划审批

planning_mode = multi-phase

, get explicit user approval for the whole-feature phase sequence and the selected current phase before handing off to validation.

This approval is about planning shape, not execution readiness.

It confirms:

the feature should be treated as multi-phase
the phase order is believable
the selected current phase is the right first / next slice
later phases are intentionally deferred

This does not replace validation approval. Validation approval still happens later and applies only to execution readiness for the current phase.

<HARD-GATE> If the user has not explicitly approved the multi-phase sequence and current-phase selection, do not hand off to `beo-validating`. If the user is confused or hesitant, tighten the phase framing first: revise `phase-plan.md`, `approach.md`, or current-phase naming before asking again. </HARD-GATE>

如果

planning_mode = multi-phase

，在移交验证前，需要获得用户对全功能阶段序列和选定的当前阶段的明确批准。

这个审批是针对规划结构的，不是针对执行就绪性的。

它确认：

该功能应该按多阶段处理
阶段顺序合理
选定的当前阶段是正确的第一个/下一个切片
后续阶段是有意推迟的

这个审批不替代验证审批。验证审批仍会在后续开展，仅针对当前阶段的执行就绪性。

<HARD-GATE> 如果用户没有明确批准多阶段序列和当前阶段选择，不要移交到`beo-validating`。如果用户有困惑或犹豫，先收紧阶段框架：修改`phase-plan.md`、`approach.md`或是当前阶段命名后再重新申请。 </HARD-GATE>

Phase 4: Current Phase Contract

阶段4：当前阶段契约

Before creating beads, define the current phase as a closed loop.

Write to

.beads/artifacts/<feature-name>/phase-contract.md

using

references/phase-contract-template.md

phase-contract.md

always describes the current phase being prepared now, not the whole feature.

The current phase contract must answer, in plain language:

Why this phase exists now
What the entry state is
What the exit state is
What the simplest demo story is
What this phase unlocks next
What is explicitly out of scope
What signals would force a pivot

创建bead前，将当前阶段定义为一个闭环。

使用

references/phase-contract-template.md

模板编写

.beads/artifacts/<feature-name>/phase-contract.md

。

phase-contract.md

始终描述当前正在准备的阶段，不是全功能。

当前阶段契约必须用通俗易懂的语言回答：

为什么现在要做这个阶段
准入状态是什么
准出状态是什么
最简单的演示故事是什么
这个阶段会解锁什么后续能力
明确不在范围内的内容
哪些信号会触发调整方向

Rules for a good current phase contract

优质当前阶段契约的规则

The exit state must be observable, not aspirational
The phase must close a meaningful small loop by itself
The demo story must prove the phase is real
If the phase fails, the team should know whether to debug locally or rethink the larger plan

If you cannot explain the current phase in 3-5 simple sentences, the phase is not ready. Revise

approach.md

plan.md

, or

phase-plan.md

before moving on.

<HARD-GATE> If `phase-contract.md` does not exist, do not create beads. Define the current phase first. If a draft exists but the exit state is vague, fix the contract instead of pushing uncertainty into bead descriptions. </HARD-GATE>

准出状态必须是可观测的，不是预期性的
阶段本身必须能闭环一个有意义的小循环
演示故事必须能证明阶段成果真实有效
如果阶段失败，团队应该知道是要本地调试还是重新考虑更大的规划

如果你无法用3-5句简单的话说明当前阶段，说明阶段还没准备好。先修改

approach.md

、

plan.md

或是

phase-plan.md

再继续。

<HARD-GATE> 如果`phase-contract.md`不存在，不要创建bead。先定义当前阶段。如果已有草稿但准出状态模糊，先修改契约，不要把不确定性推到bead描述里。 </HARD-GATE>

Phase 5: Current Phase Story Mapping

阶段5：当前阶段故事映射

Break the current phase into Stories, not "plans inside a phase."

Write to

.beads/artifacts/<feature-name>/story-map.md

using

references/story-map-template.md

story-map.md

maps the internal narrative of the current phase only. If later phases exist, they remain deferred in

phase-plan.md

将当前阶段拆解为用户故事，而不是「阶段内的计划」。

使用

references/story-map-template.md

模板编写

.beads/artifacts/<feature-name>/story-map.md

。

story-map.md

仅映射当前阶段的内部叙事。如果有后续阶段，仍保留在

phase-plan.md

中推迟处理。

Story rules

故事规则

Every story must state:

Purpose
Why now
Contributes to (which exit-state statement)
Creates (code, contract, data, capability)
Unlocks (what later stories can now do)
Done looks like (observable finish line)

每个故事必须说明：

用途
为什么现在做
贡献于（哪条准出状态说明）
产出（代码、契约、数据、能力）
解锁（后续可以开展哪些故事）
完成标准（可观测的结束节点）

Story quality checks

故事质量检查

Story 1 must have an obvious reason to exist first
Every story must unlock or de-risk a later story, or directly close part of the exit state
If all stories complete, the phase exit state should hold
If a story cannot answer "what does this unlock?" it is probably not a real story

第一个故事必须有明确的优先开展的理由
每个故事必须能解锁或降低后续故事的风险，或是直接完成部分准出状态
如果所有故事都完成，阶段准出状态应该达成
如果一个故事回答不了「这能解锁什么？」，那它大概率不是一个真实的故事

Story count guidance

故事数量指引

Typical current phase: 2-4 stories
Small current phase: 1-2 stories
Large current phase: revise the phase shape instead of creating 5+ stories

Stories are the human-readable narrative. Beads come after.

<HARD-GATE> If `story-map.md` does not exist, do not create beads. Map the current phase stories first. If stories exist informally in `plan.md` but not as a real map, promote them into `story-map.md` before decomposition. </HARD-GATE>

典型当前阶段：2-4个故事
小型当前阶段：1-2个故事
大型当前阶段：调整阶段结构，不要创建5个以上的故事

故事是通俗易懂的叙事，之后才是bead。

<HARD-GATE> 如果`story-map.md`不存在，不要创建bead。先映射当前阶段的故事。如果故事已经零散写在`plan.md`里但没有形成正式的映射，先把它们迁移到`story-map.md`再拆解。 </HARD-GATE>

Phase 6: Multi-Perspective Check (HIGH-Stakes Only)

阶段6：多视角检查（仅高风险场景）

Only for HIGH-stakes features: multiple HIGH-risk components, core architecture, auth flows, data model changes, or anything with a large blast radius. For standard features, skip to Phase 7.

Load

references/planning-operations.md

for the exact multi-perspective review procedure and prompt.

仅适用于高风险功能：包含多个高风险组件、核心架构、鉴权流程、数据模型变更，或是任何影响范围大的内容。标准功能直接跳到阶段7。

查阅

references/planning-operations.md

获取明确的多视角评审流程和提示词。

Phase 7: Task Bead Creation

阶段7：任务Bead创建

Convert current-phase plan tasks into bead graph entries.

Load

references/planning-operations.md

for the exact create/write/wire/validate sequence, priority mapping, and handoff-safe checkpointing rules.

<HARD-GATE> After all beads are created, read every bead back and verify. No bead may be handed off without passing the checklist in `references/bead-creation-guide.md`. </HARD-GATE>

将当前阶段规划的任务转化为bead图谱条目。

查阅

references/planning-operations.md

获取明确的创建/编写/关联/验证流程、优先级映射和移交安全检查点规则。

<HARD-GATE> 所有bead创建完成后，逐一审读验证。没有通过`references/bead-creation-guide.md`中检查清单的bead不得移交。 </HARD-GATE>

Story-to-Bead Decomposition Rules

故事到Bead的拆解规则

See

references/bead-creation-guide.md

for decomposition rules. Key points: one story becomes 1-3 beads, no bead spans multiple stories, 4+ beads means the story may be too large.

For multi-phase work, create beads for the current phase only. Do not pre-create execution beads for future phases in this planning model.

拆解规则见

references/bead-creation-guide.md

。核心要点：一个故事拆分为1-3个bead，单个bead不能跨多个故事，超过4个bead说明故事可能太大。

多阶段工作仅创建当前阶段的bead，不要在这个规划模型中提前创建后续阶段的执行bead。