dev-orchestrator

Name: dev-orchestrator
Author: rysweet

github.com/rysweetエージェントワークフロー7690 回インストール21 週間前に更新

リポジトリ

dev-orchestrator について

amplihackで複雑な開発や調査を扱う既定のオーケストレーションスキルです。依頼を分類し、作業を分割してレシピのワークフローを実行し、結果を検証します。

主な機能

01タスク種別と目標の分類
02並行ワークストリームへの分割
03レシピワークフローの実行
04ネストしたセッション深度の制御
05結果の確認と障害対応

活用シーン

01複数部分からなる開発作業の調整
02定められた手順でのコードベース調査
03実装後の結果検証

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/rysweet/amplihack --skill dev-orchestrator

インストール後、Claude Code で/dev-orchestratorを入力して読み込まれたか確認します。

詳細

Dev Orchestrator Skill

目的

これは、amplihack における、重要度の高いすべての開発および調査タスクのデフォルトのオーケストレーターです。ultrathink-orchestrator スキルに代わるものです。

ユーザーから、重要度の高いものの構築、実装、修正、調査、作成を依頼された場合、このスキルによって以下が確実に行われます。

タスクが分類される — Q&A／運用／調査／開発
目標が定められる — 明確な成功基準を特定
ワークストリームが検出される — 並列タスクを自動的に分割
レシピランナーが使用される — コードによって強制されるワークフローの実行
成果が検証される — 振り返りによって目標の達成を確認

仕組み

User request
     │
     ▼
[Classify] ──→ Q&A ──────────────────→ analyzer agent (technical/code questions)
     │
     ├──────→ Ops ────────────────────→ builder agent
     │
     └──→ Development / Investigation
             │
         [Recursion guard] (AMPLIHACK_SESSION_DEPTH vs AMPLIHACK_MAX_DEPTH=3)
             │         │
           ALLOWED   BLOCKED → [announce-depth-limited banner]
                                    ↓
                           [execute-single-fallback-blocked]
                                    ↓
                           [Execute round 1 (single-session)]
             │
         [Decompose]
             │         │
             1 ws     N ws ──→ [multitask parallel] + tree context in env
             │
         [Execute round 1]
             │
         [Reflect] ──→ ACHIEVED ──→ [Summarize]
             │
           PARTIAL/NOT_ACHIEVED
             │
         [Execute round 2]
             │
         [Reflect] ──→ ACHIEVED ──→ [Summarize]
             │
           PARTIAL/NOT_ACHIEVED
             │
         [Execute round 3 (final)]
             │
         [Final reflect + Summarize]

セッションツリーによる強制（無限再帰を防止します）：

各サブプロセスは AMPLIHACK_TREE_ID、AMPLIHACK_SESSION_DEPTH、AMPLIHACK_MAX_DEPTH を継承します
深度が 3 以上の場合：再帰ガードがサブワークストリームの起動をブロックし、単一セッションに切り替えます
ツリーあたりの同時セッション数は最大 10 です。それを超える分は FIFO 順にキューに入ります
状態は /tmp/amplihack-session-trees/{tree_id}.json で追跡されます

有効化

このスキルは、開発および調査に関するキーワードを検出すると自動的に有効になります。また、CLAUDE.md に定められているデフォルトの動作でもあり、重要度の高いタスクでは必ず呼び出してください。

UserPromptSubmit フックは、開発／調査タスクで Claude に Skill(skill="dev-orchestrator") を呼び出すよう指示する分類プロンプトを挿入して、この動作を補強します。

実行手順

このスキルを読んだ後、次に行う操作には、必ず run_recipe_by_name("smart-orchestrator") を実行する Bash ツール呼び出しを含めてください。 実行環境で report_intent の呼び出し（Copilot CLI など）が必要な場合は、Bash の起動と並行して出力してください — 両方のツール呼び出しを同じ応答で行います。Bash の起動より前に、ほかの実質的な操作（ファイルの読み込み、TodoWrite の呼び出し、Agent の起動、応答の入力）を行ったり、Bash の起動に代えたりすることは禁止されています。

レシピランナーを起動せずに別の操作をしていることに気づいたら、ワークフローを迂回しています。停止して、最初に戻り、レシピランナーを実行してください。

開発および調査タスクの実行経路は、レシピランナーの1 つだけです。「別の方法」はありません。「手順を手動で進める」ことも、「少しだけ確認する」こともできません。ワークフローそのものがレシピランナーです。これを省略すると、23 ステップのプロセス、再帰ガード、目標の検証、そして適切な理由があって設けられた品質ゲートも省略することになります。

