bootstrap

您正在当前仓库中安装（或改造）一套文档驱动约定。最终状态是一个可由人类和编码代理通过一组规范文件驱动的仓库。请严格按照此处描述的机制执行——不要涉及任何其他项目。

第 1 步 — 检测情况

在询问任何问题之前，先检查仓库。重用本次会话中已提供的明确答案和确认信息；绝不使用配置文件默认值替换它们或再次询问。在写入之前，根据这些答案总结已解析的产物根目录、深度、队列、门控和协调/集成模式。如果主机将选定的文件夹镜像到沙箱中，请识别实际的目標路径以及已验证的输出如何到达选定的文件夹；绝不因为镜像通过测试就认为未触及的目标已完成。

新仓库（无源代码，无文档）：从零开始搭建。
现有仓库：进行改造。
- 在提议更改之前，阅读当前的 README.md、CONTRIBUTING.md、AGENTS.md、CLAUDE.md、docs/、adr/、.github/。
- 保留现有内容。合并，不要覆盖。如果现有约定与以下约定冲突，请在评估摘要中说明冲突。
- 如果 ADR 已以其他格式存在，请提出迁移计划（重新编号、保留、翻译），而不是创建平行树。
已具有 docflow 的仓库（包含 AGENTS.md + CONVENTIONS.md + ADR 目录）：您是在扩展现有设置，而不是搭建新结构。不要重新搭建核心或重新询问已解决的问题——从 CONVENTIONS.md/AGENTS.md 中读取已记录的选项（ADR 形状、状态生命周期、产物根目录、多代理模式以及已存在的可选层）。然后提供启用任何仍缺失的、之前选择不启用的可选层——plan/、_agent/、GLOSSARY.md、domains/ 或第二个 ADR 形状（技术模板）——并仅通过合并方式，在已记录的产物根目录下写入选中的层，保持其他所有内容不变。仅询问新层所需的问题（例如，启用 _agent/ 时的协调问题——如果单个写入者没有同时记录验证门控和计划队列，则最终完全没有 _agent/ 目录，该层根本不需要）。这是添加您在首次引导时推迟的层的入口点。仍携带先前搭建写入的协调文件的仓库保留它们：在此处保持原样，让审计技能报告布局。

启用 GLOSSARY.md 写入规范框架，绝不重写。 当选择该层且文件不存在时，从 templates/GLOSSARY.md 写入——可选标题和散文，然后是从生成的 CONVENTIONS.md §术语表中记录的一个 术语 | 定义 表。如果文件已存在，则保持不变：启用该层不添加任何内容，add-convention 以规范形状扩展现有文件，或 audit 提供同意后的迁移。

启用第二个 ADR 形状是方案切换，而不是文件复制。 它是唯一一个更改已记录选项的延迟层，因此请一次性全部写入或完全不写入：用双形状文本替换 CONVENTIONS.md 中的 §ADR 形状，在 AGENTS.md 中添加技术部分顺序和形状项目，写入 adr/0000-template-technology.md，并使用形状列重新生成 INDEX.md。现有 ADR 保留其编号并保留能力属性——缺少 shape: 字段已经意味着能力，因此不会重写任何 ADR，也不会重新编号。切换的一半会使用户仓库处于第 4.5 步交叉检查称为矛盾的状态：单形状方案永远不会选择的技术模板。

已使用旧版范围编码的仓库会收到迁移提议。 一些双形状仓库是在形状成为声明字段之前搭建的，并将其编码在编号中：§ADR 形状记录了一个截止点（低于它的为能力，高于或等于它的为技术），并且 adr/ 包含一个编号不是 0000 的模板（例如 adr/0100-template.md）。这两个信号中的任何一个都可以识别它。这样的仓库并不缺少一个层——它已经具有两种形状——因此不要提供上述方案切换，这会使它面临两种竞争编码。提供迁移到声明字段的选项，条件与审计技能使用的相同：
- 首先以试运行形式显示旧到新的编号映射：能力 ADR 保留其编号；技术 ADR 取能力 ADR 最高编号之后的编号，按原始相对顺序。同时，列出要跟随的引用（depends-on、supersedes / superseded-by、相对 adr/NNNN-*.md 链接、INDEX.md、域 README.md 列表、plan/todo/ 拥有 ADR 行）以及保留为历史的内容（plan/done/ 页脚、提交消息、标签）。
- 在没有明确确认该映射的情况下不要写入任何内容。 拒绝是有效的结果：仓库保留范围编码并继续通过自己的规则。
- 确认后，完全按照审计技能的迁移步骤指定应用迁移——重新编号、在每个 ADR 上盖章 shape:、重写目录中的每个引用、用 adr/0000-template-technology.md 替换边界模板、将 §ADR 形状重写为声明字段并删除任何种子 ADR 异常子句、使用形状列重新生成 INDEX.md——并将其作为一条提交落地，其消息列出每个旧到新的配对。该过程是唯一真相来源；不要在此处解释另一个变体。
- 然后继续常态重新运行，处理真正缺失的层（plan/、_agent/、GLOSSARY.md、domains/）。

