不同 agent 不要搶同一棵樹

並行 agent 的難題

s09-s11 讓你能同時啟多個 teammate，但有個暗坑：他們都在同一個工作目錄裡。 alice 改 auth.py、bob 同時也在改 auth.py——git 衝突、文件錯亂、測試互相污染。

s12 的解法是 git worktree：同一個倉庫，透過 git worktree add 可以在不同目錄裡 checkout 不同分支。每個 agent 拿到自己的 worktree，在自己的目錄裡工作，互不可見。

my-repo/                           # 主工作区（lead 用）
.worktrees/
  alice-auth/                      # alice 的隔离目录
    (branch: wt/alice-auth)
  bob-api/                         # bob 的隔离目录
    (branch: wt/bob-api)
  index.json                       # worktree 注册表
  events.jsonl                     # 生命周期事件日志

兩平面分工

s12 把系統明確地拆成兩個平面：

• 控制面 (control plane)：.tasks/ 裡的 JSON 檔案。 task 是「要做什麼」的抽象單位，有依賴、owner、status。
• 執行面 (execution plane)：.worktrees/ 裡的目錄。 worktree 是「在哪裡做」的實體容器，一個目錄 + 一個分支。

兩者透過 task.worktree 和 worktree.task_id 雙向綁定。

這種解耦讓你可以：重複使用 task 管理機制但換執行環境（例如不是 git worktree，而是 docker 容器）。 或換 task 機制但重複使用 worktree（例如不是 JSON 檔案而是資料庫）。

生命週期演示

下面要完整走一次：create task → create worktree → run commands → keep 或 remove。每步都有事件日誌記錄（events.jsonl），production 裡靠它做可觀測性。

keep vs remove

worktree 完成使命時有兩個終局：

• remove: git worktree remove --force，目錄刪除。分支一般也會被清理。相當於「這個探索不要了」。
• keep: 只在 .worktrees/index.json 裡標 status: kept，實體目錄保留。相當於「這個結果要了，等我合併」。

常見模式：subagent 跑一個實驗性 refactor → 跑出來效果好 → keep → 人類 review → 合入主分支 → 手工 remove。效果差？直接 remove 丟掉。