Menú
对项目的文档结构与基础文档做一次性初始化。从 assets/ 的模板生成 docs/ 目录树、AGENTS.md、CLAUDE.md、README.md 以及基础文档。
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Basado en la clasificación ocupacional SOC
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 后有意见或改进想法，或想为框架本身留下改进线索时使用。
| name | docs-init |
| description | 对项目的文档结构与基础文档做一次性初始化。从 assets/ 的模板生成 docs/ 目录树、AGENTS.md、CLAUDE.md、README.md 以及基础文档。 |
一次性初始化：从 assets/ 的模板生成标准文档 Library 布局与基础文档，并确保项目忽略 .harness-runtime/ 这棵树（逐 plan 的 FDD 状态存放于此）。运行后，项目就具备了 docs/ Library 树、占位模板以及基础文档（golden-rules）。属于其他领域的内容（architecture、design docs、changelog）由各自归属的技能创建；逐 plan 的状态（plan、contract、feature）永远不放在 docs/ 里——它们存放在被 gitignore 的 .harness-runtime/。
docs/ 目录、没有 AGENTS.md，或者只有一个空壳 README不用于重复运行。 本技能负责初始化，不负责重新生成。若结构已存在，技能会报告当前现状并退出，不做任何改动。各文档后续的日常维护，发生在归属该文档的技能里。
本技能创建或填充（当缺失时）：
| Target | Source in assets/ |
|---|---|
AGENTS.md | assets/AGENTS.md |
CLAUDE.md | symlink → AGENTS.md |
README.md | assets/README.md（仅当不存在 README 时） |
docs/README.md | assets/docs/README.md |
docs/golden-rules.md | assets/docs/golden-rules.md |
docs/design-docs/{README,_template}.md | assets/docs/design-docs/ |
docs/references/README.md | assets/docs/references/README.md |
docs/generated/README.md | assets/docs/generated/README.md |
.gitignore 条目 .harness-runtime/ | 缺失时追加（见 Step 4b） |
本技能不创建：
docs/architecture.md —— architecture 内容在别处定义docs/design-docs/<doc>.md —— 单个 design doc 在别处撰写docs/user-test-patterns.md —— 由 harness-stack:fdd-validation-contract 首次运行时 bootstrap.harness-runtime/ 内容 —— 逐 plan 的状态由 harness-stack:fdd 与 fdd CLI 创建；它被 gitignore，不在脚手架范围内CHANGELOG.md —— changelog 在别处维护读项目根目录，报告已有哪些内容。对 scope 表里的每个 target，记录三种状态之一：缺失、已存在、或已存在但为空 / 仅占位。
同时收集：
package.json、Cargo.toml、pyproject.toml、go.mod，或目录名取得）对 scope 表里的每个 target，按此判断：
| Current state | Action |
|---|---|
| 缺失 | 从 assets/ 模板创建，替换占位符 |
| 已存在但为空 / 仅占位 | 提议覆盖；等待确认 |
| 已存在且有真实内容 | 不动；报告已保留 |
绝不覆盖带有真实内容的文件。若用户要求「初始化」一个已经有实质文档的项目，报告现状并建议做有针对性的编辑，而非整体重写。
assets/ 里的模板用到这些占位符：
| Placeholder | Source |
|---|---|
{{PROJECT_NAME}} | 检测到的项目名称 |
{{BUILD_COMMAND}} | 检测到的 build 命令，未知时用 <build command> |
{{TEST_COMMAND}} | 检测到的 test 命令，未知时用 <test command> |
{{LINT_COMMAND}} | 检测到的 lint 命令，未知时用 <lint command> |
{{INSTALL_COMMAND}} | 检测到的 install 命令，未知时用 <install command> |
若某条命令无法可靠检测，保留方括号占位符，并在验证报告中点明，让用户自行补上。
把每个模板拷到目标路径并施加上面的替换。对 CLAUDE.md，创建一个指向 AGENTS.md 的 symlink。在不支持 symlink 的平台或文件系统上，退化为一行文件：See [AGENTS.md](AGENTS.md).
确保项目的 .gitignore 含有 .harness-runtime/。这里是 fdd 存放逐 plan 状态（plan、contract、feature、handoff）的地方；它绝不能被提交。幂等：若该行已存在，什么都不做；若 .gitignore 缺失，创建它并写入该条目；否则在一行简短注释下追加。不要触碰任何其他 .gitignore 条目。
当某种情况阻碍了干净的初始化，停下来，把具体情形连同一小串可选项一并呈现。不要默默替用户做决定。典型情况：
| Situation | Suggestion |
|---|---|
| 已有 AGENTS.md 超过 150 行 | 报告行数；建议在替换前把细节移进 docs/ |
| 已有 README.md 含真实内容 | 不覆盖；建议用户审定后做有针对性的编辑 |
docs/ 存在但布局非标准 | 列出偏离的目录；询问是规整还是保持原样 |
| 无法检测项目名称 | 列出已查过的来源；向用户索要名称 |
| 文件系统不支持 symlink | 退化为 CLAUDE.md 桩文件，并标注此退化 |
| architecture / product / design 内容已部分散落各处 | 报告位置；内容不动，并标注后续应由哪个归属技能来整合 |
写入后，打印一张表，覆盖 scope 表里的每个 target，状态取以下之一：created、preserved、skipped (conflict)、或 needs attention。把任何未解决的占位符一并列出，供用户填写。确认 CLAUDE.md 能解析到 AGENTS.md。
AGENTS.md 存在，且不超过 150 行CLAUDE.md 能解析到 AGENTS.md（symlink 或桩文件）README.md 存在（原已存在，或从模板创建）docs/README.md 与 docs/golden-rules.md 存在docs/design-docs/ 含有 README.md 与 _template.mddocs/references/README.md 与 docs/generated/README.md 存在.gitignore 含有 .harness-runtime/