git-multi-agent

name	git-multi-agent
description	Worktree-first Git automation for every repository task, especially concurrent editing by multiple AI agents. MUST use isolated Git worktrees so each AI has a separate filesystem, index, and HEAD; never use branch switching in a shared checkout as isolation. Automatically provision session worktrees, commit owned changes, validate and merge through a temporary integration worktree, update the local default branch, and clean up. Only remote or cloud writes require fresh user confirmation.
argument-hint	要执行的 Git 任务，例如“为每个 AI 建立独立 worktree 并自动集成”
user-invocable	true
disable-model-invocation	false

多 AI Git 自动化

每次进入工作区或仓库任务时都加载本 Skill，不以用户是否提到 Git 为前提。并行隔离的基本单位是 worktree：每个 AI 会话拥有独立目录、索引和 HEAD，任何开发读写、测试和提交都只在自己的 worktree 中进行。分支只是 worktree 必需的内部提交引用，不得用“在共享目录里切换分支”代替隔离。

强制触发与收尾

• 每个工作区任务开始时都加载本 Skill；SessionStart Hook 在 Git 仓库中自动创建本会话 worktree，并注入其精确绝对路径。
• 加载本 Skill 表示用户已持续明确授权任务范围内的本地 worktree、内部引用、暂存、commit、本地集成和安全清理；不需要再次询问。该授权不适用于任何远端或云端写入。
• 只读分析、答疑或未产生文件变化的任务不修改 Git，但仍遵守本 Skill 的归属与远端安全规则。
• 首次仓库读写前确认当前操作路径就是 Hook 注入的会话 worktree。所有搜索、读取、编辑、生成、测试和 Git 命令都以该目录为根；原项目目录只作为默认分支的集成入口。
• 任务完成且验证通过后，在会话 worktree 内显式暂存 owned-paths 并创建本地 commit，再通过一次性集成 worktree 合入本地默认分支。
• 合并成功后自动清理本会话任务 worktree、集成 worktree及其内部引用，不把用户留在临时目录或 ai/... 引用上。
• 只有三种情况不自动提交：用户明确要求本次不要提交；没有本会话文件变化；验证失败或变更归属无法安全确定。此时保留现场并说明原因。
• 目标分支无法唯一确定、默认分支 worktree 不干净、发生冲突、组合验证失败或默认分支在验证期间前进时，不强行更新；保留本会话 worktree并报告或重建集成 worktree重试。
• commit 成功不代表任务完成。除非存在明确阻塞，否则发送最终答复前必须确认任务提交可从默认分支到达，且本会话 worktree 已清理。
• 不得把“是否需要本地提交”作为例行问题询问用户。真正无法自动判断的变更归属或冲突属于阻塞，可请求用户决定，但不能先猜测或破坏现有改动。

核心规则

1. worktree 是隔离边界。 每个 AI 会话必须使用不同的已注册 worktree；多个 AI 不得编辑同一个目录，即使它们声称负责不同文件。
2. 分支不是工作空间。 内部 ai/... 引用只承载 worktree 的提交历史；禁止在原项目目录中通过 switch/checkout 来轮换 AI 任务。
3. 只操作本会话目录。 只提交本会话 worktree 中由本会话产生的路径；始终显式暂存，禁止 git add .、git add -A 和 git commit -a。
4. 默认分支目录是集成通道。 不在其中开发；只在组合结果已于集成 worktree 验证后执行短暂的 ff-only 更新。
5. 不接管既有改动。 不 stash、不还原、不覆盖、不删除用户或其他 AI 的未提交内容和 worktree。
6. 提交前验证。 在任务 worktree 验证单项行为；在集成 worktree 再验证组合结果。
7. 本地操作自动，云端操作确认。 worktree、内部引用、commit、merge 和安全清理无需确认；任何 push、远端引用、PR/MR 或 release 写入必须逐次确认。
8. 保留会话归属。 沿用仓库 Git 身份，并用 commit trailer 记录 AI 会话；不修改全局身份配置。

