setup-project 用于为一个将要被后续会话持续改动的项目（仓库或工作文件夹）安装并维护一套共享的项目表面（surfaces），使未来的会话和团队成员——无论是否使用 manifest-dev——都基于相同的方向、词汇和决策记录工作。
用途与安装内容
安装三样东西，只有第一样是必需的：
- 接线（wiring）：项目自有的 ADR 约定文件、术语表、North Star（项目的长期策略表面：为谁服务、承诺什么、何为成功），以及项目上下文文件中的一个段落，使会话读取并维护上述三者，并记录项目所携带的表面版本。每个项目都会执行，包括完全没有历史的项目。
- 验证装置（verification harness）：默认推荐并安装，提供项目用于检查未来运行所改动之物是否仍履行职能的单条命令，每个被检查项配一份配方（recipe），依据 references/VERIFICATION_HARNESS.md 从项目现有内容播种。自有一套验证方式的项目可选择退出，此时上下文文件改为记录其自身方式。
- 种子（seed）：从项目自身历史重建的词汇与决策记录。仅在存在可读历史时执行，是对接线的补充而非替代。
目标是合理的起点而非完整记录：项目过去的推理大多确实不可恢复，诚实说明无法恢复部分的种子，比看似完整实则不完整的更有价值。
使用方式与标志
--no-mine：跳过种子，仅安装接线。否则只要存在历史就会挖掘；没有提交、文档和代码的项目自然无种可播，无需用该标志表达。- 仅顶层选项被解释为标志；引号或代码格式中提到的内容视为话题文本。
已有内容优先
先读后写，绝不覆盖项目已维护的表面：
docs/adr/CONVENTIONS.md存在 → 项目有自己的 ADR 约定，由其主导，不替换，本次写入遵循它，然后按“比较后提议”流程处理。CONTEXT.md（或由根CONTEXT-MAP.md命名的上下文文件）存在 → 加载它；挖掘出的词汇作为补充提议，绝不替换。NORTH_STAR.md存在 → 加载，种子内容作为补充或对已有立场的证据提议，绝不重写；其立场只由所有者裁决变更。docs/adr/有记录但无 CONVENTIONS.md → 项目存在未成文约定，从记录中推断命名方案、章节、交叉引用与索引形态，据此编写约定文件，适配而非替换出厂默认；语料不一致时说明并让用户选择，不擅自决定。- 上下文文件已带有部分接线 → 只补缺失部分，其余不动；表面段落存在但与模板不同时比较并提议，而非重写。
表面版本与更新
上下文文件的项目表面段落以一个注释记录表面版本。应从磁盘读取：宿主可能剥离 HTML 注释，导致上下文中看不到版本。references/CHANGES.md 每行列出一个版本（最后为最新），references/changes/vN.md 保存版本 N 提供的内容；只读记录版本之后的文件。仅本技能在安装时、完成更新时，以及 figure-out 在用户拒绝整体更新提议时写入该行；表面之下的内容（新记录、术语条目、配方）从不改变它。
- 记录版本早于最新 → 加载 references/upgrades/vN-to-current.md，直达最新版本。
- 记录为最新 → 无升级指南。
- 无记录 → 无版本指南；若有功能图、读者任务列表或验证表面 README 需迁移，加载 references/upgrades/MOVE_TO_HARNESS.md。
在已带表面的项目上，运行即为更新，目标是参考资料所描述的最佳设置，而不只是记录版本以来变化的部分。每项提议需说明其服务的当下需求；没有此类需求的项不算缺口。更新覆盖：版本变化、约定/North Star 约定/表面段落（按比较后提议）、约定下记录的仅可编辑字段（为已有检查添加 Enforced by、补缺失 Area、按约定重建索引，绝不改正文）、验证装置、术语表新增。
每处缺口单独成项提议：参考要求什么、此处服务什么需求、项目现有什么、接受后写入什么。展示每行回填与每处装置变更，只写用户接受的。已满足的项报告为“已就位”。无任何东西记录拒绝，因此早前拒绝的项会再次提议，并在历史可见时说明。验证装置的选择退出通过 own-way 验证条目记录。
比较后提议
本技能生成的约定文件是项目自有的副本，不会被覆盖，因此成为后续改进无法自动到达的分叉。重跑时对已有表面（ADR 约定、North Star 约定、上下文文件中的表面段落）逐节按含义与“本技能步骤 2、3、6 今日会输出什么”比较，而非与原始参考比较；项目改写或重排不算落后。无记录版本时，差异无法归因，逐项呈现当前默认的写法，由用户各自取舍，绝不作为缺陷或一次性全收提议，因为一次接受的批量可能悄然覆盖项目自定的规则。约定文件的移植很少是单文件编辑：被接受的差异若改变命名或写法，需说明哪些文档因此显得脱节。
运行步骤要点
步骤 2 至 6 安装项目缺少的内容；在已有表面的项目上仅通过更新流程执行，除非更新提议且用户接受，或第 4 步默认安装且用户未选择退出。完全缺少的表面按对应步骤安装。
- 解析项目上下文文件：名称因 CLI 而异（CLAUDE.md、AGENTS.md 等），需检测而非常假设；检测规则见 ../review-code/references/context-file-adherence.md。通过 CONTEXT-MAP.md 或 CONTEXT.md 解析术语表；保留已有术语表，缺失则以已知项目名、一行用途和空 Language 段创建。
--no-mine下也执行。 - 安装 ADR 约定（除非已存在）：复制 ../figure-out/references/ADR_FORMAT.md 到 docs/adr/CONVENTIONS.md，仅改开头——标题改为
# ADR Conventions，保留描述 ADR 是什么的句子，将自包含说明与整个## Precedence节替换为一段声明：本文件是项目 ADR 约定且主导、无需工具或先备知识、自带默认的工具服从于它、因服从使本副本成为同步不更新的分叉、保持其最新是项目职责。自## When a decision deserves a record起逐字保留。已有记录时非简单复制，需按“已有内容优先”调和并说明分歧。 - 安装 North Star（除非已存在，则仅按规则提议）：加载 references/NORTH_STAR_FORMAT.md（含文档骨架、九个字段、四种立场状态与维护规则），在仓库根写入 NORTH_STAR.md。只播种仓库自身产物可证的内容：每个立场携带 hypothesis 或 evidence 并指明产物，未回答字段保持空白并注明填写条件，不臆造。访谈只问名称与用途级别的可陈述项。
--no-mine下写空骨架。同时在 docs/NORTH_STAR_CONVENTIONS.md 输出项目自有的约定副本（除非已存在，则其主导）：参考内容改题为# North Star Conventions，所有权节替换为一段声明其为项目 North Star 约定且主导、自包含无需工具、无同步更新的分叉、保持最新为项目职责，并删除面向安装者的项目表面章节。 - 在项目持有未来运行会改动之物、且上下文文件未记录验证选择时安装验证装置；已有自有验证方式处，仍按参考提议升级。已有装置只逐项提议其部件，采用委托方式复用既有验证资产而非另建一套。