Back to Details

beo-router

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Beo Router

Beo Router

Overview

概述

The router is the entry point for every beo session. It bootstraps the workspace, detects current state, and routes to the correct pipeline skill.
Core principle: Always know where you are before deciding where to go.
路由是每个beo会话的入口点。它负责引导初始化工作区、检测当前状态，并路由到正确的流水线skill。
核心原则：在决定去向之前，先明确你当前所处的位置。

Key Terms

关键术语

  • instant: single-file or similarly tiny work, well-scoped, typically under 30 minutes, with no meaningful planning ambiguity
  • current phase: the slice being prepared or executed now; in multi-phase work this is narrower than the whole feature
  • single-phase: one closed loop can safely deliver the feature
  • multi-phase: the feature needs 2-4 intentional slices, and only one slice should be prepared now
  • feature complete: no later phases remain and the final execution scope has passed review
  • instant：单文件或类似的小型工作，范围清晰，通常耗时不超过30分钟，没有明显的规划歧义
  • current phase：当前正在准备或执行的工作片段；在多阶段工作中，其范围小于整个功能的总范围
  • single-phase：通过一个闭环即可安全交付功能
  • multi-phase：功能需要2-4个有意拆分的工作片段，当前仅需准备一个片段
  • feature complete：没有后续待完成阶段，最终执行范围已经过评审

Default Router Loop

默认路由循环

Use this happy-path loop before loading deeper reference material:
  1. confirm the workspace is initialized and healthy
  2. check for 
    HANDOFF.json
  3. identify the active epic, if any
  4. inspect the core artifacts for that feature
  5. classify the current state
  6. report the state in human terms
  7. load exactly one next skill
Reach for 
references/router-operations.md
when you need the exact command sequence, instant-path scaffolding details, or doctor-mode mechanics.
在加载更深入的参考材料之前，请先使用这个正常流程的循环：
  1. 确认工作区已初始化且运行正常
  2. 检查是否存在
    HANDOFF.json
  3. 识别当前活跃的史诗（epic，如有）
  4. 检查该功能的核心 artifacts
  5. 对当前状态进行分类
  6. 用自然语言上报当前状态
  7. 仅加载下一个需要的skill
当你需要确切的命令序列、instant路径脚手架细节或诊断模式机制时，请查阅
references/router-operations.md
。

Router Default Rule

路由默认规则

If the current pipeline phase is unclear, use 
beo-router
before loading any other beo skill. Do not guess the phase from memory, partial artifacts, or the last conversational turn alone.
如果当前流水线阶段不明确，在加载任何其他beo skill之前先使用
beo-router
。 不要仅凭记忆、不完整的artifacts或上一轮对话内容猜测当前阶段。

Minimal Bootstrap Fallback

最小引导 fallback 方案

If router reference files are unavailable, do the minimum safe sequence manually:
  1. Check 
    .beads/HANDOFF.json
  2. List open epics
  3. Inspect the active epic and its task graph
  4. Check whether 
    CONTEXT.md
    , 
    approach.md
    , 
    phase-contract.md
    , and 
    story-map.md
    exist
  5. Report the current state, then route to the next matching skill
如果路由参考文件不可用，请手动执行最小安全操作序列：
  1. 检查
    .beads/HANDOFF.json
  2. 列出所有开放的史诗
  3. 检查活跃史诗及其任务图谱
  4. 检查是否存在
    CONTEXT.md
    、
    approach.md
    、
    phase-contract.md
    和
    story-map.md
  5. 上报当前状态，然后路由到匹配的下一个skill

Skill Catalog

Skill 目录

