setup-project

安装项目所需的各项基础设施，确保每个未来的会话，以及每位队友（无论是否使用 manifest-dev），都遵循相同的方向、使用相同的术语，并依据同一份决策记录开展工作。

安装或提供四项内容，只有第一项是必需的：

• 基础配置 — 项目自行维护的 ADR 约定文件、术语表、北极星（项目对自身宗旨的长期陈述：项目的目的及服务对象、目标、坚持的原则、衡量进展的方式，以及赖以成立的关键假设），以及一段项目上下文文件内容，要求会话读取并维护上述三项，并记录项目采用的基础配置版本。所有项目都会安装这项配置，包括完全没有历史记录的项目。
• 验证框架，建议安装并默认安装 — 项目用于检查未来运行要修改的内容是否仍能正常工作的唯一命令，并为每项检查内容提供一套方案，根据项目现有内容生成。安装验证框架、提供升级选项或审查现有框架之前，请先阅读 references/VERIFICATION_HARNESS.md。项目可以选择继续使用自己的验证方式；上下文文件会记录该方式。
• 种子内容 — 根据项目自身历史重建的术语和决策记录，以及一些 Taste 条目（项目所有者已经说明过的指导偏好），供用户选择是否接受。只要有历史记录可供读取，就会执行此项；它是在基础配置之上的补充，绝不能替代基础配置。
• 原则技能，供选择 — 针对项目工作中信号最强的领域（例如设计或提示词），为每个领域提供一项项目技能，记录项目成员希望如何开展该领域的工作，并在上下文文件中添加指向该技能的指引；将上下文文件中仅适用于某一领域工作的原则和 Taste 条目移入该领域的技能。提供、编写或审查原则技能之前，请先阅读 references/PRINCIPLES_SKILLS.md：这就是操作方法。只有用户明确同意，才会写入任何内容。

以上内容都面向项目：即存放或即将存放后续会话将要修改的工作的仓库或工作文件夹——用户正在开始的新项目或空项目也算项目，详见下文的 空输入。如果此技能运行时没有这样的项目——例如没有工作区的聊天、主目录或临时文件夹、仅存放一个已完成成品的文件夹，或与当前会话所在文件夹无关的问题——请说明这一点，并询问要为哪个文件夹进行设置；在用户指定文件夹之前，不要写入任何内容。

目标是建立良好的起点，而不是整理出完整记录。项目过去的大部分推理确实无法恢复；坦诚说明无法恢复哪些内容的种子，远胜于看似完整、实则不完整的种子。

标志

--no-mine 会跳过种子生成；基础配置和验证框架仍照常安装。否则，只要存在历史记录，就会进行挖掘——没有提交记录、文档和代码的项目，自然没有可用于生成种子的内容，无需通过标志表达这一点。

只有顶层选项才作为标志处理；对它们加引号或使用代码格式的提及，都视为主题文本。

已存在的内容具有约束力

先阅读，再编写；绝不覆盖项目已经维护的内容：

• 存在 docs/adr/CONVENTIONS.md → 项目有自己的 ADR 规范。以它为准。不要替换它；本次编写的任何内容都要遵循它，然后根据 references/UPDATE.md → 先比较，再提出 进行比较；这一规则同样适用于此文件、docs/NORTH_STAR_CONVENTIONS.md 和上下文文件的 surfaces 部分。
• 存在 CONTEXT.md（或根目录 CONTEXT-MAP.md 指定的上下文文件）→ 加载它。挖掘出的词汇应作为补充内容提出，而不是取而代之。
• 存在 NORTH_STAR.md → 加载它。播种的内容应作为补充内容提出，或作为其已有立场的依据——绝不能将其重写：只有在明确授权范围内作出授权裁定时，才能依据 references/NORTH_STAR_FORMAT.md 中的维护规则更改其立场。
• docs/adr/ 中有记录，但不存在 CONVENTIONS.md → 项目有一套未成文的规范，这些记录就是证据。根据记录推断规范——命名方案、包含哪些章节、如何交叉引用、索引的形式——并编写描述现有规范的规范文件；应调整随附的默认规范，而不是将其原样替换。未经修改地安装默认规范，会宣告现有记录集不符合规范；这既不正确，也是让该文件遭到忽视的最快方式。如果记录集前后不一致，或遵循它会导致索引无法重建，应如实说明并让用户选择；绝不能默默替用户决定。
• 项目上下文文件已包含部分相关设置 → 补上缺少的设置，其余部分保持原样；如果文件已有 surfaces 部分，但与模板不同，则依据 references/UPDATE.md → 先比较，再提出 进行比较并提出建议，而不是重写。

预期用途和范围调整

先阅读适用的项目和个人指令。../ticket-up/references/AUTHORITY.md 定义了任务、委派的决策和保留的验收权；如需进行范围调整，请以此为准。设置会配置后续任务的运行方式，但不会指定项目如何运作。

