alignfirst-setup-guide

AlignFirst 设置指南

根据用户意图选择路径。仅加载该路径所需的参考资料。docmap、workspace 和 AlignFirst skills 均可独立采用。

术语

AlignFirst CLI 是 alignfirst npm 包及其可执行文件。它提供 guide、ticket、sync、 plans、docmap、conventions、context、config 和 doctor。

AlignFirst skills 是运行 CLI 的存根。九个命令 skills alspec、alplan、 al、almerge、alreview、aldescription、alcatchup、alcatchupaad 和 alcatchupspec 保留 disable-model-invocation: true；用户可以在 Claude Code、GitHub Copilot、 Cursor 中通过 /alspec，在 Codex 中通过 $alspec，或在 Pi 中通过 /skill:alspec 调用它们。可选的 alignfirst skill 让 Agent 能识别以自然语言提及的协议；如果项目的指令文件以规范的 alignfirst context 部分开头，则该项目已自行提供此能力。

工作文件仓库是通过 alignfirst plans setup 配置的一种可选 CLI 模式。

AlignDev CLI aligndev 提供助手的操作手册、编码 Agent 委派和项目发现功能。OpenClaw 助手主机安装它；编码 Agent 助手则通过 npx 运行它。

未经改动的仓库

如果用户不希望在仓库中写入任何内容，以下所有路径都应通过 companion-setup.md 进行。此时，项目的 AlignFirst 文件位于其伴随目录中，并且仅适用该模式支持的工具。

指定工具

如果用户指定了某个工具，请检查仓库并直接执行该工具的设置。只安装或升级用户要求的内容。

• AlignFirst CLI、协议或 skills：alignfirst-skills-setup.md。仅安装用户要求的组件；skills 通过 npx 调用 CLI，无需单独安装。 对于现有的 v1、v2 或 v3 安装、具有 ~/.config/alignfirst/ 的机器，或包含 paths 的伴随注册表，请从 alignfirst-upgrade.md 开始。
• 工作文件仓库：plans-setup.md。
• docmap：docmap-setup.md。如果指令文件包含旧版 docmap 正文（“每项任务都必须执行”），则需要执行更新 Docmap 片段。
• workspace：workspace-setup.md。如果 workspace.mjs 中存在 ports 组或 setupProfiles，则需要执行将 Workspace 端口移至 Dev-Server。
• AlignDev（aligndev）：询问用户它是用于 OpenClaw 助手还是编码 Agent（Claude Code、Codex 或 Pi）。对于 OpenClaw，请遵循 OpenClaw 的 AlignDev。对于编码 Agent，请遵循 coding-agent-assistant.md，该文件会全局安装 aligndev skill。旧版 ~/.alignfirst/aligndev.config.json 需要执行重命名 AlignDev 设置。

此路径下不要展示工具菜单，也不要添加无关工具。

工具推荐

如果用户询问可以在项目中设置哪些内容，请检查上下文中列出的 skills 并检查仓库。将全局 skills 与项目工具分开列出。安装或配置之前，让用户选择任意子集。

全局技能

使用上下文中的技能列表检查当前 Agent 可用的技能：

• aligndev：编码 Agent 助手的操作手册。
• alignfirst：识别正文中提及的协议。
• paseo-alignfirst-workspace：推荐 Paseo 用户使用；介绍如何在 Paseo 中使用 AlignFirst 工作区。
• 命令技能：alspec、alplan、al、almerge、alreview、aldescription、alcatchup、alcatchupaad 和 alcatchupspec。

报告哪些技能可用，并建议为当前 Agent 全局安装缺少的技能。未列出的名称表示此会话中不可用；这并不能证明磁盘上不存在该技能。如果宿主未提供技能列表，请报告可用性未知。此检查无需扫描文件系统、运行安装命令或执行 doctor。

