agestra 4.4.2 → 4.5.2

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "agestra",
       "source": "./",
       "description": "Orchestrate Ollama, Gemini, and Codex for multi-AI debates, cross-validation, and GraphRAG memory",
-      "version": "4.4.2",
+      "version": "4.5.2",
       "author": {
         "name": "mua-vtuber"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agestra",
-  "version": "4.4.2",
+  "version": "4.5.2",
   "description": "Claude Code plugin — orchestrate Ollama, Gemini, and Codex for multi-AI debates, cross-validation, and GraphRAG memory",
   "mcpServers": {
     "agestra": {

package/.gemini/commands/agestra/design.toml

@@ -0,0 +1,16 @@
+description = "Run the Agestra design workflow for an architecture or implementation topic."
+prompt = """
+You are executing the Agestra design workflow inside Gemini CLI.
+
+User topic:
+{{args}}
+
+Use the shared workflow spec below as the source of truth and adapt it to the current Gemini host session:
+@{commands/design.md}
+
+Gemini-specific rules:
+- Start with `environment_check` and `provider_list`.
+- Prefer Agestra MCP tools, workspace documents, and debate flows over free-form brainstorming.
+- Translate Claude-specific wording into leader-host wording when Gemini is the active host.
+- Keep the final answer in the user's language.
+"""

package/.gemini/commands/agestra/idea.toml

@@ -0,0 +1,16 @@
+description = "Run the Agestra idea workflow to discover improvements or compare options."
+prompt = """
+You are executing the Agestra idea workflow inside Gemini CLI.
+
+User topic:
+{{args}}
+
+Use the shared workflow spec below as the source of truth and adapt it to the current Gemini host session:
+@{commands/idea.md}
+
+Gemini-specific rules:
+- Start with `environment_check` and `provider_list`.
+- Prefer Agestra MCP tools, workspace documents, and provider comparisons over one-shot brainstorming.
+- Translate Claude-specific wording into leader-host wording when Gemini is the active host.
+- Keep the final answer in the user's language.
+"""

package/.gemini/commands/agestra/implement.toml

@@ -0,0 +1,16 @@
+description = "Run the Agestra implementation workflow with leader-only or multi-provider execution."
+prompt = """
+You are executing the Agestra implementation workflow inside Gemini CLI.
+
+User task:
+{{args}}
+
+Use the shared workflow spec below as the source of truth and adapt it to the current Gemini host session:
+@{commands/implement.md}
+
+Gemini-specific rules:
+- Start with `environment_check` and `provider_list`.
+- Prefer Agestra MCP tools and worker orchestration over ad-hoc shell-heavy implementation plans.
+- Translate Claude-specific wording into leader-host wording when Gemini is the active host.
+- Keep the final answer in the user's language.
+"""

package/.gemini/commands/agestra/review.toml

@@ -0,0 +1,16 @@
+description = "Run the Agestra review workflow for a target, diff, or feature."
+prompt = """
+You are executing the Agestra review workflow inside Gemini CLI.
+
+User target:
+{{args}}
+
+Use the shared workflow spec below as the source of truth and adapt it to the current Gemini host session:
+@{commands/review.md}
+
+Gemini-specific rules:
+- Start with `environment_check` and `provider_list`.
+- Prefer Agestra MCP tools and prompt assets over ad-hoc review prompting.
+- If the workflow refers to Claude-specific wording, translate it to the current leader-host path rather than asking the user to switch hosts.
+- Keep the final answer in the user's language.
+"""

package/AGENTS.md

@@ -0,0 +1,36 @@
+# Agestra for Codex
+
+This repository includes a Codex-friendly host wrapper for Agestra.
+
+## First Run
+
+1. Build the bundled MCP server if needed: `npm run bundle`
+2. Register Agestra with Codex once per machine: `npm run install:codex`
+3. Open this repository in Codex. This `AGENTS.md` file is loaded automatically.
+
+## How to Work Here
+
+- Treat `commands/*.md` as the source of truth for Agestra workflows.
+- When the user asks for review, design, idea, or implementation help, start with `environment_check` and `provider_list`.
+- Prefer Agestra MCP tools over ad-hoc multi-provider prompting.
+- If a workflow mentions "Claude only", interpret that as the current leader-host-only path when Claude is not the active host.
+
+## Workflow Mapping
+
+- Review requests: follow `commands/review.md`
+- Design and architecture requests: follow `commands/design.md`
+- Idea discovery requests: follow `commands/idea.md`
+- Implementation requests: follow `commands/implement.md`
+
+## Core MCP Tools
+
+- `environment_check` and `provider_list`: inspect host/provider state first
+- `agent_debate_moderate` and `agent_debate_review`: run structured multi-provider review flows
+- `cli_worker_spawn`, `agent_changes_review`, `agent_changes_accept`, `agent_changes_reject`: use for autonomous Codex/Gemini worker tasks
+- `qa_run`: verify implementation before reporting completion
+
+## Project Assets
+
+- `agents/`: canonical role prompts (`agestra-team-lead`, `agestra-reviewer`, etc.)
+- `skills/`: reusable workflow references
+- `GEMINI.md` and `.gemini/commands/`: Gemini-specific host assets; keep behavior aligned with them when updating shared workflows

package/GEMINI.md

@@ -0,0 +1,34 @@
+# Agestra for Gemini CLI
+
+This repository includes Gemini-native wrapper assets for Agestra.
+
+## First Run
+
+1. Build the bundled MCP server if needed: `npm run bundle`
+2. Register Agestra with Gemini in this project: `npm run install:gemini`
+3. Open the repository in Gemini CLI. `GEMINI.md` and `.gemini/commands/` are loaded automatically.
+
+## Project Commands
+
+After setup, Gemini project commands are available:
+
+- `/agestra:review`
+- `/agestra:design`
+- `/agestra:idea`
+- `/agestra:implement`
+
+Each command delegates to the shared workflow specs in `commands/*.md`.
+
+## Usage Rules
+
+- Start orchestration requests with `environment_check` and `provider_list`.
+- Prefer Agestra MCP tools instead of rebuilding workflows in free-form prompts.
+- Treat `commands/*.md` and `agents/*.md` as the canonical workflow and role assets.
+- If a shared workflow mentions "Claude only", translate that to the current leader-host-only path when Gemini is the active host.
+
+## Core MCP Tools
+
+- `agent_debate_moderate`, `agent_debate_review`: structured multi-provider reviews and debates
+- `cli_worker_spawn`, `agent_changes_review`, `agent_changes_accept`, `agent_changes_reject`: autonomous worker lifecycle
+- `workspace_*`: document-backed review and aggregation flows
+- `qa_run`: final verification step before completion

package/README.ja.md

@@ -3,7 +3,7 @@
 [![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 上で複数の AI プロバイダーをオーケストレーションするプラグイン。
+**Agent + Orchestra** — Claude Code、Codex CLI、Gemini CLI で共通利用できるマルチホスト・オーケストレーションツールキット。
 
 [English](README.md) | [한국어](README.ko.md) | [日本語](README.ja.md) | [中文](README.zh.md)
 
@@ -11,14 +11,39 @@ Agestra は Ollama（ローカル）、Gemini CLI、Codex CLI を Claude Code
 
 ## クイックスタート
 
-Claude Code で次を実行します:
+### Claude Code
 
 ```
 /plugin marketplace add mua-vtuber/Agestra
 /plugin install agestra@agestra
 ```
 
-これだけです。Agestra は初回利用時に `environment_check` を通じて利用可能なプロバイダー（Ollama、Gemini CLI、Codex CLI）を自動検出します。
+Claude では既存のプラグイン UX をそのまま維持します。Agestra は初回利用時に `environment_check` を通じて利用可能なプロバイダー（Claude host、Ollama、Gemini CLI、Codex CLI）を自動検出します。
+
+### Codex CLI
+
+```
+npm run bundle
+npm run install:codex
+```
+
+Codex ではリポジトリ直下の [AGENTS.md](AGENTS.md) と、登録済みの `agestra` MCP サーバーを一緒に使います。
+
+### Gemini CLI
+
+```
+npm run bundle
+npm run install:gemini
+```
+
+Gemini ではリポジトリ直下の [GEMINI.md](GEMINI.md) と、[`.gemini/commands/agestra/`](.gemini/commands/agestra) のプロジェクトコマンドを一緒に使います。
+
+セットアップ後に利用できる Gemini コマンド:
+
+- `/agestra:review`
+- `/agestra:design`
+- `/agestra:idea`
+- `/agestra:implement`
 
 ### 前提条件
 
@@ -39,6 +64,16 @@ Claude Code で次を実行します:
 
 **Multi-AI はトークン節約のためではなく、検証のために使います。** レビュー、設計探索、アイデア創出のワークフローは、速度のための並列化ではなく、複数の AI プロバイダーから独立した視点を集めて見落としを防ぐ検証プロセスとして設計されています。
 
+## ホストごとの入口
+
+| ホスト | 自然な入口 |
+|--------|------------|
+| Claude Code | `/agestra review`, `/agestra design`, `/agestra idea`, `/agestra implement` |
+| Codex CLI | `AGENTS.md` に沿った自然言語リクエスト |
+| Gemini CLI | `/agestra:review`, `/agestra:design`, `/agestra:idea`, `/agestra:implement` |
+
+3 つのホストはすべて同じ MCP サーバーと `commands/*.md` の共通ワークフロー仕様を利用します。
+
 ## コマンド
 
 | コマンド | 説明 |
@@ -100,7 +135,7 @@ Turborepo モノレポで、8 パッケージ構成です:
 
 - **Provider abstraction** — すべてのバックエンドは `AIProvider`（`chat`, `healthCheck`, `getCapabilities`）を実装します。新規プロバイダー追加は専用パッケージとファクトリ登録に分離されます。
 - **Zero-config** — プロバイダーは起動時に自動検出されます。手動設定は不要です。
-- **Plugin-native** — Claude Code プラグインとして配布され、Skills、hooks、MCP サーバーがひとまとめになっています。
+- **Host-native** — Claude はプラグインバンドル、Codex は `AGENTS.md`、Gemini は `GEMINI.md` とプロジェクトコマンドを使いますが、内部の MCP サーバーとワークフローコアは共通です。
 - **Modular dispatch** — 各ツールカテゴリは `getTools()` + `handleTool()` を持つ独立モジュールです。サーバーが動的に収集してディスパッチします。
 - **Atomic writes** — すべてのファイル操作は一時ファイルへの書き込み後に rename する方式で、破損を防ぎます。
 - **Dead-end tracking** — 失敗したアプローチは GraphRAG に記録され、今後のプロンプトに注入されます。
@@ -135,7 +170,7 @@ Turborepo モノレポで、8 パッケージ構成です:
 | `agent_debate_create` | ターン制ディベートセッションを作成（debate ID を返す） |
 | `agent_debate_turn` | 1 プロバイダー分のターンを実行。`provider: "claude"` で Claude の独立参加も可能 |
 | `agent_debate_conclude` | ディベートを終了し、最終トランスクリプトを生成 |
-| `agent_debate_moderate` | 完全自動のディベートを実行。セッション作成、専門エージェントによるラウンド、合意検出を行い、要約のみ返す |
+| `agent_debate_moderate` | 完全自動のディベートを実行。セッション作成、provider ラウンドの実行、専門エージェント選定の記録、合意検出を行い、要約のみ返す |
 | `agent_debate_review` | 文書を複数プロバイダーへ送り、独立したレビューを依頼 |
 | `agent_cross_validate` | 出力をクロスバリデーション（agent-tier validators のみ） |
 | `agent_changes_review` | 分離タスクでのファイル変更をレビュー |
@@ -263,9 +298,18 @@ npm run clean      # dist/ を削除
 
 ```
 agestra/
+├── AGENTS.md               # Codex ホスト向け指示
+├── GEMINI.md               # Gemini ホスト向け指示
 ├── .claude-plugin/
 │   ├── plugin.json          # Claude Code プラグインマニフェスト
 │   └── marketplace.json     # プラグインマーケットプレイスのメタデータ
+├── .gemini/
+│   └── commands/
+│       └── agestra/
+│           ├── review.toml  # Gemini CLI の /agestra:review
+│           ├── design.toml  # Gemini CLI の /agestra:design
+│           ├── idea.toml    # Gemini CLI の /agestra:idea
+│           └── implement.toml # Gemini CLI の /agestra:implement
 ├── commands/
 │   ├── review.md            # /agestra review — 品質検証
 │   ├── idea.md              # /agestra idea — 改善案探索
@@ -289,7 +333,9 @@ agestra/
 ├── dist/
 │   └── bundle.js            # 単一ファイル MCP サーバーバンドル
 ├── scripts/
-│   └── bundle.mjs           # esbuild バンドルスクリプト
+│   ├── bundle.mjs           # esbuild バンドルスクリプト
+│   ├── install-host-mcp.mjs # Codex/Gemini に Agestra を登録
+│   └── uninstall-host-mcp.mjs # Codex/Gemini から Agestra 登録を削除
 ├── packages/
 │   ├── core/                # AIProvider、レジストリ、セキュリティ、ワーカー
 │   ├── provider-ollama/     # Ollama HTTP アダプター
@@ -313,13 +359,25 @@ agestra/
 
 ## アンインストール
 
-Claude Code で:
+Claude Code:
 
 ```
 /plugin uninstall agestra@agestra
 ```
 
-プラグイン自体はきれいに削除されます。生成済みのプロジェクトデータも削除したい場合は、`.agestra/` ディレクトリを手動で削除してください。
+Codex CLI:
+
+```
+npm run uninstall:codex
+```
+
+Gemini CLI:
+
+```
+npm run uninstall:gemini
+```
+
+生成済みのプロジェクトデータも削除したい場合は、`.agestra/` ディレクトリを手動で削除してください。
 
 ---
 

package/README.ko.md

@@ -3,22 +3,47 @@
 [![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** — 여러 AI 공급자를 Claude Code에서 오케스트레이션하는 플러그인.
+**Agent + Orchestra** — Claude Code, Codex CLI, Gemini CLI에서 공통으로 쓰는 멀티 호스트 오케스트레이션 툴킷.
 
 [English](README.md) | [한국어](README.ko.md) | [日本語](README.ja.md) | [中文](README.zh.md)
 
-Agestra는 Ollama(로컬), Gemini CLI, Codex CLI를 Claude Code에 플러그형으로 연결합니다. 독립 취합, 합의 토론, 자율 CLI 워커, 병렬 작업 분배, 교차 검증, 품질 기반 공급자 라우팅, 지속적 GraphRAG 메모리 시스템을 42개 MCP 도구로 제공합니다.
+Agestra는 Claude 호스트, Ollama(로컬), Gemini CLI, Codex CLI를 플러그형 공급자로 연결합니다. 독립 취합, 합의 토론, 자율 CLI 워커, 병렬 작업 분배, 교차 검증, 품질 기반 공급자 라우팅, 지속적 GraphRAG 메모리 시스템을 42개 MCP 도구로 제공합니다.
 
-## 빠른 시작
-
-Claude Code에서 실행:
-
-```
-/plugin marketplace add mua-vtuber/Agestra
-/plugin install agestra@agestra
-```
-
-끝. Agestra가 첫 사용 시 `environment_check`로 사용 가능한 공급자(Ollama, Gemini CLI, Codex CLI)를 자동 감지합니다.
+## 빠른 시작
+
+### Claude Code
+
+```
+/plugin marketplace add mua-vtuber/Agestra
+/plugin install agestra@agestra
+```
+
+Claude는 기존 플러그인 설치 UX를 그대로 유지합니다. Agestra가 첫 사용 시 `environment_check`로 사용 가능한 공급자(Claude 호스트, Ollama, Gemini CLI, Codex CLI)를 자동 감지합니다.
+
+### Codex CLI
+
+```
+npm run bundle
+npm run install:codex
+```
+
+Codex는 저장소 루트의 [AGENTS.md](AGENTS.md)와 등록된 `agestra` MCP 서버를 함께 사용합니다.
+
+### Gemini CLI
+
+```
+npm run bundle
+npm run install:gemini
+```
+
+Gemini는 저장소 루트의 [GEMINI.md](GEMINI.md)와 [`.gemini/commands/agestra/`](.gemini/commands/agestra) 프로젝트 커맨드를 함께 사용합니다.
+
+설치 후 Gemini에서 사용할 수 있는 명령:
+
+- `/agestra:review`
+- `/agestra:design`
+- `/agestra:idea`
+- `/agestra:implement`
 
 ### 사전 요구사항
 
@@ -39,7 +64,17 @@ Claude Code에서 실행:
 
 **멀티 AI는 검증을 위한 것이지, 토큰 절약을 위한 것이 아닙니다.** 리뷰, 설계 탐색, 아이디어 발굴 워크플로우는 검증 프로세스로 설계되었습니다 — 속도를 위한 병렬화가 아니라, 사각지대를 잡기 위해 여러 AI 공급자로부터 독립적인 의견을 얻는 것입니다.
 
-## 커맨드
+## 호스트별 진입 방식
+
+| 호스트 | 자연스러운 진입 방식 |
+|--------|----------------------|
+| Claude Code | `/agestra review`, `/agestra design`, `/agestra idea`, `/agestra implement` |
+| Codex CLI | `AGENTS.md`에 맞춘 자연어 요청 |
+| Gemini CLI | `/agestra:review`, `/agestra:design`, `/agestra:idea`, `/agestra:implement` |
+
+세 호스트 모두 같은 MCP 서버와 `commands/*.md` 공유 워크플로우를 사용합니다.
+
+## 커맨드
 
 | 커맨드 | 설명 |
 |--------|------|
@@ -100,7 +135,7 @@ Turborepo 모노레포, 8개 패키지:
 
 - **공급자 추상화** — 모든 백엔드가 `AIProvider`(`chat`, `healthCheck`, `getCapabilities`)를 구현. 새 공급자 추가는 전용 패키지 구현과 팩토리 등록으로 분리됩니다.
 - **제로 설정** — 시작 시 공급자를 자동 감지. 수동 설정 불필요.
-- **플러그인 네이티브** — Claude Code 플러그인으로 설치. Skills, hooks, MCP 서버가 함께 번들.
+- **호스트 네이티브** — Claude는 플러그인 번들을, Codex는 `AGENTS.md`를, Gemini는 `GEMINI.md`와 프로젝트 커맨드를 사용하지만 내부 MCP 서버와 워크플로우 코어는 공통으로 공유합니다.
 - **모듈형 디스패치** — 각 도구 카테고리가 `getTools()` + `handleTool()`을 내보내는 독립 모듈. 서버가 동적으로 수집·디스패치.
 - **원자적 쓰기** — 모든 파일 연산이 임시 파일 → rename 방식. 크래시 시 손상 방지.
 - **실패 추적** — 실패한 접근법이 GraphRAG에 자동 기록, 이후 프롬프트에 주입.
@@ -135,7 +170,7 @@ Turborepo 모노레포, 8개 패키지:
 | `agent_debate_create` | 턴 기반 토론 세션 생성 (토론 ID 반환) |
 | `agent_debate_turn` | 공급자 1턴 실행; `provider: "claude"`로 Claude 독립 참여 지원 |
 | `agent_debate_conclude` | 토론 종료 및 최종 트랜스크립트 생성 |
-| `agent_debate_moderate` | 완전 자동화 토론 — 세션 생성, Specialist 에이전트 참여 라운드 실행, 합의 검출, 요약만 반환 |
+| `agent_debate_moderate` | 완전 자동화 토론 — 세션 생성, provider 라운드 실행, Specialist 선택 기록, 가능할 때 Claude host-backed 턴에 반영, 합의 검출, 요약만 반환 |
 | `agent_debate_review` | 문서를 여러 공급자에게 독립적으로 리뷰 요청 |
 | `agent_cross_validate` | 출력 교차 검증 (에이전트 등급 검증자만 가능) |
 | `agent_changes_review` | 격리된 작업의 파일 변경 리뷰 |
@@ -262,10 +297,19 @@ npm run clean      # dist/ 삭제
 ### 프로젝트 구조
 
 ```
-agestra/
-├── .claude-plugin/
-│   ├── plugin.json          # Claude Code 플러그인 매니페스트
-│   └── marketplace.json     # 플러그인 마켓플레이스 메타데이터
+agestra/
+├── AGENTS.md               # Codex 호스트용 지침
+├── GEMINI.md               # Gemini 호스트용 지침
+├── .claude-plugin/
+│   ├── plugin.json          # Claude Code 플러그인 매니페스트
+│   └── marketplace.json     # 플러그인 마켓플레이스 메타데이터
+├── .gemini/
+│   └── commands/
+│       └── agestra/
+│           ├── review.toml  # Gemini CLI의 /agestra:review
+│           ├── design.toml  # Gemini CLI의 /agestra:design
+│           ├── idea.toml    # Gemini CLI의 /agestra:idea
+│           └── implement.toml # Gemini CLI의 /agestra:implement
 ├── commands/
 │   ├── review.md            # /agestra review — 품질 검증
 │   ├── idea.md              # /agestra idea — 개선점 발굴
@@ -288,9 +332,11 @@ agestra/
 │   └── user-prompt-submit.md  # 도구 추천 hook
 ├── dist/
 │   └── bundle.js            # 단일 파일 MCP 서버 번들
-├── scripts/
-│   └── bundle.mjs           # esbuild 번들 스크립트
-├── packages/
+├── scripts/
+│   ├── bundle.mjs           # esbuild 번들 스크립트
+│   ├── install-host-mcp.mjs # Codex/Gemini에 Agestra 등록
+│   └── uninstall-host-mcp.mjs # Codex/Gemini에서 Agestra 제거
+├── packages/
 │   ├── core/                # AIProvider 인터페이스, 레지스트리, 보안, 워커
 │   ├── provider-ollama/     # Ollama HTTP 어댑터
 │   ├── provider-gemini/     # Gemini CLI 어댑터
@@ -311,15 +357,27 @@ agestra/
 
 ---
 
-## 제거
-
-Claude Code에서:
-
-```
-/plugin uninstall agestra@agestra
-```
-
-플러그인 자체는 깔끔하게 제거됩니다. 프로젝트에 생성된 데이터까지 지우려면 `.agestra/` 디렉터리를 수동으로 삭제하세요.
+## 제거
+
+Claude Code:
+
+```
+/plugin uninstall agestra@agestra
+```
+
+Codex CLI:
+
+```
+npm run uninstall:codex
+```
+
+Gemini CLI:
+
+```
+npm run uninstall:gemini
+```
+
+프로젝트에 생성된 데이터까지 지우려면 `.agestra/` 디렉터리를 수동으로 삭제하세요.
 
 ---
 

package/README.md

@@ -3,22 +3,47 @@
 [![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** — A Claude Code plugin that orchestrates multiple AI providers.
+**Agent + Orchestra** — A multi-host orchestration toolkit for Claude Code, Codex CLI, and Gemini CLI.
 
 [English](README.md) | [한국어](README.ko.md) | [日本語](README.ja.md) | [中文](README.zh.md)
 
-Agestra connects Ollama (local), Gemini CLI, and Codex CLI to Claude Code as pluggable providers, enabling multi-agent orchestration with independent aggregation, consensus debates, autonomous CLI workers, parallel task dispatch, cross-validation, quality-based provider routing, and a persistent GraphRAG memory system — all through 42 MCP tools.
+Agestra connects the Claude host, Ollama (local), Gemini CLI, and Codex CLI as pluggable providers, enabling multi-agent orchestration with independent aggregation, consensus debates, autonomous CLI workers, parallel task dispatch, cross-validation, quality-based provider routing, and a persistent GraphRAG memory system — all through 42 MCP tools.
 
-## Quick Start
-
-In Claude Code, run:
-
-```
-/plugin marketplace add mua-vtuber/Agestra
-/plugin install agestra@agestra
-```
-
-That's it. Agestra auto-detects available providers (Ollama, Gemini CLI, Codex CLI) on first use via `environment_check`.
+## Quick Start
+
+### Claude Code
+
+```
+/plugin marketplace add mua-vtuber/Agestra
+/plugin install agestra@agestra
+```
+
+Claude keeps the existing plugin UX. Agestra auto-detects available providers (Claude host, Ollama, Gemini CLI, Codex CLI) on first use via `environment_check`.
+
+### Codex CLI
+
+```
+npm run bundle
+npm run install:codex
+```
+
+Codex uses the repository-level [AGENTS.md](AGENTS.md) instructions plus the registered `agestra` MCP server.
+
+### Gemini CLI
+
+```
+npm run bundle
+npm run install:gemini
+```
+
+Gemini uses the repository-level [GEMINI.md](GEMINI.md) context file plus project commands under [`.gemini/commands/agestra/`](.gemini/commands/agestra).
+
+Available Gemini commands after setup:
+
+- `/agestra:review`
+- `/agestra:design`
+- `/agestra:idea`
+- `/agestra:implement`
 
 ### Prerequisites
 
@@ -39,7 +64,17 @@ Optional but recommended:
 
 **Multi-AI is for verification, not token savings.** The review, design exploration, and idea generation workflows are structured as validation processes — getting independent opinions from multiple AI providers to catch blind spots, not to parallelize for speed.
 
-## Commands
+## Host Workflows
+
+| Host | Natural entrypoint |
+|------|--------------------|
+| Claude Code | `/agestra review`, `/agestra design`, `/agestra idea`, `/agestra implement` |
+| Codex CLI | Plain-language requests guided by `AGENTS.md` |
+| Gemini CLI | `/agestra:review`, `/agestra:design`, `/agestra:idea`, `/agestra:implement` |
+
+All three hosts drive the same MCP server and shared workflow specs from `commands/*.md`.
+
+## Commands
 
 | Command | Description |
 |---------|-------------|
@@ -100,7 +135,7 @@ Turborepo monorepo with 8 packages:
 
 - **Provider abstraction** — All backends implement `AIProvider` (`chat`, `healthCheck`, `getCapabilities`). Adding a new provider is isolated to a provider package plus factory registration.
 - **Zero-config** — Providers are auto-detected at startup. No manual configuration required.
-- **Plugin-native** — Installed as a Claude Code plugin. Skills, hooks, and MCP server are bundled together.
+- **Host-native** — Claude uses the plugin bundle, Codex uses `AGENTS.md`, and Gemini uses `GEMINI.md` plus project commands, while all three share the same MCP server and workflow core.
 - **Modular dispatch** — Each tool category is an independent module with `getTools()` + `handleTool()`. The server collects and dispatches dynamically.
 - **Atomic writes** — All file operations use write-to-temp-then-rename to prevent corruption.
 - **Dead-end tracking** — Failed approaches are recorded in GraphRAG and injected into future prompts.
@@ -135,7 +170,7 @@ Turborepo monorepo with 8 packages:
 | `agent_debate_create` | Create a turn-based debate session (returns debate ID) |
 | `agent_debate_turn` | Execute one provider's turn; supports `provider: "claude"` for Claude's independent participation |
 | `agent_debate_conclude` | End a debate and generate final transcript |
-| `agent_debate_moderate` | Run a fully automated debate — creates session, runs rounds with specialist agents, detects consensus, returns summary only |
+| `agent_debate_moderate` | Run a fully automated debate — creates session, runs provider rounds, records specialist selection, applies it to Claude's host-backed turn when available, detects consensus, returns summary only |
 | `agent_debate_review` | Send a document to multiple providers for independent review |
 | `agent_cross_validate` | Cross-validate outputs (agent-tier validators only) |
 | `agent_changes_review` | Review file changes from an isolated task |
@@ -262,10 +297,19 @@ npm run clean      # Remove dist/
 ### Project Structure
 
 ```
-agestra/
-├── .claude-plugin/
-│   ├── plugin.json          # Claude Code plugin manifest
-│   └── marketplace.json     # Plugin marketplace metadata
+agestra/
+├── AGENTS.md               # Codex host instructions
+├── GEMINI.md               # Gemini host instructions
+├── .claude-plugin/
+│   ├── plugin.json          # Claude Code plugin manifest
+│   └── marketplace.json     # Plugin marketplace metadata
+├── .gemini/
+│   └── commands/
+│       └── agestra/
+│           ├── review.toml  # /agestra:review in Gemini CLI
+│           ├── design.toml  # /agestra:design in Gemini CLI
+│           ├── idea.toml    # /agestra:idea in Gemini CLI
+│           └── implement.toml # /agestra:implement in Gemini CLI
 ├── commands/
 │   ├── review.md            # /agestra review — quality verification
 │   ├── idea.md              # /agestra idea — improvement discovery
@@ -288,9 +332,11 @@ agestra/
 │   └── user-prompt-submit.md  # Tool recommendation hook
 ├── dist/
 │   └── bundle.js            # Single-file MCP server bundle
-├── scripts/
-│   └── bundle.mjs           # esbuild bundle script
-├── packages/
+├── scripts/
+│   ├── bundle.mjs           # esbuild bundle script
+│   ├── install-host-mcp.mjs # Register Agestra with Codex/Gemini
+│   └── uninstall-host-mcp.mjs # Remove Codex/Gemini MCP registration
+├── packages/
 │   ├── core/                # AIProvider interface, registry, security, workers
 │   ├── provider-ollama/     # Ollama HTTP adapter
 │   ├── provider-gemini/     # Gemini CLI adapter
@@ -311,15 +357,27 @@ agestra/
 
 ---
 
-## Uninstall
-
-In Claude Code:
-
-```
-/plugin uninstall agestra@agestra
-```
-
-The plugin is removed cleanly. If you want to delete generated project data as well, remove the `.agestra/` directory manually.
+## Uninstall
+
+Claude Code:
+
+```
+/plugin uninstall agestra@agestra
+```
+
+Codex CLI:
+
+```
+npm run uninstall:codex
+```
+
+Gemini CLI:
+
+```
+npm run uninstall:gemini
+```
+
+If you also want to delete generated project data, remove the `.agestra/` directory manually.
 
 ---