操作分类

无需额外确认，但只能在用户请求所涵盖的仓库和任务内执行：

• 为每个 AI 会话创建、使用并清理独立 worktree
• 在本会话 worktree 内检查、暂存、提交和验证改动
• 查看状态、日志、diff、分支、worktree 和远端配置
• 创建一次性集成 worktree，合并并验证组合结果
• 将已验证的集成结果快进到本地默认分支
• 删除已安全集成且干净的本会话 worktree 和内部引用
• fetch 远端引用；优先用 fetch 加显式 merge/rebase，避免隐式 pull

提交信息规范

• 默认使用 Conventional Commits 结构：<type>: <subject>。
• type 必须使用英文小写前缀，例如：feat、fix、refactor、perf、docs、test、build、ci、chore、revert。
• subject 使用中文，简洁描述本次改动结果，不写英文长句。
• 若仓库已有更严格约定（如作用域、长度、Issue 关联），在不冲突前提下优先遵循仓库约定。
• 可选作用域时使用：<type>(<scope>): <中文 subject>，其中 scope 保持英文标识。

必须在执行前单独确认的云端写操作：

• git push，包括新分支、现有分支和标签
• git push --delete、删除远端标签或分支
• 任何 force push；默认禁用 --force，只有用户明确批准时才可使用 --force-with-lease
• 创建、更新、关闭或合并 PR/MR
• 创建 release 或通过托管平台 API/CLI 改写远端状态

确认只适用于展示过的精确远端、源引用、目标引用和命令。命令或提交发生变化后必须重新确认；“以后都可以”“帮我全自动”不能永久豁免云端确认。

标识约定

首次进入任务时生成并报告：

• agent-id：稳定的代理名，例如 copilot
• session-id：优先使用 SessionStart Hook 注入的 Git session token；Hook 不可用时回退为 <agent-id>-<YYYYMMDD-HHmmss>
• 项目分类目录：D:\Documents\git_worktrees\<repo>，其中 <repo> 取默认主 worktree 的目录名
• 任务 worktree：D:\Documents\git_worktrees\<repo>\<session-id>
• 任务内部引用：ai/<agent-id>/<session-id>
• 集成 worktree：D:\Documents\git_worktrees\<repo>\<session-id>-integrate
• 集成内部引用：ai/integrate/<session-id>

名称只使用小写 ASCII 字母、数字和连字符。只复用 Hook 明确分配给当前 session-id 的 worktree；上一会话或其他 AI 的 worktree 即使目录可见也不得使用。

每个 AI 提交追加 trailer：

AI-Agent: <agent-id>
AI-Session: <session-id>
AI-Branch: <branch-name>

优先使用 git commit --trailer 添加 trailer。若当前 Git 不支持该参数，再使用仓库兼容的提交消息方式；不要为了 trailer 修改全局 Git 配置。

工作流

1. 预检仓库

先运行并阅读：

git rev-parse --show-toplevel
git status --short --branch
git branch --show-current
git worktree list --porcelain
git remote -v
git symbolic-ref --quiet --short refs/remotes/origin/HEAD
git log -5 --pretty=format:"%h %s"

然后判断：

• 不是 Git 仓库：只有用户已要求初始化时才执行 git init，否则说明阻塞。
• HEAD detached：从当前 HEAD 创建本会话分支后再修改。
• 存在未提交改动：将其视为他人所有，不 stash、不重置、不纳入提交。
• 存在未合并状态、rebase、cherry-pick、revert 或 index lock：停止自动操作，先报告当前操作，不擅自继续或中止。
• 仓库没有首个提交：可在当前工作树内创建本会话分支并显式提交；多 worktree 隔离通常要等首个提交后再启用。
• 记录任务起始提交、起始分支和默认主分支，供完成后的安全回并与并发移动检查使用。
• 在创建任务分支前先按“自动回并默认主分支”的优先级确定本地目标分支；任务基线使用该目标分支 tip，不使用当前恰好检出的旧 AI/feature 分支 HEAD。

