sefirot-loop

この本文は AI(Claude)が読むための原文(英語または中国語)です。日本語訳は順次追加中。

sefirot とは

Sefirot は Claude Code 上のマルチエージェントオーケストレーションフレームワーク。3つのエージェント（Planner / Builder / Verifier）が Milestone 単位で設計→実装→検証のループを自動で回す。

Planner: 設計ドキュメントからタスクを分割し、Wave（並列実行単位）を割り当てる
Builder: 各タスクを独立した git worktree 内で並列実装する（最大8並列）
Verifier: Builder のブランチをマージし、テスト・リント・型チェックで検証する。失敗時は fix task を生成して再ループ

すべての状態は milestones.json（タスクディレクトリ内）と設計ドキュメント（Markdown）で管理される。エージェント間の直接通信はなく、これらのファイルを介して連携する。

エージェントが判断に迷った場合は milestones.json の questions 配列に質問を書き込み、ループが一時停止する。このスキルがその質問をユーザーに仲介し、回答を設計ドキュメントに反映してループを再開する。

前提チェック

まず sefirot CLI がインストールされているか確認してください:

command -v sefirot

インストールされていない場合は、以下のメッセージを返して終了してください:

sefirot CLI がインストールされていません。以下のコマンドでインストールしてください:
uv tool install git+https://github.com/agarichan/sefirot.git

概要

sefirot のビルドループをバックグラウンドで実行し、エージェントからの質問があればユーザーに確認して回答を反映した上で再実行する。

手順

ステップ0: 対象タスクの確認

sefirot list --active を実行して未完了タスクの一覧を確認する:

見つからない場合: 以下を案内して終了する:

未完了のタスクがありません。/plan で設計ドキュメントを作成し、/milestone で milestones.json を生成してください。
1つだけ見つかった場合: そのまま使う。
複数見つかった場合: sefirot list --active の結果を提示して AskUserQuestion でユーザーにどのタスクを実行するか確認する。

ステップ1: バックグラウンドでループ実行

Bash ツールの run_in_background: true を使ってバックグラウンドで起動する:

sefirot loop --from-skill --task-dir <ステップ0で特定したタスクディレクトリ>

起動後、ユーザーに以下を伝える:

sefirot loop をバックグラウンドで開始しました。完了時に通知します。実行中も自由に質問できます。

ステップ2: ユーザーとの対話（ループ実行中）

バックグラウンドタスクの完了通知が届くまで、ユーザーの入力を待つ。ユーザーから質問や依頼があった場合は通常通り応答する。

典型的なリクエスト:

「進捗は？」「状況教えて」 → TaskOutput でバックグラウンドプロセスの出力を読み、進捗を報告する。各エージェントの詳細ログは .sefirot/sessions/<タスク名>/ 配下にあるので、必要に応じてそちらも確認する
その他の質問 → 通常通り応答する

ステップ3: 完了時の処理

バックグラウンドタスクが完了したら、TaskOutput で出力を取得する。出力の末尾に [SEFIROT:ACTION] 行が含まれているので、そのアクション指示に従う:

[SEFIROT:ACTION] COMPLETE: 正常完了。ステップ5 に進む。
[SEFIROT:ACTION] QUESTIONS_PENDING: 質問が保留中。ステップ4 に進む。
[SEFIROT:ACTION] ERROR: エラー。[SEFIROT:MESSAGE] 行のメッセージをユーザーに報告し、終了する。
[SEFIROT:ACTION] が見つからない場合: 予期しないクラッシュ。出力の末尾をユーザーに報告し、終了する。

ステップ4: 質問の処理

エージェントからの質問が milestones.json の $.questions 配列に格納されている。 milestones.json は docs/tasks/<タスクディレクトリ>/milestones.json に配置されている。

milestones.json を読み、questions 配列を取得する
各質問について:
- 質問内容をユーザーに提示する。フォーマット:
```
[質問 N/{total}] from {agent} (task: {task_id})
{question}
```
- AskUserQuestion ツールを使ってユーザーの回答を得る
- 回答を関連する設計ドキュメントに反映する: a. milestones.json から該当タスクの所属する Milestone を特定する b. その Milestone の plan_doc フィールドから設計ドキュメントのパスを取得する。plan_doc がない場合（Planner からの質問等）は、milestones.json の source フィールド（design.md）を使う c. 設計ドキュメント内の該当タスクのセクション（または末尾）に「追加指示」として回答を追記する:
```
   #### 追加指示（ユーザー回答）
   - Q: {元の質問}
   - A: {ユーザーの回答}
```
全ての質問を処理したら、milestones.json の questions 配列を空にする（"questions": []）

変更をコミットする:

git add -A && git commit -m "chore: resolve agent questions"

ステップ1 に戻り、再度バックグラウンドでループを実行する

ステップ5: 完了報告

ループが正常完了したら、結果を報告する:

milestones.json を読み、現在の状態を把握する
以下の情報を報告する:
- 完了した Milestone とそのゴール
- 完了したタスクの一覧
- 次の未完了 Milestone があればその情報
- 検証結果のサマリー

注意事項

ループは必ずバックグラウンドで実行する。 フォアグラウンドで実行しない
ループ実行中もユーザーの入力を受け付け、進捗確認などに応答する
質問が発生した場合のみユーザーの判断を求める
質問への回答は設計ドキュメントに永続化されるため、再実行時にエージェントが参照できる
1回のループで複数の質問が発生する場合がある。全て処理してから再実行すること

🇯🇵 日本人クリエイター向け解説

🎯 このSkillでできること

📦 インストール方法 (3ステップ)