@chenguangyao/devflow-kit 0.1.43

package/skills/df-orchestrator/SKILL.md

@@ -0,0 +1,407 @@
+---
+name: devflow-df-orchestrator
+description: |
+  devflow-kit 的顶层协调者。当用户(a) 开始一个新任务、(b) 粘贴 Wiki / Confluence / Notion / JIRA
+  URL 或 bug 告警、(c) 发起任何 `df` / `/df:*` 命令、(d) 询问"下一步该跑什么"、(e) 流程在中间
+  phase 卡住不知道怎么继续时,**必须首先**触发本 skill。本 skill 不做具体工作,只做:识别入口
+  → 路由到正确 sub-skill → 守住 phase 闸门 → 遇到异常时诊断并给出下一步。
+when_to_use: |
+  每个开发任务的第一步;任何一次用户不确定该跑哪个 `df` 命令时;任何一次 sub-skill 报
+  BLOCKED / NEEDS_INPUT 时由本 skill 决定要不要回退 phase / 重走 clarification。
+---
+
+# df-orchestrator
+
+顶层 coordinator。自身不写代码、不产文档,只做 4 件事:
+
+1. **识别入口**(URL / JIRA / idea / incident / 已有 change resume)→ 选择正确起点。
+2. **路由到 devflow sub-skill**:
+   - 核心流程:`devflow-brainstorm` / `devflow-complexity-grading` / `devflow-requirement-analysis` / `devflow-tech-spec` / `devflow-test-spec` / `devflow-plan` / `devflow-apply` / `devflow-code-review` / `devflow-verify` / `devflow-deliver` / `devflow-archive`
+   - 风险增强:`devflow-frontend-quality` / `devflow-ci-fix` / `devflow-dependency-upgrade` / `devflow-handoff-resume` / `devflow-security-hardening`
+3. **守 workflow gate**:优先读取 `state.workflow.steps`;旧 change 没有 workflow 时才退回固定 phase 顺序。
+4. **异常诊断**:sub-skill 报错或卡住时,决定回退到哪个 phase 重新进入。
+
+## 项目上下文加载(每次会话第一步)
+
+本 skill 是用户级安装(`~/.cursor/skills/`、`~/.claude/skills/`、`~/.agents/skills/`),所有项目共用同一份。
+要让通用 skill 适配当前项目,先判断用户意图是否是 deploy/test/provider/status 这类 CLI 操作。
+如果是,优先按"入口路由"直接执行对应命令,不要为了补项目背景先跑 `devflow status` 或 `devflow init`。
+其他开发流程类任务,按下面顺序读项目上下文:
+
+1. 读 `<repo>/devflow/config.json`(可选)
+   - `projectOverview.referencedFile` → 项目概览文件相对路径(如 `CLAUDE.md` / `AGENTS.md` / `README.md`)
+   - `detect.language` / `detect.buildTool` / `detect.defaultBranch` / `detect.remote` → 工程画像
+2. 若 `projectOverview.referencedFile` 存在,**完整读取**该文件,作为本次会话的"项目背景"
+3. 读 `<repo>/devflow/changes/<current-slug>/state.json`(若有)→ 决定从哪个 phase 续走
+4. 读当前 change 的 `project-roots.json`(若有)→ 获取已确认的 primary / dependency 项目路径
+5. 读 `<repo>/devflow/specs/`(若有)→ 已有能力列表,避免重复设计
+
+如果 `devflow/config.json` 不存在,只能说明缺少 devflow 流程元数据;部署类命令不受影响。
+明确规则: devflow/config.json 不存在时,部署类命令不受影响。
+只有当用户要进入 requirement/design/plan/apply/review/verify/deliver/archive 等阶段流程,且确实需要项目背景或 change state 时,才提示用户跑 `devflow init`。
+
+## Workspace 模式（默认）
+
+所有新需求默认使用外置 workspace 作为需求主账。单服务也可以使用 workspace；多服务必须使用 workspace。项目仓库只保留代码、服务局部 change、以及长期规格真源 `devflow/specs/`。
+
+**固定路径：**
+
+```
+~/.devflow/workspace/changes/<feature-xx>/
+├── requirement.md         # 当前需求过程文件
+├── design.md
+├── plan.md
+├── tests.md               # 可选：L3 或显式 --with-tests
+├── reports/               # 按需：devflow test/report 生成
+├── delta/                 # 按需：devflow design --with-spec 生成
+├── requirements/          # 原始需求材料、Wiki/JIRA 拉取内容
+├── services/              # 每个服务的局部方案 / 计划 / 验证报告
+│   ├── go_member/
+│   └── go_manager/
+├── knowledge/             # 本需求统一知识沉淀（不分散写到服务仓）
+└── .workflow-state.json   # 跨服务状态
+```
+
+**命名规则：**
+
+```
+~/.devflow/workspace/changes/member-upgrade/
+```
+
+活跃目录使用需求短 slug，保持英文 / 数字 / `-`，避免空格。归档目录再加日期前缀：
+
+```
+~/.devflow/workspace/archive/2026-05-07-member-upgrade/
+```
+
+**项目仓 / 服务仓本地保留两类内容：**
+
+```
+<service-repo>/devflow/changes/<slug>/
+├── workspace.json   # 指向 ~/.devflow/workspace/changes/<feature-xx>
+├── design.md        # 仅本服务实现细节
+├── plan.md
+├── verify.md
+└── state.json       # 本服务局部状态
+
+<service-repo>/devflow/specs/
+└── <domain>/<capability>.md  # 长期规格真源，archive 阶段由 delta 合入
+```
+
+**关键约束：**
+
+- `requirement.md` 只有 workspace 一份，是跨服务唯一需求源。
+- `design.md` 写跨服务总方案、接口边界、调用关系。
+- `tests.md` 写跨服务总测试策略。
+- `services/<service>/` 写该服务的实现方案、任务和验证结果。
+- `knowledge/` 只写在 workspace 当前需求目录下，archive 时统一同步 / 提交到外部 KB。
+- `specs/` 不放 workspace；规格真源放各项目仓的 `devflow/specs/`，archive 时由 workspace 的 `delta/` 合入。
+- 归档时执行双归档：`~/.devflow/workspace/changes/<feature-xx>/` → `~/.devflow/workspace/archive/<yyyy-mm-dd-feature-xx>/`；每个服务仓归档本服务 `devflow/changes/<slug>/`。
+
+## 入口路由(Entry Routing)
+
+用户第一句话 / 第一个 URL / 第一个命令决定起点:
+
+| 用户给到的输入 | 识别信号 | 起点动作 |
+| --- | --- | --- |
+| Wiki / Confluence / Notion / 飞书 / 语雀 URL | 域名匹配 intake provider 列表 | 先执行"入口项目路由"，再用 **Shell 工具** 在项目目录执行 `devflow ingest "<url>" --follow-links --project-root=<primary>[,<dependency>]`；若用户未指定项目且当前目录是多项目根，可执行 `devflow ingest "<url>" --follow-links --search-root=<multi-project-root>` |
+| JIRA / 内部 issue ID(如 SCRUM-15803、PROJ-123) | 正则 `[A-Z]+-\d+` 且不是 commit SHA | 先执行"入口项目路由"，再用 **Shell 工具** 执行 `devflow ingest <id> --project-root=<primary>[,<dependency>]` |
+| 部署 / 提测 / 发测试 / 部署测试 | 包含"部署"或"提测",且未出现 `/df:deliver`、"交付 PR"、"归档" | 用 **Shell 工具** 执行 `devflow deploy test --project=<name>`；若项目名缺失但 `~/.devflow/projects.json#defaults.lastDeploy.project` 存在,可执行 `devflow deploy test` |
+| **极简模式**：用户说"极简" / "不要文档" / "直接写" / "就改一行" + 已知改法 | 关键词匹配 + 改动范围 ≤ 1 文件、无 DDL | 用 **Shell 工具** 执行 `devflow new <slug> --micro` |
+| 模糊想法、纯自然语言、无任何外部链接 | 无可识别 provider 前缀 / URL,且不是部署/测试/状态查询等明确 CLI 操作 | 用 **Shell 工具** 执行 `devflow new <slug>` → `brainstorm` |
+| Bug 告警 / 监控 incident ID | "告警 / alert / incident / P0 / P1" + ID | 用 **Shell 工具** 执行 `devflow ingest incident:<id>` |
+| 恢复已有 change(用户说"继续 xxx 那个事") | 存在 `devflow/changes/<slug>/state.json` | 用 **Shell 工具** 执行 `devflow status` |
+| `df` / `/df:*` 命令 | CLI 前缀 | 用 **Shell 工具** 直接执行,本 skill 只在 exit ≠ 0 时介入诊断 |
+| "帮我评估下这个方案" / "这个 PR 怎么看" | 非 devflow 任务 | 明确告知**不**进入 devflow 流程,普通对话处理 |
+
+## ⛔ HARD RULE：所有 devflow 命令必须用 Shell 工具执行
+
+```
+正确：Shell 工具 → devflow ingest "<url>" --follow-links --project-root=<primary>[,<dependency>]
+正确：Shell 工具 → devflow ingest "<url>" --follow-links --search-root=<multi-project-root>
+错误：WebFetch 工具 / curl / browser 工具 / 自己实现 ingest 逻辑
+```
+
+**当用户给出 URL 时，必须先完成入口项目路由，然后调用 Shell 工具执行带项目参数的 `devflow ingest`；
+不是 WebFetch，不是 curl，不是 browser navigate，不是让用户复制粘贴内容，也不是裸跑 `devflow ingest` 后再选项目。**
+
+原因：
+- 内网 URL（wiki.corp.com 等）只有 `devflow ingest` 通过配置好的 intake provider + token 才能访问
+- 你自己无法访问内网，报超时/401 是预期现象，**正确处理不是放弃，而是执行 Shell 命令**
+- `devflow ingest` 执行路径：Shell → devflow CLI → intake.confluence provider → 带 token 的 HTTP 请求 → 返回内容到本地文件
+- Wiki 正文中的接口文档/业务规则链接默认只跟一层：使用 `--follow-links`，不要自行递归抓站点。
+
+如果 Shell 工具执行 `devflow ingest` 失败（exit ≠ 0），读取错误信息再诊断，不要退回到"请用户粘贴内容"。
+
+## ⛔ HARD RULE：入口项目路由必须发生在 change 创建前
+
+ARB 的工作流习惯是先确定"这次需求属于哪个代码项目/工作上下文"，再创建任务目录；devflow 也必须这样做，因为 change slug 需要依赖 primary 项目的 git branch。
+
+在执行 `devflow ingest` / `devflow new` 前：
+
+1. 如果用户已经明确项目路径，必须把它作为 `--project-root` 传给入口命令。
+2. 如果当前是多项目目录但用户没指定项目，先询问用户 primary project；用户允许自动推荐时，使用 `--search-root=<multi-project-root>`。
+3. 不允许在开发流程入口裸跑 `devflow ingest "<url>"` 后才去 requirement 阶段选项目；那样 slug 已经生成，分支信息来不及参与命名。
+4. 只有单项目仓、或用户明确说"先导入材料，暂不关联代码项目"时，才允许不带项目参数；此时可加 `--no-project-routing` 表达意图。
+
+常用命令：
+
+```bash
+devflow ingest "<url>" --project-root=/path/to/primary,/path/to/dependency
+devflow ingest "<url>" --search-root=/path/to/health-java
+devflow new <slug> --project-root=/path/to/primary
+```
+
+详细路由规则与边界情况(多 URL、跨项目、多 slug)见 [`references/routing-rules.md`](references/routing-rules.md)。
+
+> **入口路由完成后必须立即触发 `devflow-complexity-grading` skill**，在 requirement-analysis 之前完成定级。
+> 唯一例外：用户说"继续 xxx"恢复已有 change，且 `state.level`、`state.problemCardConfirmedAt`、`state.projectConfirmationAt` 都已存在 → 跳过，直接续走当前 phase。
+> 若只有 `state.level`，但缺少 `problemCardConfirmedAt` 或 `projectConfirmationAt`，说明这是旧流程遗留状态，必须回到 complexity-grading 补展示"问题卡 + 涉及项目确认"，不能继续 requirement / Round 2。
+> 其他 phase 不得代替 complexity-grading 补写 `problemCardConfirmedAt` / `projectConfirmationAt`；发现缺失时只能路由回 complexity-grading，让它在当前回复正文展示卡片并等待用户确认。
+
+触发 complexity-grading 时，必须把 ingest/new 得到的需求摘要和 `state.projects` 一起交给分级器展示：
+
+- **问题卡**：标题、来源、change、已导入 refs/assets、1-3 条目标/现象摘要。
+- **涉及项目**：`state.projects` 中的 primary / dependency，以及 `state.projectRouting.candidates` 中未选候选。
+- **项目清单文件**：入口或 requirement 阶段确认项目后会写 `project-roots.json`；后续阶段必须优先读取它，多个项目不在同一个父目录时尤其不能重新从当前目录猜。
+- **统一确认**：用户在同一张分级确认卡里确认或修改 level 与涉及项目；不要在分级卡只问 L0/L1/L2/L3，也不要把项目确认推迟到 requirement Round 1 后。
+- **可修改格式**：提示用户用 `项目=<primary>[,<dependency>]` 调整，或 `项目=none` 表示暂不关联代码项目。
+
+## Phase 顺序(硬约束)
+
+> 新流程优先使用入口命令自动生成的 workflow draft,再通过 `devflow flow picker` / `devflow flow apply-selection` / `devflow flow card` / `devflow flow confirm` 完成选项卡确认并冻结 `state.workflow.steps`。`flow check` 仍保留给脚本做预检。下面的 phase 顺序是内置 recipe 的默认展开形态,不是所有需求都必须硬走的唯一链路。`level` 只影响验证强度;实际 skill 编排由 workflow recipe 决定。完整说明见 `docs/workflow-orchestration.md`。
+
+**入口后的 workflow 确认：**
+```
+intake / brainstorm
+      ↓
+★ complexity-grading ★
+      ↓
+new / ingest 自动生成 workflow draft
+      ↓
+devflow flow picker --json
+      ↓
+用户如调整勾选: devflow flow apply-selection --selection='<json>' --json
+      ↓
+devflow flow card --json
+      ↓
+devflow flow confirm
+      ↓
+按 state.workflow.steps 逐步路由 skill
+```
+
+**标准路径（L1/L2/L3）：**
+```
+intake / brainstorm
+      ↓
+★ complexity-grading ★   ← 自动插入，输出判定卡，等用户确认后写 state.level
+      ↓
+devflow-requirement-analysis
+      ↓
+devflow-tech-spec ── (L2/L3 并行) ─→ devflow-test-spec
+      ↓
+plan
+      ↓
+apply  ←──── 内部 TDD 循环:write-test → impl → commit
+       ←──── L2/L3 可启用子 agent 编排（pre-review 内嵌）
+      ↓
+devflow-code-review  ←── 3 轮硬闭环
+      ↓
+verify  ←── reports/test-report.md 中所有 required sections must exist
+      ↓
+deliver  ←── 4 modes: pr / merge / keep / discard
+      ↓
+archive
+```
+
+**极简模式（L0 / micro）：** `devflow new <slug> --micro`
+```
+★ complexity-grading ★   ← 同样触发（L0 需用户二次确认）
+      ↓
+plan (1-3 行改动意图)
+      ↓
+apply (代码 + 单测)
+      ↓
+devflow-code-review ← 至少 1 轮
+      ↓
+verify (仅 test-report.md#unit，生成测试文档)
+      ↓
+deliver --notify=test-report (发测试邮件)
+  (不进 archive)
+```
+
+> **极简模式识别关键词**：用户说"极简模式" / "不要文档" / "直接写代码" / "就改一行" + 已明确改法，且改动范围 ≤ 1 文件、无 DDL、无接口变更。
+
+**硬规则**:不许绕过 workflow gate。用户说"直接写代码",先判是否满足极简模式条件;满足则走 L0/micro recipe;不满足则回:"当前 change 尚未确认 workflow,要我先执行 `devflow flow recommend` / `devflow flow draft`,还是你直接贴 URL 我走 ingest?"
+
+状态机详细转移规则(哪些 step/phase 之间可直接跳、哪些必须回退、skip 条件是什么)见 [`references/workflow-state-machine.md`](references/workflow-state-machine.md)。
+
+## 复杂度分级(L0 / L1 / L2 / L3)
+
+开始时必须判一个 level,写入 `state.json.level`。它影响:
+
+- 走哪条 phase 路径（L0 极简 vs 标准流）
+- `requirement-analysis` 的 clarifying 轮数
+- `tech-spec` 是否强制 `test-spec` 伴随
+- `plan` 的任务粒度下限
+- `verify` 的 required reports
+- `code-review` 的严重度尺度
+
+| Level | 粗判特征 | 例子 |
+| --- | --- | --- |
+| **L0** | 改动方向已完全确定 / 单文件 / 无 DDL / 无契约变更 / 用户不需要任何文档辅助 | 一行 bug fix、配置项调整、文字纠错 |
+| **L1** | 单文件 / 无 DDL / 无契约变更 / 小于 100 行 diff | 改一个错误提示文案、修一个空指针 bug、加一行日志 |
+| **L2** | 多文件、有 DDL 或契约变更、有测试计划 | 新增一个列表筛选、加一个审批状态、对接一个新的外部 API |
+| **L3** | 跨服务 / 有架构影响 / 有性能 / 安全 /合规评审 | 新模块、链路重构、热点接口优化、引入新中间件 |
+
+拿不准 → 默认 L2,告诉用户判定依据 + 如果命中 L3 的任一条件就升级。完整分级矩阵(含"L0 极简模式适用范围"、"L1 不做哪些步骤"、"L3 必须额外做哪些")见 [`references/complexity-grading.md`](references/complexity-grading.md)。
+
+## apply 阶段：子 agent 编排决策
+
+进入 apply phase 时，根据 plan 的 task DAG 和 ready wave 自动决定执行模式。用户不需要每次显式说"并行"或"用子 agent"。
+
+| 条件 | 决策 |
+| --- | --- |
+| L1 且只有 1 个 task | 普通模式，当前 agent 直接实现 |
+| task ≥ 2，但 task 间有强依赖 / 共享文件 | 子 agent + worktree，按依赖 wave 串行推进 |
+| 同一 ready wave 内 ≥ 2 个互不依赖 task | **自动子 agent 并行 + worktree**，不得等待用户再说"并行" |
+| 用户明确说「直接做」| 普通模式，记入 state 的 `applyMode: direct` |
+| 用户明确说「用子 agent」| 子 agent 模式，记入 `applyMode: subagent` |
+
+**授权规则**：plan checkpoint 确认的是"接受 plan 并允许进入 apply"；进入 apply 后，`devflow apply` / `/df:apply` 本身就是按 plan 执行的授权。若 plan 中存在可并行 ready wave，controller 必须自动并行分派，不得因为用户没有再次显式说"并行"就退回父 agent 顺序编码。只有在用户明确选择 `applyMode: direct`、工具环境不支持 subagent，或 task 之间存在共享文件 / 强依赖时，才不并行。
+
+子 agent 模式下，orchestrator 的角色变为 **controller**：
+- 只做协调（读文件、传上下文、分派子 agent、回答问题、执行 `--done`）
+- 自身不写代码
+- 详细流程见 `apply/references/subagent-orchestration.md`
+
+## 风险增强 skill 路由
+
+这些 skill 不是新的强制 phase,而是叠加在现有 phase 上的专项检查。orchestrator 只负责识别触发信号并把对应约束带入当前 phase。
+
+| 触发信号 | 路由 skill | 接入点 | 必须留下的证据 |
+| --- | --- | --- | --- |
+| React/Vue/Next/Vite/CSS/UI/页面/表单/弹窗/轮询页/redirect 改动 | `devflow-frontend-quality`;同时 `devflow status risk add frontend_change --reason="..."` | review + verify | `reports/test-report.md#joint` 或 `#e2e`;无法跑浏览器时写入 `verify.md` 原因 |
+| Jenkins/GitHub Actions/GitLab CI 失败、required check 未过、PR/MR comment 未解决 | `devflow-ci-fix`;同时 `devflow status risk add ci_failure --reason="..."` | review → apply → verify → deliver | CI 日志归因、comment 分级、修复后最小测试 |
+| package/go module/maven/python 依赖、lockfile、漏洞修复、框架升级 | `devflow-dependency-upgrade`;同时 `devflow status risk add dependency_change --reason="..."` | apply + verify | 版本清单、breaking/peer 风险、manifest+lockfile、回滚说明 |
+| 用户说"继续"、上下文压缩、长任务换人/换 agent、工作中断恢复 | `devflow-handoff-resume` | 任意 phase | `handoff.md` 或从 `state.json`/checkpoint/test-report 恢复出的下一步 |
+| L3、安全/支付/隐私/鉴权/权限/回调/上传/OSS/SLS/token/cookie/password | `devflow-security-hardening`;同时 `devflow status risk add security_sensitive --reason="..."` | design + review + verify | design security section、review security finding、验证或风险接受 owner/reason |
+
+优先级:
+
+1. `handoff-resume` 优先于新建 change,避免用户说"继续"时重新开始。
+2. `ci-fix` 优先于普通 deliver;required checks 未过不能直接交付。
+3. `security-hardening` 可升级 level;如果 L1/L2 发现支付/鉴权/隐私风险,先回 complexity/design 确认是否升 L3。
+4. `frontend-quality` 和 `dependency-upgrade` 不单独改变 phase,但会增加 review/verify 的必查项。
+
+## 硬闸门(Hard Gates)
+
+本 skill 强制检查下面这些闸门,sub-skill 被本 skill 调用时必须已满足前置;不满足则**先回退**,不要放行。
+
+| 目标 phase | 前置硬闸门（标准 L1/L2/L3） | 极简模式(L0)差异 |
+| --- | --- | --- |
+| `requirement` | `state.level` 已写入（complexity-grading 已完成） | — |
+| `plan` (L0) | `state.level = L0` 且用户已二次确认极简模式 | — |
+| `tech-spec` | `requirement.md` 存在且有 ≥1 条可验收的功能需求 | **跳过** |
+| `plan` | `design.md` 存在且有"改动点汇总表";若有 `tests.md` 则 plan 必须引用 TC，否则在 task 的 Test 字段写内联验收 | L0：`plan.md` 1-3 行改动意图即可，无 design.md 要求 |
+| `apply` | `plan.md` 存在且非空,每个 task 含 Files/Behavior/Test/Implementation/Commit | L0：`plan.md` 存在即可，无 5 要素要求 |
+| `code-review` | `state.phases.apply.status=completed`,至少一次 `devflow test unit` 产出 `reports/test-report.md#unit` | 同标准（不可降低） |
+| `verify` | `state.phases.review.status=completed` 且 `code-review-report.md` 存在 且 `finalOutcome ∈ {pass, force-pass}` | 同标准（不可降低） |
+| `deliver` | `state.phases.verify.status=completed`,所有 required report sections 存在,`devflow doctor --scope cred` 无错 | L0 还需：自动触发 `devflow deliver --notify=test-report` 发测试邮件 |
+| `archive` | `state.phases.deliver.status=completed`,MR / PR 已合入主干,spec deltas 可无冲突合入 | L0 **跳过 archive** |
+
+执行前闸门校验使用 `devflow doctor audit`(code-only 程序化调用),结果作为"是否阻止进入下一 phase"的判定依据。
+
+## 异常诊断(sub-skill 报错时)
+
+sub-skill 用"完成状态协议"回报 `DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_INPUT`。本 skill 据此决定回退 / 追问 / 终止。
+
+| sub-skill 状态 | 典型场景 | 本 skill 动作 |
+| --- | --- | --- |
+| `DONE` | 正常完成 | 进入下一 phase(按上表) |
+| `DONE_WITH_CONCERNS` | 完成但有遗留风险(如 SHOULD 未修、监控未配齐) | 进入下一 phase,但在 state 里打 `followup` 标签,deliver 时会拼进 PR |
+| `BLOCKED` | code-review 3 轮未过 / verify 缺 required report / archive 有 delta 冲突 | 按 `references/escalation-matrix.md` 表决定回退到哪个 phase,要求用户或 sub-skill 修正后再来 |
+| `NEEDS_INPUT` | brainstorm 要澄清 / requirement-analysis Round 1 Q / code-review 要仲裁 | 代 sub-skill 向用户收集输入,本 skill 不代答 |
+
+回退决策矩阵见 [`references/escalation-matrix.md`](references/escalation-matrix.md)。
+
+## 常见误用(Anti-patterns)
+
+- **⛔ 自己 curl / fetch / 用浏览器抓 URL**：用户给了 URL，agent 不应该自己去抓，**必须执行 `devflow ingest "<url>"` shell 命令**。devflow 内部有配置好 token 的 intake provider，agent 自己去抓一定会被认证拦住（尤其内网 URL）。报错"需要登录"/"无法访问"时，正确处理是执行 `devflow ingest`，而不是让用户复制粘贴内容。
+- **⛔ intake/brainstorm 完成后直接走 `devflow requirement`**：这是最常见的错误！intake/brainstorm → **必须先触发 complexity-grading** → 用户确认 level → 才能进 requirement。`nextAction: devflow requirement` 在 currentPhase=intake 时是错的。
+- **⛔ 部署类请求先跑 `devflow status` / `devflow init`**：用户说"部署测试"、"提测"、"发测试环境"时,优先执行 `devflow deploy test --project=<name>`。没有 `devflow/config.json` 不阻塞部署;项目/Jenkins 配置来自用户级 `~/.devflow/projects.json`。
+- **替用户拍板 L1/L2/L3**:分级影响后续所有 phase 的尺度,一定要给依据让用户确认,别默认收敛。
+- **放行"我们边写边想"**:这是跳 phase 的常见借口;如果用户真的很急,走 L1 快路径,别假装走了 L2。
+- **对着 PRD URL 直接开始写代码**:URL 要走 `devflow ingest` → `complexity-grading` → `requirement-analysis`,不要把 URL 当作"已有 requirement"。
+- **sub-skill 回 BLOCKED 时继续调用下一个**:必须先按 escalation-matrix 回退处理。
+- **把自己变成 sub-skill**:orchestrator 不写 `requirement.md` / `design.md` / `plan.md`;想动手时请改调 sub-skill。
+- **忘记更新 state.json**:每次 phase 推进必写 `state.json`(sub-skill 负责写,但本 skill 要校验写成功)。
+- **L1 任务硬推 L3 全套**:浪费用户 token 与耐心;判定分级要坦诚,哪怕偶尔误判也胜于过度流程化。
+
+## 常用 slash 命令
+
+`/df:status`、`/df:doctor`、`/df:ingest <input>`、`/df:brainstorm`、`/df:grade`（手动触发 complexity-grading）、`/df:requirement`、`/df:design [--with-tests] [--with-spec]`、`/df:plan`、`/df:apply`、`/df:review`、`/df:verify`、`/df:deliver`、`/df:archive`、`/df:knowledge <deposit|query|sync>`。
+
+## 每个 phase 完成后：强制提示下一步
+
+> **HARD RULE**：任何 phase 输出 STATUS 后，agent **必须**立即以醒目格式展示下一步，不得让用户猜测。
+
+格式：
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ [当前 phase] 完成
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+下一步：[下一步操作的一句话描述]
+命令：`<nextAction command>`
+
+回复明确确认词或告知调整意见；涉及用户确认点时不得复用早前的"继续"。
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+- `result: DONE` → 展示下一步 + 命令，等待用户「继续」
+- `result: DONE_WITH_CONCERNS` → 展示下一步 + **明确列出遗留风险**，让用户决定是否推进
+- `result: BLOCKED` → 不展示下一步，只展示**如何解除阻塞**
+- `result: NEEDS_INPUT` → 展示需要用户提供的信息（问题列表）
+
+## 完成状态协议
+
+orchestrator 每次介入都以下面这段收尾(给调用它的 agent runner 看):
+
+```
+---STATUS---
+result: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_INPUT
+currentPhase: <phase>
+nextAction: <command user/agent should run next>
+gates: [list of gates passed / blocked]
+---END_STATUS---
+```
+
+### nextAction 映射表（必须按此填写，不得自行推断）
+
+| currentPhase | 正常 nextAction | 说明 |
+| --- | --- | --- |
+| `intake` | **触发 complexity-grading skill** | ingest 完成后立即分级，不是 `devflow requirement` |
+| `brainstorm` | **触发 complexity-grading skill** | proposal.md 完成后立即分级 |
+| `complexity-grading` | `devflow requirement`（L1/L2/L3）或 写 plan.md（L0） | 分级确认后才进入 requirement |
+| `requirement` | `devflow design` | — |
+| `design` | `devflow plan` | L2/L3 先 `devflow test-spec` |
+| `plan` | 等用户确认计划审查卡（确认后 `devflow apply`） | plan DONE 后必须展示 `plan.md` 摘要和任务清单；写入 `state.planReviewConfirmedAt` 前不得自动执行 `devflow apply` |
+| `apply` | `devflow review` | — |
+| `review` | 等用户确认 `verify_start` 检查点（先 `devflow checkpoint resolve --id=<checkpoint-id> --decision=start-verify`，再由用户另行确认或触发 `devflow verify --slug=<slug>`） | review 通过后不得自动执行 verify；不得把早前"继续/按推荐"当作 verify 确认 |
+| `verify` | `devflow deliver` | — |
+| `deliver` | `devflow archive` | L0 例外：不进 archive |
+
+> **重要**：intake / brainstorm 完成后，`nextAction` **永远是"触发 complexity-grading"**，
+> 绝对不能直接写 `devflow requirement`。这是最常见的误用，已列入 Anti-patterns。
+
+> **重要**：plan 完成后，`nextAction` 是"等待用户审查 plan"；不得自动执行 `devflow apply`。
+
+> **重要**：review 通过后，`nextAction` 只能是确认 `verify_start` 检查点。不得输出或执行 `devflow checkpoint resolve ... && devflow verify ...` 这种串联命令；不得因为用户在更早阶段说过"继续吧"、"按推荐"、"剩余按推荐"就自动开始 verify。即使用户在 review pass 卡片后回复"继续"，也只能 resolve checkpoint，随后停止并展示 `devflow verify --slug=<slug>` 作为新的下一步。
+> 只有用户明确确认计划，且 state 写入 `planReviewConfirmedAt` 后，才允许进入 apply。
+
+## 参考
+
+- [`references/routing-rules.md`](references/routing-rules.md) — 入口识别细则(多 URL / JIRA / incident / 模糊 idea)
+- [`references/workflow-state-machine.md`](references/workflow-state-machine.md) — phase 转移矩阵 + 可跳 / 必回退条件
+- [`references/complexity-grading.md`](references/complexity-grading.md) — L1/L2/L3 完整判定矩阵与每级的流程差异
+- [`references/escalation-matrix.md`](references/escalation-matrix.md) — BLOCKED 时回退到哪个 phase、如何向用户解释