读取仓库内适用的贡献说明和 Git 约定。只检查与当前任务直接相关的文件，不把预检扩大成全仓审计。

2. 建立会话 worktree

在 Git 仓库中，每个会话都使用独立 worktree，不等待检测到第二个 AI。SessionStart Hook 默认执行等价操作：

git worktree add -b ai/<agent-id>/<session-id> "D:\Documents\git_worktrees\<repo>\<session-id>" <target-branch>

创建基线必须是任务开始时识别出的默认主分支 tip，不得从当前恰好打开的 feature/旧 AI 引用派生。创建后验证：

git -C "<session-worktree>" status --short --branch
git worktree list --porcelain

• 后续所有仓库搜索、读取、编辑、生成、测试和 Git 命令必须使用 <session-worktree> 的绝对路径或将终端 cwd 切到该目录。
• 禁止继续编辑原项目目录，也禁止编辑 git worktree list 中属于其他会话的路径。
• PreToolUse Hook 会拒绝写入本会话 worktree 之外的同仓库路径。
• 每个终端命令都显式锚定会话 worktree，例如先执行 Set-Location -LiteralPath '<session-worktree>'；不要依赖终端上一条命令遗留的 cwd。
• 若工具无法对该绝对路径工作，报告阻塞并停止编辑；不得退回共享目录。

非 Git 目录不创建 worktree，也不自动执行 Git 操作。

3. 记录本会话路径

在工作过程中维护明确的 owned-paths 清单：只加入本会话 worktree 内由本会话实际创建、修改、移动或删除的路径。

以下情况不能自动认领：

• 会话 worktree 创建前已存在的来源不明内容
• 会话 worktree 外部的任何路径
• 工具未曾编辑但随后出现在 status 中的路径
• 生成器顺带改动且尚未检查内容的路径

格式化器或生成器修改多个文件后，逐个检查 diff，只有确属本任务且内容合理的文件才能加入清单。出现来源不明的改动时保留现场并报告，不做清理。

4. 选择提交时机

只要任务产生 owned-paths 且验证通过，就必须在最终答复前自动创建本地提交，不等待用户提出 Git 要求，也不请求本地提交确认。以下时机还可创建中间阶段提交：

• 一个可独立回滚的逻辑阶段完成，下一阶段会明显扩大改动范围
• 执行本地 rebase、merge、cherry-pick 或分支清理前需要稳定检查点
• 用户明确要求 checkpoint 或 commit

不要为每次文件保存制造提交，也不要把互不相关的改动塞入同一提交。若任务未完成、验证失败或归属不明，保留本地改动并报告，不创建伪装成完成状态的提交。用户明确要求本次不要提交时服从该要求。

5. 提交前检查

按顺序执行：

1. 运行任务范围内最小且有效的测试、lint、类型检查或构建。
2. 用 git diff --check -- <owned-paths> 检查空白错误。
3. 查看 git diff --stat -- <owned-paths> 和完整 git diff -- <owned-paths>。
4. 检查 git status --short，识别 owned-paths 之外的变化。
5. 检查 staged 区；若已有非本会话 staged 内容，停止，不改动其 staged 状态。
6. 检查 owned-paths 中是否含密钥、令牌、.env、凭据、私钥、大型二进制或意外生成物。

测试命令可能产生新的文件。提交前重新检查 status，不自动把测试产物纳入提交。

6. 显式暂存并提交

仅暂存 owned-paths：

git add -- <owned-path-1> <owned-path-2>
git diff --cached --name-status
git diff --cached

暂存后必须确认 cached 路径集合是 owned-paths 的子集。发现额外路径时停止提交并报告，不通过 reset/restore 擅自改写他人的暂存区。

提交主题遵循仓库最近历史和贡献规范，描述一个具体结果。示例：

