synapse-manager

Synapse Manager

構造化された委任、監視、品質ゲートによって、複数のエージェントによる作業をオーケストレーションします。

使用する場面

• 関連するサブタスクについて、2 つ以上のエージェントを調整する場合
• 委任した作業の進捗を監視する場合
• エージェントの出力を検証する場合（テスト、ファイル変更、統合）
• エラーの詳細と修正方法を示し、対象を絞ってフィードバックを送る場合
• エージェント間の相互レビューをオーケストレーションする場合
• 複数フェーズの計画（3 フェーズ以上、または 10 ファイル以上の変更）を実施する場合
• 複数ファイルにわたる変更で、エージェントの割り当てを計画する場合

ワークフロー（7 ステップ）

ステップ 1：計画、仕様、セットアップ

範囲が明確な場合は、テストファーストを優先します。テストを作成し、仕様を提示・確認してから実装します。探索的な作業、プロトタイプ、または些細な修正では、実装後にテストを作成してもかまいません。

まず plugins/synapse-a2a/skills/ を編集し、次に sync-plugin-skills で生成されたコピーを同期します。

エージェントを起動する前に、既存のエージェントを確認します。再利用したほうが速く（起動オーバーヘッド、指示の注入、準備完了までの待機を避けられます）：

synapse list --json

WORKING_DIR、ROLE、STATUS、TYPE を確認します。すぐに作業を受け付けられるのは READY 状態のエージェントだけです。 その他の関連する状態：SENDING_REPLY（短時間の A2A 送信／返信 POST。前の状態に戻るまで待機します）、PROCESSING（作業中）、WAITING（権限確認プロンプト。synapse approve／synapse reject を使用します）、WAITING_FOR_INPUT（#538 — 入力を求めてタスクが一時停止中。synapse reply "<message>" または synapse reply "<message>" --to <sender_id> で返信します）、RATE_LIMITED（#561 — LLM プロバイダーのレート制限に到達。再送信する前に制限がリセットされるまで待ちます）、DONE（約 10 秒後に READY に降格）、SHUTTING_DOWN（送信しないでください）。

既存のエージェントでタスクに対応できない場合に限り、起動します：

synapse spawn claude --worktree --name Impl --role "feature implementation"
synapse spawn gemini -w --name Tester --role "test writer"

異なるモデル間でエージェントを起動する（Claude が Gemini を起動するなど）と、それぞれの強みを活用でき、プロバイダー間でトークン使用量が分散されるため、レート制限を回避できます。

ヘルパースクリプトを使って準備完了を待ちます。コマンドがどの作業ディレクトリからでも機能するよう、プラグインのソース内にいる場合でも同期済みのコピー内にいる場合でも、スキルのルートからパスを解決します：

cd plugins/synapse-a2a/skills/synapse-manager
scripts/wait_ready.sh Impl 30
scripts/wait_ready.sh Tester 30

# Synced copy example
cd .agents/skills/synapse-manager
scripts/wait_ready.sh Impl 30

CLI ごとの権限スキップフラグについては、references/auto-approve-flags.md を参照してください。

ステップ 2：テストを作成し、仕様を確認する

実装を始める前に、テスト／仕様のタスクを割り当て、範囲を確認します：

synapse send Tester "Write the tests first and confirm the spec for auth module.
- Cover valid login, invalid credentials, token expiry, refresh flow
- Report any scope gaps before implementation starts" --attach synapse/server.py --force --wait

エージェントに調査させる参考ファイルを送るには、--attach を使用します。 テスト／仕様を確認している間は --wait を使い、実行の準備が整ったら --silent または --notify を使用します。

ステップ 3：実装を委任し、監視する

テスト／仕様を確認したら、実装タスクを委任します：

synapse send Impl "Implement auth module — tests/spec are confirmed.
- Add OAuth2 flow in synapse/auth.py
- Follow existing patterns" --attach synapse/server.py --force --silent

synapse list --json                       # AI-safe snapshot
synapse history list --agent Impl         # Completed work

または、集約スクリプトを使用します：

cd plugins/synapse-a2a/skills/synapse-manager && scripts/check_team_status.sh

エージェントが PROCESSING のまま 5 分を超えたら、中断を送ります：

synapse interrupt Impl "Status update — what is your current progress?" --force

ステップ 4：計画を承認する