#SkillOne-line descriptionLoad when...
1
beo-router
This file. Bootstrap, state detection, routing.Starting any session
2
beo-exploring
Socratic dialogue → lock decisions → CONTEXT.mdFeature request is vague or new
3
beo-planning
Research + synthesis → 
discovery.md
+ 
approach.md
+ optional 
phase-plan.md
+ current-phase contract/story/beads		Decisions are locked (CONTEXT.md exists)
4
beo-validating
Verify current phase contract, story map, and bead graph (8 dimensions)Stories and beads exist; prove execution-readiness
5
beo-swarming
Launch + tend worker pool via Agent Mail + bvBeads validated; execute at scale (3+ independent tasks)
6
beo-executing
Single worker loop: claim → build prompt → implement → verify → reportSpawned by swarming, or direct for ≤2 tasks
7
beo-reviewing
5 parallel review agents (P1/P2/P3) + artifact verification + UATFinal execution scope complete; quality gate before close
8
beo-compounding
Capture learnings → critical-patterns.mdFeature shipped; extract patterns/decisions/failures
9
beo-debugging
Root-cause analysis for blocked beads and execution failuresAgent stuck, bead blocked, unexpected error
10
beo-dream
Periodic consolidation of learnings across featuresLearnings stale (>30 days or 3+ since last)
11
beo-writing-skills
TDD-for-skills: create and pressure-test beo skillsImproving or creating beo skills
#Skill单行描述加载时机
1
beo-router
即本文档。负责引导初始化、状态检测、路由。启动任何会话时
2
beo-exploring
苏格拉底式对话 → 锁定决策 → 生成CONTEXT.md功能需求模糊或为新需求时
3
beo-planning
调研 + 信息整合 → 生成
discovery.md
+ 
approach.md
+ 可选的
phase-plan.md
+ 当前阶段合同/故事/beads		决策已锁定（CONTEXT.md已存在）时
4
beo-validating
验证当前阶段合同、故事地图和bead图谱（8个维度）故事和beads已存在；验证是否可开始执行
5
beo-swarming
通过Agent Mail + bv启动 + 管理工作池beads已验证；需要大规模执行（3个以上独立任务）时
6
beo-executing
单工作者循环：认领任务 → 构建prompt → 实现 → 验证 → 上报由swarming启动，或任务数≤2时直接调用
7
beo-reviewing
5个并行评审agent（P1/P2/P3） + artifact验证 + UAT最终执行范围已完成；收尾前的质量门禁
8
beo-compounding
沉淀经验 → 生成critical-patterns.md功能已上线；提取模式/决策/失败经验时
9
beo-debugging
针对阻塞的bead和执行失败进行根因分析Agent卡住、bead阻塞、出现意外错误时
10
beo-dream
定期整合跨功能的经验沉淀经验沉淀已过时（超过30天或自上次整合后新增3个以上经验）时
11
beo-writing-skills
Skill的测试驱动开发：创建和压力测试beo skill改进或创建beo skill时

Phase 0: Workspace Bootstrap

阶段0：工作区初始化引导

Run once per session. Skip if 
.beads/
already exists and is healthy.
Default bootstrap sequence:
bash
undefined
每个会话运行一次。如果
.beads/
已存在且运行正常可跳过。
默认初始化引导序列：
bash
undefined

Inspect the workspace

检查工作区

ls .beads/ 2>/dev/null
ls .beads/ 2>/dev/null

Initialize only when missing

仅当目录不存在时初始化

br init
br init

Verify the CLI and workspace health

验证CLI和工作区健康状态

br --version br doctor

If `.beads/` exists and `br doctor` is clean, continue. If health is unclear or bootstrap behaves unexpectedly, then load `references/router-operations.md` for the full recovery and doctor-mode playbook.
br --version br doctor

如果`.beads/`存在且`br doctor`检查无问题，可继续执行后续步骤。如果健康状态不明确或初始化引导出现异常，请加载`references/router-operations.md`查看完整的恢复和诊断模式操作手册。

Phase 1: State Detection

阶段1：状态检测

Determine the current state of work by querying the bead graph.
通过查询bead图谱确定当前工作状态。

Step 1: Check for HANDOFF.json

步骤1：检查HANDOFF.json

bash
cat .beads/HANDOFF.json 2>/dev/null
If HANDOFF.json exists, go to Phase 3: Resume.
bash
cat .beads/HANDOFF.json 2>/dev/null
如果HANDOFF.json存在，进入阶段3：恢复会话。

Step 2: Detect Active Feature

步骤2：检测活跃功能

bash
undefined
bash
undefined

List all epics including in_progress and closed (filter in application logic)

列出所有史诗，包括进行中和已关闭的（在应用逻辑中过滤）

br list --type epic -a --json

Parse the output:
- **No epics** → New feature request → go to Phase 2
- **One open epic** → Active feature → go to Step 3
- **Multiple open epics** → Ask user which feature to work on
br list --type epic -a --json

解析输出：
- **无史诗** → 新功能需求 → 进入阶段2
- **1个开放史诗** → 活跃功能 → 进入步骤3
- **多个开放史诗** → 询问用户要处理哪个功能

Step 3: Assess Feature Progress

步骤3：评估功能进度

For the active epic, gather full state:
bash
undefined
针对活跃史诗，收集完整状态：
bash
undefined

Get epic details

获取史诗详情

br show <EPIC_ID> --json

Extract the immutable `slug: <feature_slug>` line from the epic description. Use that slug for all artifact existence checks below.

```bash
br show <EPIC_ID> --json

从史诗描述中提取不可变的`slug: <feature_slug>`行，后续所有artifact存在性检查都使用这个slug。

```bash