git commit -m "feat: 新增多 AI 并行分支隔离流程" --trailer "AI-Agent: <agent-id>" --trailer "AI-Session: <session-id>" --trailer "AI-Branch: <branch-name>"

提交后立即验证：

git show --stat --oneline --decorate HEAD
git status --short --branch

报告 commit hash、主题、分支、worktree、包含的路径、验证命令与结果，以及尚未提交且不属于本会话的改动。

7. 通过集成 worktree 回并

任务 worktree 完成提交后，使用一次性集成 worktree 构造组合结果。不要直接在原项目目录中解决冲突或运行合并后的修改。

这是任务的强制完成阶段，不是可选建议。除非回并条件明确阻塞，否则不得在创建 commit 后直接结束，也不得把“请用户稍后自行合并”作为正常完成结果。

按以下优先级确定目标分支：

1. 用户为本任务明确指定的本地目标分支。
2. 默认远端 HEAD 指向的本地分支，例如将 origin/main 解析为 main。
3. 仓库中唯一存在的常见默认分支：main、master 或 trunk。

无法唯一确定时停止回并，不猜测目标。任务分支本身就是目标分支，或任务提交已经可从目标分支到达时，不重复合并。

创建集成 worktree 前确认任务 worktree已提交、单项验证通过且干净。记录当前目标 tip 为 integration-base，然后执行：

git worktree add -b ai/integrate/<session-id> "D:\Documents\git_worktrees\<repo>\<session-id>-integrate" <target-branch>
git -C "<integration-worktree>" merge --no-ff --no-commit ai/<agent-id>/<session-id>

若 Git 报 Already up to date，无需创建 merge commit。否则在集成 worktree 解决仅属于本任务的明确冲突，并运行覆盖组合结果的测试、lint、类型检查或构建；验证通过后创建 chore: 合并本次 AI 任务到默认分支，并追加本会话 trailer。随后：

1. 确认默认分支仍等于 integration-base，且承载默认分支的 worktree 干净、无进行中的 Git 操作。
2. 在默认分支 worktree执行 git merge --ff-only ai/integrate/<session-id>。该步骤只发布已经验证的提交，不在此目录开发或解冲突。
3. 若默认分支已被其他 AI 推进，删除并重建本会话集成 worktree，从新的目标 tip 重新合并和验证；不得跳过组合验证。
4. 验证 git merge-base --is-ancestor ai/<agent-id>/<session-id> <default-branch> 成功，才算回并完成。

并行 AI 可以同时在各自任务 worktree 开发，也可以在各自集成 worktree 预合并；默认分支的最终快进天然串行。先完成的会话推进默认分支后，其他会话必须基于新 tip 重建集成结果。

Stop Hook 会检查当前会话 worktree 对应提交是否已从默认分支可达。未回并或仍有未提交内容时阻止一次结束；已回并且 worktree 干净时，Hook 自动移除本会话任务/集成 worktree和内部引用。

8. 集成其他 AI 分支

每个 AI worktree按上一节独立集成；只有用户明确要求批量收尾时，才接管其他会话留下的 worktree。不得在某个 AI 的任务 worktree 中直接合并另一个 AI 的未完成内容。

1. 用 git worktree list --porcelain 列出候选会话目录和内部引用。
2. 只选择工作树干净、提交完整、AI-Session trailer 可核对的会话。
3. 每个会话仍单独创建集成 worktree，并按顺序合入最新默认分支。
4. 每次默认分支推进后，后续会话都从新 tip 构造和验证，不复用过期集成结果。
5. 冲突或验证失败时保留对应会话 worktree，不影响其他 AI 继续开发。

不要仅凭“最新提交”判断归属；使用分支名、worktree、owned-paths、commit hash 和 trailer 交叉确认。不要 squash 掉会话归属，除非用户明确要求压缩历史，并在新提交正文中保留来源 commit hash。

9. 云端写入确认门

