chrislacey89/execute

執行

執行一個完整的工作單元：規劃它、建構它、驗證實際成果、提交它。

調用位置

這是一個主要管線技能，用於 /prd-to-issues 已產出具體切片之後，或當使用者已經有明確範圍的實作任務時。

當工作已準備好建構、驗證並提交時，使用 /execute。

當任務切片在實作期間仍需要使用者主動判斷、監督或接受決策時，使用 HITL /execute。僅當下一個切片已在 GitHub 中穩定、無阻礙且可從其 Issue、邊界地圖及任何連結的研究產出（歸檔檔案或 spike Issue）或 docs/solutions/ 上下文被理解時，才使用 AFK /execute。

對於一個不持有任何上述資訊的讀者可理解——這就是 AFK 迭代的意義。/prd-to-issues §4 的上下文完整性檢查是該條件的閘門：它要求每個 AFK 切片在 Issue 提交前都攜帶一個 ### Context 區塊，或明確的空宣告。一個標記為 AFK 但沒有此區塊的切片從未被檢查是否滿足此條件，僅被假定滿足。將其視為以 HITL 執行該切片，或將其送回 /prd-to-issues 的理由，而非可輕輕放過的形式。

請參閱下方步驟 0：先決條件以了解強制的 Ralph 自動偵測與 TDD 標記閘門。

當問題或形狀仍未解決時，請勿用它來取代 /shape、/research 或 /write-a-prd。一旦實作完成並準備好進行審查，請勿將其用作 /pre-merge 的替代品。

工作流程

0. 先決條件

分支隔離閘門。 在進行任何實作工作之前，請確保您在為此特定任務建立的乾淨分支上工作——而非先前工作遺留的功能分支。

已提供隔離——原地待命（先檢查此項，再進行編號規則）。 某些環境在 /execute 運行之前，會為工作階段提供一個專用的隔離工作目錄樹與分支——Conductor 工作區、GitHub Codespaces、devcontainer 及類似主機各自提供「一個工作區 = 一個分支，從基底自動分支」，且設置腳本已運行。在這種情況下，管線不擁有供應權：在此處建立工作目錄樹會嵌套在主機的工作目錄樹內，且主機的分支（以工作區命名，而非任務）並非「陳舊」。讀取環境的信號並將工作目錄樹的管理權讓給已擁有它的人（Norman——讀取世界中的符號，而不是帶著管線總是負責供應的假設；Meadows——每個庫存一個行動者，因此管線延遲而非增加競爭的管理者）。

從 .claude/settings.json 中的 worktree.provisioning 解析供應模式——"host" | "pipeline" | "auto"，當鍵值不存在時預設為 "auto"（比照現有的 research.storage 先例）：

• host——隔離由主機擁有。無條件原地待命。
• pipeline——管線負責供應。跳過此待命步驟並運行下方的編號閘門。
• auto（預設）——如果任一信號觸發則原地待命：
  • 主機環境變數描述了此目錄樹——下方的區塊會印出 host_owned=yes。這是最便宜的主要判別器：管線唯一的偵測機制是 Bash，而這些變數在代理程式的 shell 中是可見的。僅有存在性是不夠的：CONDUCTOR_WORKSPACE_PATH 會被在 Conductor 下啟動的任何 shell 繼承，且可能命名不同儲存庫的工作區，因此僅在它包含目前頂層目錄時才算數。（不要透過 cwd 中的 .conductor 目錄來偵測——Conductor 將其保存在 $CONDUCTOR_ROOT_PATH 下，而非工作區。）
  • 目前工作目錄樹並非儲存庫的主要工作目錄樹——git rev-parse --show-toplevel 與 git worktree list --porcelain 中的第一個路徑不同。