先根据请求和现有指令推断预期用途，再提出问题。这里的协调是指 orchestrate 技能在各自独立的会话中运行项目的 Tickets，或执行分配给它的结果。仅项目设置不需要协调、Ticket 存储库（项目的 Tickets 所在位置：仓库中的文件、GitHub Issues 或其他跟踪工具）或通知配置。如果预期用途涉及协调，请加载 ../ticket-up/references/STORE_CONFIG.md，并据此确认现有 Ticket 存储库、它所在的跟踪工具、自动化所用的账号，以及运行需要人工介入时应通知谁；不要编写 Tickets。找出项目已经指定、用于判断其目标进展的依据，以及通知来源；仅询问尚未解决且影响重大的选择，并检查可用访问权限。指出任何会阻碍启动的能力或访问权限缺失。如果有人希望运行持续推进直至工作完成，请使用宿主已提供的能力；设置不会安装调度器。

保留技能当前的默认设置。仅提出对预期用途有影响的项目专属调整，并用通俗语言说明范围、责任方、委派的决策和保留的决策。例如，可以委派方向决策，同时由用户保留对最终呈现结果的验收权。持久化新的用户选择前，先展示准确的拟定文本和保存位置：共享规则写入检测到的项目上下文文件或其可访问的配套文件；个人规则写入现有的私人指令机制。复用已提供的决策；无需创建空白政策文件，也无需编制详尽的权限矩阵。

有人接受协调或要求进行范围调整时，询问他们要保留哪些决策。将每项保留决策记录为一条原则，并附上他们给出的示例，而不是封闭式列表；写入现有的范围指令栏之前，先展示拟定文本。由所有者指定这组决策。仅项目设置不提出此类问题。如果项目已开展协调，但其范围指令未指定保留的决策，那么在有人参与时，也将这一询问作为单独事项提出。

无人参与时，不得将其缺席视为同意或答复。根据现有指令进行推断，不代表在无人参与时可将可选事项视为已获同意。需要写入委派或保留决策，或需要准备协调的可选事项，均须由所有者判断：只有某人的答复，或项目已有记录的选择，才能确定这些事项。应在报告中标记这些事项，且不得写入。纯机械事项以及运行本次设置任务的指派已涵盖的步骤，可在任务授权范围内继续；其余事项应予标记，并且在每项已标记事项得到答复前，不得写入 surfaces 版本。

surfaces 版本

上下文文件中的项目 surfaces 部分会记录一个 surfaces 版本，形式为模板附带的注释。请从磁盘上的文件读取：将上下文文件载入会话的宿主可能会剥除 HTML 注释，因此上下文中已有的副本可能看不到文件所记录的版本。references/CHANGES.md 每行列出一个版本，最后一行是最新版本；references/changes/vN.md 说明已安装项目如何获得版本 N 的内容；只读取记录版本之后的文件。该行说明项目包含哪些 surfaces，因此只有此技能会写入它——在安装时，以及完成更新时。写入 surfaces 下方的内容——新记录、术语表条目、配方——都不会改变它。

figure-out 会在单独一行 `` 记录用户拒绝的更新提议。该拒绝行只会阻止 figure-out 重复提议；它并不说明项目包含什么，因此本次运行不会从中读取版本，并会在写入 surfaces 版本时将其移除。若项目 surfaces 部分只有版本行，旁边可能还有拒绝行，则这是先前 figure-out 拒绝提议后留下的，并非此技能所写：将其版本行视为截至该版本的拒绝行，并将项目视为未记录版本，然后安装此部分。

记录的版本还决定了是否会根据 references/UPDATE.md → 比较后再提议，提议项目自有副本中的哪些差异。

更新流程

如果上下文文件记录了 surfaces 版本，或者项目已有 docs/adr/CONVENTIONS.md、docs/NORTH_STAR_CONVENTIONS.md、NORTH_STAR.md 或上下文文件中的项目 surfaces 部分，则本次运行属于更新：在提议或写入任何内容之前，先阅读 references/UPDATE.md。该文件说明更新范围、如何提议并报告每项差异，以及如何比较项目自有的副本。要添加哪些升级指南，取决于项目记录的版本：

记录的版本	加载
vN，早于 CHANGES.md 列出的最新版本	references/upgrades/vN-to-current.md，然后加载该文件夹中之后每个 vM-to-current.md
最新版本	不加载指南
无	不加载版本指南

