القائمة
对项目的文档结构与基础文档做一次性初始化。从 assets/ 的模板生成 docs/ 目录树、AGENTS.md、CLAUDE.md、README.md 以及基础文档。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف 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/