# host-signal: 主機環境變數是否描述了此樹，而不僅僅是此 shell？
host_owned=no
top=$(cd "$(git rev-parse --show-toplevel)" && pwd -P)
if [ -n "${CONDUCTOR_WORKSPACE_PATH:-}" ]; then
  ws=$(cd "$CONDUCTOR_WORKSPACE_PATH" 2>/dev/null && pwd -P) || ws=
  if [ -n "$ws" ]; then
    case "$top/" in "$ws"/*) host_owned=yes ;; esac
  fi
fi
if [ -n "${CODESPACES:-}" ] || [ -n "${REMOTE_CONTAINERS:-}" ]; then host_owned=yes; fi
echo "host_owned=$host_owned"

CODESPACES 與 REMOTE_CONTAINERS 不攜帶可供比較的路徑，而是根據存在與否讀取；它們是容器作用域的，因此看到它們的 shell 就在描述其儲存庫的容器內部。相同區塊也出現在 /closeout、/lfg 與 /init-pipeline 中，位元組完全相同，並由 pack 自身儲存庫中的 scripts/test-host-signal-containment.sh 鎖定。

當原地待命時：跳過工作目錄樹建立與 EnterWorktree，並在目前分支上就地工作。 下方的編號規則已滿足——特別是規則 3 不適用（主機供應的分支既非基底也非任務命名，但它並非陳舊；不要嵌套工作目錄樹，也不要停止）。主機已預先播種了 git-ignore 的配置與依賴項，因此「工作目錄樹設置檢查清單」大部分僅供參考——如果命令失敗則抽查 .env.local/依賴項，但不要重新供應。其 git-hooks 項目是例外情況，仍適用。 主機供應的是追蹤的檔案加上依賴項；git hooks 位於 .git/hooks，這是每個工作目錄樹獨立的且未追蹤，因此主機供應的工作區通常沒有 hooks。即使原地待命時也要檢查該項目。繼續進行 Issue 形狀閘門。

此待命設定刻意與 /closeout 的拆卸檢查不對稱。流入方向只需回答 「我是否已經隔離？」——通用偵測（頂層 ≠ 主要）與環境變數提示皆能解決此問題。流出方向的問題——「誰負責拆卸？」——則更嚴格，不能僅依賴通用啟發式，因為管線建立的工作目錄樹也滿足頂層 ≠ 主要；/closeout 僅根據顯式設定或主機環境變數來判斷。

1. 檢查目前分支：git branch --show-current
2. 如果目前分支是基底分支（例如 main、prod、master），為此任務建立一個新的功能分支。
3. 如果目前分支是不同的功能分支（非基底分支，也非以此任務命名的分支），則您處於先前工作的陳舊分支上。不要在此處提交新的工作。例外： 如果目前分支是一個以此任務的 Consumes from #N 宣告命名的同層切片分支，則您是有意要從它進行分支以進行堆疊 PR 切片——請繼續。例外（主機供應）： 如果上方的待命檢查已觸發，則此分支是主機的隔離工作區分支——它並非陳舊；就地工作。

要建立隔離分支，請使用以下方法之一（按偏好順序）：

• Worktrunk（如果 wt 可用）：wt switch --create <branch-name>——從適當的基底建立一個新的工作目錄樹 + 分支並切換過去，提供完整的檔案系統隔離。請參閱 /worktrunk 技能以取得指引。
• 純 Git：git checkout <base> && git checkout -b <branch-name>——在目前工作目錄中，從適當的基底建立一個新分支。

適當的基底在預設情況下是儲存庫自身的基底分支——即 bash "$SC" base-ref --name 列印的內容，其中 SC 設為此技能的 references/sidecar.sh。不要假設是 main。對於一個具有未合併的 Consumes from #N 依賴項的切片，且該依賴項產生了此切片匯入的符號，則改從該同層切片的分支進行分支，以便堆疊 PR 可以鎖定同層的 PR（Hammant 基於主幹的開發 第 13 章：每個故事多個 PR；同層的 PR 仍必須在 2 天內合併到儲存庫的基底分支）。

從任務衍生分支名稱：例如 issue-5-landing-page、landing-page 或 Issue 標題縮寫。不要重複使用先前工作的分支名稱。

以工作階段進入工作目錄樹（當您建立了工作目錄樹時）。 建立工作目錄樹不等同於工作階段在其中運行——wt switch --create 在每個命令後會將 shell 的 cwd 重置回專案根目錄，因此沒有進一步的步驟，工作階段會停留在原始簽出位置，而報告的 cwd 會對實際工作地點給出錯誤資訊。建立工作目錄樹後，使用 harness EnterWorktree 工具進入它，以便工作階段的實際工作目錄確實是該工作目錄樹：

• 調用 EnterWorktree { path: <absolute-worktree-path> }。此路徑必須已存在於此儲存庫的 git worktree list 中（它會存在，因為您剛剛建立了它）。這會持久地將工作階段切換到工作目錄樹中。
• 確切地將建立步驟保持如上——wt switch --create / git worktree add 會運行 worktrunk 的 pre-start hooks，這些 hooks 會播種 .env.local 與依賴項。EnterWorktree 僅切換 cwd；它不會運行這些 hooks。先建立（以播種環境/依賴項），然後進入。
• 這將知識置於世界中，而非腦中：cwd 真實地告訴您編輯與提交落在何處（觀察的操作者可看到它），且沒有每個命令都要加上 cd 前綴的遺忘風險——消除了未加前綴的命令寫入錯誤目錄樹的疏失類型。
• 純 Git 選項（git checkout -b，無工作目錄樹）在目前的簽出中建立分支——沒有需要進入的工作目錄樹，因此跳過 EnterWorktree 並就地工作。

AFK / 無頭模式備援。 如果無法使用 EnterWorktree（無頭運行、AFK Ralph、cron），則回退到 cwd-前綴紀律：每個 Bash 命令後 shell cwd 會重置為專案根目錄，因此在此工作階段中將每個 Bash 調用前綴加上 cd <absolute-worktree-path> &&。僅在 harness 工具確實不可用時使用此方法——這是舊的解決方案，為沒有原生機制的環境保留。

此工作目錄樹的拆卸由管線尾端的 /closeout 負責——在 PR 合併後，/closeout 將 shell 重新錨定到基底簽出、移除工作目錄樹並清除已合併的分支。/execute 是工作目錄樹生命週期的流入端；/closeout 是流出端。下方的步驟 6 清理僅移除 .tdd-* 標記——它刻意不移除工作目錄樹。

建立工作目錄樹後，請進行設置。 一個新的工作目錄樹會繼承追蹤的檔案，但不會繼承 git-ignore 的檔案（.env.local、每個工作目錄樹的依賴項、建置快取）。有兩種路徑：

首選——透過 worktrunk hooks 一次性配置（專案中的 .config/wt.toml）：

[pre-start]
copy = "wt step copy-ignored"
install = "pnpm install"

pre-start hooks 是阻塞式的——工作目錄樹在它們完成之前不會被報告為就緒。對兩者都使用 pre-start（而非 post-start），因為 post-start 在背景執行，而後續需要 .env.local 或 node_modules 的命令會與 hook 競爭。完整配方請參閱 /worktrunk。每個專案僅需一次。

備援——純 git worktree add 的手動設置（無 worktrunk）：

• cp <source-repo>/.env.local <worktree>/.env.local（以及專案使用的任何其他 git-ignore 配置）。
• 從工作目錄樹運行專案的安裝命令（pnpm install、npm ci、pip install -r requirements.txt 等）。

工作目錄樹設置檢查清單（務必確認——執行每個步驟，然後在繼續前驗證）。 無論工作目錄樹如何建立都適用：

• Git-ignore 的配置已複製——.env.local（以及任何其他 .env.*、*.local 或專案特定的已忽略配置）存在於工作目錄樹中
• 依賴項已安裝——安裝命令（pnpm install、npm ci 等）在工作目錄樹中無錯誤執行
• 工作階段位於工作目錄樹內部——pwd 報告工作目錄樹路徑，因為您已透過 EnterWorktree { path } 進入它（非專案根目錄）。在 AFK/無頭備援情況下，此項目改為意味著 cd <absolute-worktree-path> && 前綴正被應用於每個 Bash 調用
• $CLAUDE_PROJECT_DIR 作用域正確——如果專案在腳本中參考此環境變數，請驗證它解析為工作目錄樹路徑，而非主要儲存庫
• 本地 git hooks 已安裝且其管理器在 PATH 上——ls "$(git rev-parse --git-dir)/hooks/" | grep -v '\.sample$' 列出一些內容，且儲存庫宣告的管理器（lefthook、husky、pre-commit……）可解析。Hooks 位於 .git/hooks，這是每個工作目錄樹獨立且未追蹤的，因此一個新的工作目錄樹不會繼承任何 hooks——而故障在最糟糕的方向上是無聲的：每個提交都成功，且儲存庫在提交時保證的每項措施根本沒有運行。如果管理器缺失，請安裝它（lefthook install）或在步驟 6 的審查記錄中記錄本地閘門在此分支期間處於非活躍狀態，以便沒有人將綠色的本地運行解讀為合併閘門
• 分類標記不存在——.claude/.tdd-active、.claude/.tdd-skipped 與 .claude/.lfg-active 在工作目錄樹中不存在（全新狀態；步驟 3 會建立一個）
• 審查後鎖定標記不存在——.claude/.review-stamped 與 .claude/.fix-findings-active 不存在。兩者皆屬於前一個分支的審查：/pre-merge 階段 4 寫入第一個，/fix-findings 寫入第二個，而 /closeout 與 /fix-findings 分別在該分支結束時將其移除。洩漏的 .review-stamped 會在切片開始前拒絕所有實作寫入；洩漏的 .fix-findings-active 會為整個切片保持鎖定開啟，這是最糟糕的無聲方向。刪除您找到的任何一個——您處於一個尚未經過任何審查的分支開頭，因此兩者都不可能描述此分支

Issue 形狀與阻礙閘門。 如果任務是一個 GitHub Issue，請在實作前確認它是一個可實作的切片：不是未分解的 PRD、未被阻擋、也未被其他人的開放 PR 正在關閉。一次 GraphQL 讀取即可回答所有三個問題，並由區塊決定——不要憑肉眼判斷任何一個：

N=<n>
VERDICT_JQ='
def lines: split("\n")[];
[inputs][0] | if (.errors // []) | length > 0 then "unknown" else
.data.repository.issue as $i
| if $i == null or $i.number != $n or (($i.title // "") == "")
     or ($i.bo

…

[為翻譯而截斷]