super-plumber: Skill for Claude Code

Plumber Design — 主线程编排剧本：需求 → 拓扑图 → 预览审核

Overview

• 产出物 = 用户审核通过的拓扑图（v0.5 起含领域结构：bounded context 与 ADR 是图中一等公民），不是执行结果。
• 本页是完整设计流程：无 sp-designer 也可独立完成需求理解、建图、验证与审核。Operations 手册提供操作语法；sp-designer 是可选的 subagent 角色适配，不是本技能的运行依赖。细则按需读 attachments/。

审核是硬性 gate：用户批准之前绝不进入执行阶段；审核通过后切换 plumber-execute。

代理层级边界：skill 文本和“有 subagent 工具”都不能可靠识别代理深度，故每个会话默认无派单权，不得从能力存在推断授权。只有直接承接用户需求的外层协调者可持一次性、不可转授的 orchestrator 授权直接派 sp-designer；授权在派发时耗尽，子任务只收到 leaf 约束，绝不可向下复制。缺授权一律走 solo。当前通用宿主未向 skill 暴露可验证的签名层级令牌，因此这是行为协议而非硬隔离：需要强保证的宿主还必须在工具层移除子 agent 的派发能力。

When to Use / 衔接关系（subagent 与 skill 已解耦）

• Use：接到新需求需拆解为 3–20 个有依赖关系的任务；设计或修改 .graph/ 拓扑（entry/exit、节点、边）；验证拓扑质量；serve 预览并请求用户审核；审核后提修改意见 → 回本 skill（改图 → 重验 → 重预览 → 再审）。Do NOT：执行已审核通过的拓扑（用 plumber-execute）；纯 todo 列表。
• 本技能保留完整设计方法；sp-designer 供支持 subagent 的应用独立派单使用，两者允许必要的方法重叠。
• 外层协调者持未使用的 orchestrator 授权且需要专职设计 → 按「派单模板」直接派一个叶子 sp-designer；未持授权或检测不到可用 subagent → 走「solo 分支」主线程扮演。被派会话一律不得再派。
• 用户审核通过 → 进入 plumber-execute（建议用户明确说"开始执行"）；节点状态裁决 / checkpoint 聚合 / 重试管理 → super-mario agent。

流程（Phase 0 定档 + 5 步，严格按序，绝不跳步）

Phase 0 — 路由决策表（两问定档，先于 Step 1；DEC-2，adr_0018 修订）

按顺序定档：① 关键未知是否阻止形成可信交付计划？ 是 → program（切 chart 模式，研究后渐进完善计划）；否 → ② 一个会话内能完成并验收吗？ 是 → quick（单节点图，entry/exit 各一句话，跳过 serve 人审与 doctor、只跑 graph validate，claim→report→passed，init 后 graph approve --by <agent 名> --status self 自签）；否 → standard（Step 1–5 一项不减）。跨会话、跨图、跨仓库和并行人数不单独触发 program。可信计划的定义、判例、存疑处理、转档条件与凭据纪律（adr_0016）→ attachments/workflow-classes.md；定档后出现使主要计划失效的关键未知 → 回本节重判。

Step 1 — 理解需求

向用户确认：目标是什么？交付物是什么？边界（不做什么）？有歧义就问，不要猜——需求不清，图必错。

Step 2 — 设计建图（可选委派）（先 entry/exit 后 L1-Ln 是铁律）

• 两条铁律写进派单：entry 和 exit 永远第一个定义（先图级字段后 L1-Ln 分层动脉）；需求跨多个关注点 → 领域建模与 ADR 甄别是 designer 必做项（bounded context 划界/术语表/跨 context 契约边、够三判据的 ADR），点名不可裁剪。节点类型×默认纪律与 plan 纪律指针写法（WF07）→ attachments/disciplines-map.md。
• 按下列完整建图序列执行并通过体检，操作语法查手册 §2；不要求读取或安装 designer 角色文件。置层准则（IL-001）：level 表达少数有意义的分层带（与分期/领域结构对齐），不把依赖深度编码进 level，层数建议 ≤5、避免单节点层；designer 出图前先声明置层方案（分几带、每带含义），声明与图不符按设计缺陷返工——细则 → 手册 §2.9。
• 完整建图序列：先定义图级 entry（输入/约束）与 exit（交付物/验收），再划 L1 主干（通常 3–7 项，quick 单节点例外）并细化可执行节点。每个 task 写明 plan、可核验 DoD、level 与 checkpoints（通常 2–4 个，quick 按档位裁剪）。依赖边 source 为前置、target 为后继；按真实门槛选 depends_on、fan_out/fan_in 等边型，不把所有关系都写成阻塞依赖（九边语义查手册 §3）。跨关注点时建立 context 的 boundary、glossary、contracts，明确成员归属与跨域契约。决策同时满足“难逆转、脱离上下文令人费解、存在真实权衡”才建 proposed ADR 并以 decides 挂到管辖对象，否则写进 plan；accept/supersede 留给裁决方。设计报告列 L1、置层方案、context/ADR 数量（为零说明理由）和验证结果。
• 查历史拒绝理由（WF05，出图/改图前必做）：看软删归档（ls .graph/*/nodes/*.deleted*.yaml，读 deleted_reason 等顶层键）→ graph events -k node_deleted --json 补全旧档理由 → 待建/待改节点命中已删方案时，设计报告逐一回应删除理由（换道，或给出理由已失效的依据），无回应 = 重蹈已否决方案，按设计缺陷返工。有 subagent 时主线程先筛、命中结果随派单交付 designer；solo 分支动笔前自跑。
• 有未使用的 orchestrator 授权且需要专职设计：按「派单模板」直接派出一个叶子 sp-designer，等待其交付 .graph/ 与设计报告；无授权、无 subagent 或当前已经被派 → 走「solo 分支」。