| name | mid-plan |
| description | Use when the user says "mid 计划", "中等需求设计", "需求架构一起做", "批量设计需求架构", or has a L2-complexity feature (multi-module single system, 3-5 Waves, 2-3 NFR dimensions). Produces requirements.md + system-architecture.md (+ .html) + clarify.json (CW clarify action 入参). 对应 CW action: clarify (skill 名 mid-plan 对应 CW 的 clarify 状态). Not for L3 heavy (use full-*). Not for L1 small feature (use lite-plan). Not for issues/nfr/code-arch/execution (that is mid-detail-plan). |
mid-plan（需求 + 架构，L2 标准档）
对应 CW action: clarify（coding-workflow tool；skill 名 mid-plan 对应 CW 的 clarify 状态）。
本 skill 产出 clarify.json + review-fix-loop 收敛后落盘 review 文件。完成后调
cw(action=clarify, topicId, clarifyJson)——CW 预检 changes/review-{clarity,architecture}.md
存在 → 跑机器检查（clarity/architecture）→ pass 后返回 nextAction（→ detail）。
为 L2 复杂度需求同时产出 requirements.md + system-architecture.md。内容对齐 full-clarity +
full-architecture 全量；编排改为 draft → batch-ask → review-fix-loop（mid 风格）。
[铁律] 本 skill 只做需求 + 架构设计，不进入 issue 拆分 / NFR / 代码架构 / 执行计划（那是 mid-detail-plan）。
也不做代码级 API 签名/时序图/DB schema（属 full-code-arch，mid-detail-plan 复用）。
范围守门（L2 判定，开始前必做）
[MANDATORY] 按 ../full-shared/references/loop-skeleton.md「复杂度自评」（8 信号打分）判定档位：
- L2（12-18 分，本 skill 目标） → 继续
- L1（8-11 分，小功能无架构改动） → 停止，改用
/skill:lite-plan
- L3（19-24 分，重型） → 停止，改用 full 工作流（每阶段深度收敛不可省）
mid 的定位是 L2 专用。L1 走 lite 更快，L3 走 full 更稳。范围错了后面全白做。
判定结果写入 {topic_dir}/_progress.md frontmatter 的 complexity_tier，用户可覆盖（判定后 ask_user 确认一次）。
前置
- coding-init 已完成：项目文档容器就绪（AGENTS.md/CONTEXT.md/ARCHITECTURE.md 骨架）。未完成 →
/skill:coding-init
- 已调
cw(action=create, slug, tier="mid", objective) 拿到 topicId（第一步，锁 tier=mid；后续 clarify.json 路径依赖此 topicId）。Step 0 建的是文件系统目录（.xyz-harness/{slug}/ + decisions.md + _progress.md），CW topic 由 create 建——两者都必要，不互替
执行流程
按当前进度 read 对应参考，逐步推进：
| 步骤 | 做什么 | read 参考 |
|---|
| 0. 建 topic 基建 | 建 {slug}/ 目录 + decisions.md + _progress.md | ../full-clarity/references/decisions-template.md + _progress-template.md |
| 1. 统一起草初稿 | 主 agent 读代码+文档，opinionated 起草 requirements.md + system-architecture.md | ../full-clarity/references/deliverable-template.md + ../full-architecture/references/{deliverable-template|architecture-perspectives}.md |
| 2. 批量收集决策点 | draft 过程积累「代码答不了」的决策，分类（D-不可逆/D-可逆/K） | ../mid-shared/references/batch-ask.md（B1+B2 阶段） |
| 3. 批量提问 | D-不可逆 + K 打包，一次 ask_user（4~8 个，附推荐+理由） | ../mid-shared/references/batch-ask.md（B3 阶段） |
| 4. 纳入 + 机器检查 | 答案落 decisions.md + 更新初稿；机器检查由 CW gate 在 cw(action=clarify) 调用时自动执行（clarity/architecture） | — |
| 5. review-fix-loop | 派 4 路并行 reviewer → 汇总 must_fix → 修复 → 收敛（MAX=2 轮） | ../mid-shared/references/review-fix-loop.md + 本 SKILL「维度审查分配」节 |
| 6. 二次 ask | loop 残留 D-不可逆打包二次 ask_user | ../mid-shared/references/batch-ask.md（二次 ask 节） |
| 7. 定稿 + 渲染 | 定稿两份 .md + 派 fresh subagent 加载 coding-visualizer 渲染 2 个 HTML | coding-visualizer skill |
[铁律] 步骤 1 不做 issue 拆分 / NFR / 代码架构。架构决策落到 system-architecture.md 为止，向下只给约束（grep 规则、Port 清单、不变式），不给实现。
Announce at start: "我正在使用 mid-plan skill 来高效产出需求 + 架构设计（L2 标准档）。"
Step 0：建 topic 基建
mid-plan 是 mid 工作流首阶段，负责建 topic 级基建：
- 建 topic 目录：
.xyz-harness/{slug}/（{slug} = CW create 时传入的 slug；与 create.ts 默认 topicDir = join(workspacePath, '.xyz-harness', slug) 对齐，不再用日期前缀 {yyyy-MM-dd}-{topic-slug}）
- 建 decisions.md（空骨架，直接 copy）：
cp ../full-clarity/references/decisions-template.md {topic_dir}/decisions.md
decisions.md 是本 topic 的 append-only 决策账本，mid 全程沿用 full 的机制（见 ../full-shared/references/loop-skeleton.md Step 1.2）。
- 建 _progress.md（含 complexity_tier）：
cp ../full-clarity/references/_progress-template.md {topic_dir}/_progress.md
写入 complexity_tier: L2（范围守门判定结果）。
状态追踪说明： mid 不接 design_status 的 7 阶段状态机（阶段语义对不上——mid 合并成 2 阶段）。用 _progress.md + todo 追踪。_progress.md 记跨会话交接（已完成阶段表 + 不可推翻决策引用 decisions.md）。
Step 1：主 agent 统一起草初稿
先读已确认决策（建工作上下文）： mid-plan 是首阶段（decisions.md 刚建为空），直接进起草。读 CONTEXT.md（统一语言）+ 项目根 ARCHITECTURE.md（当前架构态，coding-init 建的骨架或已有文档）+ 项目源码。
起草顺序（先需求后架构，但同一 Step）：
1a. requirements.md（业务目标，不碰实现）
读 ../full-clarity/references/deliverable-template.md 用其骨架。沿业务目标树起草：
业务目标（根）
├── G1: {目标} — 成功标准（可衡量）
│ ├── Actor: 谁来达成？ → 用例 → 主流程/替代/异常 + 前置/后置
│ ├── 数据: 产生/消费什么？
│ └── 界面: 在哪完成？
└── 约束 & 不做
起草纪律（agent opinionated，不等问题）：
- 基于代码扫描 + 业务输入直接产出初稿，遇到「代码答不了」的决策点记到 batch 队列（Step 2），不立即问
- 能 grep 代码答的（现有 Actor、现有用例、现有数据表），dispatch 只读 subagent 查，不问用户
- 业务用例非技术用例；区分「目标」和「方案」
- 同步写入项目根
CONTEXT.md（统一语言/领域术语）
[铁律] requirements.md 不考虑系统实现。 不做技术栈选型/架构设计/API 定义/数据库建模。技术约束（「必须用 Postgres」）只记录到 Constraints 不展开。与 full-clarity 同源铁律。
1b. system-architecture.md（系统设计）
读 ../full-architecture/references/deliverable-template.md + architecture-perspectives.md（边界划分原则、复杂度归位、证伪三连）用其骨架。沿架构决策树起草：
系统设计立场（根：核心计算是什么？）
├── 分层决策 → DDD 4 层 or 三层？（看核心计算是业务规则还是技术编排）
├── 领域建模 → 有状态机？aggregate/实体 or DTO？
│ └── Status 枚举 + Reason 字段（正交）+ 不变式守卫
├── 模块拆分 → 按变化轴（问「会因为什么改」，答 2+ 原因=该拆）
└── 外部依赖 → 4 类分类决定 port（In-process/Local-sub/Remote-owned/True-external）
统摄 metric：复杂度归位 — 所有决策回问「复杂度是否归位到正确的地方？」。边界划分原则（三层代价台阶）、Seam 纪律（一个 adapter=假设 seam，两个=真 seam）、Port≠interface（结构边界 vs 控制边界反向）——详见 architecture-perspectives.md。
[铁律] system-architecture.md 不进入代码级细节。 不做代码级 API 签名/时序图/DB schema（属 full-code-arch，mid-detail-plan 复用），不做 issue 拆分（mid-detail-plan），不做性能/成本量化（mid-detail-plan 的 nfr）。
Step 2：批量收集决策点
读 ../mid-shared/references/batch-ask.md（B1 收集 + B2 分类阶段）。
draft 过程中积累的决策点，按四类分流：
| 类型 | 本阶段典型 | 处理 |
|---|
| D-不可逆 | 分层（DDD4 vs 三层）、核心计算复杂度预期、Seam/port 真伪、领域模型边界（aggregate vs DTO）、状态机结构 | 进 batch 提问（标红） |
| D-可逆 | 命名、模块拆分细节、Context Map 画法、不变式推导 | agent 自决，定稿暴露 |
| K | 归档保留期合规、外部契约稳定性、业务规则细节 | 进 batch 提问 |
| 可代码自决 | 现有依赖 4 类分类、现有状态枚举、现有模块边界 | agent 直接产出 |
Step 3：批量提问（一次 ask_user）
读 ../mid-shared/references/batch-ask.md（B3 批量提问阶段）。
本阶段必问决策点清单（D-不可逆 + K，合并 clarity + architecture）：
- 核心计算的复杂度预期 — "核心是业务规则编排（→DDD4层）还是技术流程编排（→三层）？未来会长出复杂规则引擎吗？"【D-不可逆】
- 业务目标 + 成功标准 — 可衡量（「X 达到 Y 指标」非「做好 X」）。目标 vs 方案要分清。【D-不可逆】
- Actor 清单（含隐含） — 审核人/管理员等隐含 Actor 是否纳入。【K】
- 状态机结构 + 严格度 — 有哪些状态转换？显式转换表（紧）还是只守终态（松）？【D-不可逆 + D】
- Seam/port 真伪边界 — 哪些依赖值得做 port（可替换性 vs 复杂度成本）？假设 seam 还是真 seam？【D-不可逆】
- 领域模型边界争议 — aggregate vs DTO、有状态机 vs 无状态。【D-不可逆】
- 跨系统依赖契约 — 外部系统功能依赖 + 同步/异步 + 自有可控 vs 第三方不可控。【K】
- 搭便车改造清单（候选） — business-goal→system-goal 转换时发现的「趁机可做的重构」，逐个问本轮是否做（候选意向，mid-detail-plan code-arch 骨架验证后最终确认）。【D】
决策点细节（提问话术、方案对比、推荐理由的展开）参考 ../full-clarity/SKILL.md 和 ../full-architecture/SKILL.md 的「Step 1 必问决策点」节——mid 不重复内容，只做编排整合。
按 batch-ask B3 的 5 条纪律批量提问（一次 4~8 个，每问附推荐+理由，D-不可逆标红，附方案对比，分类排序）。强依赖链的决策拆出来单问（见 batch-ask「何时仍走单问」）。
Step 4：纳入 + 机器检查
- 即时 append decisions.md——每个 D 类决策按
../full-shared/references/loop-skeleton.md Step 1.2 schema append（id/decision/rationale/classification/confirmed_by:ask_user/stage:mid-plan/source/status:confirmed）。
- 更新初稿——把用户答案纳入 requirements.md + system-architecture.md 对应章节。
- 机器检查由 CW gate 自动执行——
cw(action=clarify) 调用时 CW gate 内部跑 clarity/architecture 机器检查（agent 不再手动自跑脚本）。FAIL → 当场修低级硬伤（占位符/缺章节/每 UC 缺 AC/系统实现越界/frontmatter verdict 缺/分层缺失），重新调用直到 PASS。
Step 5：review-fix-loop（4 路并行 reviewer）
读 ../mid-shared/references/review-fix-loop.md（完整 loop 协议）+ 本节维度分配。
维度审查分配（4 路并行，wait:false）
| 路 | 认知帧 | 读什么 | 复用 reference |
|---|
| 需求完整性 | 对齐/补齐（同向） | requirements.md + 项目源码 | ../full-clarity/SKILL.md 的 5 视角（目标可追溯/角色用例完整/数据流/界面场景/跨系统） |
| 架构合理性 + 边界 | 对齐/补齐（同向） | system-architecture.md + requirements.md + 源码 | ../full-architecture/references/architecture-perspectives.md（边界划分/复杂度归位/证伪三连） |
| 禁读重建 | 反向（他证） | 禁读两份初稿，只读 CONTEXT.md + 项目源码，独立重建 Actor/用例/数据流 + 模型/边界/状态机 → diff | 范式抄 ../full-clarity/SKILL.md 重建器 + ../full-issues/references/fog-of-war.md 角色 A |
| 红队 · 反过度设计 | 反向（删/质疑） | 两份初稿 + 上游 | ../full-shared/references/review-agent.md 红队节（必要性与比例性，deletion test） |
派发： 按 review-fix-loop L2 的派发模板，4 路 wait:false 同消息派发，context 注入 decisions.md。
汇总： 按 L4 汇总去重（HIGH-CONFIDENCE / CROSS-VALIDATED / NEEDS-VERIFY）。
收敛： 按 L5/L6（无 must_fix → CONVERGED；有 → 修复回 L1，round ≥ MAX=2 → 进 Step 6）。
[CROSS-VALIDATED 冲突处理] 红队说「某 port 该删」、对齐说「该 port 是上游对齐必需」——涉及 D-不可逆（分层/边界）→ 必须 ask_user，不能 agent 自判。与 full Step 6 同源。
review 落盘（AC-15.3，CW clarify gate 前置）
review-fix-loop CONVERGED 后，必须把各维度的 review 结论落盘到 changes/ 目录，供 CW clarify gate
的机器检查（clarity/architecture）预检（#7 review 桩机制——CW 不产桩，靠 skill 落盘）：
changes/review-clarity.md ← 需求完整性路 + 禁读重建路的 review 结论合并
changes/review-architecture.md ← 架构合理性路 + 红队的 review 结论合并
每份 review 文件含 frontmatter verdict: APPROVED（CONVERGED 的 review 才落 APPROVED；未 CONVERGED
不落盘，重跑 loop）。文件格式参考 ../full-shared/references/review-fix-loop.md 的 review 落盘模板。
CW clarify action 调用前会预检这两个文件是否存在（findMissingReviewStubs），缺失返 hint 不跑 gate。
落盘是 skill 的职责，不是 CW 的（CW 不造假桩，D-007 方案 A）。
Step 6：二次 ask（loop 残留 D-不可逆）
读 ../mid-shared/references/batch-ask.md（二次 ask 节）。
loop 收敛后（CONVERGED 或 round ≥ MAX），残留未解决的 D-不可逆 must_fix 打包二次 ask_user（通常 1~3 个）。用户拍板后 append decisions.md（推翻首次确认的标 [REVISIT of D-NNN]）。
Step 7：定稿 + 渲染 HTML
- 主 agent 定稿 requirements.md + system-architecture.md：
- 已解决 D 类 gap 两处同步写（各 .md 决策记录章节写完整推理 + decisions.md 写权威索引，见
../full-shared/references/loop-skeleton.md Step 5a）
[UNRESOLVED] gap 标 [AMBIGUOUS] 显式列出- frontmatter 含
verdict: pass
- 派 fresh subagent 渲染 HTML（2 个，可并行）：
- 加载
coding-visualizer skill（本包内置，无需安装）
- requirements.md → hero=用例图（Actor×用例×边界）
- system-architecture.md → hero=分层架构图 + 状态机图
- 按
../full-shared/references/loop-skeleton.md Step 5b 的渲染 task prompt 模板派发
交接（定稿后）：
定稿后必须额外产出 clarify.json（CW clarify action 的入参，D-006 结构化 JSON）。
clarify.json schema 见 ../lite-shared/references/cw-json-schemas.md「clarify.json」节（字段约束 + format 锁定）。
关键提醒：format 必须 === "mid-clarify"（D-003）；不含 waves/testCases（mid clarify 只确认 tier + 交付物，T2.9）。
clarify.json 写到 .xyz-harness/{slug}/clarify.json。写完后调 CW：
cw(action=clarify, topicId="<create 时返回的 topicId>", clarifyJson=<JSON.parse(clarify.json 文件内容)，必须传 object 不能传 string>)
[MANDATORY] clarifyJson 必须是 object（JSON.parse 后的值），不是 JSON 字符串。
传 string 会被 CW 在 assertFormat 拒（报 invalid plan json: not an object），因为 schema 声明的是 type: object。
CW clarify gate 预检 changes/review-{clarity,architecture}.md 存在 → 跑机器检查（clarity/architecture）→
通过后返回 nextAction: {action:"detail", skill:"mid-detail-plan", ...}。
Self-Check
[MANDATORY] 全部满足才算 mid-plan 完成。
范围与基建：
batch-ask：
机器检查 + loop：
定稿：
标记说明
| 标记 | 含义 | 修改约束 |
|---|
| [铁律] | 阶段核心不可逾越的边界 | 不允许削弱或移除 |
| [MANDATORY] | 流程强制要求 | 必须严格遵守 |
