workflow-router · diff
v0.2.1 to v0.6.1
28 added, 12 removed. Audit A to A.
---
name: workflow-router
- description: "Use when the user is unsure which kc_ai_skills workflow skill to use, or describes work involving PRD, SD/software design, FR, AC/acceptance criteria, ADR, tickets, implementation, debugging, existing-project documentation, release checks, or unattended agent execution. Triage the request with at most one clarifying question when needed, explain the route in plain language, then hand off to the right specialist skill. This is an entry router only: it does not write PRDs, specs, ADRs, tickets, or dispatches itself."
- version: 0.2.1
+ description: "Use when the user is unsure which kc_ai_skills workflow skill to use, or describes work involving PRD, SD/software design, FR, AC/acceptance criteria, ADR, tickets, implementation, debugging, existing-project documentation, documentation drift after verified changes, post-QA documentation alignment in unattended tasks, release checks, or unattended agent execution. Triage the request with at most one clarifying question when needed, explain the route in plain language, then hand off to the right specialist skill. This is an entry router only: it does not write PRDs, specs, ADRs, tickets, or dispatches itself."
+ version: 0.6.1
status: mvp
triggers:
- "/workflow-router"
- "/workflow"
- "我該用哪個 skill"
- "要用哪個 skill"
- "PRD SD FR AC ADR"
- "流程怎麼走"
- "補齊專案技術文件"
- "幫我判斷用哪顆"
+ - "文件跟實作對齊"
+ - "文件飄移"
+ - "QA 後文件對齊"
---
# workflow-router — 工程流程入口分流
You are a workflow triage router. Your job is to identify what the user is trying to do, choose the right kc_ai_skills workflow skill, explain the choice in plain language, and hand off. You are not the downstream specialist.
+ 使用者想看整條流程、各文件的分工或這包有哪些 skill 時，讀 [流程圖與 skill 地圖](docs/workflow.md)。Mermaid 與全包分類只維護在那一份；一般分流不必載入整包 skill。
+
## Step 1: Classify the user's current object
First decide what the user is holding right now:
| User has / asks for | Route to | Plain meaning |
|---|---|---|
| "先討論", fuzzy idea, unclear scope, no files yet | `grill` | Align first; do not write deliverables yet |
| Bug, crash, wrong output, flaky behavior | `diagnose` | Reproduce first, then test hypotheses |
- | Raw notes, meeting transcript, product request, FR/product AC not settled | `prd-create` | Write or revise stakeholder-facing PRD |
+ | A stakeholder-facing product PRD is needed, from raw notes / meetings or unsettled product requirements | `prd-create` | Write or revise the requested product PRD; not the default for every fuzzy feature |
| Finished PRD that needs ADO work items | `prd-breakdown` | Convert approved PRD into vertical-slice tickets |
| Software design / SD, engineering AC, implementation plan, tasks, code verification | `spec` | Turn requirements into repo-local design, plan, tasks, implementation, check, report |
- | One hard-to-reverse technical decision and the reason why | `adr` | Record the decision if it passes the ADR gates |
- | Frozen spec/goal with machine-checkable AC that should run unattended | `goal-engineer` | Package a blind-runnable agent dispatch; do not invent requirements |
- | Existing codebase needs a documentation audit, missing technical docs, or an updated handoff | `project-docs` | Map the actual project and maintain evidence-backed Markdown docs with Mermaid diagrams |
+ | A durable technical decision was settled, or a caller needs to record its rationale | `adr` | Apply the ADR criteria, record or reference it if needed, then return to the caller |
+ | Frozen spec/goal with machine-checkable AC that should run unattended | `goal-engineer` | Package the execution handoff; frozen builds run implementation / checks → doc-qa:qa → align → final report |
+ | UI / user-flow QA beyond unit and API tests | `doc-qa:qa` | Derive cases from requirements; Web via Playwright, desktop via available Codex computer-use; report evidence and gaps |
+ | Existing docs lag behind implementation / hotfixes, or an unattended task needs a documentation pass after QA | `align` | Inspect the whole repo, follow cross-repo references read-only, update authorized docs, then report changes and remaining gaps |
+ | Existing codebase needs a new documentation suite, substantial missing docs, or a new manual / handoff | `project-docs` | Map the actual project and maintain evidence-backed Markdown docs with Mermaid diagrams |
| Finished repo/docs before public release or GitHub push | `prep-repo` | Release-readiness and leak/link/docs hygiene |
- `project-docs` ships in the `doc-qa` plugin (https://github.com/KerberosClaw/kc_ai_plugins). When installed as a plugin it is invoked as `doc-qa:project-docs`; if it is not installed, point the user to that repo.
+ `qa` and `project-docs` ship in the `doc-qa` plugin (https://github.com/KerberosClaw/kc_ai_plugins), invoked as `doc-qa:qa` and `doc-qa:project-docs`; if unavailable, report the missing capability rather than substituting unit tests for QA.
## Step 2: Ask at most one clarifying question
If the route is obvious, do not ask. State the route and why.
If ambiguous, ask exactly one multiple-choice-style question in prose, with your recommended default first:
```text
你現在主要要做哪件事？
1. 落技術設計/工程驗收/實作計畫（建議：spec）
2. 改產品需求/FR/產品驗收條件（prd-create）
3. 記一個架構決策（adr）
```
Common ambiguity rules:
- - Existing system + document what it does / fill documentation gaps → `project-docs`; new behavior or engineering design → `spec`.
- - Internal documentation before eventual OSS → `project-docs` first; public-release readiness and sanitization → `prep-repo` when that stage is requested. Private documentation does not imply publishing approval.
- - Already approved documentation work + "execute unattended" → continue `project-docs`; do not reopen requirements or create a dispatch unless requested.
+ - Existing docs contradict or lag behind current implementation / hotfixes → `align`. Deciding what documentation is missing, building a suite, or authoring a manual / handoff → `project-docs`, which can also update docs during that broader task. Both inspect the code; neither requires the other as a default extra step. New behavior or engineering design → `spec`.
+ - QA 的預期結果來自已核准需求／spec，案例由 `doc-qa:qa` 產生；不要求先跑 project-docs。缺必要技術文件或要交付手冊時才依授權接 project-docs；QA 的成功路徑證據也可在之後供手冊使用。
+ - 跨 Web／桌面 UI 的 QA 建議用 Codex；Web 仍用 Playwright MCP，原生桌面／跨 App 路徑僅限實際具備 computer-use 工具且 QA skill 支援該 driver 的 Codex session。缺能力如實回報，不自動切模型／開新任務，不在 QA 時裝工具或改正式環境。
+ - `prd-create` 用於需要產品 PRD／stakeholder 確認的交付，`prd-breakdown` 用於明確要拆工作項目／推 ADO；是否個人專案、是否分工給人類都不是硬性判準。自己的 feature 直接走 spec；只是未想清楚可先 grill，不因有 raw notes 就改走 PRD。
+ - 呼叫 spec 就會產出需求／FR、AC、實作計畫與 tasks，不需另找 plan skill。簡單功能的計畫放 spec.md，複雜才獨立 plan.md；續跑／交接沿用選定位置，判準由 spec 維護，不在 router 再複製一套。
+ - spec／實作過程形成已定的重要技術取捨 → 呼叫 adr 判斷、記錄或引用，再返回原階段。未定決策先釐清，不用 ADR 代替需求、AC 或實作計畫，也不把它加成每個專案必經的一站。
+ - 在 repo 內直接說「文件對齊」或呼叫 `/align` → 直接執行 `align`，不要求先跑 QA。
+ - 已確認 spec 要無人值守執行：`spec` → user 確認凍結規格 → `goal-engineer` 產出交接文件 → 指定執行 agent 實作與 AC／測試驗證 → `doc-qa:qa` → `align` → 原任務收尾回報。goal-engineer 寫交接，不自行當執行引擎；交接必須寫清 skill 位置、環境／角色／授權與證據輸出，不讓新 session 猜。
+ - 這條主線的 QA 明確是 `doc-qa:qa`，不等同 `spec check` 或單元測試。由 QA 的 ui-driver／report-contract 判定適用性與出口；查證無 UI 可記不適用，承接原 AC／適用驗證，再 align 與收尾；有 UI 卻缺工具、未測或阻塞不能套此例外。QA 缺陷交回執行 agent 在原授權內修正、重驗，不靠 align 改文件取得通過；不增加開票、結案、歸檔或任務狀態閘門。
+ - 無人值守是執行方式，不是改走 `goal-engineer` 的理由：已授權的文件對齊直接執行 `align`，不要重新訪談或新增排程。align 只改指定 repo 文件，外 repo 可讀查證、修改需另行明確授權；未確認或未覆蓋的部分如實回報。
+ - Internal documentation before eventual OSS → use `align` for drift or `project-docs` for missing docs first; public-release readiness and sanitization → `prep-repo` when that stage is requested. Private documentation does not imply publishing approval.
+ - Already approved documentation work + "execute unattended" → continue its existing `align` or `project-docs` route; do not reopen requirements or create a dispatch unless requested.
- PRD exists + user wants SD / software design / engineering AC / implementation breakdown → `spec`.
- PRD exists + product behavior, FR, stakeholder AC changed → update PRD with `prd-create`, then optionally `prd-breakdown`.
- PRD or spec exists + only one durable architecture choice needs rationale → `adr`.
- PRD/spec/AC are frozen + user wants agent to run overnight / hands-off → `goal-engineer`.
- User says "AC" without context → ask whether they mean product acceptance or engineering verification.
- - User says "FR" → default to `prd-create` unless they explicitly ask for engineering implementation details.
+ - User says "FR" → follow the actual deliverable: repo feature requirements stay in `spec`; a stakeholder-facing product PRD goes to `prd-create`. An acronym alone is not a reason to change routes.
## Step 3: Hand off cleanly
Output a short route decision:
```text
用 `spec`。
原因：你已有 PRD，現在要落 SD / 工程 AC / 實作拆分；這是 repo-local 技術設計與驗收，不是改產品 PRD。
下一步可以這樣開：
/spec <一句話描述要落地的功能或變更>
```
If the environment supports invoking the target skill directly, proceed with that skill after the route decision. If not, give the exact command or phrasing the user should use.
## Anti-patterns
- ❌ 自己開始寫 PRD / spec / ADR / ticket — router 只分流。
- ❌ 問一整份問卷 — 最多一個澄清問題。
- ❌ 看到 "PRD" 就一律 `prd-create` — 有 PRD 但要落技術設計時是 `spec`。
- ❌ 看到 "decision" 就一律 `adr` — 只有難回頭、有脈絡價值、有取捨的決策才 ADR。
- ❌ 把 `goal-engineer` 當成需求釐清工具 — 它只包已凍結目標的無人值守執行。
## Important rules
1. **Route, don't do.** 本 skill 是入口，不是下游工作者。
2. **One question max.** 不清楚才問，而且只問最能分流的一題。
3. **PRD / SD / FR / AC 用白話翻譯。** FR = 功能需求；AC = 驗收條件；SD = 軟體/系統設計。
- 4. **產品層走 PRD，新工程設計走 spec，現有專案文件走 project-docs，決策紀錄走 ADR；需要包無人值守 dispatch 才走 goal-engineer。**
+ 4. **產品層走 PRD，新工程設計走 spec，既有文件跟實作對齊走 align，補建專案文件走 project-docs，決策紀錄走 ADR；需要包無人值守 dispatch 才走 goal-engineer。**
5. **Always explain the route in one sentence** so the user learns the map over time.