无论记录的是哪个版本，只要项目有待迁移的功能映射、读者任务列表或验证 surfaces README，就要加载最新版本中包含的 references/upgrades/MOVE_TO_HARNESS.md，并将迁移作为一个事项提议——在该指南加载时，由 v3-to-current.md 指定的事项；是否需要迁移取决于项目的结构，而非记录的版本号。同样，只要项目的 NORTH_STAR.md 仍采用较旧的九字段格式，就要加载 references/upgrades/RESHAPE_NORTH_STAR.md，并将其结构调整作为一个事项提议：如果负责人尚未对其中各行作出决定，每次运行都会再次向其提议。

运行流程

步骤 2 至 6 会安装项目缺少的内容。对于已有 surfaces 的项目，这些步骤只会在上述更新流程中运行：除非更新提议了相应内容且用户接受，或对于机械性事项，任务作者授权执行，否则不会写入其中任何内容；或者，对于默认安装的 harness 步骤 4，用户已获告知且没有选择退出。无论项目当前使用什么方式进行验证，只要它完全缺少某个 surface——没有约定文件、North Star、surfaces 部分，或推荐的验证 harness——在用户接受后，该 surface 就会由对应步骤安装；无论项目记录的是哪个版本，更新都会将其作为一个事项提议。

1. 解析项目上下文文件。 文件名因 CLI 而异，可能是 CLAUDE.md、AGENTS.md 或其他名称，因此应检测，而不是想当然地指定。活动宿主检测和上下文文件解析规则位于 ../review-code/references/context-file-adherence.md；请阅读并遵循。存在 CONTEXT-MAP.md 时，通过它解析术语表，否则使用 CONTEXT.md。保留现有术语表；如果缺失，则先创建一个术语表，写入已知的项目名称、一行用途说明，以及空的 Language 部分，然后再进行挖掘或接入。即使使用 --no-mine，也要执行此操作。

2. 安装 ADR 约定，除非 docs/adr/CONVENTIONS.md 已存在。将 ../figure-out/references/ADR_FORMAT.md 复制到 docs/adr/CONVENTIONS.md，并按以下要求修改开头，除此之外不作任何更改：

   • 将标题改为 # ADR Conventions；
   • 保留描述 ADR 是什么的句子；
   • 将自包含说明和整个 ## Precedence 部分替换为一段文字，说明此文件是项目的 ADR 约定并具有约束力；决定和撰写 ADR 所需的一切内容都在此文件中，无需任何工具或先验知识；自带默认约定的工具应遵循此文件；并且，由于这种遵循意味着此副本是一个分支，不会通过同步进行更新，因此保持其内容最新是项目的责任；重新运行安装它的设置流程，是了解当前默认约定所包含内容的一种方式。

从 ## When a decision deserves a record 开始的所有内容都必须原样保留——此文件旨在自成一体，没有工具的读者也必须能够从头到尾遵循它。

如果已有记录，这就不能直接复制：应根据上文的 What already exists governs，协调默认约定与现有记录体现的做法，并说明你解决的任何分歧。

如果项目有自动化检查——测试套件或验证框架——则提供一项检查，按照约定中的重建规则重建 ADR 索引；如果 North Star 维护了 Strategy choices in force 列表，也要按其约定重建该列表，包括各条记录的 Revisit when 行中的提示标记，并在结果与文件内容不一致时失败。手动重建的派生列表会像手动维护的索引一样逐渐偏离；这项检查能确保那些从未读过规则的贡献者也遵循规则。请使用项目自己的测试形式，或编写一个框架场景。没有自动化检查的项目无需添加检查；重建仍然是撰写记录时的一部分。如果某项决策记录决定保留索引或列表，则在检查完成后，在该记录的 Enforced by 行中注明此检查。 3. 安装 North Star，除非 NORTH_STAR.md 已存在（若已存在，则仅按照 现有内容为准 提出建议）。加载 references/NORTH_STAR_FORMAT.md——其中包含文档骨架、六个部分、North Star 可包含的四种行、四种立场状态以及维护规则——并在仓库根目录写入 NORTH_STAR.md。按照参考文档中的 诚实地生成 进行初始填充，其中说明了哪些内容可以预填、需要询问负责人什么，以及哪些部分应留待之后各自调查；empty 立场就是文档的待办清单。初始填充即为挖掘：在 --no-mine 下，则只写入基本骨架——每个部分均设为 empty，并注明其填充条件。除文档外，还需在 docs/NORTH_STAR_CONVENTIONS.md 写入项目自有的约定副本，除非该文件已存在（若已存在，则以其为准——与 ADR 约定遵循相同规则）：将参考文档的内容标题改为 # North Star Conventions，把所有权部分替换为一段文字，说明此文件是项目的 North Star 约定且具有约束力；内容须自成一体，无需任何工具；这是一个分支副本，不会通过同步更新——维护其时效性是项目的职责。可将重新运行安装它的设置流程作为了解当前默认内容的一种方式；删除面向安装程序的 项目界面部分 章节——项目维护者会在上下文文件本身中看到该部分。