List tasks under this epic (canonical enumeration; see pipeline-contracts.md)

列出该史诗下的所有任务（标准枚举方式，见pipeline-contracts.md）

br dep list <EPIC_ID> --direction up --type parent-child --json
br dep list <EPIC_ID> --direction up --type parent-child --json

Check graph health (scoped to active epic)

检查图谱健康状态（限定在活跃史诗范围内）

bv --robot-triage --graph-root <EPIC_ID> --format json
bv --robot-triage --graph-root <EPIC_ID> --format json

Check what's actionable

检查可执行的任务

bv --robot-next --format json br ready --json br blocked --json
bv --robot-next --format json br ready --json br blocked --json

Check planning artifacts exist

检查规划类artifact是否存在

cat .beads/artifacts/<feature-name>/CONTEXT.md 2>/dev/null cat .beads/artifacts/<feature-name>/discovery.md 2>/dev/null cat .beads/artifacts/<feature-name>/approach.md 2>/dev/null cat .beads/artifacts/<feature-name>/phase-plan.md 2>/dev/null cat .beads/artifacts/<feature-name>/phase-contract.md 2>/dev/null cat .beads/artifacts/<feature-name>/story-map.md 2>/dev/null
undefined
cat .beads/artifacts/<feature-name>/CONTEXT.md 2>/dev/null cat .beads/artifacts/<feature-name>/discovery.md 2>/dev/null cat .beads/artifacts/<feature-name>/approach.md 2>/dev/null cat .beads/artifacts/<feature-name>/phase-plan.md 2>/dev/null cat .beads/artifacts/<feature-name>/phase-contract.md 2>/dev/null cat .beads/artifacts/<feature-name>/story-map.md 2>/dev/null
undefined

Step 4: Classify Feature State

步骤4：分类功能状态

See 
references/state-routing.md
for the full routing table. At minimum, distinguish these practical states:
  • context_locked_needs_planning
  • approach_ready_needs_phase_decision
  • phase_plan_ready_needs_current_phase_validation
  • current_phase_planned
  • current_phase_in_execution
  • current_phase_complete_more_phases_remain
  • final_phase_complete_ready_for_review
  • feature_complete
If 
phase-plan.md
exists, treat 
phase-contract.md
and 
story-map.md
as current-phase artifacts, not whole-feature artifacts.
完整路由表见
references/state-routing.md
。至少要区分以下实用状态：
  • context_locked_needs_planning
  • approach_ready_needs_phase_decision
  • phase_plan_ready_needs_current_phase_validation
  • current_phase_planned
  • current_phase_in_execution
  • current_phase_complete_more_phases_remain
  • final_phase_complete_ready_for_review
  • feature_complete
如果存在
phase-plan.md
，则将
phase-contract.md
和
story-map.md
视为当前阶段的artifact，而非全功能的artifact。

Step 5: Report State

步骤5：上报状态

Before routing, always report the current state to the user:
text
Feature: <epic title>
Mode: <single-phase | multi-phase | unknown>
Current phase: <n>/<total or unknown> - <phase name if known>
State: <state from table>
Progress: <closed>/<total> tasks (<in_progress> in progress)
Blockers: <count> (<details if any>)
Next action: Loading <skill name>...
在路由之前，始终要向用户上报当前状态：
text
功能：<epic title>
模式：<single-phase | multi-phase | unknown>
当前阶段：<n>/<total or unknown> - <已知阶段名>
状态：<上表中的状态>
进度：<已完成>/<总> 任务（<进行中数量> 进行中）
阻塞项：<数量>（如有详情可补充）
下一步操作：正在加载 <skill name>...

Phase 2: New Feature

阶段2：新功能

When no active feature exists and the user has a request:
当没有活跃功能且用户提出需求时：

Step 1: Create the Epic

步骤1：创建史诗

Default sequence:
bash
br create "<feature-name>" -t epic -p 1 --json
Save the returned epic ID for all downstream operations, then preserve the immutable slug using 
../reference/references/slug-protocol.md
.
Load 
references/router-operations.md
when you need the exact slug-storage procedure or instant-path scaffolding details.
默认序列：
bash
br create "<feature-name>" -t epic -p 1 --json
保存返回的史诗ID用于所有后续操作，然后按照
../reference/references/slug-protocol.md
的要求保存不可变的slug。
当你需要确切的slug存储流程或instant路径脚手架细节时，请加载
references/router-operations.md
。

Step 2: Classify Request Complexity

步骤2：分类需求复杂度