synapse approve <task_id>
synapse reject <task_id> --reason "Use refresh tokens instead of long-lived JWTs."

ステップ 5：検証する

すばやくフィードバックを得るため、まずステップ 2 で作成したテストを実行します。その後、変更が共有モジュールや公開インターフェースに影響する場合は、より広範なリグレッションテストを検討します：

# New tests first (fast feedback)
pytest tests/test_auth.py -v

# Full regression (catches cross-module breakage)
pytest --tb=short -q

リグレッションのトリアージ — 新たに発生した不具合と既存の問題を区別します：

cd plugins/synapse-a2a/skills/synapse-manager && scripts/regression_triage.sh tests/test_failing_module.py -v

• 終了コード 0 = REGRESSION（変更による不具合）→ ステップ 6 に進みます
• 終了コード 1 = PRE-EXISTING（すでに発生していた問題）→ 記録して続行します

ステップ 6：フィードバック

具体的で実行可能なフィードバックにより、反復の回数を減らせます：

synapse send Impl "Issues found — please fix:

1. FAILING TEST: test_token_expiry (tests/test_auth.py)
   ERROR: TypeError: cannot unpack non-iterable NoneType object
   FIX: Add None guard at the top of validate_token()

2. REGRESSION: test_existing_endpoint broke
   ERROR: expected 200, got 401
   CAUSE: auth middleware intercepts all routes
   FIX: Exclude health-check endpoints from auth" --force --silent

チームで使えるパターンを保存します：

synapse memory save auth-middleware-pattern \
  "Auth middleware must exclude /status and /.well-known/* endpoints" \
  --tags auth,middleware --notify

フィードバックを送信したら、ステップ 3（監視）に戻ります。

ステップ 7：レビューと完了

相互レビューで見落としを検出します — 各エージェントがもう一方の作業をレビューします：

synapse send Tester "Review implementation. Focus on: correctness, edge cases" --force \
  --attach synapse/auth.py --wait
synapse send Impl "Review test coverage. Focus on: missing cases, assertion quality" --force \
  --attach tests/test_auth.py --wait

最終検証とクリーンアップ：

pytest --tb=short -q                      # All tests pass
synapse kill Impl -f && synapse kill Tester -f
synapse list --json                       # Verify cleanup

起動したエージェントを終了すると、ポート、メモリ、PTY セッションを解放できます。孤立したエージェントが、ほかのエージェント向けの今後のタスクを誤って受け付けてしまうことがあります。

判断表

状況	アクション
エージェントが PROCESSING のまま 5 分を超えている	synapse interrupt <name> "Status?"
エージェントが CLI/TUI ダイアログで停止している（codex の編集確認、モデル選択、レート制限のプロンプト）	synapse send-keys <name> <keys> — synapse jump を使わず、PTY に書き込んでプログラムからダイアログに応答します（例：codex の「今後確認しない」には a、Enter には \r）（#695）
エージェントが WAITING_FOR_INPUT の状態	synapse reply <task_id> "<answer>"
エージェントが RATE_LIMITED の状態	LLM プロバイダーのウィンドウがリセットされるまで待ってから、再送信します
すべてのエージェントを一度に確認する	synapse broadcast "Status check" -p 4
新しいテストが失敗する	エラーと修正案を添えてフィードバックします（ステップ 6）
回帰テストが失敗する	scripts/regression_triage.sh で分類します
エージェントが READY だが出力がない	git diff を確認し、必要に応じて再送信します
エージェントが計画を提出する	synapse approve または synapse reject --reason "..."
再利用可能なパターンを発見した	synapse memory save <key> "<pattern>" --notify
クロスレビューで問題が見つかった	--attach を付けて修正を依頼し、再確認します
すべてのテストに合格し、レビューに問題がない	エージェントを終了し、完了を報告します

参考資料

参考資料	内容
references/auto-approve-flags.md	CLI ごとの権限スキップフラグ
references/worker-guide.md	ワーカーエージェントの責任とコミュニケーションのパターン
references/features-table.md	コマンドを使った A2A 機能
references/commands-quick-ref.md	マネージャーに関係するすべてのコマンド
scripts/wait_ready.sh	エージェントが READY 状態になるまでポーリングします
scripts/check_team_status.sh	チームのステータスを集計します
scripts/regression_triage.sh	テストの失敗が回帰か既存の問題かを分類します