| name | vibe-roadmap |
| description | Use when the user wants project-level roadmap planning, version goals, backlog triage, governance suggest review, or issue placement decisions. Triggered by "vibe roadmap", "/vibe-roadmap", "版本规划", "roadmap 审查", "消化 governance suggest", "下一个版本做什么", or "这个 issue 放哪一版". Do not use for assignee pool governance (use vibe-orchestra) or single-flow execution. |
/vibe-roadmap - 版本规划与治理审查
维护版本路线图，同时作为三层治理架构的 Layer 3 审查者，消化 governance 层的 [governance suggest][roadmap-intake] / [governance suggest][assignee-pool] 并形成最终 [roadmap decision]。
三层架构、标签语义（orchestra-scanned / orchestra-governed / roadmap-reviewed）和三级审查框架（Level 1/2/3）见 @vibe/supervisor/roadmap-common.md（使用 vibe3 handoff show @vibe/supervisor/roadmap-common.md 命令读取）。
权限模型（强制执行）
| 标记 | 含义 | Agent 允许的操作 |
|---|
[Agent] | Agent 可自主执行 | 只读查询、治理漏网检查、反模式评分、data-driven 的 close/hold/rfc 判断 |
[人类确认] | 必须经人类确认 | 禁止自主执行 milestone 分配、版本目标定义、intake 纳入决策 |
硬约束：
[人类确认] 步骤中，Agent 必须停下来，展示分析结果和建议方案，等待人类明确回复后才能执行- Agent 不得在未获人类确认的情况下修改 milestone、写
close decision、或对非明显的 rfc 做最终判断
- 写
[roadmap decision] 前必须先搜索是否已有同类 decision，避免重复评论
- 所有 state/ 标签操作必须通过
vibe3 命令，禁止直接用 gh issue edit 操作 state/ 标签
核心原则
- 审查纠正 governance 决策：消化 roadmap-intake / assignee-pool 的分层
[governance suggest]，写 [roadmap decision]，打 roadmap-reviewed
- GitHub-as-truth：所有操作通过 GitHub labels
- 先搜后写：写
[roadmap decision] 前必须搜索是否已有同名 decision，避免重复评论
- 用 vibe3 命令操作状态：需要修改 state/ 标签时，使用
vibe3 task 命令，禁止直接用 gh issue edit 操作 state/ 标签
- 不做执行：不处理单个 flow 执行
- manager assignee：分配 assignee 时使用
vibe3 task intake <number>（shell），禁止手动指定人类用户名
Scope
做：
- 消化 governance 层的
[governance suggest][roadmap-intake] / [governance suggest][assignee-pool]（Step 0）
- 治理漏网检查（Step 0.5）
- 版本目标定义与 milestone 分配
- Issue 分类与 roadmap/priority labels 设置
- Intake gate 判断：纳入 / rfc / 建议关闭（Step X）
不做：
- Assignee issue pool 实时治理（由
vibe-orchestra 负责）
- RFC issues 处理（由
vibe-task 负责）
- 根据当前 runtime 现场做即时抢占排序（由
vibe-orchestra 负责）
Workflow
Step 0: 消化未处理的 governance suggest [Agent]
每次 /vibe-roadmap 被触发，必做的第一步。
0.0 查看需要处理的 issue：
vibe3 task status
0.1 找到上次决策锚点：
REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
gh search issues "repo:$REPO [roadmap decision]" --match comments --limit 20 \
--json number,updatedAt --jq 'sort_by(.updatedAt) | reverse | .[0] | {number, updatedAt}'
若无历史 [roadmap decision] 评论（首次运行），锚点设为 7 天前。
0.2 列出未消化的分层 [governance suggest]（过滤已决策的 issue）：
REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
gh search issues "repo:$REPO [governance suggest]" --match comments --limit 50 \
--json number,labels,title \
--jq '.[] | select(.labels | map(.name) | index("roadmap-reviewed") | not)
| select(.labels | map(.name) | index("roadmap/rfc") | not)
| {number, title}'
0.3 按 suggest 类型排列决策优先级：
- 先处理
needs split（产出最大）
- 再处理
Recommend Close（清积压）
- 再处理
waiting on #X（依赖校验）
- 最后处理
Skipped (needs human)（判断是 rfc 还是可继续）
0.4 决策前检查已有评论（防重复）：
gh issue view <N> --comments --limit 50 | grep "\[roadmap decision\]"
IF 已有 "[roadmap decision]" 评论 AND 由当前 agent 在近期写入:
SKIP 此 issue（已有决策，不重复写入，不重复打 roadmap-reviewed）
0.5 依赖验证（写 proceed / unblock 决策前必须执行） [Agent]：
当决策意图是解除阻塞（proceed、unblock）并声称"依赖已解除"时，必须先验证依赖项的实际状态，不可仅凭 governance suggest 的描述或 issue body 中的自然语言声明。
验证方法：
vibe3 task show <dep_number> --full
gh issue view <dep_number> --json state,labels --jq '{state, labels: [.labels[].name]}'
判定标准（全部满足才可写 proceed）：
- 依赖 issue 的 GitHub
state 为 CLOSED，或
- 依赖 issue 带有
state/done 或 state/merge-ready 标签，或
- 依赖 issue 有已合并的 PR（
gh pr list --search "<dep_number>" --state merged）
不满足时：
- 写
[roadmap decision] hold: 依赖 #N 未完成（当前状态: <state/label>），不解除阻塞
- 打
roadmap-reviewed
- 不写
proceed
背景：#2171 被错误解除阻塞的根因是 roadmap decider 声称"依赖 #2169 已完成"，但 #2169 实际仍在 state/handoff。此步骤防止同类错误。
0.6 闭环要求：处理完每个 suggest 后：
- 写
[roadmap decision] 评论（marker 含义见 roadmap-common.md Comment Marker Contract）
- decision 不是
rfc → 打 roadmap-reviewed：gh issue edit <number> --add-label "roadmap-reviewed"
- decision 是
rfc → 不打 roadmap-reviewed，打 roadmap/rfc，等人类决策后再处理
0.7 proceed/unblock 时必须移除 orchestra-scanned [Agent]：
当 decision 是 proceed 或 unblock（依赖已解除、可以继续推进）时，如果 issue 带有 orchestra-scanned 标签，必须移除。否则 roadmap-intake 的过滤规则会永久跳过该 issue，即使依赖已解除也无法被重新纳入。
LABELS=$(gh issue view <number> --json labels --jq '[.labels[].name]')
if echo "$LABELS" | grep -q "orchestra-scanned"; then
gh issue edit <number> --remove-label "orchestra-scanned"
fi
背景：#2381 被标记为 orchestra-scanned 后，即使依赖已解除（#2376、#2380 CLOSED），roadmap-intake 仍无法看到它。roadmap 写了 proceed 但没移除标签，导致 issue 被永久跳过。
适用场景：
- 依赖解除后的 proceed
- 错误 skip 后的 override
- 任何导致 issue 需要重新进入 pipeline 的 decision
不适用场景：
- decision 是
hold（保持 blocked）
- decision 是
close（关闭 issue）
- decision 是
rfc（等待人类决策）
0.8 推翻 intake skip 时的三步处理 [Agent]：
当被审查的 [governance suggest][roadmap-intake] 来自 intake 层 skip 决策（issue 带 orchestra-scanned 且无 assignee），如果你决定纳入该 issue，必须显式执行三步（标签语义见 roadmap-common.md）：
gh issue edit <number> --remove-label "orchestra-scanned"
vibe3 task intake <number> --yes
gh issue comment <number> --body "[roadmap decision] override intake skip: <理由>"
gh issue edit <number> --add-label "roadmap-reviewed"
Step 0.5: 治理漏网检查 [Agent]
Step 0 处理完后，检查两类"漏网" issue：
类型 A：有 assignee 但缺 state 标签（通过了 intake 但 pool 还没处理，卡在两层之间）
vibe3 status
gh issue list --assignee <manager> --limit 50 --json number,title,labels,state \
--jq '.[] | select(.state == "OPEN")
| select([.labels[].name] | map(select(startswith("state/"))) | length == 0)
| {number, title}'
对每个漏网 issue：
- 应执行（范围明确、有 priority）→ 使用
vibe3 task intake <N> 补 state/ready
- 应关闭（过时/冲突/无价值）→ 写
[roadmap decision] close + 打 roadmap-reviewed
禁止：对漏网 issue 直接使用 gh issue edit --add-label state/ready。必须通过 vibe3 task intake 命令确保三源同步。
类型 B：state/done 但 issue 仍 OPEN（系统未自动关闭）
gh issue list --label "state/done" --limit 30 --json number,title \
--jq '.[] | select(.state == "OPEN") | {number, title}'
对每个漏网 issue，必须代码实际验证（不能只看标签或 PR 状态）：
git log --oneline -10 --all --grep="<issue 关键词>"
uv run python src/vibe3/cli.py inspect files <相关路径>
- 完成了（代码实际包含改动）→ 关闭 issue，comment 说明代码证据
- 没完成（代码中无改动）→ 关闭当前 issue + 创建新 issue（范围更明确，引用原 issue）
处理完后打 roadmap-reviewed，结果写入 .agent/context/memory.md 缓存。
Step 0.6: 反模式检查 [Agent]
Step 0.5 处理完后，对候选 issue 执行反模式识别（定义见 roadmap-common.md「反模式 Issue 识别标准」）。
扫描范围：
- Step 0 处理完的未决策 governance suggest（已排除 roadmap-reviewed 和 roadmap/rfc）
- Step 0.5 漏网检查中发现的 issue
评估流程：
对照 roadmap-common.md 的 5 条反模式特征逐项评分：
- 无明确痛点
- 高复杂度低 ROI
- 与现有能力重叠
- 违反项目原则
- 边缘场景驱动
对每个特征，给出具体证据（如："缺少用户场景描述"、"改动涉及 3 个模块但收益仅为边缘场景"）。
评分 >= 2 的处理（判定为反模式）：
gh issue comment <number> --body "[roadmap decision] close: 反模式
- #1: <是否满足 + 具体证据>
- #2: <是否满足 + 具体证据>
- ...
评分: <总数> 条，判定为反模式"
gh issue edit <number> --add-label "roadmap-reviewed"
gh issue close <number>
评分 < 2 的处理：
继续走正常 roadmap 流程（Step 1 检查版本目标）。
Step 1: 检查版本目标 [人类确认]
vibe3 task status
gh issue list --limit 50
gh issue list -l "roadmap/p0"
gh issue list -l "roadmap/p1"
向人类展示当前版本目标状态和建议，由人类决定版本目标。
Step 1.5: Milestone 健康检查 [Agent]
每次版本规划必须执行，生成统计报告并选择性处理缺失 milestone 的 issues。
Step 1.5a: 统计报告 [Agent]
检查无 milestone 的 issues 并生成报告：
COUNT=$(gh issue list --state open --limit 100 --json milestone --jq '[.[] | select(.milestone == null)] | length')
echo "发现 $COUNT 个 open issues 没有 milestone"
echo -e "\n按 roadmap 优先级分布："
gh issue list --state open --limit 100 --json number,title,milestone,labels \
--jq '.[] | select(.milestone == null)
| {number, title, priority: ([.labels[].name | select(startswith("roadmap/p"))] | first // "none")}' \
| jq -s 'group_by(.priority) | .[] | {priority: .[0].priority, count: length}'
Step 1.5b: 分批处理 [Agent]
当发现大量无 milestone issues 时，不要一次性全部处理。采用以下策略：
策略 1: 按优先级分批
gh issue list --state open --limit 100 --json number,title,milestone,labels \
--jq '.[] | select(.milestone == null)
| select([.labels[].name] | index("roadmap/p0") or index("roadmap/p1"))
| .number' \
| head -5 | while read NUM; do
echo "处理 #$NUM..."
done
策略 2: 按标题关键词分批
gh issue list --state open --limit 100 --json number,title,milestone \
--jq '.[] | select(.milestone == null)
| select(.title | test("Phase [0-9]"))
| {number, title}' \
| head -10
单个 Issue 处理流程：
-
分析 issue 内容和 scope：
- 使用
vibe3 task show <N> 查看标题、body、已有评论、PR 状态
- 判断属于哪个 feature/阶段
- 检查是否为 epic issue 或 sub-issue
-
分配 milestone [人类确认]：
gh api repos/{owner}/{repo}/milestones --paginate -q '.[] | {number, title, open_issues}'
gh issue edit <number> --milestone "<milestone title>"
- 记录决策：
gh issue comment <number> --body "[roadmap decision] milestone assigned: <milestone> (理由: <scope/feature归属>)"
gh issue edit <number> --add-label "roadmap-reviewed"
Milestone 分配原则：
- Epic issue → 放入对应的版本/阶段 milestone（如 "Phase 6: 架构清理与模块化"）
- Sub-issue → 与父 epic issue 使用相同 milestone
- 独立小修复 → 根据紧急程度放入当前版本或下一版本 milestone
- RFC/架构讨论 → 不分配 milestone，等待决策后再归档
Step 2: 版本规划决策 [人类确认]
场景 A: 没有版本目标
- 提示用户定义版本目标，展示 backlog issues 供选择
场景 B: 有版本目标但有新 issues
- 对新 issues 分类：分配 milestone、添加 roadmap 状态标签、必要时补
priority/[0-9]
- 对候选 issues 做 intake gate 判断（见 Step X）
场景 C: 版本结束
- 确认下一版本目标，重新评估待分类 Issue，更新 roadmap 状态标签
Step X: Intake 判断 [人类确认] ⚠️
强制约束：
- 每次只处理一个 issue，禁止批量处理
- 发布
[roadmap decision] comment 前，必须进行代码级深度分析（禁止只汇报 issue 标题）
- 必须等待人类明确回复"通过"、"执行"、"下一个"等确认词后，才能发布 comment 和执行 intake
代码验证流程（参照 #2926 示例）：
1. Read: 读取 issue 提及的代码文件（完整上下文）
2. Grep: 检查相关依赖（数据库 schema、配置项、调用链）
3. Analyze: 给出技术分析（代码位置、改动范围、风险评估、ROI）
4. Recommend: 给出明确的可行性判断 + 建议
5. Ask: 等待人类确认
违规示例：
❌ 错误：只汇报 issue 标题 + 问"是否可以执行"
❌ 错误：连续处理 #2926、#2927、#2928 而不等待人类确认
❌ 错误：直接发布 comment + intake 而不先汇报分析结果
❌ 错误：用户说"下一个"时理解为"执行下一个并发布"，而不是"汇报下一个分析"
正确示例（#2926）：
✅ 正确：
用户: "我们看下现有issue，哪些成熟可以执行了"
→ 我:
- 读取目标 service 和直接消费方的实际代码
- 检查持久化接口、数据模型和索引是否支持目标语义
- 检查所有读写入口与失败路径
- 用 Git/AST/测试证据核对 issue 的前提假设
- 给出完整评估报告（问题确认、数据库能力、改动方案、风险评估、ROI）
- 明确结论："可行性：完全可行，建议加 state/ready"
→ 用户: "通过"
→ 我: 发布 comment + intake #2926
对新进入的 issue 运行三级审查（Level 1/2/3，见 roadmap-common.md）后，选择：
场景 A: 适合自动化推进（通过全部三级审查）[人类确认]
先根据 issue 内容判断是否为简单任务：
简单任务路由（同时满足以下条件）：
- 只涉及测试文件修改（
tests/、test_*.py、*_test.py、测试夹具、测试配置）
- 不涉及业务代码改动（
src/、lib/、核心逻辑文件）
- 预估改动范围 ≤ 5 个文件、≤ 100 行
满足时，路由到 supervisor/apply 快速通道（复用 assignee-pool Step 2.5 的判断标准）：
gh issue edit <number> --add-label "supervisor,state/handoff"
gh issue comment <number> --body "[roadmap decision] simple task → supervisor/apply: <判断依据>."
gh issue edit <number> --add-label "roadmap-reviewed"
不满足时，走完整 manager intake 路径：
vibe3 task intake <number>
gh issue comment <number> --body "[roadmap decision] Intake completed (scope=<bugfix|feature|refactor>)."
gh issue edit <number> --add-label "roadmap-reviewed"
场景 B: 需要人类讨论（目标不明确/架构方向未定/scope 过大无法判断拆分）[人类确认]
gh issue comment <number> --body "[roadmap decision] rfc: <具体原因>."
gh issue edit <number> --add-label "roadmap/rfc"
架构级 rfc 判据（见 docs/decisions/_template.md 和 ADR 结晶条件）：如果 rfc 满足"跨任务/跨模块架构选型 + 有真实权衡 + 期望长期有效"，不要只要求后续实现 PR 顺手写 ADR；应推动一个小型 ADR PR（只含 ADR 文件、INDEX 更新和必要的最小链接更新），并在决策 comment 中写明 ADR PR: <url>。非架构级 rfc 维持现有流程不变。
场景 C: 建议关闭（Level 2/3 不通过：依赖已移除/API 废弃/重复）[人类确认]
gh issue comment <number> --body "[roadmap decision] close: <关闭原因>."
gh issue edit <number> --add-label "roadmap-reviewed"
Step 3: 应用标签 [Agent]
gh issue edit <issue-number> --milestone "Phase 1: 基础设施"
gh issue edit <issue-number> --add-label "roadmap/p0"
gh issue edit <issue-number> --add-label "priority/5"
注意：roadmap/ 和 priority/ 标签可通过 gh issue edit 操作（非 state/ 标签，不涉及三源同步）。但 state/ 标签的操作必须通过 vibe3 命令（见 Step X）。
Step 4: 输出状态 [Agent]
审查时先参考 docs/decisions/INDEX.md 中已有 accepted ADR，再读取相关 ADR 正文。决策不得违反当前有效 ADR；如需偏离，必须显式提议 supersede。
版本规划状态
当前版本: Phase 1: 基础设施
P0 (紧急)
- #36: GitHub Projects 整合 [roadmap/p0, priority/8]
当前版本
- #34: Issue 同步 [roadmap/p1, priority/5]
- #35: save 自动关联 [roadmap/p1, priority/5]
下一个版本
- #37: 智能调度 [roadmap/p2, priority/3]
RFC (需讨论)
- #77: 架构方向未定 [roadmap/rfc]
禁止行为清单
| 禁止行为 | 说明 | 正确做法 |
|---|
gh issue edit <N> --add-label state/ready | 直接操作 state/ 标签无法同步三源 | 用 vibe3 task intake <N> 或 vibe3 task resume <N> |
gh issue edit <N> --remove-label state/blocked | 同上，label 改了但 flow state 不变 | vibe3 task resume <N> --label auto --yes |
未搜索已有 [roadmap decision] 就写新 decision | 造成重复评论 | Step 0.4 先 grep "\[roadmap decision\]" |
写 proceed 前不验证依赖项的实际状态 | 可能错误解除阻塞（#2171 教训） | Step 0.5 执行 vibe3 task show <dep> + gh issue view <dep> |
不检查 issue body 中的已有 [governance suggest] 就写 decision | 覆盖已有分层决策 | Step 0.2 先列出所有未消化的 suggest |
proceed/unblock 后不移除 orchestra-scanned | issue 被永久跳过（#2381 教训） | Step 0.7 检查并移除 orchestra-scanned |
| 对 state/done 但 OPEN 的 issue 只看标签不验证代码 | 标签和实际代码状态可能不一致 | Step 0.5 类型 B: git log + inspect files |
| 批量处理 issue 而不逐个汇报 | 违反 [人类确认] 约束（#2926-2928 教训） | Step X: 每次只处理一个，汇报后等待确认 |
| 发布 comment 前不等待人类确认 | 同上 | 汇报分析结果 → 等待"通过"/"执行" → 发布 comment |
与其他 Skills 的区别
- vibe-roadmap: 版本规划、治理审查、governance suggest 消化（Layer 3 decider）
- vibe-orchestra: assignee issue pool 治理（人机协作入口，Layer 2）
- vibe-task: RFC 和 blocked issues 检查
- vibe-debug-serve: vibe3 serve 运行状态与深度调试
Restrictions
- 不处理执行层管理（转
vibe-orchestra）
- 不看 RFC 或 blocked issues（转
vibe-task）
- 不根据当前 runtime 现场做即时抢占排序（转
vibe-orchestra）
- 所有决策必须写
[roadmap decision] marker，禁止写 [governance suggest]
- 禁止直接用
gh issue edit 操作 state/ 标签
- 写 decision 前必须先搜索已有 decision
- 写 proceed 前必须先验证依赖项的实际状态（使用 vibe3 task show）
Pre-flow Dependency Rules
完整规范见 roadmap-common.md § Pre-flow Dependency Rules
vibe-roadmap 在 pre-flow 阶段（issue 无 flow/branch context）的约束：
- ✅ 在 issue body 正文中用自然语言说明依赖：
Blocked by #N、Depends on #N
- ✅ 添加
roadmap/*、priority/* 规划类 labels
- ❌ 禁止直接添加
state/blocked 标签 — pre-flow 无法保证三源（label/body/cache）原子写入，会导致 dispatcher 无法识别
- ❌ 禁止直接写 managed section（
Blocked by: / Dependencies: 结构化字段）
- ❌ 禁止调用
vibe3 flow blocked / flow bind — 这两个命令需要 branch 存在
依赖的正式注册（写入 managed section + flow_issue_links）由 manager 入场后完成；pre-flow 只负责把依赖关系说清楚。
