在草擬、修訂或回覆之前,請先閱讀寫作指南與集合慣例;該集合的簽出內容位於 shared/ 目錄下。
影片迭代協調
技能類型:嚴格 — 保留工單範圍、中斷工作、相依性血緣與證據關卡。一般失敗進入復原流程;不會終止實作嘗試。
目的與所有權
將 Jira 史詩、GitHub Issue 佇列或明確的需求清單(可選擇縮小至特定工單)轉換為持久的交付佇列。每個被選取的工單或修正項目都獲得專屬的實作代理程式與工作目錄。在派發之前,協調器將選取僅後端、僅前端或跨層的範圍,並提供完整的執行合約。每個實作代理程式都使用 video-iterative-development 來執行該合約並產生其經過驗證的提交。
協調器委派執行,而非決策權。它專屬擁有原始碼解釋、工單範圍、產品行為、儲存庫與層級選擇、相依性順序、分支與 PR 拓撲、偏差、阻礙處理、生命週期狀態、最終驗收與工單回報。它會調用而非重述其伴隨工具:
resume-and-reconcile.md擁有中斷工作探索與來源變更偵測。extract-figma-visuals擁有 Figma 階層選擇、匯出與套件驗證。feature-conformance擁有原始碼權威、決策記錄、可追溯性與交付宣稱驗證。video-iterative-development擁有指派的實作、復原機制、證據與提交。它回傳觀察結果與結構化的決策請求;不會變更執行合約或指派交付狀態。agent-implementation-reviewer擁有獨立的唯讀計畫對差異報告。協調器在應用功能合約轉接器時,不會變更該共享審查者。- 工程指引審查 檢查最終差異是否符合適用的儲存庫慣例。它記錄具體後果與合理的例外,而不將偏好轉變為新的工單需求。
決策權
重大決策是指任何改變原始碼解釋、範圍、產品或設計行為、參與的儲存庫或層級、相依性順序、分支或 PR 拓撲、所需證據、已核准的偏差、阻礙處理或最終工單狀態的選擇。協調器在派發之前或回應工作者請求時,做出並記錄每一項重大決策。此技能授權的自動原始碼解析也屬於協調器的決策。
實作代理程式只能選擇可逆的、符合儲存庫慣例的機制,且不變更執行合約,例如:在地程式碼組織、指令順序、確定性的選擇器細節,或如何診斷並重試範圍內的失敗。當指示不完整、衝突或需要重大選擇時,工作者不得猜測、擴大範圍、聯絡提示者或自行指派終端狀態。它應回傳結構化的 decision_request 給協調器,並繼續所有未受影響的指派工作。
輸入
- 一個 Jira 史詩金鑰/連結、GitHub Issue 佇列或明確的優先級需求清單。從請求中解析選取的佇列;無需強制使用 Jira 來執行基於 GitHub 或無追蹤器的執行。
- 對於修正模式,一個唯讀的發現事項 Markdown 文件。
- 當無法從工作區發現儲存庫根目錄時,提供之。
- 一個選用的唯讀設計文件或連結。架構是文件的子類型,而非獨立的輸入類別。
- 針對適用的 UI 工單,選用的唯讀 Figma 根框架連結,其中包含
node-id。 - 一個可選的請求,要求透過 Slack 協調此次執行,包括一個明確命名的頻道或明確要求直接訊息執行。若無指定目的地,
slack-coordinator將使用儲存庫預設值。 - 任何明確的外部權威或截止日期。
無需請求功能 ID、合約檔案、核准旗標、Figma 修訂版或層級分類。缺少選用的 Figma 或設計文件背景資訊不構成阻礙。
當要求 Slack 協調時,直接將 slack-coordinator 作為協調的一部分調用;不要產生獨立的 Slack 代理程式或面板。為協調使用一個 Slack 執行緒。協調器是唯一的 Slack 聯絡人,也是其 run_id 的唯一消費者;實作代理程式向協調器報告,從不自行呼叫協調器或消費擁有者輸入。
在唯讀取入解析史詩與選取的工單後,檢查現有的記錄以尋找活躍的協調器 run_id。若存在則恢復該執行。否則,確認可執行檔可用,並在第一次狀態變更動作之前呼叫 run start,將史詩作為工作、要求的結果作為目標、選取的工單作為範圍。僅針對目前指示中明確命名的單一頻道傳遞 --channel;僅當提示者明確要求直接訊息執行時才傳遞 --dm;否則讓協調器使用儲存庫預設值。在記錄檔中記錄回傳的 run_id、頻道、執行緒時間戳記與永久連結,並在其允許的第一次寫入時進行。不要僅因工單開始、恢復、重試或更換擁有者而啟動第二次協調器執行。
在每個協調器狀態變更動作之前,以及在每個授權實作工作的派發或後續行動之前,立即執行 run check。退出碼 0 允許該動作。退出碼 10 時,使用 run resolve 套用、回答或拒絕擁有者輸入,然後再次檢查。退出碼 11 時,暫停、短暫等待後重試,並報告原因;在協調不可用時,絕不變更狀態、派發工作或轉向其他 Slack 路徑。退出碼 12 是操作者的明確中斷決策,允許執行在無需進一步 Slack 呼叫的情況下繼續。
使用 run event 記錄協調階段變更、工單生命週期變更以及阻礙開始或清除;守護行程擁有靜默間隔的狀態重新發布。當協調達到其最終的已完成、失敗或已取消結果時,呼叫 run finish 一次。遵循獨立技能的指令、頻道選擇、訊息與失敗合約,而不是在此重述或削弱它們。當未要求 Slack 協調時,不要啟動執行,也不要加入 Slack 關卡。
選擇執行模式
使用交付模式(不含發現事項):對於 Jira,請閱讀 Jira 交付工作流程;對於 GitHub 與無追蹤器佇列,請閱讀交付模式。當選取的佇列包含發現事項文件時,使用修正模式。請閱讀修正工作流程。
在任何模式下,在建立工作目錄之前,先執行恢復與原始碼協調。對於 Jira,狀態具有決定性:In Progress 與 Code Review 屬於 resume_required,必須採用現有工作,而不是從基礎開始。
工單範圍與設計權威
選取工單的需求與驗收標準定義了工作的邊界。史詩提供成員資格、順序與相依性背景;永遠不假設它包含 Figma 或設計文件中呈現的所有行為。僅對應有助於釐清選取工單的 Figma 節點與文件章節。未對應的設計內容是背景資訊,而非遺失、延遲或超出範圍的工作。
在工單邊界內:
- 已對應的 Figma 是視覺與互動行為的預設權威,包括模糊或衝突的工單細節;
- 已對應的 Figma 會自動覆蓋衝突的設計文件;
- 若無適用的 Figma,已對應的設計文件可解析模糊的工單細節;
- 儲存庫與 API 慣例解析其餘的實作細節。
在 .agent-evidence/orchestration/<run-id>/decision-log.md 中記錄每個自動解析。僅對那些替代方案會實質改變產品範圍或使用者行為的罕見未解決選擇,暫停受影響的工單。來自權威來源的明確核准偏離是 approved_deviation;一般的實作決策與 Figma 解析不是偏離。
建立一個執行層級的設計文件清單,位於 .agent-evidence/orchestration/<run-id>/design-documents/manifest.json。它記錄來源識別碼、整個文件的 SHA-256,以及僅對應到選取工單的章節的穩定 ID、標題與 SHA-256 值。feature-conformance 會參考此清單;它不會建立另一個。
對於每個提供的 UI 根節點,在派發前調用 extract-figma-visuals,並將其驗證過的套件傳遞給適用的工作者。在存取檢查與實質重試後仍無法讀取的已提供 Jira、Figma 或設計文件來源,僅會阻擋受影響的工單。絕不替換過時的內容、重新建立的原型或猜測的需求。
建立執行狀態
在派發之前:
- 為選取的史詩工作建立或繼續一個目標。只要任何工單仍有可恢復或獨立的工作,就保持其活躍。
- 檢查儲存庫指引、目前狀態、工作目錄、工單分支、開啟的 PR、程式碼生成規則以及文件化的驗證指令。對於現有的 PR,識別其來源工作目錄以及該工作目錄不可用的原因。對於跨層工作,將參與儲存庫的文件化複合啟動配置解析為完整的程序拓撲:每個指令、參數、工作目錄、環境來源、相依性順序、連接埠、健康/功能探測、遷移/資料夾步驟、客戶端生成步驟、執行期定義以及 Android Patrol 指令。將選取的工作目錄、驗證指令以及解析後的拓撲傳遞給實作代理程式。儲存庫文件化的 IDE 複合配置是拓撲定義,而不是調用 IDE 的指令。
- 透過選取追蹤器的已驗證介面解析工單與相依性,然後執行恢復/原始碼協調。Jira 使用 Jira MCP;基於 GitHub 或明確清單的執行則保留自己的範圍與狀態權威。
- 提取並驗證適用的 Figma 套件。在提供時建立單一的設計文件清單。
- 在預檢模式下調用
feature-conformance。修復代理程式產生的綱要或對應錯誤並重新執行;不要將其呈現為工單阻礙。 - 解析明確的工作目錄或已設定的工作根目錄。使用如下所述的不可變索引收據。建立一個被忽略的記錄檔、
decision-log.md以及可重新建立的resume-state.json與source-index.json快取。當快取遺失或過期時,Jira、Git、PR、當前清單與當前原始碼讀取仍保持權威。 - 建立相依性表格,並記錄擁有者、選取的範圍與未變更的層級、採用或新的寫入表面、PR 目標、原始碼對應、合約行、協調器決策、證據關卡、規範執行期租賃狀態、復原狀態與最終狀態。當啟用 Slack 協調時,也在執行層級記錄其
run_id、頻道、執行緒時間戳記、永久連結與當前協調狀態。
使用規範的 snake_case 機器狀態:ready、waiting、resume_required、resume_needs_lineage、resume_source_missing、active、source_update_detected、reconciliation_active、correction_active、needs_product_decision、locally_verified、submitted、submitted_verified 與 blocked。
保存索引記錄與證明
index.json 是任務工件的權威來源。將合約收據記錄為 feature-contract (design.contract)、符合性記錄為 feature-conformance (review.conformance)、提議的阻礙記錄為 delivery-disposition (delivery.disposition)、以及驗證過的提交收據記錄為 submission-closure (delivery.closure)。為每個持久修訂分配一個新的不可變迭代,綁定其確切的 JSON 快照路徑/雜湊值、工單、來源頭部與相關的合約/審查記錄。在使用前選取並使用摘要驗證當前記錄;無效的索引不會回退到掃描。使用相鄰的可選任務工件輔助工具或確切的手動慣例。僅有真正未索引的遺留任務使用編號記錄。
執行記錄檔、恢復清單與來源索引是可重新建立的營運快取,不能取代不可變的驗收或審查收據。原始視覺套件與擷取仍然是排除在外的在地證據。GitHub PR 主體、獨立的證據評論、直接託管的擷取以及當前頭部的回讀仍然是發布權威;絕不削弱已安裝的發布掛鉤或基線/當前證明要求。
隔離與堆疊工單工作
賦予每個活躍的實作代理程式在其修改的每個儲存庫中一個專屬的工作目錄與分支。絕不共享可變的簽出或丟棄中斷的變更。
- 對於
In Progress與Code Review工單,採用選取的來源,包括屬於該工單的髒工作目錄。 - 僅為沒有採用工作的合格工單建立新工作。
- 從其先決條件的已驗證提交遠端頭部建立相依分支。
- 將相依 PR 的目標設為該先決條件分支,使 PR 僅包含其工單的差異。記錄堆疊的血緣。
- 重複使用現有的修正 PR 來源分支與 PR。僅在其舊工作目錄不可用時,重新建立該確切分支的簽出。
- 絕不為了簡化設定而重設、清理、暫存、強制推送或重寫中斷的工作。
- 為重疊的寫入表面排序,或建立專用的整合工單分支。
已提交的先決條件分支足以供下游實作、在地驗證與提交使用