在询问评估问题之前，用一行说明适用哪种情况。

第 2 步 — 目标布局

<repo>/
  AGENTS.md              # 编码代理的硬规则 — 入口
  CLAUDE.md              # 一行：@AGENTS.md
  README.md              # 面向人类用户的项目概要（若存在则保留）
  CONVENTIONS.md         # 创作规则：ADR、命名、状态、审计、git
  INDEX.md               # 所有 ADR 的生成索引
  GLOSSARY.md            # 共享术语（可选 — 见问题 7）
  adr/
    0000-template.md     # 能力 ADR 模板（始终）
    0000-template-technology.md  # 技术 ADR 模板（仅双形状时 — 见问题 2）
    NNNN-<kebab-slug>.md # 每个决策一个 ADR，连续编号
  domains/<slug>/README.md   # 可选（见问题 7）
  plan/
    README.md
    todo/NNNN-<slug>.md
    done/<YYYY-MM-DD>-<slug>.md
  _agent/                # 代理操作契约（见问题 5）— 可选
    ROLES.md             # 谁写什么（仅多个写入者）
    LOCKS.md             # 文件声明互斥锁（仅共享检出现）
    prompts/autonomous.md  # 无人值守运行时的行为（仅当有
                         #   验证门控 — 问题 8 — 且有计划队列 — 问题 4a）
  federation.md          # 仅多仓库（问题 11）：此仓库的回指
  federation-index.md    # 仅多仓库（问题 11）：成员索引 — 仅主页仓库

放置。 上面的树显示根选项。AGENTS.md 和 CLAUDE.md 始终位于仓库根目录；adr/、plan/、_agent/、INDEX.md 和 CONVENTIONS.md 位于问题 12 中选择的产物根目录下（默认为 .docflow/，例如 .docflow/adr/、.docflow/plan/）。

发现。 工具无需先读取 CONVENTIONS.md 即可定位产物根目录：仓库根目录处的 .docflow/ 目录就是根目录；对于任何其他根目录，bootstrap 在仓库根目录处写入一个 .docflow 文件——一个单行指针，root: <路径>（例如 root: docs/、root: .）。两者都不存在意味着是预契约仓库（工具探测 docs/，然后是仓库根目录，查找命名了产物根目录的 CONVENTIONS.md）或不是 docflow 仓库。

_agent/ 是代理操作契约——谁写什么、一个真正的互斥锁以及无人值守运行的运作方式。它只包含 git 无法告知的内容：没有重复的发货记录、没有进行中的状态仪表板、没有当前状态的快照、没有交接。上述三个文件的存在完全取决于问题 5、问题 8 和问题 4a，而完全没有 _agent/ 目录的仓库是有效结果。

核心与可选层。 仅核心始终写入：AGENTS.md、CLAUDE.md、CONVENTIONS.md、adr/0000-template.md 和 INDEX.md。仅有这些文件的仓库是一个有效的、轻量级的 docflow 仓库——一个带有约定的经典 ADR 目录。其他所有内容都是可选加入的层：plan/ 队列（问题 4a）、_agent/ 契约（问题 5 + 问题 8 + 问题 4a — 没有同时具备验证门控和计划队列的单个写入者将得到零个文件）、GLOSSARY.md 和 domains/（问题 7）。省略任何可选层都是有效状态，而不是错误；需要缺失层的生命周期技能会干净地拒绝并命名缺失的内容。

对于多仓库产品（一个产品分布在多个仓库中 — 见问题 11），会出现两个额外文件：federation.md，每个成员仓库携带的一个小型回指针；以及 federation-index.md，仅存在于主页/建立仓库中的权威成员列表。所有联合制品——federation.md、federation-index.md 以及派生的汇总 ROLLUP.md——都放置在配置的产物根目录下。独立仓库没有它们。