PostToolUse フックは、このスキルが有効になった後のすべてのツール呼び出しを監視します。レシピランナーを実行した形跡がないままツールを 3 回呼び出したことを検出すると、重大な警告を発します。警告を待たず、直ちにレシピランナーを実行してください。

このスキルが有効になったら：

必須：レシピランナー経由で直ちに実行

次のツール呼び出しには、レシピランナーの起動を含めてください（ランタイムで必要な場合は report_intent も併せてください）。重要：Claude Code の run_in_background は、約10分後にプロセスを終了します。レシピの作業には何時間もかかる場合があります。実行には必ず tmux セッションを使用してください：

LOG_FILE=$(mktemp /tmp/recipe-runner-output.XXXXXX.log)
chmod 600 "$LOG_FILE"
tmux new-session -d -s recipe-runner "env -u CLAUDECODE PYTHONPATH=src python3 -c \"
import os
os.environ.pop('CLAUDECODE', None)

from amplihack.recipes import run_recipe_by_name

result = run_recipe_by_name(
    'smart-orchestrator',
    user_context={
        'task_description': '''TASK_DESCRIPTION_HERE''',
        'repo_path': '.',
    },
    progress=True,
)
print(f'Recipe result: {result}')
\" 2>&1 | tee \"$LOG_FILE\""
echo \"Recipe runner log: $LOG_FILE\"

重要なポイント：

env -u CLAUDECODE — ネストした Claude Code セッションを起動できるよう、環境変数を解除します
PYTHONPATH=src python3 — PATH 上のインタープリターを使用し、チェックアウトしたリポジトリのソースツリーからのインポートを強制します（.venv/bin/python をハードコードしないでください）
run_recipe_by_name — Rust バイナリに処理を委譲します。アダプターのパラメーターは不要になりました
progress=True — レシピランナーの stderr をリアルタイムでストリーミングし、tmux のログにネストしたステップの動作を記録します
chmod 600 "$LOG_FILE" — tmux のログを現在のユーザーだけが読めるようにします
tmux new-session -d — デタッチされたセッションを作成します。タイムアウトせず、接続が切れても実行を続けます
次のコマンドで監視します：tail -f "$LOG_FILE" または tmux attach -t recipe-runner

古い tmux セッションの再起動：一部のランタイム（Copilot CLI など）では、数値の PID を対象にしていないため、tmux kill-session がブロックされます。代わりに、次のシェルポリシーに準拠した方法のいずれかを使用してください：

# Option A (preferred): use a unique session name per run to avoid collisions
tmux new-session -d -s "recipe-$(date +%s)" "..."

# Option B: locate the tmux server PID and terminate with numeric kill
tmux list-sessions -F '#{pid}' 2>/dev/null | xargs -I{} kill {}

# Option C: let tmux itself handle it — send exit to all panes
tmux send-keys -t recipe-runner "exit" Enter 2>/dev/null; sleep 1

オプション A を使用する場合は、tail -f／tmux attach コマンドも同じセッション名を使うように更新してください。

レシピの実行に run_in_background を使用しないでください。約10分後に終了します（Issue #2909）。

開発および調査タスクでは、レシピランナー経由での実行が必須です。 まず必ず smart-orchestrator を試してください。

次のような、よくある正当化は認められません：

「まずコードベースを理解します」— レシピのステップ0で実行します
「ワークフローの手順を手動で進めます」— いいえ。レシピが手順を徹底します
「レシピランナーは動かないかもしれません」— まず試し、失敗した場合はエラーを報告してください
「簡単なタスクです」— 簡単なタスクでも複雑なタスクでも、レシピランナーで対応します

Q&A と運用タスクに限り、レシピランナーを使わなくてもかまいません：

Q&A：直接回答します（アナライザーエージェント）
運用：ビルダーエージェントを使用します（直接実行し、ワークフローの手順はありません）

エラーリカバリー：適応型戦略（劣化ではありません）

smart-orchestrator が失敗した場合、失敗は必ず可視化し、ユーザーに伝える必要があります。決して握りつぶしたり、黙って劣化させたりしないでください。このレシピでは組み込みの適応型戦略ステップによってエラーリカバリーが自動で行われますが、レシピの外で失敗を確認した場合は、次の手順に従ってください。

1. 全文脈とともにエラーを伝える：

正確なエラー、失敗したステップ、ログ出力を報告します。「何か問題が起きました」とだけ伝えるのではなく、必ず具体的な失敗の詳細を含めてください。