4. 安装验证工具链，前提是项目中存在未来运行会更改的内容，且其上下文文件尚未记录验证方案。它是推荐的默认方案，因此除非用户选择退出、继续使用项目自己的验证方式，否则应安装。写入前说明它会添加什么，让用户可以选择退出。若项目已有自己的验证方式——包括一条自有方式的条目，或项目自行编写的测试、脚本或工具链——仍应提供升级到推荐工具链的选项：它会通过委托方式纳入这些检查，将每项检查转为调用项目自有命令的配方场景，因此不会替换项目信赖的任何内容；说明用户此前是否选择退出。若用户拒绝，则保持原有条目和检查不变；如果发现磁盘上已有工具链但上下文中未记录，则记录该条目。安装时，加载 references/VERIFICATION_HARNESS.md 并遵循其中的 设置会创建什么，以及运行会构建什么 一节；其 组成部分 一节说明如何提供和覆盖工具默认语言。若用户选择退出，则与用户确认项目的命令和步骤，并按步骤 6 中验证条目的自有方式格式记录，以免在后续的梳理、定义或执行过程中再次提供工具链。若项目没有未来运行会更改的内容，则不安装；在报告中说明。--no-mine 下也执行此操作：目录依据当前源文件，而非历史记录。

5. 进行初始填充，除非使用 --no-mine 或项目已记录界面版本（更新时仅按照 references/UPDATE.md 进行挖掘）。加载 references/MINING.md 并遵循其中的说明。该文档涵盖每种来源可以和不可以得出什么结论、推理过程缺失时如何在记录中说明，以及为什么术语表候选项要经过确认而非直接写入。然后，即使在 --no-mine 下，也要按照 references/PRINCIPLES_SKILLS.md，为项目的高信号领域提供原则技能：在 --no-mine 下或缺少历史记录时，只提供该文档针对无历史记录项目列出的领域。

6. 接入项目上下文文件。 按照 references/NORTH_STAR_FORMAT.md → 项目界面部分 生成项目界面部分，模板是生成文本的唯一来源。仅包含已接受且限定范围的调整，按照其可选条目要求——此文件会在每个会话中读取，因此其中每一行都是永久成本——并将导入内容写成项目上下文文件的导入，而非特定工具链的文件名。

7. 报告已落地的内容，以及哪些事项需要先由用户决定：标记为尚未回答的负责人判断事项，以及任何不可用的访问权限或能力和后续步骤。然后说明配置的范围和保留的决定；如果已设置协调机制，则说明该机制已启动但尚未执行任何操作；接着说明安装了什么、写入的 surfaces 版本、提供的每项原则技能及写入的行数和上下文文件分类、更新提供了什么以及用户对每项内容的选择、已就位事项的总数、项目采用了 harness 还是保留自己的做法；如果采用了 harness，则说明它采用并编入目录的内容、先询问的选择，以及证明运行执行的场景，并说明播种了什么。如果执行了播种，references/MINING.md 中的 Reporting 部分规定了这一部分必须涵盖的内容。无论结果如何，都要报告比较结果，遵循 references/UPDATE.md → Compare, then offer：指出哪些副本的哪些部分与当前步骤生成的内容不同，以及用户对每项内容的选择；或者明确说明已比较这些副本，且它们已包含当前默认项的全部内容——不报告比较结果，就等于没有运行过比较，这正是整个步骤要避免的失败。如果跳过播种，要报告实际原因：--no-mine 跳过了播种、项目已经记录了 surfaces 版本，或没有可用历史记录。

空输入

如果指向的仓库没有提交、文档或代码，则安装接线后停止：创建 conventions 文件、一个包含项目名称、一行用途和空 Language 部分的 CONTEXT.md、每个部分均为 empty 并附带填写条件的 NORTH_STAR.md 骨架，以及包含 surfaces 版本的上下文文件部分。此时还没有可供 harness 检查的产物，因此除非用户在此选择退出，否则将验证要点的形式记录为建议默认值；首次构建待检查内容的运行会构建 harness 的第一部分，从该要点指定的命令开始。说明没有播种任何内容，因为没有可供播种的内容。这是全新项目的情况，也是成功运行，而不是降级运行——项目一开始就接好了各个 surfaces，正是我们的目标。

如果无法得知项目名称或用途，请询问用户。两者各占一行；猜错会让词汇表建立在错误的前提上。

注意事项

• 丰富的历史记录不代表典型历史记录。 能在拉取请求中记录设计理由的项目并不常见。不要根据发现的第一个文档完善的提交来调整本次运行的目标。
• 不要在项目上下文文件中重述 conventions。 该文件会在每次会话中加载；conventions 文件则在有人需要时加载。重复这些细节会增加每次会话的开销，还会产生第二份逐渐偏离的副本。