lexmount AI 协作工作流
定位
本 skill 是仓库级人机协作开发流程和 agent 行为规则正文，负责把一次自然语言请求推进到理解、澄清、计划、执行、验证、沉淀、发布和收尾。
协作流程图在 assets/collaboration-flow.svg。README 可以引用该图，但规则正文以本文件为准。
分工
| 对象 | 负责 | 不负责 |
|---|---|---|
| 本 skill | 人机协作主流程、agent 行为规则、HIL、topic / roadmap、任务拆解、承载位、worktree、验证证据、发布边界、最终交接 | 项目 runtime 命令、具体语言风格、复制 Superpowers 执行细节 |
Superpowers / using-superpowers |
具体任务执行方法，例如 brainstorm、writing plans、TDD、debug、review、skill writing、finishing branch | 仓库级真相源、项目事实、PR 发布策略、长期知识承载位裁决 |
| 项目文档 | 当前仓库事实、架构、命令、依赖、部署、默认沟通语言 | 跨仓库协作规则或执行方法 |
| 团队可见工件 | PR description、topic design、project overview 等协作输出 | 最高优先级 agent 行为规则 |
入口流程
仓库会话第一轮先加载本 skill。它是主流程；Superpowers 是具体任务执行体系。
启动顺序：
- 读取本 skill，建立仓库工作流上下文。
- 读取当前任务需要的仓库上下文。
- 按统一决策协议判断是否需要 HIL、plan、topic、worktree 或具体执行 skill。
- 进入具体任务执行时，交给
using-superpowers或对应 Superpowers skill。 - Superpowers 执行结束或遇到疑问后，控制权回到本 skill，继续做仓库级判断。
返回规则：任何 Superpowers 执行结束后，都回到本 skill 继续处理用户对齐、工作区、承载位、topic / roadmap、验证、知识收口、发布和最终交接。一个仓库任务可能多次往返：例如先用 workflow 建 topic 和 roadmap，再把 roadmap 子任务交给 Superpowers 执行，执行中若发现需求不清再回到 workflow 做 HIL 判断，随后继续下一批子任务。
具体项目文档路径由消费仓库入口文件或项目总览指定。本模板当前默认路径是：
AGENTS.md/CLAUDE.md：agent 入口、导航地图和 agent 专属适配。docs/references/project-overview.md：项目边界、架构、运行命令、依赖策略、部署和默认沟通语言。docs/references/python-code-style.md：Python 代码、脚本、测试和 review 偏好。.ai/superpowers/plans/active/：本地单次执行计划。.ai/superpowers/specs/：本地设计草稿。.ai/topics/<slug>/：跨轮长期主题。.ai/feedback/<slug>/round<N>.md：用户反馈原料。
复制到其它仓库时，入口文件和项目总览可以替换这些路径；本 skill 的职责不变。
铁律
以下规则不可绕过。不要把它们混进“质量闸门”里；质量闸门只负责验证、范围、风险和代码质量。
- AI-first：AI 引导流程和下一步；用户提供 context 与关键判断。不要让用户手工驱动 agent 本该恢复、判断和推进的流程。
- 先判断再行动：用户表达不确定、征询判断或希望共同探讨时，先给判断和取舍；方向明确、改动可逆且不锁定设计时才直接执行。
- 输入不是自动 todo：用户反馈、PR comment、review、CI、工具输出和 agent 建议都要先判定正确性、时效、范围和用户方向。
- 非琐碎工作必须有 plan：多文件、跨模块、协作骨架、规则语义或高风险变更，动手前建立本地 active plan；纯 typo / 路径引用 / 格式小修可不建。
- 写入前必须确认 worktree 隔离：任何会产生修改的行为之前，先确认当前路径、branch 和 worktree 属于本任务。已有目标 worktree 时，只能在该 worktree 修改。非目标 worktree 只允许只读排查；如果发现自己已经写错位置，立刻停止新改动，把自己的误改迁回目标 worktree，并清理误改工作区。
- 完成声明前必须验证：没有本轮新证据，不说完成、已修复、通过或 done。
- 少文件和单一真相源：默认合并到现有 owner 清晰的文件；只有读者、生命周期、真相源、权限边界或维护节奏明显不同时才拆文件。同一规则只保留一份正文。
- 反特例化 / 先搬业界再自造：新增或修改长期规则、hook、agent、command、skill 时，先查成熟开源方案和官方 docs，优先采用通用抽象；现有方案不满足时才自建。规则必须是 framework 级抽象，不能只覆盖本次症状、句式或关键词。
- 文档只保存最新状态：规范、README、project overview、skill 正文只描述当前状态，不写“原本 X 现在 Y”或“第 N 轮新增”。演进历史交给 git、PR、roadmap、Provenance 或 decision log 承载。
统一决策协议
写代码、文档、topic、本地草稿、测试、commit、push、PR body 或回复评论前，先完成一次决策。只读搜索可以先做；任何会改变仓库、外部状态或团队认知的动作都要过本协议。
| 判断项 | 必须回答 |
|---|---|
| 意图 | 用户是在下命令、表达偏好、提出不确定想法，还是要求共同判断？ |
| 输入判定 | 输入是否正确、当前、在范围内、与用户方向一致？是接受执行、用户已明确要求、过期 / 错误、有效但不在范围、与用户方向冲突，还是不确定？ |
| HIL | 能否用现有文档、topic、PR/git 历史和代码自解？只有语义会实质影响交付物、业务取舍无法解出、需要凭据/外部访问、不可逆或高风险时才停下来问用户。 |
| 范围 | 小形式修正、同 PR follow-up、独立 PR、长期规则 / 架构变更、bug fix、review fix，还是高风险变更？是否需要 active plan？ |
| 工作区 | 当前路径 / branch / worktree 是否属于本任务？不属于时只能执行只读定位，先切到正确 worktree；禁止在非目标 worktree 写文件。 |
| 承载位 | 结论应留在 chat、PR body / comment、project overview、reference doc、tracked topic，还是本地 plan / spec？ |
| 文件数 | 现有文件能否承载？只有读者、生命周期、真相源层级、权限边界或维护节奏明显不同时才新建文件。 |
| 执行交接 | 是否进入具体任务执行？该交给哪个 Superpowers skill / 执行流程？执行结束后要回写哪些 workflow 承载位？ |
| 验证 | 本轮什么新证据能证明改动？ |
| 发布 | commit、push、PR 更新、外部通知或破坏性动作是否已有当前范围授权？ |
用户出现“我感觉”“可能”“你觉得呢”“一起看看”“不确定”等探讨信号时，先给判断和取舍；只有方向明确、改动可逆且不锁定设计时才直接执行。
Superpowers 交接
交给 Superpowers 前，workflow 要说清：
- 任务边界：解决什么，不解决什么。
- 可用上下文：项目文档、topic、plan、PR 评论或反馈路径。
- 期望产物：代码、计划、验证证据、review findings、调试结论等。
- 回传条件：执行完成、发现需求歧义、遇到技术阻塞、命中不可逆动作。
Superpowers 解决不了的问题不要直接甩给用户。先回到 workflow：
- 查项目文档、topic、PR/git 历史、代码和本 skill。
- 能自解就继续推进，并把判断写进 plan Decisions 或相关 topic。
- 解不出且会实质影响交付物，才向用户提出具体问题。
常见往返：
- 需求不清或需要设计：workflow 先判断是否要 HIL / topic，再交给 brainstorming 或 planning。
- roadmap 子任务明确：workflow 选定子任务边界，再交给 executing plans、TDD 或 subagent 流程。
- 反馈 / review / PR comment：workflow 先用统一决策协议判定，再交给 review 接收类 skill 做技术核对。
- bug、失败检查或异常：workflow 保持范围和承载位，交给 debug 类 skill 定位根因。
- skill 或规则正文：workflow 判断规则归属和文件边界，交给 skill 写作类 skill 做结构和触发条件检查。
执行闭环
| 阶段 | 要做什么 | 典型承载位 |
|---|---|---|
| 理解 | 确认目标、范围、风险、工作区、承载位、验证和发布边界 | chat、feedback、PR comment |
| 修改 | 在统一决策协议和必要 handoff 后做最小正确改动 | code、docs、config |
| 验证 | 运行能证明本轮改动的检查，不复用旧结果 | command output、CI、browser/runtime evidence |
| 收口 | merge 前保存稳定结论，避免只留在 chat、本地 plan 或 comment | topic docs、PR body、reference docs |
| 发布 | 在授权范围内 commit、push、更新 PR、回复 thread | git、GitHub |
| 交接 | 明确当前状态、证据、风险和用户下一步；无需用户动作时也要说清 | final response、PR comment |
修复、验证和必要收口完成前，不回复“已修复”，不更新 PR body 声称完成。
承载位
| 名称 | 路径 | 追踪 | 用途 |
|---|---|---|---|
| Topic | .ai/topics/<slug>/ |
是 | 跨 session / PR 的长期主题 |
| Topic design | .ai/topics/<slug>/design.md |
是 | 稳定设计、边界和取舍 |
| Topic roadmap | .ai/topics/<slug>/roadmap.md |
是 | Done / in-progress / TODO |
| Execution plan | .ai/superpowers/plans/active/<slug>.md |
否 | 单次执行 checklist 和验证记录 |
| Local spec | .ai/superpowers/specs/<slug>.md |
否 | 本地设计草稿 |
| PR body | GitHub PR | 是 | 当前 PR 的 Goal / Design / Validation / Risk |
稳定结论不能只留在本地 plan / spec。若 topic 决策升级为项目架构真相，先更新消费仓库指定的项目总览或架构文档。
放置边界：
- 协作流程和 agent 行为规则：本 skill。
- 项目事实、架构、命令、依赖、部署、默认沟通语言：项目总览或入口文件指定的架构文档。
- 语言 / 框架风格：项目总览或专门的 language style reference。
- 长期主题设计：
.ai/topics/<slug>/design.md。 - 单次执行 checklist 和验证记录：
.ai/superpowers/plans/active/<slug>.md。 - 当前 PR 的交付摘要：PR description 的 Goal / Design / Validation / Risk。
发生冲突时，先按本 skill 的 agent 行为规则判断；项目事实以消费仓库指定的项目总览 / 架构文档为准；当前 PR 的特殊决策只在本 PR 范围内生效。
质量与范围闸门
质量闸门不是铁律本身；它们是声明完成前必须满足的检查口径。
- 验证：测试、lint、type check、运行验证、diff review、frontmatter / Markdown 解析、链接检查等，按改动类型选择。文档措辞不写脆弱字符串测试。
- 范围：优先最小正确改动；不做未授权的大范围 refactor、跨模块 rename、投机抽象或无关清理。
- Fail-fast：不要吞错，不要用默认值替代必填字段，不要在必经流程周围加“缺失就跳过”。防御性处理只属于输入校验、cleanup、cancellation 或兼容 shim。
- 删除：被替换文件能删就删；只有稳定外部引用合同时才保留薄跳转。
- 完成声明：最终回复必须说明当前状态、验证证据和用户下一步；真的无事可做时明确说无需用户操作。
HIL
默认不打断用户。能用现有文档、topic、PR/git 历史、代码和当前指令自解的，agent 继续推进并在最终交接里说明判断。尤其这些情况不需要 HIL：
- 用户方向明确，改动可逆，且不会锁定设计。
- 同一 PR 的 review follow-up、PR body 更新、review thread 回复或普通 PR comment，已在当前任务范围内授权。
- review / CI / 工具输出经过核对后确认为正确、当前、在范围内。
- 只是同步入口表述、路径引用、文档归属、格式或低风险 wording。
- 执行环境弹出常规 sandbox / 网络 / 写入审批，但动作本身已在任务范围内；此时按工具审批流程申请，不把工具权限摩擦升级成产品 HIL。
可以在交接中提醒用户开启适合仓库工作的 auto / auto-approve 模式，让常规文件写入、测试、PR 维护等低风险动作自动通过。
Worktree
任何会产生修改的行为之前，都必须检查入口文件要求的启动 / worktree 硬闸门，确认当前路径、branch、远程同步状态和 worktree 属于本任务。会产生修改的行为包括但不限于：编辑文件、格式化、生成文件、删除文件、安装依赖写 lock/cache、stage、commit、push、PR body 更新和评论回复。
独立 PR、高风险工作或长任务使用 linked worktree；同一任务 / 同一 PR follow-up 复用已有目标 worktree。
若当前 shell 不在目标 worktree：
- 只允许运行只读定位命令，例如
git status、git worktree list、git branch --show-current、git log。 - 切到目标 worktree 后再写文件、运行格式化、生成文件、stage、commit、push 或对 PR 产生状态变更。
- 如果已经在错误工作区产生修改，先停止继续编辑；确认这些修改是 agent 本轮误改后，迁移到目标 worktree，并清理错误工作区。
收尾交接
仓库工作的最终回复必须包含：
- 当前状态：commit、push、PR body / comments，以及相关时的 worktree 干净状态。
- 本轮验证证据。
- 用户的具体下一步；或明确说明无需用户操作，以及下一步由哪个系统 / 人承载。
交接不是礼貌性结尾，而是流程的一部分。每轮完成后都要把下一步说成可执行动作，例如“刷新 PR 看 Files changed”“等 CI 完成”“确认这个讨论项后我再搬目录”“无需操作，下一步由 reviewer / CI 承载”。不要只说“完成”。
常见错误
- 把最高优先级协作规则误解成团队工件层级，又把 PR body、topic design、project overview 当成规则正文。
- 把铁律混进质量闸门，导致“必须怎样协作”和“怎样证明做完”混在一起。
- “项目文档由消费仓库指定”之后只列抽象类别，不告诉当前仓库实际路径。
- Superpowers 一遇到疑问就问用户，没有先回到 workflow 查项目文档、topic、PR/git 历史和代码。
- 把输入判定、review 判定和决策协议拆成多套重复流程。
- 新建文件只是为了显得分类清楚，没有证明读者、生命周期、真相源、权限边界或维护节奏确实不同。
- 没有先确认 worktree 隔离，就在当前 shell 里编辑、格式化、生成文件、stage、commit、push 或回复 PR。