2. 再現情報を添えてバグを報告する：

インフラストラクチャの障害（インポートエラー、環境変数の不足、バイナリが見つからない、分解によって無効な出力が生成されるなど）の場合は、GitHub issue を作成してください。

gh issue create \
  --title "smart-orchestrator infrastructure failure: <one-line summary>" \
  --body "<full error context, reproduction command, env details>" \
  --label "bug"

3. 代替戦略を評価する：

smart-orchestrator がインフラストラクチャレベルで失敗した場合（タスク自体に問題がある場合を除く）、特定のワークフローレシピを直接呼び出してもかまいません。これは適応型戦略であり、黙って実行するのではなく、必ず明示的に伝える必要があります。

分類	直接呼び出すレシピ	許可される条件
調査	`investigation-workflow`	smart-orchestrator が解析／分解／起動で失敗した場合
開発	`default-workflow`	smart-orchestrator が解析／分解／起動で失敗した場合

例：

# ANNOUNCE the strategy change first — never do this silently
print("[ADAPTIVE] smart-orchestrator failed at parse-decomposition: <error>")
print("[ADAPTIVE] Switching to direct investigation-workflow invocation")
run_recipe_by_name("investigation-workflow", user_context={...}, progress=True)

これは smart-orchestrator を迂回してよいという意味ではありません。 まず必ず smart-orchestrator を試してください。直接呼び出しが許可されるのは、smart-orchestrator がインフラストラクチャレベルで失敗した場合だけです。「タスクが簡単そうだから」は、インフラストラクチャの障害ではありません。

4. 見かけだけの成功を検出する：

レシピは構造上は完了（すべてのステップが終了コード 0）していても、空または意味のない結果を生成することがあります。たとえば、エージェントが「コードベースが見つかりません」と報告したり、作業が行われていないのに振り返りで ACHIEVED と判定されたりする場合です。実行後、次の点を確認してください。

ラウンドの結果に実際の調査結果やコード変更が含まれている（「アクセスできませんでした…」ではない）
開発タスクでは、PR の URL または具体的な出力がある
少なくとも 1 つの成功基準が検証可能な形で評価されている

結果が空疎な場合は、具体的にどの出力が空だったのかを添えてユーザーに報告してください。エージェントが意味のある作業を行っていない場合、成功を宣言してはいけません。

必須の環境変数

レシピランナーの動作には、次の環境変数が必要です。

変数	用途	デフォルト
`AMPLIHACK_HOME`	amplihack のインストールルート（アセット検索用）	自動検出
`AMPLIHACK_AGENT_BINARY`	使用するエージェントバイナリ（claude、copilot など）	`claude`
`AMPLIHACK_MAX_DEPTH`	入れ子のセッションの最大再帰深度	`3`
`AMPLIHACK_NONINTERACTIVE`	対話型プロンプトをスキップする場合は `1` を設定	未設定

AMPLIHACK_HOME が設定されておらず、自動検出にも失敗した場合、parse-decomposition と activate-workflow は「orch_helper.py not found」というエラーで失敗します。amplifier-bundle/ を含むディレクトリを設定してください。

実行後：振り返りと検証

実行完了後、目標が達成されたことを確認してください。達成されていない場合：

情報が不足している場合：ユーザーに尋ねます
修正可能な不足がある場合：残りの作業内容を指定して再実行します
インフラストラクチャの障害の場合：バグを報告し、適応型戦略を試します

強制：PostToolUse ワークフローガード

PostToolUse フック（workflow_enforcement_hook.py）は、このスキルが呼び出された後のすべてのツール呼び出しを積極的に監視します。次の項目を追跡します。

/dev または dev-orchestrator が呼び出されたか（フラグを設定）
レシピランナーが実際に実行されたか（フラグをクリア）
ワークフローの証拠がないまま経過したツール呼び出しの数

レシピランナーが実行された証拠がないままツール呼び出しが3回以上経過すると、フックは重大な警告を出力します。これは提案ではありません。必須のワークフローに違反しているという意味です。状態は /tmp/amplihack-workflow-state/ に保存されます。

タスク種別の分類

種別	キーワード	アクション
Q&A	"what is", "explain", "how does", "how do I", "quick question"	直接回答する
Operations	"clean up", "delete", "git status", "run command"	builder エージェント（直接実行、ワークフロー手順なし）
Investigation	"investigate", "analyze", "understand", "explore"	investigation-workflow
Development	"implement", "build", "create", "add", "fix", "refactor"	smart-orchestrator
Hybrid*	調査と開発の両方のキーワード	調査と開発のワークストリームに分解する

