maintain-workflow-using-unified

Only when the user explicitly enters the Unified workflow must you execute the skill discovery process. Ordinary repo Q&A, ordinary coding requests, and direct tasks that do not mention Unified do not automatically enter this skill.

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.

Entry/Exit

• Entry: The user explicitly invokes /brainstorm /refine /design /plan /build /review /ship /save /restore /learn /help, or explicitly says "use the Unified workflow / enter a certain stage / follow Unified"
• Exit: The activation gate decision is complete; if activated, complete skill discovery and announce loading, otherwise remain in direct mode
• Preloading: CANON.md (10 constitutional articles, the underlying constraints of all skills)
• Output path: Skill discovery result → corresponding stage skill loading (define → design → build → verify → ship → maintain → reflect)

When not to use

• The current agent is a dispatched subagent, and <SUBAGENT-STOP> has already been hit
• The user only asks to explain Unified Skills itself and does not need to enter task execution
• The current platform has already had the host automatically complete equivalent skill discovery and provided a clear result
• The user only makes an ordinary repo Q&A, ordinary coding request, or ordinary debug request, but does not explicitly request use of the Unified workflow or a stage command

Instruction priority

1. User explicit instructions(direct request) and project entry AGENTS.md — highest priority
2. Unified Skills — overrides default system behavior
3. Default system prompt — lowest priority

If the user explicitly says "skip X", follow the user's instruction. But if the user only says "do Y", it means following this skill only after explicitly entering the Unified workflow.

Activation gate + proactive discovery flow

Step 0: Determine whether to activate Unified runtime

Activate only in the following cases:

• The user explicitly invokes /brainstorm /refine /design /plan /build /review /ship /save /restore /learn /help
• The user explicitly says "use the Unified workflow", "follow Unified", or "enter the refine / plan / build / review / ship stage"
• The user is discussing Unified's own startup, routing, skill contract, or loading mechanism

If none of the above conditions are met:

• Remain in direct mode
• Do not read skills-router.json
• Do not announce loading tier
• Do not automatically load Unified stage skills just because they "might be relevant"

Checkpoint: has explicitly recorded activated or direct mode; when not activated, stop this skill immediately.

Step 1: Read lightweight routing

先读取 skills-router.json 获取 compact routing surface。
只有当 router 无法回答、需要完整库存、或进入 full 模式时，才读取 skills-index.json。

Checkpoint: skills-router.json has been successfully read, and the routing surface is already in context.

Step 2: Analyze task characteristics

Identify the following 6 dimensions:

• Stage — Is this the define/design/build/verify/ship/maintain/reflect stage?
• Artifact type — First identify runtime artifact_type(software/document/article/deck/visual), then map to canonical delivery_class（software/content/visual）
• Trigger words — What keywords does the user message contain?
• Context signals — What is the current state? (Has spec but no plan? Has code but no review?)
• Risk factors — Involves user input? Authentication? UI changes? Performance-critical?
• loading tier — This time it should be light、standard、expanded or full？

Checkpoint: All 6 dimensions have explicit values; uncertain dimensions are recorded as unknown, not skipped.

Step 3: Select loading tier

Tier	Trigger	Default loading	Extension condition
light	Already explicitly entered Unified, but the task is still simple explanation, status query, command lookup, with no repo editing	Boot Kernel + skills-router.json	Read a small number of files only when the answer depends on current repository facts
standard	Regular workflow task	1 main workflow skill	Append 1 specialist skill when artifact_type or trigger explicitly requires it
expanded	Naming risk or mixed artifacts	1 main workflow skill + up to 2 specialist skills	Each additional skill must state its trigger / risk
full	--full, adversarial review, full-body inspection, high-risk release, explicit user request	All relevant roles/skills allowed by the stage skill	Must state the reason for the full trigger

Step 4: Query relevant skills

Based on the analysis in Step 2-3, query from skills-router.json :

相关技能 = 
  routes.user_says[匹配的关键词]
  + routes.context_signals[匹配的上下文]
  + routes.risk[匹配的风险因素]
  + skills[候选技能].phase / role / default_tier

If skills-router.json does not cover the current problem, then read skills-index.json as the complete inventory fallback, and record the reason.

Checkpoint: At least 1 candidate skill has been identified; when there is no match, the reason has been recorded and skills-index.json has been read as fallback.

Step 5: Decision loading

Decide by tier:

• light → Do not load a full skill, unless the current facts must be verified from the repository.
• standard → Load 1 main workflow skill; at most 1 specialist skill.
• expanded → Load 1 main workflow skill; at most 2 specialist skills; each specialist must have a named trigger / risk.
• full → Select all relevant skills according to the stage skill and Risk-Based Role Escalation; roles not selected do not produce placeholder feedback.

Boundary between loading authority and scheduling authority:

