agestra 4.13.2 → 4.13.4

package/.claude-plugin/marketplace.json

@@ -4,15 +4,15 @@
     "name": "mua-vtuber"
   },
   "metadata": {
-    "description": "Multi-AI orchestration plugin for Claude Code",
+    "description": "Multi-host MCP orchestration plugin for Claude Code",
     "version": "1.0.0"
   },
   "plugins": [
     {
       "name": "agestra",
       "source": "./",
-      "description": "Orchestrate Ollama, Gemini, and Codex for multi-AI debates, code review, and cross-validation",
-      "version": "4.13.2",
+      "description": "Multi-host MCP orchestration across Claude, Ollama, Gemini, and Codex for review, QA, and cross-validation",
+      "version": "4.13.4",
       "author": {
         "name": "mua-vtuber"
       },
@@ -21,18 +21,24 @@
       "license": "GPL-3.0-only",
       "keywords": [
         "claude-code-plugin",
+        "mcp-server",
         "mcp",
+        "multi-agent",
         "multi-ai",
         "ollama",
+        "local-llm",
         "gemini",
         "codex",
-        "ai-orchestration"
+        "ai-orchestration",
+        "agent-orchestration"
       ],
       "category": "external-integrations",
       "tags": [
         "orchestration",
+        "multi-agent",
         "debate",
         "code-review",
+        "qa",
         "cross-validation"
       ]
     }

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agestra",
-  "version": "4.13.2",
-  "description": "Claude Code plugin — orchestrate Ollama, Gemini, and Codex for multi-AI debates, code review, and cross-validation",
+  "version": "4.13.4",
+  "description": "Claude Code plugin — multi-host MCP orchestration across Claude, Ollama, Gemini, and Codex for review, QA, and cross-validation",
   "mcpServers": {
     "agestra": {
       "command": "node",

package/README.ja.md

@@ -3,56 +3,34 @@
 [![npm version](https://img.shields.io/npm/v/agestra.svg)](https://www.npmjs.com/package/agestra)
 [![license](https://img.shields.io/npm/l/agestra.svg)](LICENSE)
 
-**Agent + Orchestra** — Claude Code、Codex CLI、Gemini CLI で共通利用できるマルチホスト・オーケストレーションツールキット。
+**Agent + Orchestra** — Claude Code、Codex CLI、Gemini CLI、ローカルモデルを調整するマルチホスト MCP オーケストレーションツールキット。
 
 [English](README.md) | [한국어](README.ko.md) | [日本語](README.ja.md) | [中文](README.zh.md)
 
-Agestra は Ollama（ローカル）、Gemini CLI、Codex CLI を Claude Code にプラガブルなプロバイダーとして接続し、独立集約、合意形成ディベート、自律 CLI ワーカー、並列タスク配分、クロスバリデーション、品質ベースのプロバイダー選択を 44 個の MCP ツールで提供します。
+Agestra は Claude host/CLI、Ollama（ローカル）、Gemini CLI、Codex CLI をプラガブルなプロバイダーとして接続し、独立集約、合意形成ディベート、自律 CLI ワーカー、並列タスク配分、クロスバリデーション、任意の trace 根拠を参照する能力ベースのプロバイダールーティングを 45 個の MCP ツールで提供します。
 
 ## クイックスタート
 
-### Claude Code
+まず作業するホストを選びます。ホストネイティブのコマンド/エージェントも入れる場合は `--assets` の経路を使い、サーバー接続だけでよい場合は MCP-only 登録を使います。
 
-```
-/plugin marketplace add mua-vtuber/Agestra
-/plugin install agestra@agestra
-```
-
-Claude では既存のプラグイン UX をそのまま維持します。Agestra は初回利用時に `environment_check` を通じて利用可能なプロバイダー（Claude host、Ollama、Gemini CLI、Codex CLI）を自動検出します。
-
-### Codex CLI
+| ホスト | このリポジトリから | グローバル npm から | `--assets` が追加するもの |
+|--------|--------------------|---------------------|-----------------------------|
+| Claude Code | `/plugin marketplace add mua-vtuber/Agestra` の後 `/plugin install agestra@agestra` | 同じプラグインフロー | プラグインバンドル、コマンド、エージェント、hooks、MCP サーバー |
+| Codex CLI | `npm run bundle` の後 `npm run install:codex:assets` | `npm install -g agestra` の後 `agestra-install codex --assets` | `.codex/agents/` 配下の生成 custom agents |
+| Gemini CLI | `npm run bundle` の後 `npm run install:gemini:assets` | `npm install -g agestra` の後 `agestra-install gemini --assets --scope user` | project scope では管理ファイル、user scope では native `agestra` Gemini extension |
 
-```
-npm run bundle
-npm run install:codex:assets
-```
+MCP-only 登録も利用できます:
 
-グローバル npm パッケージから使う場合:
+| ホスト | リポジトリパッケージ | チェックアウトからのグローバル登録 |
+|--------|----------------------|------------------------------------|
+| Codex CLI | `npm run install:codex` | `npm run install:codex:global` |
+| Gemini CLI | `npm run install:gemini` | `npm run install:gemini:global` |
 
-```
-npm install -g agestra
-agestra-install codex --assets
-```
+Claude はネイティブのプラグイン UX を維持します。Codex は [AGENTS.md](AGENTS.md)、生成された custom agents、登録済みの `agestra` MCP サーバーを組み合わせます。Gemini は [GEMINI.md](GEMINI.md)、`.gemini/commands/agestra/`、生成された skills、project-scope 管理ファイルまたは user-scope native extension を組み合わせます。
 
-Codex ではリポジトリ直下の [AGENTS.md](AGENTS.md) と、登録済みの `agestra` MCP サーバーを一緒に使います。生成済み Codex custom agent には `--assets` が必要で、`.codex/agents/` にインストールして Agestra host-asset manifest に記録します。custom agent なしで MCP 登録だけでよい場合は `npm run install:codex` または `agestra-install codex` を使ってください。
+注: `npm run install:gemini:assets` はデフォルトで user scope を使います。チェックアウトから project-scope の Gemini 管理ファイルを入れる場合は `node scripts/install-host-mcp.mjs gemini --assets --scope project` を実行してください。
 
-### Gemini CLI
-
-```
-npm run bundle
-npm run install:gemini:assets
-```
-
-グローバル npm パッケージから使う場合:
-
-```
-npm install -g agestra
-agestra-install gemini --assets --scope user
-```
-
-Gemini ではリポジトリ直下の [GEMINI.md](GEMINI.md)、[`.gemini/commands/agestra/`](.gemini/commands/agestra)、生成された skills を一緒に使います。project scope の `--assets` は管理ファイルを書き込み、user scope の `--assets` は Agestra Gemini native extension をインストールします。MCP 登録だけでよい場合は `npm run install:gemini` または `agestra-install gemini` を使ってください。`npm run install:gemini:assets` はデフォルトで user scope を使うため、チェックアウトから project-scope の管理ファイルを入れる場合は `node scripts/install-host-mcp.mjs gemini --assets --scope project` を実行してください。
-
-セットアップ後に利用できる Gemini コマンド:
+Assets セットアップ後に利用できる Gemini コマンド:
 
 - `/agestra:setup`
 - `/agestra:review`
@@ -68,12 +46,26 @@ Gemini ではリポジトリ直下の [GEMINI.md](GEMINI.md)、[`.gemini/command
 
 | プロバイダー | インストール | 種類 |
 |-------------|---------------|------|
+| [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) | `npm install -g @anthropic-ai/claude-code` | Cloud |
 | [Ollama](https://ollama.com/) | `curl -fsSL https://ollama.com/install.sh \| sh` | Local LLM |
 | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `npm install -g @google/gemini-cli` | Cloud |
 | [Codex CLI](https://github.com/openai/codex) | `npm install -g @openai/codex` | Cloud |
 
+各 CLI は自分自身の認証を管理します。使用予定の CLI は、その CLI 固有のログイン手順で事前に認証を済ませてください — Agestra は各 CLI を子プロセスとして起動するだけで、認証情報には関与しません。
+
 任意ですが推奨:
 - **tmux** — 自律実行中の CLI ワーカーペインを可視化できます
+- **Windows の ripgrep (`rg`)** — Codex が Store app bundled path の `rg` を拾って "Access is denied" になる場合は、通常の `rg.exe` が `PATH` で先に見つかるように ripgrep を別途インストールしてください:
+
+```
+cargo install ripgrep
+```
+
+代替:
+
+```
+winget install BurntSushi.ripgrep.MSVC
+```
 
 ---
 
@@ -81,6 +73,52 @@ Gemini ではリポジトリ直下の [GEMINI.md](GEMINI.md)、[`.gemini/command
 
 **Multi-AI はトークン節約のためではなく、検証のために使います。** レビュー、設計探索、アイデア創出のワークフローは、速度のための並列化ではなく、複数の AI プロバイダーから独立した視点を集めて見落としを防ぐ検証プロセスとして設計されています。
 
+## 動作の仕組み
+
+```mermaid
+flowchart TD
+    Start([ユーザーが /agestra コマンドを実行]) --> Preflight[セットアップ状態 / 環境 / プロバイダー確認]
+    Preflight --> Domain{ワークフロー種別}
+
+    Domain -->|アイデア / 設計 / レビュー / セキュリティ| TextLead[リーダーが専門エージェントと外部 AI を編成]
+    Domain -->|QA| QaLead[リーダーが QA Brigade を編成]
+    Domain -->|実装| ImplLead[リーダーが実装作業を分解]
+
+    ImplLead --> ImplRoute{作業の性質}
+    ImplRoute -->|明確に並列化できる実装| CliWorkers[Codex / Gemini CLI ワーカー<br/>分離 worktree で実装]
+    ImplRoute -->|能力に合うスコープ付き作業| Ollama[ローカル / ツールモデル<br/>ポリシー許可時は読み書き]
+    ImplRoute -->|リスクが高い中核変更| HostImpl[ホスト実装エージェント<br/>リーダーが近くで監督]
+    CliWorkers --> ReviewDiff[リーダーが状態 / 使用量 / diff を確認]
+    Ollama --> ReviewDiff
+    HostImpl --> ReviewDiff
+    ReviewDiff --> Merge{受け入れ可能?}
+    Merge -->|いいえ| Reassign[修正指示または再割り当て]
+    Reassign --> ImplRoute
+    Merge -->|はい| QaEvidence
+
+    QaLead --> QaEvidence[ホスト QA が実行証拠を収集<br/>ビルド / テスト / E2E / スクリーンショット]
+    TextLead --> Providers{外部 AI がある?}
+    QaEvidence --> Providers
+
+    Providers -->|なし| LocalOut[ホスト専門エージェントが<br/>ドメイン別レポートや文書を作成]
+    Providers -->|あり| Individual[各 AI が独立した意見を作成]
+    LocalOut --> Final([ユーザーへ結果を報告])
+
+    Individual --> Ledger[ITEM-* JSON 合意台帳]
+    Ledger --> Round[順次ラウンド<br/>同意 / 反対 / 修正 / 意見]
+    Round --> Gate{台帳の状態}
+    Gate -->|さらに議論| Round
+    Gate -->|リーダー判断が必要| LeaderDecision[リーダーが継続 / 承認 / 却下を選択]
+    Gate -->|整理済み| LeaderDecision
+    LeaderDecision -->|継続| Round
+    LeaderDecision -->|承認| Approved[承認済み統合文書]
+    LeaderDecision -->|却下| Rejected[却下 / 未解決の統合文書]
+    Approved --> Final
+    Rejected --> Final
+```
+
+外部プロバイダーが構成されていない場合、Agestra は合意ラウンドをスキップし、ホスト専門エージェントがレビュー/QA レポート、設計文書、アイデア記録などのドメイン別成果物を作成します。構造化ディベートが実行された場合は、リーダーが承認しても却下しても統合文書を残します。却下時の文書には、合意済み、除外済み、未解決/意見待ちの項目が整理されます。
+
 ## ホストごとの入口
 
 | ホスト | 自然な入口 |
@@ -101,15 +139,15 @@ Gemini ではリポジトリ直下の [GEMINI.md](GEMINI.md)、[`.gemini/command
 | `/agestra security [target]` | 専用のセキュリティレビューを実行 |
 | `/agestra idea [topic]` | 類似プロジェクトとの比較から改善案を発見 |
 | `/agestra design [subject]` | 実装前にアーキテクチャと設計上のトレードオフを探索 |
-| `/agestra implement [task]` | Claude only または Multi-AI モードで実装を進める |
+| `/agestra implement [task]` | リーダーホスト単独または Multi-AI 分散モードで実装を進める |
 
-外部プロバイダーが利用可能な場合、review、QA、security、design、idea ワークフローは team-lead を通じてマルチ AI クロスバリデーションへルーティングされます。プロバイダーが検出されない場合、現在のホストのローカル specialist agent が自動的に処理します。
+外部プロバイダーが利用可能な場合、review、QA、security、design、idea ワークフローは team-lead を通じてマルチ AI クロスバリデーションへルーティングされます。QA では、team-lead が設定済みプロバイダー集合から QA Brigade を基本構成し、moderator engine の既存 `ITEM-*` / JSON stance ledger に渡します。ホスト QA が実行可能な根拠を集め、プロバイダーは異なる検証レンズを担当し、候補 finding は取り込む前に反証され、統合文書は合意と異論を両方保持します。E2E/browser/runtime 実行は引き続きホスト所有で、外部プロバイダーはその根拠をレビューします。プロバイダーが検出されない場合、現在のホストのローカル specialist agent が自動的に処理します。実装リクエストはまずタスクを分類し、AI タスク分配の提案を行うか確認できます。
 
 ## エージェント
 
 | エージェント | モデル | 役割 |
 |--------------|--------|------|
-| `agestra-team-lead` | Sonnet | フルオーケストレーター — 環境チェック、品質ベースのプロバイダー選択、作業モード選定、CLI ワーカー監督、QA ループ |
+| `agestra-team-lead` | Sonnet | フルオーケストレーター — 環境チェック、能力ベースのプロバイダールーティング、作業モード選定、CLI ワーカー監督、QA ループ |
 | `agestra-implementer` | Sonnet | スコープ付き実装実行役 — コード変更、テスト更新、ローカル検証 |
 | `agestra-e2e-writer` | Sonnet | 永続 E2E テスト作成役 — 承認済みブラウザフローテストのみ作成 |
 | `agestra-reviewer` | Opus | 厳格な品質検証役 — セキュリティ、孤立コード、仕様逸脱、テスト不足を確認 |
@@ -145,13 +183,14 @@ Turborepo モノレポで、8 パッケージ構成です:
 
 | パッケージ | 説明 |
 |------------|------|
-| `@agestra/core` | `AIProvider` インターフェース、難易度ベースのルーティングレジストリ、設定ローダー、CLI ランナー、アトミック書き込み、ジョブキュー、シークレットスキャナー、worktree マネージャー、タスクマニフェスト、CLI ワーカーマネージャー |
+| `@agestra/core` | `AIProvider` インターフェース、能力/難易度メタデータ付き provider descriptor、設定ローダー、CLI ランナー、アトミック書き込み、ジョブキュー、シークレットスキャナー、worktree マネージャー、タスクマニフェスト、CLI ワーカーマネージャー |
+| `@agestra/provider-claude` | Anthropic Claude CLI アダプター |
 | `@agestra/provider-ollama` | モデル検出付き Ollama HTTP アダプター |
 | `@agestra/provider-gemini` | Google Gemini CLI アダプター |
 | `@agestra/provider-codex` | OpenAI Codex CLI アダプター |
 | `@agestra/agents` | 合意検出付きディベートエンジン、ターン品質評価、タスク配分、クロスバリデーション、タスクチェーン、自動 QA、ファイル変更追跡、セッション管理 |
 | `@agestra/workspace` | レビュー、分析メモ、統合レポート向けのワークスペース文書マネージャー |
-| `@agestra/mcp-server` | MCP プロトコル層、44 ツール、環境依存のツールフィルタリング、ディスパッチ |
+| `@agestra/mcp-server` | MCP プロトコル層、45 ツール、環境依存のツールフィルタリング、ディスパッチ |
 
 ### 設計原則
 
@@ -165,37 +204,40 @@ Turborepo モノレポで、8 パッケージ構成です:
 
 ### 作業モード
 
-**Text work**（レビュー、QA、セキュリティ、設計、アイデア）: プロバイダーあり → 徹底討論モード; なし → Claude only
+マルチプロバイダーモード(徹底討論、クロス検証、レビューラウンド)では、あるプロバイダーの出力が次のプロバイダーが受け取るプロンプトの一部となる場合があります。
+
+**テキスト作業**（レビュー、QA、セキュリティ、設計、アイデア）: プロバイダーあり → 構造化ディベート; なし → リーダーホストの専門エージェント
 
-**Implementation work**（team-lead orchestration）:
-- **Claude のみ** — Claude がプロジェクト/グローバルエージェントを使って直接実装します。
-- **他の AI と併用** — CLI ワーカー（Codex/Gemini）が分離された git worktree で自律的にコーディングし、Ollama が簡単なタスクを担当し、Claude が監督・統合します。
+**実装作業**（team-lead orchestration）:
+- **リーダーホストのみ** — 現在のホストの `agestra-implementer` がスコープ付きのコード変更を行います。QA は明示的な host-only 指定がない限り、設定済みプロバイダーに応じて QA Brigade を使えます。
+- **提案型 AI 分散** — リーダーが作業表を提案して承認を得た後、フロンティアモデルとローカルモデルを含む検出済みモデルの能力に応じて作業を分配します。Codex/Gemini CLI ワーカーは適切な自律コード編集を担当し、ローカル/ツールモデルは `executionPolicy` に応じて読み取り専用または読み書き AgentLoop ツールを受け取れます。リーダーが状態、使用量、diff を監督して統合します。
 
 ---
 
-## ツール (44)
+## ツール (45)
 
 ### AI チャット (3)
 
 | ツール | 説明 |
 |--------|------|
-| `ai_chat` | 特定のプロバイダーと対話（品質ベースのルーティングには `"auto"` を使用）。必要に応じて `save_as_document` で応答を文書保存可能 |
+| `ai_chat` | 特定のプロバイダーと対話（観測値がある場合の trace 補助ルーティングには `"auto"` を使用）。必要に応じて `save_as_document` で応答を文書保存可能 |
 | `ai_analyze_files` | ディスク上のファイルを読み込み、質問と一緒にプロバイダーへ送信 |
 | `ai_compare` | 同じプロンプトを複数プロバイダーに送り、応答を比較 |
 
-### エージェントオーケストレーション (14)
+### エージェントオーケストレーション (15)
 
 | ツール | 説明 |
 |--------|------|
 | `agent_debate_start` | 複数プロバイダーによるディベートを開始（非ブロッキング、品質ループ + バリデーターは任意） |
-| `agent_debate_status` | ディベートの状態とトランスクリプトを確認 |
+| `agent_debate_status` | レガシーディベートまたは構造化セッションの進捗、phase、参加者 activity、文書パスを確認 |
 | `agent_debate_create` | ターン制ディベートセッションを作成（debate ID を返す） |
 | `agent_debate_turn` | 1 プロバイダー分のターンを実行。`provider: "claude"` で Claude の独立参加も可能 |
 | `agent_debate_conclude` | ディベートを終了し、最終トランスクリプトを生成 |
-| `agent_debate_structured` | 承認ゲート付きの構造化ディベートを開始。個別レビュー、必要に応じた別名整理、投票集計ラウンドを行い、承認されるまで合成は書かれず `ready-for-approval` で待機 |
-| `agent_debate_approve` | リーダーが `ready-for-approval` セッションを承認。合成ドキュメントを書き出してセッションを終了 |
+| `agent_debate_structured` | 承認ゲート付きの構造化ディベートを開始。個別レビュー、必要に応じた別名整理、JSON 合意ラウンドを行い、リーダーが承認または却下するまで統合文書は書かれません |
+| `agent_debate_approve` | リーダーが `ready-for-approval` セッションを承認。承認済み統合文書を書き出してセッションを終了 |
 | `agent_debate_continue` | `ready-for-approval`（または `escalated`）セッションに追加ラウンド（3/5/10）を実行 |
-| `agent_debate_reject` | 合成を書かずに構造化ディベートセッションを却下 |
+| `agent_debate_reject` | 構造化ディベートセッションを却下し、却下版の統合文書を書き出します。必要に応じて issue 文書も作成 |
+| `agent_debate_submit_turn` | 構造化ディベートの status が `phase: awaiting-host-turn` を報告したとき、ネイティブホスト専門エージェントの turn を送信します。保留中の全 turn が届くとワークフローは自動再開します |
 | `agent_debate_review` | 文書を複数プロバイダーへ送り、独立したレビューを依頼 |
 | `agent_cross_validate` | 出力をクロスバリデーション（agent-tier validators のみ） |
 | `agent_changes_review` | 分離タスクでのファイル変更をレビュー |
@@ -215,7 +257,7 @@ Turborepo モノレポで、8 パッケージ構成です:
 
 | ツール | 説明 |
 |--------|------|
-| `environment_check` | CLI ツール、ティア分類付き Ollama モデル、tmux、git worktree 対応、利用可能モードを検出 |
+| `environment_check` | CLI ツール、ローカルモデル tier、tmux、git worktree 対応、利用可能モードを検出 |
 
 ### ワークスペース (7)
 
@@ -276,7 +318,7 @@ Turborepo モノレポで、8 パッケージ構成です:
 | ツール | 説明 |
 |--------|------|
 | `trace_query` | trace レコードを条件付きで検索（プロバイダー、タスク、期間） |
-| `trace_summary` | プロバイダー別の品質統計、性能指標、難易度資格を取得 |
+| `trace_summary` | プロバイダー別の任意の過去品質観測値と性能指標を取得 |
 | `trace_visualize` | 追跡した操作フローの Mermaid 図を生成 |
 
 ---
@@ -285,7 +327,7 @@ Turborepo モノレポで、8 パッケージ構成です:
 
 ### providers.config.json
 
-`/agestra setup` が生成します。単一のプラグイン範囲の場所に保存されます（解決順: `AGESTRA_CONFIG_PATH` 環境変数 → `$CLAUDE_PLUGIN_ROOT/providers.config.json` → `~/.agestra/providers.config.json`）。リポジトリには置かない方針で、gitignore 済みです。
+`/agestra setup` が生成します。デフォルトの保存先はホスト共有の `~/.agestra/providers.config.json` です。解決順は `AGESTRA_CONFIG_PATH` 環境変数 → 既存の `~/.agestra/providers.config.json` → 既存のレガシー `$CLAUDE_PLUGIN_ROOT/providers.config.json` → 新規書き込み用の `~/.agestra/providers.config.json` です。プロジェクトリポジトリに置くものではなく、gitignore 済みです。
 
 | 項目 | 説明 |
 |------|------|
@@ -294,7 +336,7 @@ Turborepo モノレポで、8 パッケージ構成です:
 | `providers[].id` | 一意の識別子 |
 | `providers[].type` | `ollama`, `gemini-cli`, `codex-cli`, `claude-cli` |
 | `providers[].enabled` | 起動時に登録するか — `false` は明示的オプトアウト |
-| `providers[].executionPolicy` | `read-only` または `workspace-write` |
+| `providers[].executionPolicy` | `read-only`, `workspace-write`, `full-auto`; Ollama はこの値に基づいて読み取り専用または読み書き AgentLoop ツールを受け取ります |
 | `providers[].config` | タイプ別設定（host、timeout など） |
 
 ### ランタイムデータ
@@ -385,12 +427,13 @@ agestra/
 │   └── uninstall-host-mcp.mjs # ホスト登録と管理対象 assets を削除
 ├── packages/
 │   ├── core/                # AIProvider、レジストリ、セキュリティ、ワーカー
+│   ├── provider-claude/     # Anthropic Claude CLI アダプター
 │   ├── provider-ollama/     # Ollama HTTP アダプター
 │   ├── provider-gemini/     # Gemini CLI アダプター
 │   ├── provider-codex/      # Codex CLI アダプター
 │   ├── agents/              # ディベートエンジン、ディスパッチ、クロスバリデーション
 │   ├── workspace/           # ワークスペース文書マネージャー
-│   └── mcp-server/          # MCP サーバー、44 ツール、環境依存フィルタリング、ディスパッチ
+│   └── mcp-server/          # MCP サーバー、45 ツール、環境依存フィルタリング、ディスパッチ
 ├── package.json             # ワークスペースルート
 └── turbo.json               # Turborepo パイプライン
 ```

package/README.ko.md

@@ -3,11 +3,11 @@
 [![npm version](https://img.shields.io/npm/v/agestra.svg)](https://www.npmjs.com/package/agestra)
 [![license](https://img.shields.io/npm/l/agestra.svg)](LICENSE)
 
-**Agent + Orchestra** — Claude Code, Codex CLI, Gemini CLI에서 공통으로 쓰는 멀티 호스트 오케스트레이션 툴킷.
+**Agent + Orchestra** — Claude Code, Codex CLI, Gemini CLI, 로컬 모델을 함께 조율하는 멀티 호스트 MCP 오케스트레이션 툴킷.
 
 [English](README.md) | [한국어](README.ko.md) | [日本語](README.ja.md) | [中文](README.zh.md)
 
-Agestra는 Claude 호스트, Ollama(로컬), Gemini CLI, Codex CLI를 플러그형 공급자로 연결합니다. 독립 취합, 합의 토론, 자율 CLI 워커, 병렬 작업 분배, 교차 검증, 품질 기반 공급자 라우팅을 44개 MCP 도구로 제공합니다.
+Agestra는 Claude 호스트/CLI, Ollama(로컬), Gemini CLI, Codex CLI를 플러그형 공급자로 연결합니다. 독립 취합, 합의 토론, 자율 CLI 워커, 병렬 작업 분배, 교차 검증, 선택적 trace 근거를 참고하는 능력 기반 공급자 라우팅을 45개 MCP 도구로 제공합니다.
 
 ## 빠른 시작
 
@@ -46,10 +46,13 @@ Assets 설치 후 Gemini에서 사용할 수 있는 명령:
 
 | 공급자 | 설치 | 유형 |
 |--------|------|------|
+| [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) | `npm install -g @anthropic-ai/claude-code` | 클라우드 |
 | [Ollama](https://ollama.com/) | `curl -fsSL https://ollama.com/install.sh \| sh` | 로컬 LLM |
 | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `npm install -g @google/gemini-cli` | 클라우드 |
 | [Codex CLI](https://github.com/openai/codex) | `npm install -g @openai/codex` | 클라우드 |
 
+각 CLI는 자체 인증을 관리합니다. 사용하려는 CLI는 미리 해당 CLI의 로그인 절차로 인증해 두세요 — Agestra는 각 CLI를 자식 프로세스로 띄울 뿐 인증 정보에 관여하지 않습니다.
+
 선택 사항이지만 권장:
 - **tmux** — 자율 실행 중 CLI 워커 패인을 시각적으로 확인 가능
 - **Windows의 ripgrep (`rg`)** — Codex가 Store 앱 번들 경로의 `rg`를 잡아서 `Access is denied` 오류가 나면, 별도 ripgrep를 설치해 정상 `rg.exe`가 `PATH`에서 먼저 잡히게 하세요:
@@ -70,6 +73,52 @@ winget install BurntSushi.ripgrep.MSVC
 
 **멀티 AI는 검증을 위한 것이지, 토큰 절약을 위한 것이 아닙니다.** 리뷰, 설계 탐색, 아이디어 발굴 워크플로우는 검증 프로세스로 설계되었습니다 — 속도를 위한 병렬화가 아니라, 사각지대를 잡기 위해 여러 AI 공급자로부터 독립적인 의견을 얻는 것입니다.
 
+## 동작 방식
+
+```mermaid
+flowchart TD
+    Start([사용자가 /agestra 명령 실행]) --> Preflight[설정 상태 / 환경 / 프로바이더 확인]
+    Preflight --> Domain{작업 종류}
+
+    Domain -->|아이디어 / 설계 / 리뷰 / 보안| TextLead[리더가 전문 에이전트와 외부 AI 구성]
+    Domain -->|QA| QaLead[리더가 QA Brigade 구성]
+    Domain -->|구현| ImplLead[리더가 구현 작업 분해]
+
+    ImplLead --> ImplRoute{작업 성격}
+    ImplRoute -->|명확한 병렬 구현| CliWorkers[Codex / Gemini CLI 작업자<br/>격리 worktree에서 구현]
+    ImplRoute -->|능력에 맞는 범위 작업| Ollama[로컬/도구 모델<br/>정책 허용 시 읽기 / 쓰기]
+    ImplRoute -->|위험하거나 핵심 변경| HostImpl[호스트 구현 에이전트<br/>가까운 감독 아래 수정]
+    CliWorkers --> ReviewDiff[리더가 상태 / 사용량 / diff 검토]
+    Ollama --> ReviewDiff
+    HostImpl --> ReviewDiff
+    ReviewDiff --> Merge{수용 가능?}
+    Merge -->|아니오| Reassign[수정 지시 또는 재배정]
+    Reassign --> ImplRoute
+    Merge -->|예| QaEvidence
+
+    QaLead --> QaEvidence[호스트 QA가 실행 증거 수집<br/>빌드 / 테스트 / E2E / 스크린샷]
+    TextLead --> Providers{외부 AI 있음?}
+    QaEvidence --> Providers
+
+    Providers -->|없음| LocalOut[호스트 전문 에이전트가<br/>보고서 / 설계 / 아이디어 문서 작성]
+    Providers -->|있음| Individual[각 AI가 독립 의견 작성]
+    LocalOut --> Final([사용자에게 결과 보고])
+
+    Individual --> Ledger[ITEM-* JSON 합의 장부]
+    Ledger --> Round[순차 라운드<br/>동의 / 반대 / 수정 / 의견]
+    Round --> Gate{정리 상태}
+    Gate -->|더 논의| Round
+    Gate -->|리더 판단 필요| LeaderDecision[리더가 계속 / 승인 / 거절 선택]
+    Gate -->|합의 정리됨| LeaderDecision
+    LeaderDecision -->|계속| Round
+    LeaderDecision -->|승인| Approved[승인 종합 문서 생성]
+    LeaderDecision -->|거절| Rejected[거절 / 불합의 종합 문서 생성]
+    Approved --> Final
+    Rejected --> Final
+```
+
+외부 프로바이더가 구성되어 있지 않으면 합의 라운드는 건너뛰고 호스트 전문 에이전트가 도메인별 산출물(리뷰/QA 보고서, 설계 문서, 아이디어 문서 등)을 만듭니다. 구조화 토론이 열린 경우에는 리더가 승인하든 거절하든 최종 종합 문서를 남기며, 거절 문서에는 합의된 항목과 제외된 항목, 미합의/의견 필요 항목이 함께 정리됩니다.
+
 ## 호스트별 진입 방식
 
 | 호스트 | 자연스러운 진입 방식 |
@@ -90,15 +139,15 @@ winget install BurntSushi.ripgrep.MSVC
 | `/agestra security [대상]` | 전용 보안 리뷰 실행 |
 | `/agestra idea [주제]` | 유사 프로젝트 비교를 통한 개선점 발굴 |
 | `/agestra design [주제]` | 구현 전 아키텍처 및 설계 트레이드오프 탐색 |
-| `/agestra implement [작업]` | Claude only 또는 Multi-AI 모드로 실제 구현 진행 |
+| `/agestra implement [작업]` | 리더 호스트 단독 또는 Multi-AI 분산 모드로 실제 구현 진행 |
 
-외부 공급자가 있으면 review, QA, security, design, idea 워크플로우는 team-lead를 통해 멀티 AI 교차 검증으로 라우팅됩니다. 공급자가 없으면 현재 호스트의 로컬 specialist agent가 자동으로 처리합니다.
+외부 공급자가 있으면 review, QA, security, design, idea 워크플로우는 team-lead를 통해 멀티 AI 교차 검증으로 라우팅됩니다. QA의 경우 team-lead가 기본적으로 설정된 공급자 집합에서 QA Brigade를 구성하고 moderator engine의 기존 `ITEM-*` / JSON stance ledger로 넘깁니다. 호스트 QA는 실행 가능한 근거를 수집하고, 공급자들은 서로 다른 검증 관점을 맡으며, 후보 finding은 포함 전에 반박 검토를 거치고, 종합 문서는 합의와 이견을 함께 보존합니다. E2E/browser/runtime 실행은 계속 호스트가 소유하고 외부 공급자는 그 근거를 검토합니다. 공급자가 없으면 현재 호스트의 로컬 specialist agent가 자동으로 처리합니다. 구현 요청은 먼저 작업을 분류하고 AI 작업 분배 제안 여부를 물을 수 있습니다.
 
 ## 에이전트
 
 | 에이전트 | 모델 | 역할 |
 |----------|------|------|
-| `agestra-team-lead` | Sonnet | 풀 오케스트레이터 — 환경 체크, 품질 기반 공급자 라우팅, 작업 모드 선택, CLI 워커 감독, QA 루프 |
+| `agestra-team-lead` | Sonnet | 풀 오케스트레이터 — 환경 체크, 능력 기반 공급자 라우팅, 작업 모드 선택, CLI 워커 감독, QA 루프 |
 | `agestra-implementer` | Sonnet | 제한된 구현 실행자 — 코드 수정, 테스트 갱신, 로컬 검증 |
 | `agestra-e2e-writer` | Sonnet | 지속 E2E 테스트 작성자 — 승인된 브라우저 플로우 테스트만 작성 |
 | `agestra-reviewer` | Opus | 엄격한 품질 검증 — 보안, 고아 시스템, 스펙 이탈, 테스트 공백 |
@@ -134,13 +183,14 @@ Turborepo 모노레포, 8개 패키지:
 
 | 패키지 | 설명 |
 |--------|------|
-| `@agestra/core` | `AIProvider` 인터페이스, 난이도 기반 라우팅 레지스트리, 설정 로더, CLI 러너, 원자적 쓰기, 작업 큐, 시크릿 스캐너, 워크트리 관리자, 태스크 매니페스트, CLI 워커 관리자 |
+| `@agestra/core` | `AIProvider` 인터페이스, 능력/난이도 메타데이터가 포함된 공급자 descriptor, 설정 로더, CLI 러너, 원자적 쓰기, 작업 큐, 시크릿 스캐너, 워크트리 관리자, 태스크 매니페스트, CLI 워커 관리자 |
+| `@agestra/provider-claude` | Anthropic Claude CLI 어댑터 |
 | `@agestra/provider-ollama` | Ollama HTTP 어댑터 (모델 자동 감지) |
 | `@agestra/provider-gemini` | Google Gemini CLI 어댑터 |
 | `@agestra/provider-codex` | OpenAI Codex CLI 어댑터 |
 | `@agestra/agents` | 합의 검출 토론 엔진, 턴 품질 평가기, 작업 분배기, 교차 검증기, 작업 체인, 자동 QA, 파일 변경 추적기, 세션 관리자 |
 | `@agestra/workspace` | 리뷰, 분석 메모, 통합 보고서를 위한 워크스페이스 문서 관리자 |
-| `@agestra/mcp-server` | MCP 프로토콜 레이어, 44개 도구, 환경별 도구 필터링, 디스패치 |
+| `@agestra/mcp-server` | MCP 프로토콜 레이어, 45개 도구, 환경별 도구 필터링, 디스패치 |
 
 ### 설계 원칙
 
@@ -154,25 +204,27 @@ Turborepo 모노레포, 8개 패키지:
 
 ### 작업 모드
 
-**텍스트 작업** (리뷰, QA, 보안, 설계, 아이디어): 공급자 있으면 → 끝장토론; 없으면 → Claude only
+멀티 프로바이더 모드(끝장토론, 교차 검증, 리뷰 라운드)에서는 한 프로바이더의 출력이 다음 프로바이더가 받는 프롬프트의 일부가 될 수 있습니다.
+
+**텍스트 작업** (리뷰, QA, 보안, 설계, 아이디어): 공급자 있으면 → 구조화 토론; 없으면 → 리더-호스트 전문 에이전트
 
 **구현 작업** (team-lead 오케스트레이션):
-- **Claude만으로** — Claude가 프로젝트/전역 에이전트를 활용해 직접 구현.
-- **다른 AI도 함께** — CLI 워커(Codex/Gemini)가 격리된 git worktree에서 자율 코딩, Ollama가 단순 작업 처리, Claude가 감독 및 병합.
+- **리더-호스트 전용** — 현재 호스트의 `agestra-implementer`가 제한된 코드 변경을 수행합니다. QA는 요청이 없으면 설정된 프로바이더 기준으로 QA Brigade를 사용할 수 있습니다.
+- **제안된 AI 분산** — 리더가 작업표를 제안하고 승인받은 뒤, 감지된 모델(프론티어와 로컬 모델 포함)의 능력에 따라 업무를 분배합니다. Codex/Gemini CLI 워커는 적합한 자율 코드 수정 작업을 맡고, 로컬/도구 모델은 `executionPolicy`에 따라 읽기 전용 또는 읽기/쓰기 AgentLoop 도구를 받을 수 있습니다. 리더가 상태, 사용량, diff를 감독하고 병합합니다.
 
 ---
 
-## 도구 (44개)
+## 도구 (45개)
 
 ### AI 채팅 (3개)
 
 | 도구 | 설명 |
 |------|------|
-| `ai_chat` | 특정 공급자와 채팅 (품질 기반 자동 라우팅: `"auto"`); 필요하면 `save_as_document`로 응답을 문서로 저장 |
+| `ai_chat` | 특정 공급자와 채팅 (`"auto"`는 관측 기록이 있을 때 trace 보조 라우팅 사용); 필요하면 `save_as_document`로 응답을 문서로 저장 |
 | `ai_analyze_files` | 파일을 디스크에서 읽어 공급자에게 질문과 함께 전송 |
 | `ai_compare` | 같은 프롬프트를 여러 공급자에 보내 응답 비교 |
 
-### 에이전트 오케스트레이션 (14개)
+### 에이전트 오케스트레이션 (15개)
 
 | 도구 | 설명 |
 |------|------|
@@ -181,10 +233,11 @@ Turborepo 모노레포, 8개 패키지:
 | `agent_debate_create` | 턴 기반 토론 세션 생성 (토론 ID 반환) |
 | `agent_debate_turn` | 공급자 1턴 실행; `provider: "claude"`로 Claude 독립 참여 지원 |
 | `agent_debate_conclude` | 토론 종료 및 최종 트랜스크립트 생성 |
-| `agent_debate_structured` | 승인 게이트 구조화 토론 시작 — 개별 리뷰, 선택적 별칭 정리, 투표 집계 라운드, 합성은 승인 전까지 작성되지 않음 (`ready-for-approval` 상태로 대기) |
-| `agent_debate_approve` | 리더가 `ready-for-approval` 세션을 승인하여 합성 문서를 작성하고 세션을 종료 |
+| `agent_debate_structured` | 승인 게이트 구조화 토론 시작 — 개별 리뷰, 선택적 별칭 정리, JSON 합의 라운드, 리더가 승인하거나 거절하기 전까지 종합 문서는 작성되지 않음 |
+| `agent_debate_approve` | 리더가 `ready-for-approval` 세션을 승인하여 승인 종합 문서를 작성하고 세션을 종료 |
 | `agent_debate_continue` | `ready-for-approval`(또는 `escalated`) 세션에 추가 라운드(3/5/10) 실행 |
-| `agent_debate_reject` | 합성 없이 구조화 토론 세션 거부 |
+| `agent_debate_reject` | 구조화 토론 세션을 거절하고 거절 종합 문서를 작성하며, 필요하면 별도 issue 문서도 작성 |
+| `agent_debate_submit_turn` | 구조화 토론 상태가 `phase: awaiting-host-turn`을 보고할 때 네이티브 호스트 전문 에이전트 턴을 제출; 모든 대기 턴이 도착하면 워크플로우가 자동 재개됨 |
 | `agent_debate_review` | 문서를 여러 공급자에게 독립적으로 리뷰 요청 |
 | `agent_cross_validate` | 출력 교차 검증 (에이전트 등급 검증자만 가능) |
 | `agent_changes_review` | 격리된 작업의 파일 변경 리뷰 |
@@ -204,7 +257,7 @@ Turborepo 모노레포, 8개 패키지:
 
 | 도구 | 설명 |
 |------|------|
-| `environment_check` | CLI 도구, Ollama 모델 티어, tmux, git worktree 지원 여부, 사용 가능 모드 탐지 |
+| `environment_check` | CLI 도구, 로컬 모델 티어, tmux, git worktree 지원 여부, 사용 가능 모드 탐지 |
 
 ### 워크스페이스 (7개)
 
@@ -265,7 +318,7 @@ Turborepo 모노레포, 8개 패키지:
 | 도구 | 설명 |
 |------|------|
 | `trace_query` | 조건별 추적 레코드 조회 (공급자, 작업, 기간) |
-| `trace_summary` | 공급자별 품질 통계, 성능 지표, 난이도 자격 확인 |
+| `trace_summary` | 공급자별 선택적 과거 품질 관측값과 성능 지표 확인 |
 | `trace_visualize` | 추적된 작업 흐름의 Mermaid 다이어그램 생성 |
 
 ---
@@ -283,7 +336,7 @@ Turborepo 모노레포, 8개 패키지:
 | `providers[].id` | 고유 식별자 |
 | `providers[].type` | `ollama`, `gemini-cli`, `codex-cli`, `claude-cli` |
 | `providers[].enabled` | 시작 시 등록 여부 — `false`면 강제 제외 |
-| `providers[].executionPolicy` | `read-only` 또는 `workspace-write` |
+| `providers[].executionPolicy` | `read-only`, `workspace-write`, `full-auto`; Ollama는 이 값에 따라 읽기 전용 또는 읽기/쓰기 AgentLoop 도구를 받음 |
 | `providers[].config` | 타입별 설정 (host, timeout 등) |
 
 ### 런타임 데이터
@@ -374,12 +427,13 @@ agestra/
 │   └── uninstall-host-mcp.mjs # 호스트 등록과 관리 자산 제거
 ├── packages/
 │   ├── core/                # AIProvider 인터페이스, 레지스트리, 보안, 워커
+│   ├── provider-claude/     # Anthropic Claude CLI 어댑터
 │   ├── provider-ollama/     # Ollama HTTP 어댑터
 │   ├── provider-gemini/     # Gemini CLI 어댑터
 │   ├── provider-codex/      # Codex CLI 어댑터
 │   ├── agents/              # 토론 엔진, 분배기, 교차 검증기
 │   ├── workspace/           # 워크스페이스 문서 관리자
-│   └── mcp-server/          # MCP 서버, 44개 도구, 환경별 필터링, 디스패치
+│   └── mcp-server/          # MCP 서버, 45개 도구, 환경별 필터링, 디스패치
 ├── package.json             # 워크스페이스 루트
 └── turbo.json               # Turborepo 파이프라인
 ```