对于已获批准的安装，请遵循 AlignFirst 技能设置或全局安装 aligndev 技能的步骤。仅安装全局技能不会配置项目或安装 Pi 工具。除非用户另行请求这些快捷方式，否则助手准备流程仍会跳过命令技能的安装。

对于 Paseo 用户，请在获得批准后全局安装 paseo-alignfirst-workspace。将 <agent> 替换为当前 Agent 的安装目标（claude-code、codex 或 pi）：

npx -y skills add https://github.com/paleo/alignfirst --global --yes \
  --agent <agent> --skill paseo-alignfirst-workspace </dev/null

项目工具

无论项目使用何种语言或技术栈，都应推荐全局技能、AlignFirst 协议和 Docmap。检查现有配置，以区分建议采用的工具与已具备的工具：

• AlignFirst 协议通过 CLI 提供协作式规范制定、规划、实现、合并、审查、描述和进度跟进工作流。命令技能可添加快捷方式，也可单独安装。工作文件仓库是可选子项。
• docmap使仓库的 docs/ 目录树便于 Agent 和人类查找。可通过 AlignFirst CLI 使用，也可作为独立的 @alignfirst/docmap 包使用。缺少 docs/ 目录意味着可以启动文档建设，而不是省略此项建议的理由。
• workspace创建隔离的 git 工作树开发环境。对于 Node 项目，建议按照 workspace 设置安装并使用 @alignfirst/workspace。应根据项目的运行时声明、脚本、依赖项或文档判断是否使用 Node；仅用于工具配置的 package.json 不足以作为依据。如果项目中已存在工作区工具，应推荐其文档所述的工作流，而不是替换方案。对于其他技术栈，仅在用户提出请求或仓库证据支持时提供 workspace；以现有的非 Node 实现为准。

提供该选项前，先确定是否存在工作文件仓库。

项目说明

根据项目采用的工具，选择 AGENTS.md 或 CLAUDE.md 的发现说明部分：

• **AlignFirst 技能或协议：**使用 AlignFirst 设置中的 alignfirst context 部分。它会替代 Docmap - Seek Documentation；保留任何必需文档清单和项目特定说明。
• **未使用 AlignFirst 技能或协议的 Docmap：**使用 Docmap 设置中的 Docmap - Seek Documentation，并填写项目实际使用的 Docmap 命令。
• **仅使用 Workspace：**添加 workspace 说明。

仅安装 Docmap 或 workspace 不会使项目自动采用 AlignFirst 协议。全局安装技能不会使所有仓库自动采用这些技能。

适用于 OpenClaw 的 AlignDev

适用于 OpenClaw 的 AlignDev 会将 OpenClaw 助手变成一位与 AlignFirst 协作的开发者。该 助手拥有聊天身份、频道和会话，并通过编码 Agent（Claude Code、Codex 或 Pi），使用 AlignFirst 协议处理仓库工作。

一种部署方式是使用专用 Linux 服务账户，以其自身名称和频道身份运行助手，适用于 Slack 或 Discord，以及 OpenClaw 应用。本指南和它所呈现的仓库始终使用这两个术语。

准备项目可使其仓库兼容助手。创建助手则负责构建和部署。在呈现或升级之前，请阅读部署边界。三个覆盖层都使用命名配置文件和已编目的原生存储。Pi 通过明确允许可写 auth.json，保留原生身份验证；其他所有受管理资源仍受控维护保护。离线模板检查不能替代实时部署验收。

为助手准备项目

在进行更改前检查仓库。准备好的项目应具备以下所有条件：