SignalClassificationPath
Single file change, well-scoped, <30 mininstantCreate task directly, route to 
beo-executing
2-3 files, clear scope, <2 hourslightweightRoute to 
beo-exploring
(quick-depth pass, then planning)
Multi-file, needs research, >2 hoursstandardRoute to 
beo-exploring
Ambiguous, needs clarificationunclearRoute to 
beo-exploring
Error, blocker, failure symptomsdebugRoute to 
beo-debugging
信号分类路径
单文件修改、范围清晰、耗时<30分钟instant直接创建任务，路由到
beo-executing
2-3个文件修改、范围清晰、耗时<2小时lightweight路由到
beo-exploring
（快速深度梳理后进入规划）
多文件修改、需要调研、耗时>2小时standard路由到
beo-exploring
需求模糊、需要澄清unclear路由到
beo-exploring
错误、阻塞、失败症状debug路由到
beo-debugging

Step 3: Route

步骤3：路由

  • instant: create one task bead, write a concise Markdown description using the shared bead templates, scaffold the minimal artifacts, mark the epic approved, then route to 
    beo-executing
    . Load 
    references/router-operations.md
    for the exact instant-path scaffold.
  • debug: Route to 
    beo-debugging
    directly.
  • meta-skill: Route to 
    beo-writing-skills
    directly.
  • lightweight/standard/unclear: Route to the appropriate skill.
  • instant：创建一个任务bead，使用共享的bead模板编写简洁的Markdown描述，搭建最小化artifact，标记史诗已审批，然后路由到
    beo-executing
    。确切的instant路径搭建流程见
    references/router-operations.md
    。
  • debug：直接路由到
    beo-debugging
    。
  • meta-skill：直接路由到
    beo-writing-skills
    。
  • lightweight/standard/unclear：路由到对应的skill。

Promotion Guard

升级防护

If you classified as instant but discover the work is bigger:
  1. stop treating it as instant work
  2. preserve the existing task bead as planning input
  3. route to 
    beo-exploring
    or 
    beo-planning
  4. use 
    references/router-operations.md
    for the exact promotion guard details
如果你将需求分类为instant，但后续发现工作量更大：
  1. 不再将其视为instant工作
  2. 保留现有任务bead作为规划输入
  3. 路由到
    beo-exploring
    或
    beo-planning
  4. 确切的升级防护细节见
    references/router-operations.md

Phase 3: Resume from Handoff

阶段3：从交接点恢复会话

When HANDOFF.json exists:
  1. read 
    .beads/HANDOFF.json
  2. verify the epic, task graph, and current artifacts still match the handoff
  3. trust the stored 
    skill
    and 
    next_action
    unless live state clearly contradicts them
  4. resume the named skill
  5. remove or refresh 
    HANDOFF.json
    only after a fresh 
    STATE.md
    checkpoint exists
Load 
references/router-operations.md
when you need the exact resume validation procedure or cleanup rule.
当存在HANDOFF.json时：
  1. 读取
    .beads/HANDOFF.json
  2. 验证史诗、任务图谱和当前artifact仍与交接内容匹配
  3. 信任存储的
    skill
    和
    next_action
    ，除非实时状态明显与之矛盾
  4. 恢复指定的skill
  5. 仅在新的
    STATE.md
    检查点生成后，才删除或更新
    HANDOFF.json
当你需要确切的恢复验证流程或清理规则时，请加载
references/router-operations.md
。

Phase 4: Health Check (Doctor Mode)

阶段4：健康检查（诊断模式）

When asked to check project health or diagnose issues, do this minimum sequence first:
  1. inspect graph health
  2. inspect blocked work
  3. inspect stale work
  4. report the planning shape (single-phase vs multi-phase, current-phase artifacts present or missing)
  5. recommend one next corrective action
Load 
references/router-operations.md
for the exact doctor-mode commands and diagnostic table.
当被要求检查项目健康状态或诊断问题时，先执行以下最小序列：
  1. 检查图谱健康状态
  2. 检查阻塞的工作
  3. 检查过时的工作
  4. 上报规划形态（单阶段/多阶段、当前阶段artifact是否存在）
  5. 推荐一个后续修正操作
确切的诊断模式命令和诊断表见
references/router-operations.md
。

Context Budget

上下文预算

If context usage exceeds 65%, use 
../reference/references/state-and-handoff-protocol.md
for the canonical 
HANDOFF.json
shape, then add any router-specific resume detail you need before pausing.
如果上下文使用率超过65%，请查阅
../reference/references/state-and-handoff-protocol.md
了解标准的
HANDOFF.json
结构，然后在暂停前补充任何路由相关的恢复细节。

Skill Routing Quick Reference

Skill 路由快速参考