准备执行远端写操作时，先展示：

远端：<remote-name> <url>
本地源：<source-ref> @ <commit-hash>
远端目标：<target-ref>
操作：<完整命令或等价 API 动作>
风险：<新建 / 更新 / 删除 / force-with-lease / 合并 PR>
验证：<已运行的检查及结果>

然后提出可明确回答“确认执行”或“取消”的问题。未得到明确肯定答复前不得执行；沉默、模糊同意、先前对其他命令的同意都不算确认。

推送前再次确认本地 HEAD 未变化。若 hash、remote、目标 ref 或命令变化，原确认失效。禁止默认使用 --all、--mirror、--tags 或通配 refspec。凭据、令牌和密码只能由用户直接输入安全提示，不通过聊天收集。

10. 安全清理

仅清理本会话创建的资源。删除 worktree 前确认：

• 工作树干净
• 所有本会话提交均已从默认分支可达
• 本会话提交已可从默认主分支或用户指定目标分支到达
• 没有 rebase、merge、cherry-pick 或测试进程占用

优先删除集成 worktree，再删除任务 worktree，最后用 git branch -d 删除对应内部引用。不得使用 --force 或 -D，不得删除其他会话的 worktree。Hook 可在 Stop 阶段自动清理已回并且干净的本会话资源；清理失败时报告路径并保留现场。远端清理仍需新的云端写入确认。

冲突与异常分支

• 原项目目录已有脏文件： 不触碰；任务开发仍可在独立 worktree进行，但最终更新默认分支前必须等待该目录恢复干净。
• 会话 worktree创建失败： 不在共享目录降级编辑；报告路径、引用和 Git 错误。
• 写入路径不在本会话 worktree： PreToolUse Hook 拒绝操作；改用 Hook 注入的绝对路径。
• 别的 AI 改了本会话 worktree： 来源无法证明时停止；保留 worktree并报告。
• 提交钩子修改文件或拒绝提交： 检查钩子输出与新 diff，验证后重新显式暂存；不使用 --no-verify 绕过。
• 测试失败： 保留改动和输出，不创建完成提交；只修复当前任务引起的失败。
• 集成冲突或组合验证失败： 只处理/中止本会话集成 worktree中的 merge；默认分支不受影响，任务 worktree保留。
• 默认分支在验证期间前进： 丢弃本会话过期的集成 worktree，基于新 tip 重建并重新验证。
• 默认分支 worktree不干净： 不 stash、不覆盖、不强行切换；保留已验证任务 worktree并报告阻塞路径。
• 需要 force push： 优先改用新分支；确实必要时说明原因和 lease 保护，并为该精确命令单独确认。
• 用户要求提交所有改动： 先逐项展示来源；只有用户明确把现有改动转交给本会话后，才能加入 owned-paths。
• 用户要求自动推送： 可以自动准备和验证，但每一次实际云端写入仍必须停在确认门。

完成标准

任务结束前必须能回答：

• 本会话 ID、任务 worktree、集成 worktree和内部引用是什么
• 哪些路径由本会话拥有，提交中是否只包含这些路径
• 创建了哪些 commit，hash 和主题是什么
• 本会话提交是否已通过集成 worktree进入本地默认主分支
• 运行了哪些验证，结果如何
• 还存在哪些未提交或来源不明的改动
• 是否执行过云端写入，以及对应的用户确认是哪一次
• 集成或清理是否完成，保留分支在哪里

最终交接使用简洁格式：

会话：<session-id>
任务 worktree：<path>（内部引用：<ref>）
集成 worktree：<path> / 已清理
提交：<hash> <subject>
回并：<task-ref> -> <integration-ref> -> <default-branch> @ <hash> / 未回并及原因
改动：<owned paths 概要>
验证：<command> -> <result>
遗留：<未提交/冲突/来源不明内容，或“无”>
远端：未写入 / 已按本次确认推送到 <remote/ref>