1. 在 AGENTS.md 或 CLAUDE.md 中设置规范的引导部分，放在标题和简介之后的第一个 ## 章节。README 可将全局 CLI 安装作为便利选项。 由助手管理的项目必须包含 .alignfirst.json，其他项目则可选。
2. 写入 .alignfirst.json 后、设置工作区之前，运行 aligndev project doctor --root <projects-directory>，结果应无问题。如果清单不健康，请停止准备。
3. 有效的工作文件可用，且未被项目自身的仓库跟踪。单独的工作文件仓库可以跟踪这些文件。若计划文件缺失或已被项目跟踪，在产生工单或编码会话相关影响之前，请按照 aligndev 的 work-files-setup 指南主题操作；其授权的配套选择不会复制项目内容，也不会对其进行修改。
4. docmap，包括项目脚本或 CLI 说明。如果仓库没有 docs/ 目录，请在准备过程中按照 docmap-bootstrapping.md 引导其文档。
5. 记录工作树使用方式。现有项目工作区工具（包括非 Node 实现）仍具有权威性。安装完整的工作区系统是可选的；若选择安装，需满足AlignDev 合约。否则，使用 aligndev worktree，并记录独立的安装、构建、测试命令以及应用生命周期命令。
6. 项目的运行时要求。对于 Node 项目，应声明版本（.nvmrc、.node-version 或 engines.node），以便 fnm 选择该版本；若未声明版本，请询问应使用哪个版本。其他运行时遵循其文档所述工具。
7. 面向不熟悉项目的开发者编写项目专属的 DEVELOPERS.md：包含命令、架构、文档地图、开发工作流和验证流程。

如果用户要求仓库必须保持不变，请改为遵循 companion-setup.md 中的适用于助手章节。

所有为助手准备项目的流程（包括让编码 Agent 担任助手）都跳过 AlignFirst 命令技能和全局引导行。第 1 项中的引导部分仍须保留。助手的服务账户应保留本指南的全局安装，以供其委派的编码 Agent 使用。

检测并验证包管理器、运行时、构建、测试、lint、开发服务器、端口、共享目录、预置配置文件和团队计划详情。只写入从仓库确认的事实。遵循上文所选工具的参考资料，然后完成 DEVELOPERS.md，并注明 Node 版本声明方式。

创建助手

如需创建或操作助手部署本身，请阅读 aligndev-openclaw.md。普通工具设置无需加载该工作流。

将编码 Agent 用作助手

如需让 Claude Code、Codex 或持久运行的 Pi 会话在单个项目中充当助手，且不使用 OpenClaw，请阅读 coding-agent-assistant.md。Pi 使用 /skill:aligndev 和单独安装的通用后台工具；Pi 子进程使用独立的子 Agent 程序包进行计划／审查委派。仅安装技能不会提供可执行工具。

通用调查规则

根据 package.json 中的 packageManager 检测包管理器，然后检查根目录下的锁文件： package-lock.json 表示 npm，pnpm-lock.yaml 表示 pnpm，yarn.lock 表示 yarn，bun.lock 或 bun.lockb 表示 bun。若无法确定，则使用 npm。

将命令转换为对应的包管理器。npm 在脚本标志前需要加上 --；pnpm 和 yarn 省略 run 和分隔符；bun 保留 run，但省略分隔符。

提出变更前，先检测现有配置：

• docmap：存在 docmap 脚本、@alignfirst/docmap、指令文件中的 alignfirst docmap，或 docs/。
• workspace：存在已记录的工作区流程，包括非 Node 工具；workspace 脚本或 @alignfirst/workspace 是其中一种配置。
• 早于 @alignfirst 的安装：清单中存在 @paleo/docmap 或 @paleo/workspace。提出其他任何变更前，先将依赖替换为 @alignfirst 名称，并重写包装脚本（scripts/workspace/*.mjs）中的 @paleo/ 导入说明符；这两个作用域会并存，因此只修改清单会导致包装脚本仍导入旧程序包。
• AlignFirst：存在 .alignfirst.json、.plans/、运行 alignfirst context 或 npx alignfirst context 的引导部分、AlignFirst 指令部分、规范技能安装，或 npx alignfirst config 报告的伴随项目。
• work-files 仓库：存在 .plans 符号链接，或 .alignfirst.json 中的 plans.repositoryFolder。
• 助手准备：上述完整的七部分约定。

在修改项目之前，必须立即确认工作树干净。只读探索和建议无需满足此要求。