User SaysRoute To
"build X", "add X", "implement X"Phase 2 → complexity classification → appropriate skill
"what's the status?"Phase 1 → report state
"continue", "resume"Phase 3 (if HANDOFF.json) or Phase 1
"check health", "doctor"Phase 4
"plan X"
beo-planning
directly
"review"
beo-reviewing
directly
"what should I work on next?"Phase 1 → 
bv --robot-next
→ report recommendation
"debug this", "why is X failing", "fix error"
beo-debugging
"what did we learn", "capture learnings"
beo-compounding
"swarm", "parallel workers", "launch workers"
beo-swarming
"dream", "consolidate learnings"
beo-dream
"write a skill", "create a skill", "edit skill"
beo-writing-skills
"go", "run the full pipeline", "go mode"Go Mode (below)
用户输入路由到
"开发X"、"添加X"、"实现X"阶段2 → 复杂度分类 → 对应skill
"当前状态是什么？"阶段1 → 上报状态
"继续"、"恢复"阶段3（如果存在HANDOFF.json）或阶段1
"检查健康状态"、"诊断"阶段4
"规划X"直接路由到
beo-planning
"评审"直接路由到
beo-reviewing
"我接下来应该做什么？"阶段1 → 
bv --robot-next
→ 上报推荐内容
"调试这个"、"X为什么失败"、"修复错误"
beo-debugging
"我们学到了什么"、"沉淀经验"
beo-compounding
" swarm"、"并行工作"、"启动工作进程"
beo-swarming
"dream"、"整合经验"
beo-dream
"编写skill"、"创建skill"、"编辑skill"
beo-writing-skills
"开始"、"运行全流水线"、"go模式"Go模式（见下文）

Go Mode (Full Pipeline)

Go模式（全流水线）

See 
references/go-mode.md
for the full Go Mode workflow (3 human gates, sequence, context budget).
完整的Go模式工作流（3个人工门禁、序列、上下文预算）见
references/go-mode.md
。

Priority Rules

优先级规则

These override all other routing and execution decisions:
  1. P1 review findings always block. Never merge, never close epic, never proceed to compounding while P1 findings are open.
  2. Context budget always applies. If context usage exceeds 65%, write 
    .beads/HANDOFF.json
    and pause. Do not continue burning context.
  3. CONTEXT.md is the source of truth. If implementation diverges from a locked decision in CONTEXT.md, stop and surface the conflict before proceeding.
  4. Gate 2 (post-validating) is the most critical gate. Execution is irreversible at scale. If there is any doubt about the plan's soundness, do not approve; loop back to validating.
  5. Spike failures halt the pipeline. A failed spike means the approach is broken. Do not proceed to swarming; return to planning.
  6. Never skip validating. Not for small features. Not for "obvious" plans. Skipping validating is the #1 cause of wasted execution work.
  7. critical-patterns.md is mandatory context. If it exists, read it before planning or executing. Ignoring past critical patterns is the #1 source of repeat failures.
  8. Current-phase completion is not whole-feature completion for multi-phase work. If 
    phase-plan.md
    exists and later phases remain, route back to 
    beo-planning
    instead of jumping to final review.
以下规则优先级高于所有其他路由和执行决策：
  1. P1评审发现问题始终阻塞流程。 P1问题未解决前，永远不要合并代码、关闭史诗、进入经验沉淀阶段。
  2. 上下文预算始终生效。 如果上下文使用率超过65%，写入
    .beads/HANDOFF.json
    后暂停，不要继续消耗上下文。
  3. CONTEXT.md是唯一可信来源。 如果实现与CONTEXT.md中锁定的决策不一致，先停止并上报冲突，再继续后续操作。
  4. 门禁2（验证后）是最关键的门禁。 大规模执行是不可逆的。如果对计划的合理性有任何疑问，不要批准；返回验证阶段。
  5. ** Spike失败会终止流水线。** Spike失败意味着方案不可行，不要进入swarming阶段；返回规划阶段。
  6. 永远不要跳过验证阶段。 小功能也不行，「显而易见」的计划也不行。跳过验证是执行工作浪费的首要原因。
  7. critical-patterns.md是必须阅读的上下文。 如果该文件存在，在规划或执行前必须阅读。忽略过往的关键模式是重复失败的首要原因。
  8. 多阶段工作中，当前阶段完成不等于全功能完成。 如果存在
    phase-plan.md
    且还有后续阶段，路由回
    beo-planning
    ，不要直接跳转到最终评审。

Red Flags and Anti-Patterns

红色预警和反模式

See 
references/guardrails.md
for red flags (8 items) and anti-patterns (6 items).
红色预警（8项）和反模式（6项）见
references/guardrails.md
。