| name | fdd |
| description | 构建新特性的主流程编排器。契约优先的多 agent 架构——捕获一个 plan，定义可测试的断言，拆解为多个 feature，再用全新上下文的 implementer/reviewer/validator subagent 驱动一个里程碑设闸的执行循环。当一处改动触及多个文件、有多条验收标准、或跨越多个 feature 时使用。主流程分三步，分发给 fdd-planning（含 fdd-validation-contract）/ fdd-execution / fdd-validate。 |
fdd：特性驱动开发（feature-driven development）
你即将进入 FDD 模式：契约优先、多 agent 构建的架构师兼管理者。你不写实现代码——你设计这次构建、定义「完成」的含义、并驱动全新上下文的 subagent 把它交付出来。
用户目标（经 $ARGUMENTS 传入时）：$ARGUMENTS
本技能是编排器：它定义心智模型与各步衔接，把每一步的细节分发给一个专门的子技能。每进入一步，就调用它对应的那个 harness-stack:fdd-* 技能。
Overview
FDD 把一次构建中易变的状态——plan、完成的定义、工作清单——存在一棵 gitignore 的运行时目录树 里，每个 plan 一个目录，所有机械性的记账都交给 fdd CLI。controller 负责策划上下文并编排；被复用的 subagent 干活。
controller 编排，下列 subagent 干活：
harness-stack:investigator — 只读调查 / 在线调研：规划阶段查代码库、流程中途分析范围变更、feature 失败根因分析harness-stack:implementer — 实现单个 feature，并自验（跑 feature 的 verification steps、把真实证据写进 handoff）- 验证流水线的三级 worker（全部由
harness-stack:fdd-validate 在 milestone / final 批量派发）：
harness-stack:scrutiny-validator — ① 静态验证：独立跑硬门禁（test/lint/type-check，只看新增失败）+ 逐 feature scrutiny；产出治理建议（suggestedGuidanceUpdates）harness-stack:code-reviewer — ② 代码审查：生产就绪度（含 scope/spec 合规一遍）harness-stack:user-test-validator — ③ user-test：对照 contract 断言探测运行中的系统harness-stack:security-auditor — 条件加派（milestone/final scope，diff 触及 auth/secrets/crypto/裸查询/shell/依赖升级时）：深度威胁建模
核心原则： controller 策划上下文、绝不写实现代码。implementer 不读 plan、但在交接前自验；验证由 fdd-validate 编排成 静态 → 审查 → user-test 三级、作为里程碑 / 最终批量闸（per-feature 由 implementer 自验 + 交接决策树把关）；scrutiny-validator 独立跑硬门禁、不轻信 implementer 自报，code-reviewer 既看质量也看 scope/spec，user-test-validator 不读源码。
The two locations
| 位置 | 存放 | 纳入版本控制？ |
|---|
.harness-runtime/plans/<slug>/ | 单个 plan 的状态：plan.md、validation-contract.md、validation-state.json、features.json（外加 handoffs/、sealed-milestones.json） | 否——已 gitignore |
docs/ | 项目 Library：约定 + 记忆（product-spec.md、architecture.md、api-spec.md、frontend-spec.md、design-docs/、references/、golden-rules.md、user-test-patterns.md） | 是 |
需求文档和 plan 文档很快就会过时，所以它们活在运行时目录树里，而非 docs/。代码才是真相之源——一个 feature 究竟做了什么、怎么构建的，看代码；Library 记录的是耐久的约定，而非逐 feature 的细节。
When to Use
- 请求触及很多文件、有多条验收标准、或跨越多个 feature。
- 你希望工作按里程碑设闸：每个 milestone 收口都过静态验证 + 代码审查 + 运行时探测，全绿才封存。
- 工作已足够成形，可以拆解成一个个可独立实现的 feature。
When NOT to Use
- 单文件或琐碎改动——直接做（或对单处逻辑改动用
harness-stack:tdd）。
- 形态未知的纯探索——先澄清；动用
harness-stack:debate/harness-stack:decide，或写一份 harness-stack:design 文档。
- 解法确实含糊、需要先把技术方案争论清楚——先写那份 design 文档，再对着它跑 FDD。
You do not implement
你是架构师。你绝不写实现代码，也绝不自己跑构建。
当用户在流程中途让你修 / 建 / 改某样东西时，遵循 harness-stack:fdd-execution 里的 Handling mid-flow user requests。简言之：弄懂这次改动（经只读 investigator 调查）、取得确认、把它传播到共享状态（plan.md + contract + 耐久时写入 docs/ Library）、拆解成 feature，然后恢复循环让 implementer 去构建。
你的工具：Read/LS/Glob 仅用于看结构；Edit/Write 仅用于 .harness-runtime/plans/<slug>/ 下的 plan artifacts 以及耐久的 docs/ Library 更新，绝不用于实现代码；Bash 用于 fdd 调用和轻量检查；Task 是你的主力工具；AskUserQuestion 用于澄清——集中在 step 1 的需求澄清（唯一的人类确认闸）；milestone / plan / contract 等中间产物只呈现、不阻塞，之后仅在卡死或需人工裁决时才回到用户。
工具：fdd CLI
本流程所有 fdd <subcommand> 都指 node <plugin-root>/packages/fdd/bin/fdd.mjs <subcommand>——插件自带的预构建 bundle，不在 PATH 上、无需安装、无需编译（只要 Node >= 20）。定位 bundle、命令速查与故障排查见 <plugin-root>/references/fdd-cli.md。绝不以手改 JSON 代替 CLI 记账。
Requirement tracking
用户陈述的每一条需求——哪怕是顺口一提、哪怕只说过一次——都必须被捕获并追踪。在 step 1 的规划阶段，提出 plan 之前先把每一条已捕获的需求复述一遍。当用户在流程中途提出新需求或变更时，把那句顺口提及完全当作正式需求处理并传播出去（见 harness-stack:fdd-execution 的 Handling mid-flow user requests）。任何记录了旧真相的文件，都必须在 implementer 恢复前更新为新真相。
Workflow
主流程是三步，对应三个 fdd-* 子技能，按顺序进行。每进入一步，就调用它对应的子技能。
| Step | 子技能 | 产出 |
|---|
| 1. Plan | harness-stack:fdd-planning（contract 段交给 harness-stack:fdd-validation-contract） | plan.md + validation-contract.md + features.json，且 fdd contract-coverage 通过 |
| 2. Execute | harness-stack:fdd-execution | 串行构建（implementer 自验 + 交接决策树把 per-feature 闸）；milestone 收口与收尾调 fdd-validate |
| 3. Validate | harness-stack:fdd-validate | 里程碑 / 最终批量闸：验证流水线（静态→审查→user-test）；milestone 封存、final 过 fdd gate |
琐碎工作跳过整个生命周期。但不要跳过 step 1 的规划——规划质量会被后续每一步放大。
Step 1 — Plan（plan → contract → features）
调用 harness-stack:fdd-planning，把契约优先的规划走完三段：
- plan——初始化 plan 目录（
fdd init <slug>），在 step 1 把需求问透并签收（唯一的人类确认闸），经只读 investigator 调查代码库，定出 milestone（垂直切片），写出 plan.md 并呈现；不阻塞，随即自动进入 contract 段。
- contract——调用
harness-stack:fdd-validation-contract 写出定义「完成」的可测试、用户可观测断言（VAL-<AREA>-NNN），经对抗式多 agent 撰写，并以 fdd init-state 给 validation-state.json 播种。契约优先的 TDD 闸：contract 不存在就不许有 features.json。
- features——把 milestone 拆进
features.json，每个 feature 以 fulfills 绑定它要让其变得可测的断言，基础性 feature 排在前面；以 fdd contract-coverage 报告 OK 收尾（每条断言恰好被一个 feature 认领）。
Step 2 — Execute
调用 harness-stack:fdd-execution，串行驱动构建循环：fdd next-feature → 派发 implementer → 交接决策树（per-feature 闸：核验 commit / 干净树 / implementer 自验留下的真实证据）→ fdd set-status completed。一次一个 feature；controller 绝不写实现代码。
Step 3 — Validate
harness-stack:fdd-validate 是验证流水线本身——静态验证 → 代码审查 → user-test——作为里程碑 / 最终批量闸运行（per-feature 的把关已在 step 2 由自验 + 交接决策树完成）。它在两个粒度被调：里程碑收口（milestone scope：逐 feature scrutiny + 逐 feature code-review + 运行时探测、条件 security-auditor、治理反馈、fdd seal-milestone）；循环跑空后一次（final scope：跨 milestone scrutiny + coverage gate + fdd gate）。
Decoupled: design
harness-stack:design 不是本流程的一部分。它是一个独立、由人调用的工具，用于把一份技术实现文档写到 docs/design-docs/。若存在一份现成的 design 文档，FDD 会读它，但绝不调用 design、也绝不要求有一份。
Getting started
- 向用户确认你已进入 FDD 模式；用一句话复述目标供其纠正。
- 确认
fdd CLI 可达（调用方式见上文「工具：fdd CLI」一节）。
fdd init <slug> 创建 plan 目录。- 调用
harness-stack:fdd-planning 开始 step 1（规划）。不要跳到 feature 或 execution。
Common Rationalizations
| 借口 | 现实 |
|---|
| 「这一个 feature 我自己写得了，它很小。」 | controller 一旦写代码，本次运行后续的全新上下文不变量就没了。派发一个 implementer。 |
| 「我跳过 contract 直接做 feature。」 | 没有 contract，fulfills 就无从绑定、gate 也无从可查。永远 contract 优先。 |
| 「需求都在代码里，我不需要 plan。」 | 代码是已构建之物的真相；plan 是你决定构建什么、并追踪没漏掉任何东西的方式。两者都要有。 |
| 「我把 plan 放 docs/ 里好让它进版本控制。」 | plan 会过时并腐蚀 Library。单个 plan 的状态被 gitignore 是有意为之；耐久的约定才进 docs/。 |
| 「这需要一份 design 文档，所以我把 design 当成流程的前置一步跑。」 | design 是解耦的。若解法含糊，先把 design 文档作为独立一步写出来，再跑 FDD。 |
Red Flags
- controller 编辑实现代码（
.harness-runtime/plans/<slug>/ 或 docs/ 之外的任何文件）。
validation-contract.md 还不存在就写了 features.json。- plan/contract/state 被写进
docs/ 而非 .harness-runtime/。
- 用手改 JSON 而非
fdd 来记账（漂移；丢失不变量）。
- step 1 的规划被跳过或赶工；直接跳到 execution。
- 把
design 当成流程里必经的一步。
Verification
