maintain-workflow-using-unified

<SUBAGENT-STOP> 如果你是被派发的 subagent 执行特定任务，跳过本技能。 </SUBAGENT-STOP>

<EXTREMELY-IMPORTANT> 你拥有 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. </EXTREMELY-IMPORTANT>

入口/出口

• 入口: 用户显式调用 /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 工作流或阶段命令

指令优先级

1. 用户显式指令（直接请求）和项目入口 AGENTS.md — 最高优先级
2. Unified Skills — 覆盖默认系统行为
3. 默认系统提示词 — 最低优先级

如果用户明确说"跳过 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 artifacttype（software/document/article/deck/visual），再在需要解释项目级真相时映射 canonical deliveryclass（software/content/visual）
• 触发词 — 用户消息包含哪些关键词？
• 上下文信号 — 当前状态是什么？（有 spec 无 plan？有 code 无 review？）
• 风险因素 — 涉及用户输入？认证？UI 变更？性能关键？
• loading tier — 本次应该是 light、standard、expanded 还是 full？

Checkpoint: 6 个维度全部有明确值；不确定的维度记录为 unknown，不跳过。

Step 3: 选择 loading tier

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]。

<HARD-GATE> 一旦已激活 Unified，没有输出 "Using [skill-name] to [purpose]" 不得开始任何实现操作。 </HARD-GATE>

红旗 — 这些想法意味着你在跳过发现流程

<HARD-GATE> 以下任何一个想法出现，立即停止并重新检查激活门与发现流程：

</HARD-GATE>

常见说辞表

验证清单

• 已完成激活门判断；未激活时保持 direct mode
• skills-router.json 已读取；必要时才读取 skills-index.json
• 6 维度分析已完成（阶段、产物类型、触发词、上下文信号、风险因素、loading tier）
• loading tier 已宣告：light / standard / expanded / full
• 至少一个技能已宣告："Using [tier] tier: [skill-name] to [purpose] because [trigger/risk]"
• 无 Red Flags 触发

验证失败处理

好坏示例

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> 标签的内容，说明引导技能已加载，无需重复调用本技能。