AlignFirst Setup Guide 是 AlignFirst 工具链的安装与配置指南技能。它按用户意图进行路由，只加载该路线所需的参考文档，并强调 docmap、workspace 与 AlignFirst skills 可以各自独立采用。
一、术语 AlignFirst CLI 是 alignfirst npm 包及其 bin，提供 guide、ticket、sync、plans、docmap、conventions、context、config 和 doctor 等命令。 AlignFirst skills 是运行 CLI 的存根。九个命令技能 alspec、alplan、almerge、alreview、aldescription、alcatchup、alcatchupaad、alcatchupspec 保持 disable-model-invocation: true；人类在 Claude Code、GitHub Copilot、Cursor 中以 /alspec 调用，在 Codex 中以 $alspec 调用。可选的 alignfirst 技能让智能体识别散文中提到的协议；指令文件以规范 alignfirst 上下文段开头的项目自身即可提供此能力。 work-files repository 是通过 alignfirst plans setup 配置的可选 CLI 模式。 aligndev（AlignDev CLI）承载助手的 playbook、编码智能体委派与项目发现。OpenClaw 助手宿主安装它；编码智能体助手通过 npx 运行它。
二、未改动的仓库 当用户不希望仓库被写入任何内容时，以下所有路线都走 companion-setup.md。项目的 AlignFirst 文件存放在其伴随目录中，且只有该模式支持的工具适用。
三、指定工具 当用户指定某个工具时，检查仓库并直接进入该工具，只安装或升级其请求的内容。 AlignFirst CLI、协议或 skills：见 alignfirst-skills-setup.md。只安装请求的组件；skills 通过 npx 调用 CLI，无需单独安装。对于已有的 v1、v2 或 v3 安装、存在 ~/.config/alignfirst/ 的机器，或带路径的伴随注册表，从 alignfirst-upgrade.md 开始。 work-files repository：见 plans-setup.md。 docmap：见 docmap-setup.md。带有旧 docmap 正文（“Mandatory for every task”）的指令文件需要执行 Update the Docmap Snippet。 workspace：见 workspace-setup.md。workspace.mjs 中的 ports group 或 setupProfiles 需要执行 Move Workspace Ports to the Dev-Server。 AlignDev（aligndev）：询问用户它服务于 OpenClaw 助手还是编码智能体（Claude Code 或 Codex）。对于 OpenClaw，遵循 AlignDev for OpenClaw。对于编码智能体，遵循 coding-agent-assistant.md，它会全局安装 aligndev 技能。旧的 ~/.alignfirst/aligndev.config.json 需要执行 Rename the AlignDev Settings。 此路线不要展示工具菜单或添加无关工具。
四、工具推荐 当用户询问项目可以采用什么时，检查仓库并呈现以下独立选项： AlignFirst 协议通过 CLI 提供协作式规范、规划、实现、合并、审查、描述与追赶工作流。命令技能添加快捷方式，可单独安装。work-files repository 是可选的子选项。 docmap 使仓库的 docs/ 树对智能体和人类可发现。可通过 AlignFirst CLI 或独立的 @alignfirst/docmap 包获得。 workspace 创建隔离的 git-worktree 开发环境。 在提供该选项前，先确定是否存在 work-files repository。让用户选择任意子集。
五、项目指令 根据项目已采用的工具选择 AGENTS.md 或 CLAUDE.md 的发现段： AlignFirst skills 或协议：使用 AlignFirst setup 中的 alignfirst 上下文段。它替换 Docmap - Seek Documentation；保留任何必要文档列表和项目特定指令。 仅 Docmap（无 AlignFirst skills 或协议）：使用 Docmap setup 中的 Docmap - Seek Documentation，并带上项目实际的 Docmap 命令。 仅 workspace：添加 workspace 指令。 单独安装 Docmap 或 workspace 不会让项目选择加入 AlignFirst 协议。全局安装 skills 不会让每个仓库都选择加入它们。
六、AlignDev for OpenClaw AlignDev for OpenClaw 将 OpenClaw 助手转变为与 AlignFirst 协作的开发者。助手持有聊天身份、其频道与会话，并通过编码智能体（Claude Code 或 Codex）使用 AlignFirst 协议运行仓库工作。 一种部署是专用 Linux 服务账户，以自身名称和频道身份在 Slack 或 Discord 上运行助手。这两个术语贯穿本技能及其渲染的仓库。 准备项目使仓库与助手兼容。创建助手则构建并部署它。
七、为助手准备项目 在更改仓库前先检查它。已准备的项目具备以下全部内容： AGENTS.md 或 CLAUDE.md 中的规范 bootstrap 段，位于标题和引言之后的第一个 ## 段。README 可提供全局 CLI 安装作为便利。 .alignfirst.json 对助手管理的项目是必需的，否则可选。 在写入 .alignfirst.json 之后、workspace 设置之前，aligndev project doctor --root <projects-directory> 结果干净。当清单不健康时停止准备。 当团队有时，通过 alignfirst plans setup 建立 work-files repository。 docmap，包括项目脚本或 CLI 指令。当仓库没有 docs/ 目录时，作为准备的一部分通过 docmap-bootstrapping.md 引导其文档。 workspace，适配项目的运行时和开发生命周期，满足 AlignDev 契约。 Node 版本声明（.nvmrc、.node-version 或 engines.node），以便 fnm 选择项目运行时。当仓库没有时，询问要声明哪个版本。 面向不熟悉开发者的项目特定 DEVELOPERS.md：命令、架构、文档地图、开发工作流与验证流程。 当用户说仓库必须保持不动时，遵循 companion-setup.md 及其 For an Assistant 部分。 每个为助手（包括作为助手的编码智能体）准备项目的过程都跳过 AlignFirst 命令技能和全局 bootstrap 行。第 1 项的 bootstrap 段保留。助手的服务账户为其委派的编码智能体保留本指南的全局安装。 检测并验证包管理器、运行时、构建、测试、lint、开发服务器、端口、共享目录、种子配置文件与团队计划细节。只写入从仓库确认的事实。遵循上述每个选定工具参考，然后完成 DEVELOPERS.md，并指明 Node 版本声明。
八、创建助手 要创建或操作助手部署本身，请阅读 aligndev-openclaw.md。普通工具设置不要加载该工作流。
九、编码智能体作为助手 对于在一个项目上充当助手、不使用 OpenClaw 的编码智能体（Claude Code 或 Codex），请阅读 coding-agent-assistant.md。
十、共享排查规则 从 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：workspace 脚本或 @alignfirst/workspace。 @alignfirst 之前的安装：清单中的 @paleo/docmap 或 @paleo/workspace。在提议任何其他内容之前，将依赖替换为 @alignfirst 名称，并重写包装脚本（scripts/workspace/*.mjs）中的 @paleo/ 导入说明符；两个作用域会并排安装，因此仅改清单会让包装脚本仍导入旧包。 AlignFirst：.alignfirst.json、.plans/、运行 alignfirst context 或 npx alignfirst context 的 bootstrap 段、AlignFirst 指令段、规范技能安装，或 npx alignfirst config 报告的伴随目录。 work-files repository：.plans 符号链接或 .alignfirst.json 中的 plans.folder。 助手准备：上述完整的七部分契约。 在项目变更前立即要求干净的工作树。只读发现与推荐不需要。