agestra 4.13.4 → 4.14.0

package/README.ja.md

@@ -3,477 +3,119 @@
 [![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、ローカルモデルを調整するマルチホスト MCP オーケストレーションツールキット。
+Claude Code、Codex CLI、Gemini CLI、ローカルモデルで使えるマルチホスト MCP オーケストレーションです。
 
 [English](README.md) | [한국어](README.ko.md) | [日本語](README.ja.md) | [中文](README.zh.md)
 
-Agestra は Claude host/CLI、Ollama（ローカル）、Gemini CLI、Codex CLI をプラガブルなプロバイダーとして接続し、独立集約、合意形成ディベート、自律 CLI ワーカー、並列タスク配分、クロスバリデーション、任意の trace 根拠を参照する能力ベースのプロバイダールーティングを 45 個の MCP ツールで提供します。
+Agestra は、1 つの作業に複数の AI を使って比較し、整理するためのツールです。コードレビュー、QA、セキュリティ確認、設計相談、アイデア探索、provider-backed 実装向けに作られています。
 
 ## クイックスタート
 
-まず作業するホストを選びます。ホストネイティブのコマンド/エージェントも入れる場合は `--assets` の経路を使い、サーバー接続だけでよい場合は MCP-only 登録を使います。
+今使っているホストに Agestra を入れてください。
 
-| ホスト | このリポジトリから | グローバル 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 |
+| ホスト | インストール |
+|--------|--------------|
+| Claude Code | `/plugin marketplace add mua-vtuber/Agestra` のあと `/plugin install agestra@agestra` |
+| Codex CLI | `npm install -g agestra` のあと `agestra-install codex --assets --scope user` |
+| Gemini CLI | `npm install -g agestra` のあと `agestra-install gemini --assets --scope user` |
 
-MCP-only 登録も利用できます:
+インストール後、プロジェクトを開いて Agestra ワークフローを呼び出します。
 
-| ホスト | リポジトリパッケージ | チェックアウトからのグローバル登録 |
-|--------|----------------------|------------------------------------|
-| Codex CLI | `npm run install:codex` | `npm run install:codex:global` |
-| Gemini CLI | `npm run install:gemini` | `npm run install:gemini:global` |
+- Claude Code: `/agestra review`, `/agestra qa`, `/agestra security`, `/agestra design`, `/agestra idea`, `/agestra implement`
+- Gemini CLI: `/agestra:review`, `/agestra:qa`, `/agestra:security`, `/agestra:design`, `/agestra:idea`, `/agestra:implement`
+- Codex CLI: `Use Agestra with Gemini and Codex to review this branch.` のように、Agestra や複数 AI を明示して依頼
 
-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 を組み合わせます。
+初回は使う provider を聞かれることがあります。provider が 1 つだけでもセットアップやホスト所有の作業はできますが、複数 AI 比較は 2 つ以上あるとより有効です。
 
-注: `npm run install:gemini:assets` はデフォルトで user scope を使います。チェックアウトから project-scope の Gemini 管理ファイルを入れる場合は `node scripts/install-host-mcp.mjs gemini --assets --scope project` を実行してください。
+## 何に使うか
 
-Assets セットアップ後に利用できる Gemini コマンド:
+- `review`: コード品質、回帰リスク、UX、整理ポイントを複数 AI の視点で比較
+- `qa`: 設計書や計画を基準に実装を検証し、PASS/FAIL の根拠を集める
+- `security`: セキュリティ観点に絞って確認する
+- `design`: 実装前に構造やトレードオフを整理する
+- `idea`: 改善案、代替案、類似ツールを探る
+- `implement`: 複数 provider で実装を進め、最後の検証までつなぐ
 
-- `/agestra:setup`
-- `/agestra:review`
-- `/agestra:design`
-- `/agestra:idea`
-- `/agestra:implement`
-- `/agestra:qa`
-- `/agestra:security`
+## 実行すると何が起こるか
 
-### 前提条件
+1. Agestra が設定と利用可能な provider を確認します。
+2. 依頼を対象とスコープが明確なワークフローに整理します。
+3. 調査が必要なら、ホストが先に証拠を集めて整理します。
+4. 選ばれた provider は残っている論点だけをレビューまたは討論します。
+5. 結論、意見の違い、根拠を 1 つの結果として返します。
 
-少なくとも 1 つの AI プロバイダーをインストールしておく必要があります:
+普通のレビューや QA の依頼が自動で Agestra になるわけではありません。`/agestra ...` を使うか、複数 AI や provider-backed 作業を明示したときに Agestra が動きます。
 
-| プロバイダー | インストール | 種類 |
-|-------------|---------------|------|
-| [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 |
+実装と QA では、最後の確認は引き続きホストが担当します。ビルド、テスト、実行証拠、ブラウザフロー、最終的なファイル反映はホスト側で確認します。
 
-各 CLI は自分自身の認証を管理します。使用予定の CLI は、その CLI 固有のログイン手順で事前に認証を済ませてください — Agestra は各 CLI を子プロセスとして起動するだけで、認証情報には関与しません。
+## このリポジトリで使う
 
-任意ですが推奨:
-- **tmux** — 自律実行中の CLI ワーカーペインを可視化できます
-- **Windows の ripgrep (`rg`)** — Codex が Store app bundled path の `rg` を拾って "Access is denied" になる場合は、通常の `rg.exe` が `PATH` で先に見つかるように ripgrep を別途インストールしてください:
+このリポジトリを clone してローカル checkout を試す場合:
 
+```bash
+npm install
+npm run bundle
 ```
-cargo install ripgrep
-```
-
-代替:
 
-```
-winget install BurntSushi.ripgrep.MSVC
-```
+そのあと、使うホストに合わせてインストールします。
 
----
-
-## 理念
-
-**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
+```bash
+npm run install:claude
+npm run install:codex
+npm run install:gemini
 ```
 
-外部プロバイダーが構成されていない場合、Agestra は合意ラウンドをスキップし、ホスト専門エージェントがレビュー/QA レポート、設計文書、アイデア記録などのドメイン別成果物を作成します。構造化ディベートが実行された場合は、リーダーが承認しても却下しても統合文書を残します。却下時の文書には、合意済み、除外済み、未解決/意見待ちの項目が整理されます。
-
-## ホストごとの入口
-
-| ホスト | 自然な入口 |
-|--------|------------|
-| Claude Code | `/agestra setup`, `/agestra review`, `/agestra qa`, `/agestra security`, `/agestra design`, `/agestra idea`, `/agestra implement` |
-| Codex CLI | `AGENTS.md` に沿った自然言語リクエスト |
-| Gemini CLI | `/agestra:setup`, `/agestra:review`, `/agestra:qa`, `/agestra:security`, `/agestra:design`, `/agestra:idea`, `/agestra:implement` |
-
-3 つのホストはすべて同じ MCP サーバーと `commands/*.md` の共通ワークフロー仕様を利用します。
-
-## コマンド
-
-| コマンド | 説明 |
-|----------|------|
-| `/agestra setup` | 初期 AI プロバイダー選択とセットアップ |
-| `/agestra review [target]` | コード品質、セキュリティ、統合の完成度をレビュー |
-| `/agestra qa [target]` | 実装結果を検証し、PASS/FAIL の根拠を生成 |
-| `/agestra security [target]` | 専用のセキュリティレビューを実行 |
-| `/agestra idea [topic]` | 類似プロジェクトとの比較から改善案を発見 |
-| `/agestra design [subject]` | 実装前にアーキテクチャと設計上のトレードオフを探索 |
-| `/agestra implement [task]` | リーダーホスト単独または Multi-AI 分散モードで実装を進める |
-
-外部プロバイダーが利用可能な場合、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-implementer` | Sonnet | スコープ付き実装実行役 — コード変更、テスト更新、ローカル検証 |
-| `agestra-e2e-writer` | Sonnet | 永続 E2E テスト作成役 — 承認済みブラウザフローテストのみ作成 |
-| `agestra-reviewer` | Opus | 厳格な品質検証役 — セキュリティ、孤立コード、仕様逸脱、テスト不足を確認 |
-| `agestra-designer` | Opus | アーキテクチャ探索役 — ソクラテス式質問、トレードオフ分析 |
-| `agestra-ideator` | Sonnet | 改善案発見役 — Web 調査、競合分析 |
-| `agestra-moderator` | Sonnet | マルチモード進行役 — 合意検出付きディベート、独立集約、ドキュメントレビュー、衝突解決 |
-| `agestra-qa` | Opus | QA 検証役 — 設計準拠の確認、PASS/FAIL 判定 |
-| `agestra-security` | Opus | セキュリティレビュー役 — 脅威モデル、認証/データフローリスク、依存関係とシークレット衛生 |
-
-## スキル
-
-| スキル | 説明 |
-|--------|------|
-| `provider-guide` | プロバイダー選択、モード参照、オーケストレーションパイプライン |
-| `worker-manage` | CLI ワーカーの一覧、状態確認、結果回収、停止 |
-| `cancel` | ワーカー、ディベート、チェーン、タスクの安全な停止 |
-| `build-fix` | build/typecheck/lint エラーの自動診断と修正 |
-| `trace` | エージェント実行タイムラインとフローダイアグラムの表示 |
-| `setup` | 初期プロバイダー選択と `providers.config.json` 書き込み |
-| `design` | Multi-AI モード選択を含む設計探索ワークフロー |
-| `idea` | Multi-AI モード選択を含む改善案発見ワークフロー |
-| `review` | Multi-AI モード選択を含むコード品質・セキュリティ・ハードコーディングレビューワークフロー |
-| `qa` | 設計契約検証と PASS/FAIL 根拠生成ワークフロー |
-| `security` | 専用セキュリティレビューワークフロー |
-| `e2e` | 永続ブラウザ E2E テスト作成ワークフロー |
-| `leader` | マルチAI/プロバイダーオーケストレーションのエントリーポイント — 明示的なプロバイダー、ディベート、合意形成、相互検証シグナルを検知し、ドメイン分類後 `agestra-team-lead` へ委譲 |
-
----
-
-## アーキテクチャ
-
-Turborepo モノレポで、8 パッケージ構成です:
-
-| パッケージ | 説明 |
-|------------|------|
-| `@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 プロトコル層、45 ツール、環境依存のツールフィルタリング、ディスパッチ |
-
-### 設計原則
-
-- **Provider abstraction** — すべてのバックエンドは `AIProvider`（`chat`, `healthCheck`, `getCapabilities`）を実装します。新規プロバイダー追加は専用パッケージとファクトリ登録に分離されます。
-- **Zero-config** — プロバイダーは起動時に自動検出されます。手動設定は不要です。
-- **Host-native** — Claude はプラグインバンドル、Codex は `AGENTS.md` と custom agents、Gemini は `GEMINI.md`、commands、skills、または native extension を使います。すべてのホストは同じ MCP サーバーとワークフローコアを共有します。
-- **Modular dispatch** — 各ツールカテゴリは `getTools()` + `handleTool()` を持つ独立モジュールです。サーバーが動的に収集してディスパッチします。
-- **Atomic writes** — すべてのファイル操作は一時ファイルへの書き込み後に rename する方式で、破損を防ぎます。
-- **Dead-end tracking** — 失敗したアプローチは記録され、今後のプロンプトに注入されます。
-- **Preflight security** — CLI ワーカー起動前にシークレットスキャンと配列ベース引数を使い、インジェクションを防ぎます。
-
-### 作業モード
-
-マルチプロバイダーモード(徹底討論、クロス検証、レビューラウンド)では、あるプロバイダーの出力が次のプロバイダーが受け取るプロンプトの一部となる場合があります。
-
-**テキスト作業**（レビュー、QA、セキュリティ、設計、アイデア）: プロバイダーあり → 構造化ディベート; なし → リーダーホストの専門エージェント
-
-**実装作業**（team-lead orchestration）:
-- **リーダーホストのみ** — 現在のホストの `agestra-implementer` がスコープ付きのコード変更を行います。QA は明示的な host-only 指定がない限り、設定済みプロバイダーに応じて QA Brigade を使えます。
-- **提案型 AI 分散** — リーダーが作業表を提案して承認を得た後、フロンティアモデルとローカルモデルを含む検出済みモデルの能力に応じて作業を分配します。Codex/Gemini CLI ワーカーは適切な自律コード編集を担当し、ローカル/ツールモデルは `executionPolicy` に応じて読み取り専用または読み書き AgentLoop ツールを受け取れます。リーダーが状態、使用量、diff を監督して統合します。
-
----
-
-## ツール (45)
-
-### AI チャット (3)
-
-| ツール | 説明 |
-|--------|------|
-| `ai_chat` | 特定のプロバイダーと対話（観測値がある場合の trace 補助ルーティングには `"auto"` を使用）。必要に応じて `save_as_document` で応答を文書保存可能 |
-| `ai_analyze_files` | ディスク上のファイルを読み込み、質問と一緒にプロバイダーへ送信 |
-| `ai_compare` | 同じプロンプトを複数プロバイダーに送り、応答を比較 |
-
-### エージェントオーケストレーション (15)
-
-| ツール | 説明 |
-|--------|------|
-| `agent_debate_start` | 複数プロバイダーによるディベートを開始（非ブロッキング、品質ループ + バリデーターは任意） |
-| `agent_debate_status` | レガシーディベートまたは構造化セッションの進捗、phase、参加者 activity、文書パスを確認 |
-| `agent_debate_create` | ターン制ディベートセッションを作成（debate ID を返す） |
-| `agent_debate_turn` | 1 プロバイダー分のターンを実行。`provider: "claude"` で Claude の独立参加も可能 |
-| `agent_debate_conclude` | ディベートを終了し、最終トランスクリプトを生成 |
-| `agent_debate_structured` | 承認ゲート付きの構造化ディベートを開始。個別レビュー、必要に応じた別名整理、JSON 合意ラウンドを行い、リーダーが承認または却下するまで統合文書は書かれません |
-| `agent_debate_approve` | リーダーが `ready-for-approval` セッションを承認。承認済み統合文書を書き出してセッションを終了 |
-| `agent_debate_continue` | `ready-for-approval`（または `escalated`）セッションに追加ラウンド（3/5/10）を実行 |
-| `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` | 分離タスクでのファイル変更をレビュー |
-| `agent_changes_accept` | 分離タスクでの変更を受け入れてマージ |
-| `agent_changes_reject` | 変更を却下し、分離 worktree をクリーンアップ |
-
-### CLI ワーカー (4)
-
-| ツール | 説明 |
-|--------|------|
-| `cli_worker_spawn` | CLI AI（Codex/Gemini）を自律モードで起動。git worktree 分離と事前セキュリティチェック付き |
-| `cli_worker_status` | ワーカーの FSM 状態、heartbeat、出力末尾を確認 |
-| `cli_worker_collect` | 完了したワーカーの結果（git diff、出力、終了コード）を回収 |
-| `cli_worker_stop` | 実行中のワーカーを停止（SIGTERM → SIGKILL）し、worktree をクリーンアップ |
-
-### 環境 (1)
-
-| ツール | 説明 |
-|--------|------|
-| `environment_check` | CLI ツール、ローカルモデル tier、tmux、git worktree 対応、利用可能モードを検出 |
-
-### ワークスペース (7)
-
-| ツール | 説明 |
-|--------|------|
-| `workspace_create_review` | 対象ファイルとルール付きのコードレビュー文書を作成 |
-| `workspace_request_review` | プロバイダーに文書レビューを依頼 |
-| `workspace_review_status` | レビュー完了状態を確認 |
-| `workspace_add_comment` | レビューにコメントを追加 |
-| `workspace_create_document` | タイトル、Markdown 本文、任意メタデータを持つ汎用ワークスペース文書を作成 |
-| `workspace_read` | 文書内容を読む |
-| `workspace_list` | ワークスペース内のすべての文書を一覧表示 |
-
-### プロバイダー管理 (2)
-
-| ツール | 説明 |
-|--------|------|
-| `provider_list` | 状態と機能付きでプロバイダー一覧を表示 |
-| `provider_health` | 1 つまたはすべてのプロバイダーのヘルスチェック |
-
-### セットアップ (2)
-
-| ツール | 説明 |
-|--------|------|
-| `setup_status` | 利用可能なプロバイダーと現在の設定状態を確認 |
-| `setup_apply` | 選択したプロバイダー、ロケール、選択ポリシーを `providers.config.json` に書き込む |
-
-### ホストアセット (3)
-
-| ツール | 説明 |
-|--------|------|
-| `host_assets_status` | Codex custom agents や Gemini assets などの生成済みホストネイティブアセットを確認 |
-| `host_assets_install` | 管理対象のホストネイティブアセットを明示的にインストールまたは更新 |
-| `host_assets_uninstall` | Agestra が追跡する管理対象ホストネイティブアセットを削除 |
-
-### Ollama (2)
-
-| ツール | 説明 |
-|--------|------|
-| `ollama_models` | インストール済みモデルをサイズとティア分類付きで一覧表示 |
-| `ollama_pull` | モデルをダウンロード |
-
-### ジョブ (2)
-
-| ツール | 説明 |
-|--------|------|
-| `cli_job_submit` | 長時間実行する CLI タスクをバックグラウンドに投入 |
-| `cli_job_status` | ジョブの状態と出力を確認 |
+これらのコマンドは現在の checkout を登録し、helper assets をインストールします。npm のグローバルインストールではありません。
 
-### QA (1)
+現在の checkout をグローバルパッケージのように使いたい場合:
 
-| ツール | 説明 |
-|--------|------|
-| `qa_run` | 検出した build/test コマンドで自動 QA を実行し、PASS/FAIL を要約 |
-
-### トレース / 可観測性 (3)
-
-| ツール | 説明 |
-|--------|------|
-| `trace_query` | trace レコードを条件付きで検索（プロバイダー、タスク、期間） |
-| `trace_summary` | プロバイダー別の任意の過去品質観測値と性能指標を取得 |
-| `trace_visualize` | 追跡した操作フローの Mermaid 図を生成 |
-
----
-
-## 設定
-
-### providers.config.json
-
-`/agestra setup` が生成します。デフォルトの保存先はホスト共有の `~/.agestra/providers.config.json` です。解決順は `AGESTRA_CONFIG_PATH` 環境変数 → 既存の `~/.agestra/providers.config.json` → 既存のレガシー `$CLAUDE_PLUGIN_ROOT/providers.config.json` → 新規書き込み用の `~/.agestra/providers.config.json` です。プロジェクトリポジトリに置くものではなく、gitignore 済みです。
-
-| 項目 | 説明 |
-|------|------|
-| `selectionPolicy` | `"default-only"`（現状サポートされる唯一の値） |
-| `locale` | モデレーターの UI ロケール (`ko`/`en`/`ja`/`zh`) |
-| `providers[].id` | 一意の識別子 |
-| `providers[].type` | `ollama`, `gemini-cli`, `codex-cli`, `claude-cli` |
-| `providers[].enabled` | 起動時に登録するか — `false` は明示的オプトアウト |
-| `providers[].executionPolicy` | `read-only`, `workspace-write`, `full-auto`; Ollama はこの値に基づいて読み取り専用または読み書き AgentLoop ツールを受け取ります |
-| `providers[].config` | タイプ別設定（host、timeout など） |
-
-### ランタイムデータ
+```bash
+npm run bundle
+npm install -g .
+npm run install:codex:global
+```
 
-`.agestra/` 配下に保存されます（gitignore 対象）:
+Gemini では `npm run install:gemini:global` を使ってください。
 
-| パス | 用途 |
-|------|------|
-| `.agestra/sessions/` | ディベートとタスクのセッション状態 |
-| `.agestra/workspace/` | ワークスペース文書（レビュー、メモ、レポート） |
-| `.agestra/.jobs/` | バックグラウンドジョブキュー |
-| `.agestra/.workers/` | CLI ワーカー状態、マニフェスト、出力ログ |
-| `.agestra/worktrees/` | 分離 CLI ワーカー実行用 git worktree |
-| `.agestra/traces/` | プロバイダートレース JSONL（30 日後に自動削除） |
+## 参考ドキュメント
 
----
+- [docs/tool-inventory.md](docs/tool-inventory.md): MCP ツール一覧
+- [commands/](commands): ワークフロー仕様
+- [docs/plans/](docs/plans): 設計と実装の計画メモ
 
 ## 開発
 
 ```bash
-npm install        # 依存関係をインストール
-npm run build      # 全パッケージをビルド（Turborepo）
-npm test           # 全テストを実行（Vitest）
-npm run bundle     # 単一ファイルのプラグインバンドルを作成（esbuild）
-npm run dev        # ウォッチモード
-npm run lint       # Lint（ESLint）
-npm run clean      # dist/ を削除
+npm run build
+npm test
+npm run bundle
+npm run lint
 ```
 
-### プロジェクト構成
-
-```
-agestra/
-├── AGENTS.md               # Codex ホスト向け指示
-├── GEMINI.md               # Gemini ホスト向け指示
-├── .claude-plugin/
-│   ├── plugin.json          # Claude Code プラグインマニフェスト
-│   └── marketplace.json     # プラグインマーケットプレイスのメタデータ
-├── .gemini/
-│   └── commands/
-│       └── agestra/
-│           ├── setup.toml   # Gemini CLI の /agestra:setup
-│           ├── review.toml  # Gemini CLI の /agestra:review
-│           ├── design.toml  # Gemini CLI の /agestra:design
-│           ├── idea.toml    # Gemini CLI の /agestra:idea
-│           ├── implement.toml # Gemini CLI の /agestra:implement
-│           ├── qa.toml      # Gemini CLI の /agestra:qa
-│           └── security.toml # Gemini CLI の /agestra:security
-├── commands/
-│   ├── setup.md             # /agestra setup — プロバイダー設定
-│   ├── review.md            # /agestra review — 品質検証
-│   ├── qa.md                # /agestra qa — PASS/FAIL 検証
-│   ├── security.md          # /agestra security — セキュリティレビュー
-│   ├── idea.md              # /agestra idea — 改善案探索
-│   ├── design.md            # /agestra design — アーキテクチャ探索
-│   └── implement.md         # /agestra implement — 実装ワークフロー
-├── agents/
-│   ├── agestra-implementer.md # スコープ付き実装実行役（Sonnet）
-│   ├── agestra-e2e-writer.md # 永続 E2E テスト作成役（Sonnet）
-│   ├── agestra-reviewer.md  # 厳格な品質検証役（Opus）
-│   ├── agestra-designer.md  # アーキテクチャ探索役（Opus）
-│   ├── agestra-ideator.md   # 改善案発見役（Sonnet）
-│   ├── agestra-moderator.md # マルチモード進行役（Sonnet）
-│   ├── agestra-qa.md        # QA 検証役（Opus、コード書き込みなし）
-│   ├── agestra-security.md  # セキュリティレビュー役（Opus）
-│   └── agestra-team-lead.md # フルオーケストレーター（Sonnet、コード書き込みなし）
-├── skills/
-│   ├── provider-guide.md    # プロバイダー選択とモード参照
-│   ├── worker-manage.md     # CLI ワーカー管理
-│   ├── cancel.md            # 安全な操作キャンセル
-│   ├── build-fix.md         # ビルドエラー自動修復
-│   ├── trace.md             # 実行タイムラインビューア
-│   ├── setup.md             # 初期プロバイダー選択
-│   ├── design.md            # 設計探索ワークフロー
-│   ├── idea.md              # 改善案発見ワークフロー
-│   ├── review.md            # コード品質レビューワークフロー
-│   ├── qa.md                # 設計契約 QA ワークフロー
-│   ├── security.md          # 専用セキュリティレビューワークフロー
-│   ├── e2e.md               # 永続 E2E テスト作成ワークフロー
-│   └── leader.md            # マルチAIオーケストレーションルーター
-├── hooks/
-│   └── user-prompt-submit.md  # ツール推奨フック
-├── dist/
-│   └── bundle.js            # 単一ファイル MCP サーバーバンドル
-├── scripts/
-│   ├── bundle.mjs           # esbuild バンドルスクリプト
-│   ├── install-host-mcp.mjs # Claude/Codex/Gemini の MCP + host assets を登録
-│   └── 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 サーバー、45 ツール、環境依存フィルタリング、ディスパッチ
-├── package.json             # ワークスペースルート
-└── turbo.json               # Turborepo パイプライン
-```
-
-### プロバイダー追加
-
-1. `packages/provider-<name>/` を作成して `AIProvider` を実装します。
-2. `packages/mcp-server/src/index.ts` にファクトリを追加します。
-3. `npm run build && npm test`
-
----
-
 ## アンインストール
 
 Claude Code:
 
-```
+```text
 /plugin uninstall agestra@agestra
 ```
 
 Codex CLI:
 
-```
+```bash
 npm run uninstall:codex
 npm run uninstall:codex:assets
 ```
 
 Gemini CLI:
 
-```
+```bash
 npm run uninstall:gemini
 npm run uninstall:gemini:assets
 ```
 
-`*:assets` のアンインストールは、ホスト登録と未変更の生成済みホスト資産を一緒に削除します。Codex assets は custom-agent ファイルです。Gemini project-scope assets は管理ファイルで、Gemini user-scope assets は `gemini extensions uninstall agestra` で削除されます。ユーザーが生成済み資産を編集していた場合、Agestra はそのファイルを残して報告します。グローバル npm インストールでは `agestra-uninstall codex --assets` または `agestra-uninstall gemini --assets --scope user` を使ってください。
-
-生成済みのプロジェクトデータも削除したい場合は、`.agestra/` ディレクトリを手動で削除してください。
-
----
+生成されたプロジェクトデータも消したい場合は `.agestra/` を手動で削除してください。
 
-## ライセンス
+## License
 
 [GPL-3.0](LICENSE)