第 3 步 — 要安装的约定

ADR 是唯一真相来源。 每个决策一个 ADR。拆分成为新的 ADR 并取代旧决策；永远不要在现有 ADR 内扩展范围。
最多两种 ADR 形状，通过字段声明。 区分两种形状的仓库在每条 ADR 的 shape: 元数据字段中记录区别（capability 或 technology；缺少字段意味着 capability）——绝不在编号范围中。每个 ADR 无论其形状如何，都采用下一个连续编号，并且每种形状都有自己的模板，均编号为 0000。
- 能力 ADR（系统必须做什么）。章节顺序：元数据 → 上下文 → 能力陈述 → 用户故事/场景 → 验收标准 → 范围外 → 开放问题 → 引用 → 修订历史 → 批准。
- 技术 ADR（如何构建）。章节顺序：元数据 → 上下文 → 决策 → 理由 → 后果 → 验收标准 → 范围外 → 开放问题 → 引用 → 修订历史 → 批准。理由必须列出考虑的替代方案并给出具体的拒绝原因（而不是“更简单”/“更地道”）。
状态生命周期： Proposed → Accepted → Implemented → (Superseded | Deprecated)。终端状态可从任何先前状态达到。状态驱动计划文件夹放置：Accepted → plan/todo/，Implemented → plan/done/。
文件名： adr/NNNN-kebab-slug.md，零填充 4 位数字，连续，无预留间隙。交叉引用使用相对路径。
验收标准是可测试且编号的。 测试尽可能映射回去。
审计纪律。 实质性 ADR 更改追加修订历史行。编辑性更改（错别字、格式、链接修复）被排除，但在提交消息中标记为 editorial。批准表在 ADR 被接受时填充，并在每次后续实质性修订时更新。
INDEX.md 在任何 ADR 更改后根据 ADR 元数据重新生成。视为派生文件，而非手动编辑。
plan/ 是工作队列。 当工作交付时，git mv plan/todo/X plan/done/<date>-X，任何计划项状态移除、拥有 ADR 状态推进和 INDEX.md 重新生成都分组在完成提交中。在直接合并到主分支的集成下，该提交被推送到集成分支，并且移动文件的页脚命名 HEAD SHA（以及适用的部署工件 ID）。在拉取请求集成下，这些更改是拉取请求分支在标记为就绪之前的最后一个提交，页脚命名拉取请求，合并是完成事件。
协调是契约，不是日志。 _agent/ 只保存 git 无法告知的内容，每种模式（问题 5）精确规定其自己的文件——那里不写入其他任何内容。在共享检出现，代理在编辑前向 _agent/LOCKS.md 追加一行（<代理 ID> | <路径> | <ISO-8601 时间戳>），并在提交时删除它；该分类账是真正的互斥锁，队列项在项本身上声明。在单独工作树中，队列项通过推送 claim/<item-key>（队列文件名不含扩展名）来声明，如果集成基于拉取请求，则同时从该声明创建一个草图拉取请求；推送操作排除了第二个写入者，并且不保留分类账。在单个写入者下，没有需要序列化的内容，也没有需要声明的内容。任何模式都不保留重复的发货状态、进行中的状态仪表板或当前状态的快照：git 历史和 plan/done/ 是记录，活跃分支和拉取请求是进行中的工作。
Git 契约。 Conventional Commits。接触 ADR 的提交必须包含 Rationale: 页脚。签署提交，除非用户选择退出。代理工作不添加 Co-Authored-By 跟踪，除非用户要求。
AGENTS.md 是硬规则入口； CLAUDE.md 是兼容代理读取的一行 @AGENTS.md。
ADR 是内部制品——永远不对用户可见。 ADR 编号、ADR 标题以及 ADR 目录的存在绝不能出现在到达用户的产品代码路径中：UI 字符串、API 响应体、错误消息、发送给客户的日志行、公开文档、发布说明、营销文案或支持通信。ADR 是为构建者（而非用户）设计的。引用允许出现在：代码注释（// 参见 ADR-0012）、内部仪表板、内部工单、构建配置或技术入职材料中。

第 4 步 — 执行

请严格按顺序执行：