* Hybrid は独立した task_type ではありません。オーケストレーターは Development として分類し、複数のワークストリーム（調査1つ、開発1つ）に分解します。

ワークストリーム分解の例

リクエスト	ワークストリーム
"implement JWT auth"	1: auth (default-workflow)
"build a webui and an api"	2: api + webui（並列）
"add logging and add metrics"	2: logging + metrics（並列）
"investigate auth system then add OAuth"	2: investigate + implement（順次）
"fix bug in payment flow"	1: bugfix (default-workflow)

オーバーライドオプション

単一ワークストリームのオーバーライド：レシピの user_context に force_single_workstream: "true" を渡すと、タスクの構成にかかわらず、自動的な並列分解を防止できます。これはプログラムから指定するオプションであり、/dev から直接設定することはできません。

run_recipe_by_name(
    "smart-orchestrator",
    user_context={
        "task_description": task,
        "repo_path": ".",
        "force_single_workstream": "true",  # disables parallel decomposition
    }
)

レシピのコンテキストを変更せずに、単一ワークストリームでの実行を強制するには： /dev を実行する前に AMPLIHACK_MAX_DEPTH=0 を設定します。これにより再帰ガードが並列スポーンをブロックし、すべてのタスクで単一セッションモードにフォールバックします。

export AMPLIHACK_MAX_DEPTH=0  # set in your shell first
/dev build a webui and an api  # then type in Claude Code

注：環境変数は Claude Code の起動前にシェルで設定する必要があります。/dev コマンドの前にインラインで付けることはできません。この設定は並列ワークストリームのスポーンだけでなく、すべての深さチェックに影響します。

正規の参照元

レシピ：amplifier-bundle/recipes/smart-orchestrator.yaml
並列実行：.claude/skills/multitask/orchestrator.py
開発ワークフロー：amplifier-bundle/recipes/default-workflow.yaml
調査ワークフロー：amplifier-bundle/recipes/investigation-workflow.yaml
CLAUDE.md：これをデフォルトのオーケストレーターとして定義します

その他のスキルとの関係

スキル	関係
`ultrathink-orchestrator`	非推奨 — ここにリダイレクトされます
`default-workflow`	単一の開発タスクで、このオーケストレーターから呼び出されます
`investigation-workflow`	調査タスクで、このオーケストレーターから呼び出されます
`multitask`	並列の作業ストリームで、このオーケストレーターから呼び出されます
`work-delegator`	相互に独立 — バックログ主導の委任に使用します

エントリーポイント

主な方法：/dev <task description>
自動有効化：CLAUDE.md のデフォルト動作とフックの挿入による
レガシー：/ultrathink <task>（非推奨の別名 → /dev にリダイレクト）

ステータスシグナルのリファレンス

オーケストレーターでは、2 種類のステータスシグナル形式を使用します。

実行ステータス（ビルダーエージェントから）

ラウンドの実行ステップの末尾に表示されます。

STATUS: COMPLETE — ラウンドの作業がすべて完了しました
STATUS: CONTINUE — このラウンドの後も作業が残っています
STATUS: PARTIAL — 最終ラウンド（ラウンド 3）で部分的な完了に達しました
STATUS: DEPTH_LIMITED —（レガシー。現在は出力されません。代わりに BLOCKED パスを使用してください）

目標ステータス（レビュアーエージェントから）

振り返りステップの末尾に表示されます。

GOAL_STATUS: ACHIEVED — すべての成功基準を満たし、タスクが完了しました
GOAL_STATUS: PARTIAL -- [description] — 一部の基準を満たしましたが、さらなる作業が必要です
GOAL_STATUS: NOT_ACHIEVED -- [reason] — 目標を達成できず、次のラウンドが必要です

目標達成ループでは、GOAL_STATUS シグナルを使用して、ラウンド 2 または 3 を実行するかどうかを判断します。

BLOCKED パス（再帰ガード）：深度制限により複数の作業ストリームの起動がブロックされた場合、オーケストレーターは単一セッションでの実行に切り替えます。

announce-depth-limited — 修正方法の情報を含む警告バナーを表示します
execute-single-fallback-blocked — タスク全体を単一のビルダーエージェントセッションとして実行します（通知なしではなく、バナーによって戦略の変更を明示します）

Markdown 対応

ログインしてコメント

基本情報

作者: rysweet
リポジトリ: rysweet/amplihack
カテゴリ: エージェントワークフロー
インストール数: 90
GitHub スター: 76

問題を報告