| name | maintain-workflow-using-unified |
| description | Unified runtime 激活门——只在用户显式进入 Unified 工作流、调用阶段命令或提到"Unified 启动/路由/初始化"时使用；不用于普通 repo 问答或未提 Unified 的直接任务 |
如果你是被派发的 subagent 执行特定任务，跳过本技能。
你拥有 Unified Skills — 一套由 `skills-router.json` 轻量路由、由 `skills-index.json` 声明完整库存的阶段化工作流技能系统。
只有当用户显式进入 Unified 工作流时，你才必须执行技能发现流程。
普通 repo 问答、普通 coding 请求、未提 Unified 的直接任务，不自动进入本技能。
IF UNIFIED IS NOT EXPLICITLY ACTIVATED, YOU MUST STAY IN DIRECT MODE.
IF UNIFIED IS EXPLICITLY ACTIVATED AND A SKILL APPLIES, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
入口/出口
- 入口: 用户显式调用
/brainstorm /refine /design /plan /build /review /ship /save /restore /learn /help，或明确说“使用 Unified 工作流 / 进入某个阶段 / 按 Unified 来”
- 出口: 激活门判断完成；若已激活则完成技能发现并宣告加载，否则保持 direct mode
- 前置加载: CANON.md（宪法 10 条，所有技能的底层约束）
- 输出路径: 技能发现结果 → 对应阶段技能加载（define → design → build → verify → ship → maintain → reflect）
何时不使用
- 当前 agent 是被派发的 subagent，且
<SUBAGENT-STOP> 已命中
- 用户只要求解释 Unified Skills 本身，不需要进入任务执行
- 当前平台已经由宿主自动完成等价技能发现，并提供了明确结果
- 用户只是提出普通 repo 问答、普通 coding 请求、普通 debug 请求，但没有显式要求使用 Unified 工作流或阶段命令
指令优先级
- 用户显式指令（直接请求）和项目入口
AGENTS.md — 最高优先级
- Unified Skills — 覆盖默认系统行为
- 默认系统提示词 — 最低优先级
如果用户明确说"跳过 X"，遵循用户指令。但如果用户只是说"做 Y"，只有在显式进入 Unified 工作流后才意味着走本技能。
激活门 + 主动发现流程
Step 0: 判断是否激活 Unified runtime
只有以下情况才激活：
- 用户显式调用
/brainstorm /refine /design /plan /build /review /ship /save /restore /learn /help
- 用户明确说“使用 Unified 工作流”“按 Unified 来”“进入 refine / plan / build / review / ship 阶段”
- 用户在讨论 Unified 本身的启动、路由、技能合同或加载机制
如果不满足以上任一条件：
- 保持 direct mode
- 不读取
skills-router.json
- 不宣告 loading tier
- 不为了“可能相关”而自动加载 Unified 阶段技能
Checkpoint: 已明确记录 activated 或 direct mode；未激活时立即停止本技能。
Step 1: 读取轻量路由
先读取 skills-router.json 获取 compact routing surface。
只有当 router 无法回答、需要完整库存、或进入 full 模式时，才读取 skills-index.json。
Checkpoint: skills-router.json 已成功读取，routing surface 已在上下文中。
Step 2: 分析任务特征
识别以下 6 个维度：
- 阶段 — 这是 define/design/build/verify/ship/maintain/reflect 个阶段？
- 产物类型 — 先识别 runtime
artifact_type（software/document/article/deck/visual），再在需要解释项目级真相时映射 canonical delivery_class（software/content/visual）
- 触发词 — 用户消息包含哪些关键词？
- 上下文信号 — 当前状态是什么？（有 spec 无 plan？有 code 无 review？）
- 风险因素 — 涉及用户输入？认证？UI 变更？性能关键？
- loading tier — 本次应该是
light、standard、expanded 还是 full？
Checkpoint: 6 个维度全部有明确值；不确定的维度记录为 unknown，不跳过。
Step 3: 选择 loading tier
| Tier | 触发 | 默认加载 | 扩展条件 |
|---|
light | 已显式进入 Unified，但任务仍是简单解释、状态查询、命令查找、无 repo 编辑 | Boot Kernel + skills-router.json | 只有答案依赖当前仓库事实时读少量文件 |
standard | 常规工作流任务 | 1 个主 workflow skill | artifact_type 或 trigger 明确要求时追加 1 个专项 |
expanded | 命名风险或混合产物 | 1 个主 workflow skill + 最多 2 个专项 | 每个额外技能必须说明 trigger / risk |
full | --full、对抗性审核、全身体检、高风险发版、用户明确要求 | 阶段技能允许的全部相关角色/技能 | 必须说明 full 触发原因 |
Step 4: 查询相关技能
根据 Step 2-3 的分析，从 skills-router.json 查询：
相关技能 =
routes.user_says[匹配的关键词]
+ routes.context_signals[匹配的上下文]
+ routes.risk[匹配的风险因素]
+ skills[候选技能].phase / role / default_tier
如果 skills-router.json 没有覆盖当前问题，再读取 skills-index.json 作为完整库存兜底，并记录原因。
Checkpoint: 至少 1 个候选技能已识别；无匹配时已记录原因并读取 skills-index.json 兜底。
Step 5: 决策加载
按 tier 决策：
light → 不加载完整技能，除非当前事实必须从仓库验证。standard → 加载 1 个主 workflow skill；最多 1 个专项 skill。expanded → 加载 1 个主 workflow skill；最多 2 个专项 skill；每个专项必须有命名 trigger / risk。full → 按阶段技能和 Risk-Based Role Escalation 选择全部相关技能；未被选中的角色不产出占位反馈。
加载权与调度权边界：
router / command 决定进入哪个 stage workflow- stage workflow 决定加载哪些主 skill / specialist skill
- 只有在 stage workflow 明确要求时，才分派
agents/*.md persona
- persona 消费的是已被选定的阶段上下文，不得自主追加 skill、跳到新 stage 或扩大 scope
用户可见产物规则仍然成立：
document / article / deck / visual → 先加载 design-workflow-design。software + UI / 页面 / 组件 / 交互 / 视觉信号 → 追加必要的 design/frontend 技能。
Step 6: 宣告并执行
输出：
Using [tier] tier: [skill-name] to [purpose] because [trigger/risk]
然后在当前平台加载技能：Claude Code 调用 Skill 工具；Codex 读取对应 skills/<name>/SKILL.md 或使用宿主暴露的技能入口。
如果后续 stage workflow 需要 persona：
router / command
-> stage skill
-> dispatch decision
-> current agent or persona
-> main session merge
persona 没有 self-load / self-route 权；它只能执行被 stage workflow 赋予的职责。
Checkpoint: 宣告输出已生成，格式为 Using [tier] tier: [skill-name] to [purpose] because [trigger/risk]。
一旦已激活 Unified，没有输出 "Using [skill-name] to [purpose]" 不得开始任何实现操作。
红旗 — 这些想法意味着你在跳过发现流程
以下任何一个想法出现，立即停止并重新检查激活门与发现流程：
| 想法 | 现实 |
|---|
| "这个任务在 repo 里，默认就该进 Unified" | 只有显式 Unified 请求才激活；普通任务保持 direct mode。 |
| "既然 SessionStart 提示了 Unified，那就默认接管" | SessionStart 只提示可用性，不等于自动激活 runtime。 |
| "这个任务很明显不需要查 router" | 对已激活的 Unified 任务，仍然先过 skills-router.json。 |
| "我已经知道该用哪个技能" | router 可能有你不知道的相关触发。查。 |
| "让我先理解需求再查技能" | 技能告诉你如何理解需求。先查。 |
| "这只是个简单问题" | 未激活 Unified 时直接回答；已激活时可走 light，但仍要过 router。 |
| "我先探索代码库" | 技能告诉你如何探索。先查 router。 |
| "我查查文件/代码就好" | 文件缺少对话上下文。先查技能。 |
| "我先收集信息再说" | 技能告诉你如何收集信息。先查。 |
| "这不算任务" | 有行动就有任务；但先判断是否显式进入 Unified。 |
| "这不需要正式的技能" | 如果技能存在，就用它。 |
| "我记得这个技能" | 技能会演进。读当前版本。 |
| "我知道那是什么意思" | 知道概念 ≠ 使用技能。调用它。 |
| "技能太重了" | 简单的事会变复杂。用它。 |
| "我先做这一件事" | 先判断是否激活；已激活则先查 router。 |
| "这感觉挺有效率的" | 无纪律的行动浪费时间。技能防止这一点。 |
常见说辞表
| 说辞 | 现实 | 后果 |
|---|
| "我记住技能了，不用查" | 技能和 router 会演进。每次查 skills-router.json 确保用最新版。 | 用旧版技能执行已变更的流程，行为与合同不一致，产出无效或需要返工。 |
| "这个任务很明显" | 先判断是否显式进入 Unified；一旦激活，不查 = 跳过纪律。 | 该 direct mode 时强行加载技能会浪费上下文；该 Unified 时不查又会跳过验证步骤。 |
| "我直接做更快" | direct mode 适用于普通任务；已激活 Unified 时跳过发现 = 跳过质量保障。 | 模式判断错误会让系统在“过载上下文”和“无纪律执行”之间来回摆动。 |
| "这不算任务" | 有行动就有任务；但不是每个任务都要自动进入 Unified。 | 把普通任务强行塞进 Unified，会持续消耗上下文并稀释真正的阶段工作流。 |
| "我记得这个技能" | 技能会演进。读当前版本。 | 基于过期记忆执行已更新的技能流程，遗漏新增的硬门或红旗检查。 |
验证清单
验证失败处理
| 失败场景 | 处理方式 |
|---|
| 用户没有显式要求使用 Unified | 停止本技能，保持 direct mode，不读取 skills-router.json。 |
| skills-router.json 无匹配结果 | 扩大维度分析：检查是否有隐含的阶段信号（如用户说"测试"= verify 阶段）或风险因素被遗漏。仍无匹配时读取 skills-index.json 兜底。 |
| 匹配到多个冲突技能 | 按 tier 优先级排序：先选 workflow 技能，再按 risk trigger 追加专项。expanded tier 上限见 Step 3 表格，冲突时取 risk 更高的。 |
| loading tier 不确定 | 默认 standard。宁可多加载一个技能（多花 ~30 秒读取）也不跳过必要的质量保障。 |
| 技能文件读取失败 | 记录失败，降级为 light tier（router-only），告知 human partner 技能不可用。不静默跳过。 |
| 用户明确说"不用技能" | 遵循用户指令，保持 direct mode。用户只说"做 X"不等于激活 Unified。 |
好坏示例
Good — 显式激活后再发现
用户: "/build，帮我给登录功能写测试"
分析:
- 阶段: build
- 产物类型: software
- 触发词: "测试" → routes.user_says.test
- 上下文信号: has_code_no_tests
- 风险因素: authentication → routes.risk.authentication
- loading tier: expanded（安全敏感 + 需要测试）
Using expanded tier: build-quality-tdd to write tests because test trigger + has_code_no_tests
追加: verify-quality-security because authentication risk
Bad — 普通任务被错误拉进 Unified
用户: "帮我给登录功能写测试"
（因为在 Unified repo 里，就默认读取 router、宣告 loading tier、加载阶段技能）
→ 问题: 用户没有显式进入 Unified，却被额外消耗上下文
→ 问题: 普通 direct mode 任务被不必要地流程化
输出模板
技能发现完成后，输出格式：
Loading tier: [light/standard/expanded/full]
- [skill-name] — [purpose] — trigger: [具体触发原因]
- [skill-name] — [purpose] — trigger: [具体触发原因]（如有追加）
决策流程图
用户消息
↓
命中 Unified 激活门？
├─ 否 → 保持 direct mode，停止本技能
└─ 是 → 继续发现流程
↓
读取 skills-router.json
↓
分析任务特征（6 个维度）
↓
查询相关技能
↓
选择 loading tier
├─ light → router-only 或少量当前事实
├─ standard → 1 个主技能 + 最多 1 个专项
├─ expanded → 1 个主技能 + 最多 2 个专项
└─ full → 阶段允许的全部相关技能
↓
输出 "Using [tier] tier: [skill-name] to [purpose] because [trigger/risk]"
↓
技能有清单项？
├─ 是 → 为每个清单项创建 todo
└─ 否 → 直接执行
按需参考
完整技能分类速查、技能优先级、技能类型、用户指令边界和平台适配说明见 skill-reference.md。
默认不要读取 skill-reference.md。只有在已激活 Unified 且 skills-router.json 无法解释路由、需要完整库存速查、或进入 full tier 时才读取。
Session 启动检查
如果你在本 session 中已经看到过 <EXTREMELY-IMPORTANT> 标签的内容，说明引导技能已加载，无需重复调用本技能。