• router / command decides which stage workflow to enter
• The stage workflow decides which main skill / specialist skill to load
• Only when the stage workflow explicitly requires it, dispatch agents/*.md persona
• The persona consumes the stage context that has already been selected, and must not autonomously add skills, jump to a new stage, or expand scope

The user-visible artifact rules still hold:

• document / article / deck / visual → First load design-workflow-design。
• software + UI / page / component / interaction / visual signals → append the necessary design/frontend skills.

Step 6: Announce and execute

Output:

Using [tier] tier: [skill-name] to [purpose] because [trigger/risk]

Then load the skill on the current platform: Claude Code calls the Skill tool; Codex reads the corresponding skills/<name>/SKILL.md or uses the skill entry point exposed by the host.

If a later stage workflow needs a persona:

router / command
  -> stage skill
  -> dispatch decision
  -> current agent or persona
  -> main session merge

The persona does not have self-load / self-route authority; it can only perform the responsibilities assigned to it by the stage workflow.

Checkpoint: The announcement output has been generated, in the format Using [tier] tier: [skill-name] to [purpose] because [trigger/risk]。

Red flags — these thoughts mean you are skipping the discovery process

Thought	Reality
"This task is in the repo, so by default it should go into Unified"	Only explicit Unified requests activate it; ordinary tasks remain in direct mode.
"Since SessionStart mentioned Unified, it takes over by default"	SessionStart only indicates availability; it does not equal automatic runtime activation.
"This task obviously doesn't need to check the router"	For an already activated Unified task, still go through skills-router.json。
"I already know which skill to use"	The router may have relevant triggers you don't know about. Check.
"Let me first understand the requirements before checking skills"	The skill tells you how to understand the requirements. Check first.
"This is just a simple question"	When Unified is not activated, answer directly; when activated, you may go through light, but you still have to go through the router.
"I'll explore the codebase first"	The skill tells you how to explore. Check the router first.
"I'll just check the files/code"	Files lack conversational context. Check the skill first.
"I'll gather information first and then talk"	The skill tells you how to gather information. Check first.
"This doesn't count as a task"	If there is action, there is a task; but first determine whether Unified is explicitly entered.
"This doesn't need a formal skill"	If the skill exists, use it.
"I remember this skill"	Skills evolve. Read the current version.
"I know what that means"	Knowing the concept ≠ using the skill. Invoke it.
"The skill is too heavy"	Simple things become complex. Use it.
"I'll do this one thing first"	First determine whether it is activated; if activated, check the router first.
"This feels quite efficient"	Undisciplined action wastes time. Skills prevent this.

Common Excuses Table

Excuse	Reality	Consequence
"I've memorized the skill, no need to check"	Skills and the router evolve. Check every time skills-router.json to ensure you use the latest version.	Executing a changed process with an old version of the skill makes behavior inconsistent with the contract, producing invalid output or requiring rework.
"This task is obvious"	First determine whether Unified is explicitly entered; once activated, not checking = skipping discipline.	Forcing skills to load when direct mode is appropriate wastes context; not checking when Unified is appropriate skips verification steps.
"Doing it directly is faster"	direct mode is suitable for ordinary tasks; when Unified is activated, skipping discovery = skipping quality assurance.	Incorrect mode determination makes the system swing back and forth between "overloaded context" and "undisciplined execution".
"This doesn't count as a task"	If there is action, there is a task; but not every task must automatically enter Unified.	Forcing ordinary tasks into Unified continuously consumes context and dilutes the real phase workflow.
"I remember this skill"	Skills evolve. Read the current version.	Executing an updated skill process based on outdated memory misses newly added hard gates or red-flag checks.

Verification Checklist

• Activation gate judgment completed; stay in direct mode when not activated
• skills-router.json has been read; only read skills-index.json when necessary
• 6-dimension analysis completed (phase, artifact type, trigger words, context signals, risk factors, loading tier)
• loading tier has been declared:light / standard / expanded / full
• At least one skill has been declared: "Using [tier] tier: [skill-name] to [purpose] because [trigger/risk]"
• No Red Flags triggered

Verification Failure Handling

Failure Scenario	Handling Method
The user did not explicitly request to use Unified	Stop this skill, stay in direct mode, do not read skills-router.json。
skills-router.json has no matching result	Expand the dimension analysis: check whether there are implicit phase signals (e.g., the user saying "test" = verify phase) or missed risk factors. If there is still no match, read skills-index.json as a fallback.
Multiple conflicting skills matched	Sort by tier priority: first select the workflow skill, then append specialized ones by risk trigger. For the expanded tier upper limit, see the Step 3 table; when in conflict, take the one with higher risk.
loading tier is uncertain	Default standard. Better to load one extra skill (spending ~30 extra seconds reading) than to skip necessary quality assurance.
Skill file read failed	Record the failure, degrade to light tier (router-only), inform the human partner that the skill is unavailable. Do not silently skip.
The user explicitly says "don't use skills"	Follow the user's instruction, stay in direct mode. The user only saying "do X" does not equal activating Unified.

Good and Bad Examples

Good — discovered only after explicit activation

用户: "/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 — an ordinary task was wrongly pulled into Unified

用户: "帮我给登录功能写测试"

（因为在 Unified repo 里，就默认读取 router、宣告 loading tier、加载阶段技能）

→ 问题: 用户没有显式进入 Unified，却被额外消耗上下文
→ 问题: 普通 direct mode 任务被不必要地流程化

Output Template

After skill discovery is complete, output format:

Loading tier: [light/standard/expanded/full]
- [skill-name] — [purpose] — trigger: [具体触发原因]
- [skill-name] — [purpose] — trigger: [具体触发原因]（如有追加）

Decision Flowchart

用户消息
  ↓
命中 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
  └─ 否 → 直接执行

Reference as Needed

For the complete skill classification quick reference, skill priority, skill types, user instruction boundaries, and platform adaptation notes, see skill-reference.md。

By default do not read skill-reference.md. Only read it when Unified has already been activated and skills-router.json cannot explain the routing, a complete inventory quick reference is needed, or you enter the full tier.

Session Startup Check

If you have already seen the contents of the <EXTREMELY-IMPORTANT> tag in this session, it means the onboarding skill has been loaded, and there is no need to invoke this skill again.