タスクフロー
各状態変更のルールは references/estados.md にあります。カードごとに変更内容、タイミング、実行主体、必要な承認、リポジトリへの影響、順序が定義されています。このファイルではその使用方法を説明します。
キューの変更方法
キューの書き込みはすべてCLIを経由し、手動では行いません。
python -I -X utf8 "$HOME/.claude/sf/cola.py" [--raiz RUTA] [--quien propietario|principal] [--via cli|panel] [--json] <コマンド> …
- このコマンドは常に同じ形式で使用し、bash、zsh、PowerShell、どのプロジェクトでも同様です。サブエージェントも同様です。モッドがセッション開始時に「このマシンではPythonは別の名前で起動する（macOSでは
python3）」と指示した場合は、その名前を使用します（「Pythonコマンドは検出されたインタプリタから取得する」、236）。cola.py encargoもその名前を表示します。特定のフォルダ内のtools/cola.py（SFではplugins/sf/tools/cola.pyはアクティブブランチによって変わります）は使用せず、ロードされたプラグインのものを使用します。ロード時に、パネルは自身のcola.pyを~/.claude/sf/cola-<session>.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 に定義されています。ここではキュー自体に関するルールを示します。
- プリンシパルのみがキューを書き換えます。 サブエージェントは書き込みコマンドを実行せず、その報告書にその旨を記載し、プリンシパルが実行します。
- すべての要求は進行中のタスクの下で行われます。 進行中のタスクなしに作業を開始することはできません。キューの再編成（マージ、分割、再説明、ステップ追加、タイプ変更）には進行中のタスクは必要ありません（「タスクごとに1つのサブエージェントを稼働させるオーケストレーション」、149）。
- プロジェクトオーナーの承認:
cerrar、a-observacion、reobservar、descartarは承認を必要とします。進行中のタスクをen-colaに戻す場合も承認が必要ですが、それは作業がない場合に限ります。ブランチに独自のコミット（またはサブエージェントの補助ブランチ）がある場合はキューに戻らず、クローズ、観察中への移行、または破棄が行われます（「ブランチを持つ進行中のタスクはキューに戻らない」、170）。ブランチが空または既に削除されている場合、en-colaはブランチを削除し、空のサブエージェントを収集します（275）。 - 作成時のタイプ (
crear --tipo): 検討、ドキュメント作成、設計、実装、仕様作成、修正、調査。変更する場合はtipo N Tを使用します。 en-curso前の競合確認:choques Nを--archivosと予想ファイルとともに使用します。予想ファイルは説明から推測され、まだブランチがない場合に使用します。既に進行中のタスクのサブエージェント起動時には使用しません（「進行中タスク設定時の競合確認」、130）。- 最初のアクティブ化前のブランチ (
rama): 警告を伴います。サブエージェントの場合、プリンシパルがアクティブ化せずにブランチを作成し（rama --sin-activar）、サブエージェント起動前に記録します。サブエージェントはそのブランチから補助ブランチで作業し、プリンシパルがgit merge --ff-onlyで取り込みます。サブエージェントはタスクのブランチを作業ツリーでアクティブ化しません。これにより、TとCが設定されたワークツリーで動作します（「タスクごとに1つのサブエージェントを稼働させるオーケストレーション」、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のスカッシュ、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 RUTA|--texto T [--numero NNN] [--coautor "Co-Authored-By: …"] [--push]はキューを変更しません。developのdocs/decisiones/の次の番号と、名前NNN-AAAA-MM-DD-titulo.mdを割り当てます（--numeroを指定すると、その番号のファイルを名前を変えずに書き換えます）。ファイルを書き込み（テキストに# タイトルが先頭にない場合は追加。ある場合は一致している必要があります）、README.mdを再生成し、「Decisión NNN: Título」というコミットをdevelopに作成します。他のブランチがアクティブでも、その作業コピーを変更せずに、a-propuestaと同様に実行します（タスク273）。developが別のワークツリーにある場合、またはアクティブブランチでdocs/decisiones/に未コミットの変更がある場合は実行しません。developがアクティブな場合はREADME.htmlも再生成します。--pushはdevelopをプッシュし、番号とハッシュを表示します。gitがない場合やdevelopがない場合は、ファイルのみを書き込み、警告します（タスク283）。 - マージと分割はプロジェクトオーナーが記述します（パネルで
/sf_fusionar、/sf_split）。プリンシパルはfusionarで、同じドキュメントを更新する2つのタスクのみをマージできます（「更新するドキュメントごとに1つのタスク」、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）は、ブランチの有無に関わらず、また提案の場合も、「タスクをクローズする」ステップを完了し、他の保留中のステップがないことを要求します（「テストのためにブランチをアクティブ化する」は除く）。これらの2つのクローズステップは、タスクが進行中になった時点（crear --en-curso、en-curso、reabrir、probar（キューから）、restaurar、fusionar）で cola.py によって追加され、一度だけ、最後に配置され、削除もテキスト変更もされません。これらのステップがない進行中のタスクは、キュー読み込み時に追加されます。新しい作業ステップが追加されると、「テストのためにブランチをアクティブ化する」が再度保留になります（既に完了していた場合）。再度テストが必要です。テスト補助ステップ（paso añadir N "texto" --prueba）は2つのクローズステップの間に配置され、クローズを要求しません。クローズはそのままにし、追加しても「ブランチをアクティブ化」は保留に戻りません（「テスト補助: ブランチアクティブ化後、クローズ必須ではない」、184）。listo はテスト内容を記録するだけです（「クローズステップ: タスクが進行中になった時点から」、174）。probar は develop をブランチにマージ（競合がある場合はマージを元に戻し、アクティブ化しません。sub-NN のコミットが取り込まれていない場合もマージもアクティブ化もしません）、ブランチをアクティブ化（または既にアクティブな場合はそのまま）、「テストのためにブランチをアクティブ化する」を完了にマークします。cerrar も同様です。プロジェクトオーナーの承認がクローズです（172、121）。ステップは1から番号付けされ、ver の n と一致します。キューから削除されたタスクは .sf/historial.jsonl に削除時の状態（cerrada、eliminada、absorbida、descartada、および以前の「revertirが削除または保留にした」状態（134）の revertida）とともに記録され、ver で表示されます。
Revertir は宛先を必要とします: revertir N --eliminar はタスクを痕跡なくキューから削除（Eと同様）、revertir N --pendiente はタスクを保留中に戻し、キュー待ちかつ再オープン状態で、ブランチなしにします。クローズ済みにRのまま残ることはありません（「Revertirはタスクを削除または保留にする」、134）。プロジェクトオーナーが指定しない場合は、どちらかを尋ねてください。
gitが原因でコマンドが失敗した場合（スカッシュやrevertでの競合、未コミットの変更、ブランチが別のワークツリーにあるなど）、CLIは変更を元に戻し、問題を報告します。プリンシパルが解決し、コマンドを再実行します。プッシュの失敗はクローズを妨げません。履歴に記録され（push-fallido）、手動でプッシュを再実行します。