任務流程
每個狀態變更的規則在 references/estados.md 中：每個變更一張卡片，說明何時、由誰、需要何種授權、在儲存庫中執行什麼操作及其順序。本檔案說明如何使用它。
如何變更佇列
所有對佇列的寫入都必須透過 CLI 進行，絕不能手動操作：
python -I -X utf8 "$HOME/.claude/sf/cola.py" [--raiz 路徑] [--quien 擁有者|主要] [--via cli|panel] [--json] <命令> …
- 始終使用此命令，在 bash、zsh 和 PowerShell 中相同，在任何專案中也是如此；子代理也一樣。如果模型在會話開始時告知在此機器上 Python 以其他名稱啟動（在 macOS 上為
python3），則使用該名稱代替python，此處及所有 SF 的 Python 命令皆然（「Python 命令來自檢測到的直譯器」，236）；cola.py encargo命令也會告知這一點。切勿使用專案資料夾中的tools/cola.py（在 SF 中，plugins/sf/tools/cola.py會隨著活動分支而變更）：主導的是已載入外掛中的那個。載入時，面板會將其cola.py複製到~/.claude/sf/cola-<會話>.py並啟動它（「面板執行載入時建立的 cola.py 副本」，136）；~/.claude/sf/cola.py是一個啟動器，透過CLAUDE_CODE_SESSION_ID將命令傳遞給該副本：Claude 和面板使用相同的 ID（任務 252）。如果沒有該副本，則以狀態碼 2 退出並顯示訊息：/reload-plugins會重新建立它。 --raiz：專案資料夾，預設為當前資料夾。用於測試時，為佇列副本的路徑。--quien：預設為principal；當變更為擁有者的決定時（例如其關閉批准）使用propietario。- 如果執行變更則以 0 退出，如果未執行變更則以 1 退出（會說明原因且不進行任何操作），如果命令格式錯誤則以 2 退出；
choques（僅查詢）在有衝突時以 3 退出。cola.py <命令> -h提供每個命令的使用說明。
CLI 在每次寫入時執行的操作：鎖定佇列 (.sf/peticiones.lock)，在 .sf/copias/ 儲存一份副本（最多 50 份），在任務的 historial 中記錄變更，如果任務離開佇列，則將其連同歷史記錄移至 .sf/historial.jsonl。號碼不會重用。
CLI 不執行的規則
CLI 會套用每個變更的條件（起始狀態、分支、步驟、git）。在對話中如何使用（記錄時的選單、設為進行中、啟動和回收子代理、提議測試和關閉、建議合併和重新描述、文件任務、自由操作）在技能 sf:orquestacion 中定義。以下內容涉及佇列本身：
- 只有主要代理可以寫入佇列。 子代理不執行寫入命令；它會在其報告中說明，由主要代理執行。
- 所有請求都必須在進行中的任務下進行；沒有進行中的任務，就不開始工作。重新組織佇列（合併、分割、重新描述、新增步驟、變更類型）不需要進行中的任務（「每個任務一個子代理的編排」，149）。
- 擁有者的批准：
cerrar、a-observacion、reobservar和descartar需要批准；進行中的任務的en-cola也需要批准，但僅限於沒有工作時：如果其分支（或其子代理的輔助分支）上有自己的提交，則不會返回佇列；它會被關閉、設為觀察中或棄置（「有分支的進行中任務不會返回佇列」，170）。如果分支為空或已刪除，en-cola會將其刪除並回收空的子代理（275）。 - 建立時的類型 (
crear --tipo)：deliberar、documentar、diseñar、implementar、especificar、corregir 或 investigar；如果變更，則使用tipo 號碼 類型。 en-curso之前的衝突檢查：choques 號碼，如果還沒有分支，則附帶--archivos和從描述中推斷出的預期檔案。對於已經進行中的任務，在啟動子代理時不進行衝突檢查（「在將任務設為進行中時預見衝突」，130）。- 首次啟動前的分支 (
rama)，並發出警告。對於子代理，主要代理在不啟動的情況下建立分支，並在啟動子代理之前記錄它（rama --sin-activar、subagente）；子代理從該分支在輔助分支上工作，主要代理使用git merge --ff-only將其合併進來。子代理永遠不會在其工作目錄中啟動任務分支：這樣任務 T 和 C 可以與已設置的工作目錄配合使用（「每個任務一個子代理的編排」，149）。 - 子代理回收：由 CLI 執行，使用
subagente記錄的工作目錄和分支（--worktree接受相對專案的路徑），在所有使任務不再有子代理的命令中：cerrar、a-observacion、descartar、eliminar、a-propuesta、revertir、limpiar、reabrir，以及在被吸收的任務中，fusionar（僅當其輔助分支已在其保留的分支中時；保留的那個會保留其子代理）。非強制：具有未提交更改的工作目錄、具有未進入develop的提交的輔助分支，或合併時未整合的輔助分支，都會保留並發出警告。另一方面，descartar和limpiar會移除所有內容，包括具有未進入提交的輔助分支和具有未提交更改的工作目錄：棄置會棄置所有內容（189）。cerrar和a-observacion會在輔助分支具有未合併到任務分支的提交時拒絕操作，並說明如何合併它們。另一方面，reabrir會清理所有內容，包括未提交的更改且不發出警告：永遠不會重用舊的工作目錄。歷史記錄：recogida或recogida-con-avisos。主要代理只停止子代理並處理警告（「cola.py 在任務不再有子代理時回收子代理」，169）。 - 提交的簽名（「關閉提交的簽名是可設定的；未設定則無簽名行」，238）：
cerrar和a-observacion的 squash 提交、decision的提交以及 RELEASE 版本的提交會帶有.sf/proyecto.json中的coautor行（在 SF 本身中，該檔案不存在，則使用其自身的：Co-Authored-By: Claude Opus 5.5 <[email protected]>）。cerrar、a-observacion、decision和encargo接受--coautor "…"，這會覆蓋已設定的值。如果都沒有，則提交不帶共同作者行，並且 encargo 會這樣告訴子代理。 - 擁有者的決策：
decision "標題" --archivo 路徑|--texto 文字 [--numero NNN] [--coautor "Co-Authored-By: …"] [--push]不會觸碰佇列。它會給出develop分支上docs/decisiones/的下一個號碼和檔案名稱NNN-AAAA-MM-DD-titulo.md（使用--numero時，會重寫該檔案而不更改其名稱）；寫入檔案（文字，如果沒有以# 標題開頭則加上；如果已經有，則必須匹配），重新產生README.md，並在develop分支上建立提交「Decisión NNN: 標題」，即使有其他活動分支也不會更改它或觸碰其工作副本，如同a-propuesta（任務 273）。如果develop位於另一個工作目錄中，或者作為活動分支時docs/decisiones/有未提交的更改，則不會執行操作。當develop為活動分支時，也會重新產生README.html。--push會推送develop；它會顯示號碼和哈希值。如果沒有 git 或沒有develop，則只寫入檔案並發出警告（任務 283）。 - 合併和分割由擁有者執行（面板中的
/sf_fusionar、/sf_split）；主要代理使用fusionar僅限於合併兩個更新同一文件的任務（「每個要更新的文件一個任務」，142）。
按時間點的指令
| 時間點 | 指令 |
|---|---|
| 創建和啟動 | crear、choques、en-curso、en-cola、rama |
| 工作期間 | paso añadir、paso marcar、paso quitar、renombrar、tipo、subagente、informe |
| 測試 | listo、comprobado、probar |
| 關閉 | cerrar、a-observacion |
| 觀察中 | observando、seguir、cerrar、reobservar，如果出錯則使用 revertir |
| 撤銷 | descartar、limpiar、revertir、reabrir、eliminar、restaurar、a-propuesta |
| 合併和分割 | fusionar、split |
| 查詢和備份 | lista、ver、copias、recuperar |
| 佇列外 | decision |
所有關閉操作 (cerrar、a-observacion)，無論有無分支，也包括提案，都需要「關閉任務」步驟，並且除了「啟動分支以便進行測試」之外沒有其他待辦步驟。這兩個關閉步驟由 cola.py 在任務進入進行中狀態時添加（crear --en-curso、en-curso、reabrir、從佇列中的 probar、restaurar、fusionar），僅一次且始終在最後，並且不會被移除或更改文字；沒有這些步驟的進行中任務會在載入佇列時接收它們。新的工作步驟會使已完成的「啟動分支以便進行測試」再次變為待辦：需要重新測試。測試輔助步驟（paso añadir 號碼 "文字" --prueba）位於兩個關閉步驟之間，任何關閉操作都不會要求它們，會保持原樣，且添加它們不會使「啟動分支」返回待辦狀態（「測試輔助步驟：在啟動分支之後，非關閉必需」，184）。listo 僅儲存要測試的內容（「關閉步驟，從任務進入進行中開始」，174）。probar 將 develop 合併到分支中（合併；如果有衝突，則取消操作且不啟動；如果有未合併的 sub-號碼 提交，則既不整合也不啟動），啟動分支（如果尚未啟動），並將「啟動分支以便進行測試」標記為已完成，cerrar 也會這樣做：擁有者的批准就是關閉（172, 121）。步驟從 1 開始編號，如同 ver 中每個步驟的 n。離開佇列的任務會在 .sf/historial.jsonl 中包含其退出狀態（cerrada、eliminada、absorbida、descartada，以及從 revertir 刪除或保留待辦狀態（134）之前的 revertida），並且 ver 會顯示它。
還原需要指定目的地：revertir 號碼 --eliminar 會將任務從佇列中移除而不留痕跡，類似於 E；revertir 號碼 --pendiente 會將其返回待辦事項，在佇列中並重新開啟，沒有分支。它永遠不會以 R 狀態保留在已關閉項目中（「還原會刪除任務或將其保留為待辦」，134）。如果擁有者未指定，請詢問是哪一個。
當指令因 git 問題失敗時（squash 或還原中的衝突、未提交的更改、分支位於其他工作目錄中），CLI 會取消操作並說明原因；主要代理解決問題後重複指令。推送失敗不會阻止關閉：它會留在歷史記錄中（push-fallido），並手動重複推送。