harness-stack

FDD 主流程 step 1（规划与拆解）。覆盖两段——plan（与用户弄清需求、经 investigator 调查代码库、定出 milestone、写出 plan.md 并呈现）与 features（把 milestone 拆成 features.json 并过 coverage 闸）。中间的 contract 段交给 harness-stack:fdd-validation-contract。由 harness-stack:fdd 调用。

构建新特性的主流程编排器。契约优先的多 agent 架构——捕获一个 plan，定义可测试的断言，拆解为多个 feature，再用全新上下文的 implementer/reviewer/validator subagent 驱动一个里程碑设闸的执行循环。当一处改动触及多个文件、有多条验收标准、或跨越多个 feature 时使用。主流程分三步，分发给 fdd-planning（含 fdd-validation-contract）/ fdd-execution / fdd-validate。

为一个 plan 撰写 validation contract——把 definition of done 落成一组可测试、用户可观测的 assertion（VAL-<AREA>-NNN），带 persona 与声明的 Evidence。它是 fdd step 1（规划）里的 contract 阶段。契约通过逐 area 的 investigation subagent 与若干轮 adversarial review 构建，而非一人独写。产出 .harness-runtime/plans/<slug>/validation-contract.md，并经由 fdd init-state 播种 validation-state.json。在项目内首次使用时，还会 bootstrap 项目级约定文档 docs/user-test-patterns.md。

规范 git 工作流实践。任何代码改动都适用。在提交、开分支、解决冲突，或需要把多条并行工作线组织起来时使用。

harness-stack 框架的引导纲要（bootstrap doctrine）。在会话开始时自动加载，用以介绍 lifecycle map、golden rules，以及如何挑选正确的 harness-stack:* skill。在一次会话中首次调用任何 harness-stack:* skill 之前，先读它。

复盘一次 harness-stack 使用，把值得上报的摩擦、缺陷或建议提成 GitHub Issue 反馈给上游。在完成一项任务、用完某个 skill 后有意见或改进想法，或想为框架本身留下改进线索时使用。

FDD 主流程 step 2——执行循环。串行驱动 feature 构建：next-feature → 派 implementer → handoff 决策树 → complete。每个 feature 由交接决策树把关（核验 implementer 自验留下的证据）。静态验证 → 代码审查 → user-test 这条验证流水线在里程碑收口（fdd-validate scope=milestone）与循环跑空（scope=final）批量跑。由 harness-stack:fdd 在 features.json 通过 coverage 后调用。

FDD 的验证流水线——里程碑 / 最终批量闸。一条线性、成本递增的三级 gate：静态验证（scrutiny-validator 硬门禁 test/lint/type-check + 逐 feature scrutiny）→ 代码审查（code-reviewer，逐 feature）→ user-test（运行时断言探测）。由 harness-stack:fdd-execution 在里程碑收口（scope=milestone：加条件 security-auditor + 治理反馈 + seal）与循环跑空（scope=final：加 coverage gate + fdd gate）时调用。

打开一个 pull request 并把它推进到干净合并。当 commit 已干净、代码可供 review 时使用——open（检测 base、同步推送、撰写结构化 PR body、gh 创建）然后 land（盯 CI、处理 review 反馈、解决冲突，全绿时 squash-merge）。在 PR 合并或真正受阻之前不要交还控制权。不涉及 commit、code review 与发布事务。

对项目的文档结构与基础文档做一次性初始化。从 assets/ 的模板生成 docs/ 目录树、AGENTS.md、CLAUDE.md、README.md 以及基础文档。

在全局层面定义产品。在启动新产品、产品方向不清晰、或 product-spec.md 缺失或过时时使用。产出 docs/product-spec.md，作为「产品是什么」的唯一事实来源。

通过 DESIGN.md 初始化或修改项目的 UI 设计风格。在启动需要 visual design system 的新项目、采用预制设计风格（如 Linear、Vercel、Stripe）、或从零定制 UI design token 时使用。

为某个具体实现决策撰写一份 design doc（docs/design-docs/）。独立、由人触发——不属于主 build 流程。当一个解法足够含糊、技术路线应在动工前先论证清楚时使用；涵盖 feature design、技术性重构、架构决策与迁移。

在合并前派发一个全新上下文的 code-reviewer subagent。当你（作者）完成一项非平凡改动、需要对代码做审视时使用——固定 diff 区间、填写 brief 模板、通过 Task 派发，再把 findings 交出去应用。

加固代码以抵御漏洞。在处理用户输入、认证、数据存储或外部集成时使用。在构建任何接收不可信数据、管理用户会话或与第三方服务交互的 feature 时使用。

创建新的 harness-stack skill。在向框架新增 skill、扩展 lifecycle 覆盖范围，或构建自定义 skill 时使用。

以技术上的严谨而非表演式附和来处理 code review 反馈。当你（作者）收到来自 reviewer、人类或你自己早前 self-review 的 review findings 时使用。尤其当某条 finding 看起来含糊或技术上可疑时使用。

创建并维护 CHANGELOG.md。在初始化变更日志、从 git 历史中提取未发布变更、或准备发布某个版本时使用。

让多个异构 LLM agent 就同一个问题展开一场 multi-agent debate。每个 round 都做匿名处理，使参与者只就论据本身较量，而不在意来源。最终产出是一份综合后的答案外加一份 claim catalog。当一个问题含糊、有争议、或风险高到单个模型的第一反应不足以采信时使用。

引导系统化的 root cause debug。当测试失败、构建中断、行为与预期不符，或遇到任何意外错误时使用。当你需要用系统化的方法定位并修复 root cause、而不是靠猜时使用。

在单个问题上跑一轮并行多 agent 决策。每个 agent 独立作答，给出结构化的 recommendation；再由一道 synthesis 把它们的 recommendation 合并成最终决策，附带 confidence 以及浮现出来的 minority position。当你想为一次性决策拿到稳健答案、并显式追踪异议，但又不需要多轮 debate 的来回拉锯时使用。

在项目层面定义 API spec。在启动带 API 的项目、api-spec.md 缺失或过时、或跨服务出现 API 不一致时使用。产出 docs/api-spec.md，作为权威的 API contract。

在全局层面定义系统 architecture。在启动新项目、architecture.md 缺失或过时、或系统结构发生重大变化时使用。产出 docs/architecture.md，作为系统的结构地图。

在全局层面定义 frontend 工程约定与质量标准。在启动新 frontend 项目、frontend-spec.md 缺失或过时、或需要确立组件模式、accessibility 标准或 performance budget 时使用。产出 docs/frontend-spec.md，作为 frontend 工程规则的唯一事实来源。

为并行开发初始化每个 worktree 独立隔离的 runtime 环境。在创建新 worktree、dev server 因 port 或 database 冲突、或首次为某个项目搭建多 worktree 并行开发时使用。

为生产上线做准备。在准备部署到生产环境时使用。在你需要一份上线前清单、配置监控、规划分阶段灰度发布，或需要一套回滚策略时使用。

用测试驱动开发。在实现任何逻辑、修复任何 bug 或改变任何行为时使用。在你需要证明代码确实可用、收到一份 bug 报告，或即将修改已有功能时使用。