package/skills/df-orchestrator/references/complexity-grading.md

@@ -0,0 +1,177 @@
+# df-orchestrator / complexity-grading
+
+L1 / L2 / L3 复杂度分级。开始任务时由 orchestrator 判一个初始 level,写入 `state.level`,后续所有 phase 按此 level 决定尺度。
+
+---
+
+## 为什么要分级
+
+> 同样的流程套在 bug fix 和模块重构上,一定有一头痛苦:
+> - 套 L3 到 bug fix,用户被问懵,半天写不出 proposal;
+> - 套 L1 到模块重构,上线日惊现"这个场景没测过"。
+
+分级的目的是:**用尽可能少的流程覆盖尽可能多的风险**。每升一级,多产几份文档;但也换来早暴露多一阶的风险。
+
+> 4 个级别:L0(极简)/ L1(轻量)/ L2(标准)/ L3(加固)。L0 是最轻的,适合"改动方向已确定、不需要任何分析文档"的场景。
+
+---
+
+## 判定矩阵(维度 + 信号 + 级别)
+
+### 单维度信号
+
+| 维度 | L1 信号 | L2 信号 | L3 信号 |
+| --- | --- | --- | --- |
+| **代码规模** | 单文件、diff < 100 行 | 2-8 文件、diff < 500 行 | > 8 文件 / diff > 500 行 / 跨多模块 |
+| **数据层** | 无 DDL / 无数据迁移 | 有 DDL,但幂等、可回滚 | 跨表 / 大表改列 / 跨服务一致性 |
+| **对外契约** | 无接口变更 | 新接口 / 改字段类型(兼容) | 删字段 / 改语义 / 跨服务契约 |
+| **并发 / 一致性** | 单路径 | 单表事务 | 分布式锁 / Saga / 补偿 / 最终一致 |
+| **性能要求** | 用户无感知 | 延迟/QPS 不退化 | 明确 SLO / 压测 / 容量评估 |
+| **安全 / 合规** | 无敏感数据 | 权限校验、日志脱敏 | 涉及合规审计、外部审计、隐私范围变更 |
+| **团队 / 依赖** | 一人完成 | 本团队 2-3 人 | 跨团队 / 跨部门依赖 |
+| **灰度 / 回滚** | 不需要 | 简单 feature flag | 分批灰度 + 白名单 + 回滚演练 |
+| **监控 / 告警** | 不需要 | 加指标 | 加指标 + 告警规则 + runbook |
+| **测试类型** | 单元 + 冒烟 | + 集成 | + 端到端 / 性能 / 回归 |
+
+### 综合判定规则
+
+> **就高不就低**:任一维度命中 L3,整体就是 L3。
+
+1. 先按每个维度单独判级。
+2. 取**最高级**作为综合级。
+3. 如果 ≥ 2 个维度命中上一级,**升一级**(例如 2 个 L2 + 1 个 L1 → 仍为 L2;但 2 个 L3 + 若干 L2 → L3 无疑)。
+4. 拿不准,默认 L2。
+
+### 常见判定例
+
+| 任务 | 命中维度 | 级别 |
+| --- | --- | --- |
+| 改一个错误文案 | 单文件 | **L1** |
+| 修空指针 bug + 加测试 | 单文件 + 单元测试 | **L1** |
+| 新增"按标签筛选"列表接口 | 多文件 + DDL + 契约 + 单测集成 | **L2** |
+| 对接一个新的三方支付 | 多文件 + 契约 + 安全 + 监控 | **L2/L3**(按金额/合规升 L3) |
+| 全量接口加 traceId | 跨多服务 + 一致性 + 监控 | **L3** |
+| DB 分表 | DDL + 数据迁移 + 性能 + 灰度 | **L3** |
+| Redis 升级 | 依赖 + 回滚 + 风险 | **L3** |
+
+---
+
+## 每级的流程差异
+
+### L0 流程(极简模式)
+
+> **适用场景**：改动方向已完全确定、开发者不需要任何需求/设计文档辅助、只需要走质量闸和通知。
+>
+> **典型任务**：一行 bug fix、配置项调整、文字纠错、已有代码小重命名、加一条日志。
+>
+> **禁用场景**：任何 DDL 变更、接口变更、跨多文件的逻辑修改 → 强制升 L1。
+
+触发方式（满足任意一条）：
+- 用户明确说"**极简模式**" / "**不要文档**" / "**直接写代码**" / `devflow new <slug> --micro`
+- 用户说"就改一处"/"就这一行" + 已经口头描述了改法
+
+| phase | 是否必做 | 说明 |
+| --- | --- | --- |
+| intake / brainstorm | **跳** | — |
+| requirement | **跳** | — |
+| design | **跳** | — |
+| test-design | **跳** | — |
+| plan | **最简替代**：只在 `plan.md` 写 1-3 行改动意图 + 预期行为即可，不强制 5 要素格式 | |
+| apply | 必做 | 写代码 + 单测；单 worktree，无子 agent |
+| code-review | **必做，不可跳** | 至少走 1 轮；尺度偏向"生产安全"；L0 允许 `force-pass` 当 SHOULD 未解时通过 |
+| verify | **必做**：仅 unit test；需产出 `reports/test-report.md#unit` | 不要求 smoke / integration / perf；允许"跑单测 → 自动生成测试文档"一步完成 |
+| deliver | **必做**；模式通常 `pr` | 额外动作：**自动发测试邮件**（`devflow deliver --notify=test-report`，邮件正文含测试文档摘要） |
+| archive | **跳** | 无文档产物可沉淀；如有可复用经验可直接写入 `knowledge/` 后手动 `devflow knowledge deposit` |
+
+**极简模式质量底线**（不可降低）：
+- 至少 1 个单测覆盖核心改动路径
+- code-review 至少 1 轮（MUST 类问题全解）
+- 测试文档（`reports/test-report.md#unit`）落盘
+- 测试邮件送达 deliver 配置的收件人
+
+---
+
+### L1 流程(瘦身版)
+
+| phase | 是否必做 | 特殊处理 |
+| --- | --- | --- |
+| intake / brainstorm | 二选一;brainstorm 最多 1-2 个澄清问题 | 快速收敛 |
+| requirement | 做,但可只一轮(Round 2 可选) | 重点是 AC;可直接沿用 bug 复现步骤 |
+| design | 做,但可精简为"改动点汇总" + 风险 1 段 | 无 trade-off 章节,无架构图 |
+| test-design | **跳** | 测试直接写进 plan.md |
+| plan | 1-3 个 task | |
+| apply | 单 worktree,无需 swarm | |
+| code-review | 仍做,但 round 2 通常 pass | 审查尺度"生产安全" > "代码风格" |
+| verify | unit + smoke | 可不产 self-test |
+| deliver | 通常 mode=pr | |
+| archive | 做 | 如有可复用经验，直接写入 `knowledge/<分类>/` |
+
+### L2 流程(标准版)
+
+所有 phase 都做,无额外操作。clarifying 轮数按 requirement-analysis skill 的"二轮协议"。
+
+### L3 流程(加固版)
+
+| phase | 比 L2 多做的事 |
+| --- | --- |
+| brainstorm | 明确 stakeholders 与 decision-makers |
+| requirement | Round 1 必须访谈 ≥ 2 个角色;非功能需求强制(perf / security / availability) |
+| design | 必须列 ≥ 2 alternatives + trade-off,必须有灰度 / 回滚章节 |
+| test-design | 必须有 e2e 场景 + 性能基线场景 |
+| plan | 任务粒度 30-60 分钟,parallel task 用 worktree swarm |
+| apply | PR 拆分为多个原子 MR,如跨服务则每个服务独立 MR |
+| code-review | 强制 reviewer 外部视角 + 可能的"第三视角仲裁" |
+| verify | 必加 perf 或 regression 测试 |
+| deliver | PR 描述附带 runbook 和灰度计划 |
+| archive | `knowledge/` 条目必写 + 视情况出 postmortem / ADR |
+
+---
+
+## 调整级别(level 变更)
+
+任务过程中可能发现初判错了。level 可以**升级**或**降级**,但都要留 audit。
+
+### 升级(L0 → L1、L1 → L2、L2 → L3)
+
+- L0 → L1：发现需要超过 3 个文件改动 / 有接口变化 / 有 DDL
+- L1 → L2：发现隐藏的 DDL / 新接口 / 跨服务依赖
+- L2 → L3：发现需要性能评估 / 合规确认
+- 触发 `devflow status set-level <new>`,orchestrator 记 audit + 提示"补做 X、Y 文档"
+
+### 降级(少见,需慎重)
+
+- 发现原设计的高风险部分可以推迟,本次缩小 scope
+- 触发 `devflow status set-level <new> --reason=...`(reason 必填)
+- orchestrator 记 audit;如果已有文档产物就不删除,只是在 archive 时保留
+
+---
+
+## 反常识:别在 L1 上偷懒,也别在 L3 上发疯
+
+- **L1 偷懒踩坑**:省掉 brainstorm 那 1 个澄清问题,结果需求理解错,apply 之后发现方向偏;省掉 smoke test,结果线上一提测就爆。**省了 30 秒,返工 3 小时**。
+- **L3 发疯踩坑**:把一个正常的数据迁移硬拉到走 5 alternatives + 全 stakeholder 访谈,结果 design 写了 2 周还在讨论。**该有边界,不能无限展开**;L3 的 design 应该"够做决策就停",alternatives 写 2-3 个够用。
+
+---
+
+## 自动判级提示(orchestrator 给用户的话术)
+
+判级完后,告诉用户判定依据:
+
+```
+本任务初判 L2,依据:
+  ✓ 代码规模维度 → L2(预计改 4-6 个文件)
+  ✓ 数据层维度   → L2(新增 1 个表 + 加列,DDL 可重入)
+  ✓ 对外契约     → L2(新增 1 个接口,无兼容性问题)
+  ✗ 并发一致性   → L1(单表事务即可)
+  ✗ 安全合规     → L1(无敏感数据)
+综合取最高 → L2。
+
+若后续发现触发 L3 条件(跨服务、分布式锁、数据迁移),我会建议升级;
+若确认实际上只是一行改动,可以告诉我降级到 L1,省掉 test-design 一步。
+```
+
+---
+
+## 本文与 SKILL.md 的关系
+
+SKILL.md 只给了三级的粗判特征 + 例子。完整维度表、每级流程差异、level 变更流程、话术模板全在这里。orchestrator 判级时必须按本文 "判定矩阵" 逐维度打分,不要只凭感觉。