明确答案：从会话上下文或直接问题中收集每个问题的答案。记录解析的产物根目录、深度、队列、门控和模式。
创建目录：在产物根目录下创建 adr/、plan/todo/、plan/done/、domains/（如果需要）以及 _agent/prompts/（如果需要）。不要创建空目录。
编写核心文件：
- 将 AGENTS.md 写入仓库根目录。内容：硬规则入口，包含指向 CONVENTIONS.md 和 adr/ 的引用。
- 将 CLAUDE.md 写入仓库根目录。内容：单行 @AGENTS.md。
- 将 CONVENTIONS.md 写入产物根目录。内容：来自第 3 步的完整约定集，包括 ADR 形状、状态生命周期、文件名、审计纪律、git 契约等。如果有第二个 ADR 形状，请包含双形状部分。
- 将 adr/0000-template.md 写入产物根目录下的 adr 子目录。内容：具有正确章节顺序的能力 ADR 模板。
- 如果选择了第二个 ADR 形状，将 adr/0000-template-technology.md 写入同一目录。内容：技术 ADR 模板。
- 将 INDEX.md 写入产物根目录。内容：空表或根据现有 ADR 生成。
编写可选层：
- 如果选择了 plan/ 队列，将 plan/README.md 写入产物根目录下的 plan 子目录。如果 plan/todo/ 已创建，确保其存在。
- 如果选择了 _agent/ 契约：
  - 如果启用了多个写入者模式，将 _agent/ROLES.md 写入产物根目录下的 _agent 子目录。
  - 如果启用了共享检出现（互斥锁），将 _agent/LOCKS.md 写入同一位置。
  - 如果同时启用了验证门控和计划队列，将 _agent/prompts/autonomous.md 写入。
- 如果选择了 GLOSSARY.md，将其写入产物根目录。如果文件已存在，则跳过。
- 如果选择了 domains/，为每个域创建 domains/<slug>/README.md。
最终确定：
- 生成 INDEX.md 以反映所有 ADR（根据现有 ADR 或作为空表）。
- 如果项目是多仓库的并且这是主页仓库，写入 federation-index.md。
- 如果项目是多仓库的并且这是一个成员仓库，写入 federation.md。
- 更新 README.md 以反映新结构（如果存在，则合并；如果不存在则创建）。
- 总结完成了什么以及跳过了什么。

第 5 步 — 验证

验证最终布局与第 2 步匹配。确认 AGENTS.md 存在且是硬规则入口。确认 CLAUDE.md 是单行 @AGENTS.md。验证 CONVENTIONS.md 存在并包含所有已启用的约定。确认 adr/ 目录至少包含模板。确认 INDEX.md 存在。如果选择了可选层，确认该层存在且格式正确。

附录 A — 问答

Q1：项目是关于什么的？ A1：从用户会话中推断。不要问这个问题。

Q2：您想要一种还是两种 ADR 形状？ A2：两种形状（能力和技术）更彻底。一种形状更简单，适合小型项目。

Q3：您想要什么深度？ A3：Express（快速，最少问题）| Guided（引导，标准问题）| Full depth（全深度，所有选项）

Q4a：您想要计划队列（plan/）吗？ A4a：是/否。

Q4b：队列项应该放在哪里？ A4b：在产物根目录下的 plan/ 中。（这是固定位置）

Q5：写 ADR 和计划项时有多少代理在协作？ A5：1（单个写入者）| 2+（多个写入者）。

Q6：工作是如何集成的？ A6：直接合并到主分支 | 拉取请求。

Q7：您想要 GLOSSARY.md 和/或 domains/ 目录吗？ A7：仅 GLOSSARY.md | 仅 domains/ | 两者都要 | 都不要。

Q8：您想要无人值守运行模式（验证门控）吗？ A8：是/否。（仅当选择了计划队列时相关）

Q9：您想要签署提交吗？ A9：是/否。

Q10：代理工作的操作日志应该放在哪里？ A10：代理工作不写入操作日志。plan/done/ 和 git 历史是记录。

Q11：这是多仓库产品的一部分吗？ A11：是/否。

Q12：制品应该放在哪里？ A12：仓库根目录（./）或 .docflow/（默认）或其他路径。AGENTS.md 和 CLAUDE.md 始终在根目录。

EvolveHQ/docflow

docflow 是什么？

在你喜欢的 AI 中提问

文档