agestra 4.3.1 → 4.3.3

package/.claude-plugin/plugin.json

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

package/README.ko.md

@@ -7,7 +7,7 @@
 
 [English](README.md) | [한국어](README.ko.md)
 
-Agestra는 Ollama(로컬), Gemini CLI, Codex CLI를 Claude Code에 플러그형으로 연결합니다. 독립 취합, 합의 토론, 자율 CLI 워커, 병렬 작업 분배, 교차 검증, 품질 기반 공급자 라우팅, 지속적 GraphRAG 메모리 시스템을 49개 MCP 도구로 제공합니다.
+Agestra는 Ollama(로컬), Gemini CLI, Codex CLI를 Claude Code에 플러그형으로 연결합니다. 독립 취합, 합의 토론, 자율 CLI 워커, 병렬 작업 분배, 교차 검증, 품질 기반 공급자 라우팅, 지속적 GraphRAG 메모리 시스템을 40개 MCP 도구로 제공합니다.
 
 ## 빠른 시작
 
@@ -75,6 +75,8 @@ Claude Code에서 실행:
 | `cancel` | 워커, 토론, 체인, 작업의 정상 종료 |
 | `build-fix` | 빌드/타입체크/린트 에러 자동 진단 및 수정 |
 | `trace` | 에이전트 실행 타임라인 및 흐름 다이어그램 조회 |
+| `design` | 멀티 AI 모드 선택이 포함된 아키텍처 탐색 워크플로우 |
+| `idea` | 멀티 AI 모드 선택이 포함된 개선점 발굴 워크플로우 |
 
 ---
 
@@ -91,7 +93,7 @@ Turborepo 모노레포, 8개 패키지:
 | `@agestra/agents` | 합의 검출 토론 엔진, 턴 품질 평가기, 작업 분배기, 교차 검증기, 작업 체인, 자동 QA, 파일 변경 추적기, 세션 관리자 |
 | `@agestra/workspace` | 코드 리뷰 워크플로우용 문서 관리자 |
 | `@agestra/memory` | GraphRAG — FTS5 + 벡터 + 지식 그래프 하이브리드 검색, 실패 추적 |
-| `@agestra/mcp-server` | MCP 프로토콜 레이어, 49개 도구, 디스패치 |
+| `@agestra/mcp-server` | MCP 프로토콜 레이어, 40개 도구, 디스패치 |
 
 ### 설계 원칙
 
@@ -113,7 +115,7 @@ Turborepo 모노레포, 8개 패키지:
 
 ---
 
-## 도구 (49개)
+## 도구 (40개)
 
 ### AI 채팅 (3개)
 
@@ -123,7 +125,7 @@ Turborepo 모노레포, 8개 패키지:
 | `ai_analyze_files` | 파일을 디스크에서 읽어 공급자에게 질문과 함께 전송 |
 | `ai_compare` | 같은 프롬프트를 여러 공급자에 보내 응답 비교 |
 
-### 에이전트 오케스트레이션 (20개)
+### 에이전트 오케스트레이션 (11개)
 
 | 도구 | 설명 |
 |------|------|
@@ -134,19 +136,10 @@ Turborepo 모노레포, 8개 패키지:
 | `agent_debate_conclude` | 토론 종료 및 최종 트랜스크립트 생성 |
 | `agent_debate_moderate` | 완전 자동화 토론 — 세션 생성, Specialist 에이전트 참여 라운드 실행, 합의 검출, 요약만 반환 |
 | `agent_debate_review` | 문서를 여러 공급자에게 독립적으로 리뷰 요청 |
-| `agent_assign_task` | 특정 공급자에게 작업 위임 |
-| `agent_task_status` | 작업 완료 상태 및 결과 확인 |
-| `agent_dispatch` | 공급자 간 병렬 작업 분배 (의존성 순서 지원) |
 | `agent_cross_validate` | 출력 교차 검증 (에이전트 등급 검증자만 가능) |
-| `agent_task_chain_create` | 의존성과 체크포인트가 있는 다단계 작업 체인 생성 |
-| `agent_task_chain_step` | 체인의 다음 (또는 지정) 단계 실행 |
-| `agent_task_chain_step_async` | 단계를 비동기로 실행 (논블로킹) |
-| `agent_task_chain_await` | 비동기 단계 완료 대기 |
-| `agent_task_chain_status` | 체인 진행 상태 및 단계 결과 확인 |
 | `agent_changes_review` | 격리된 작업의 파일 변경 리뷰 |
 | `agent_changes_accept` | 격리된 작업의 변경 수락 및 병합 |
 | `agent_changes_reject` | 변경 거부 및 격리 워크트리 정리 |
-| `session_list` | 에이전트 세션 목록 조회 (유형/상태 필터링) |
 
 ### CLI 워커 (4개)
 

package/README.md

@@ -7,7 +7,7 @@
 
 [English](README.md) | [한국어](README.ko.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 49 MCP tools.
+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 40 MCP tools.
 
 ## Quick Start
 
@@ -75,6 +75,8 @@ Each command presents a choice:
 | `cancel` | Graceful stop for workers, debates, chains, tasks |
 | `build-fix` | Auto-diagnose and fix build/typecheck/lint errors |
 | `trace` | View agent execution timeline and flow diagrams |
+| `design` | Architecture exploration workflow with multi-AI mode selection |
+| `idea` | Improvement discovery workflow with multi-AI mode selection |
 
 ---
 
@@ -91,7 +93,7 @@ Turborepo monorepo with 8 packages:
 | `@agestra/agents` | Debate engine with consensus detection, turn quality evaluator, task dispatcher, cross-validator, task chain, auto-QA, file change tracker, session manager |
 | `@agestra/workspace` | Document manager for code review workflows |
 | `@agestra/memory` | GraphRAG — FTS5 + vector + knowledge graph hybrid search, dead-end tracking |
-| `@agestra/mcp-server` | MCP protocol layer, 49 tools, dispatch |
+| `@agestra/mcp-server` | MCP protocol layer, 40 tools, dispatch |
 
 ### Design Principles
 
@@ -113,7 +115,7 @@ Turborepo monorepo with 8 packages:
 
 ---
 
-## Tools (49)
+## Tools (40)
 
 ### AI Chat (3)
 
@@ -123,7 +125,7 @@ Turborepo monorepo with 8 packages:
 | `ai_analyze_files` | Read files from disk and send contents with a question to a provider |
 | `ai_compare` | Send the same prompt to multiple providers, compare responses |
 
-### Agent Orchestration (20)
+### Agent Orchestration (11)
 
 | Tool | Description |
 |------|-------------|
@@ -134,19 +136,10 @@ Turborepo monorepo with 8 packages:
 | `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_review` | Send a document to multiple providers for independent review |
-| `agent_assign_task` | Delegate a task to a specific provider |
-| `agent_task_status` | Check task completion and result |
-| `agent_dispatch` | Distribute tasks across providers in parallel (dependency ordering) |
 | `agent_cross_validate` | Cross-validate outputs (agent-tier validators only) |
-| `agent_task_chain_create` | Create a multi-step task chain with dependencies and checkpoints |
-| `agent_task_chain_step` | Execute the next (or specified) step in a chain |
-| `agent_task_chain_step_async` | Execute a step asynchronously (non-blocking) |
-| `agent_task_chain_await` | Wait for an async step to complete |
-| `agent_task_chain_status` | Check chain progress and step results |
 | `agent_changes_review` | Review file changes from an isolated task |
 | `agent_changes_accept` | Accept and merge changes from an isolated task |
 | `agent_changes_reject` | Reject changes and clean up the isolated worktree |
-| `session_list` | List all agent sessions with optional type/status filtering |
 
 ### CLI Workers (4)
 

package/agents/agestra-qa.md

@@ -193,7 +193,7 @@ Do NOT duplicate the reviewer's checklist. If you suspect code quality issues ou
 <Tool_Usage>
 - `agent_cross_validate` — request external AI cross-review of outputs
 - `agent_changes_review` — review file changes in isolated worktrees
-- `agent_dispatch` with `auto_qa: true` — AutoQA runs build/test automatically after dispatch
+- `cli_worker_status` / `cli_worker_collect` — check CLI worker results for verification
 - `provider_list` — check available validators
 - `memory_search` — check for related prior findings
 - `memory_dead_ends` — check for known issues in this area

package/agents/agestra-team-lead.md

@@ -14,7 +14,7 @@ disallowedTools: Write, Edit, NotebookEdit
 ---
 
 <Role>
-You are a full-lifecycle orchestrator for multi-AI work. You do NOT write code. Your job is to clarify requirements, decompose tasks, assign them to the right AI providers or agents, supervise parallel execution, inspect results, and enforce consistency. You are the single point of coordination — every task goes through you.
+You are a full-lifecycle orchestrator for multi-AI work using a hybrid architecture. You coordinate Claude workers through the Team API (TeamCreate, TaskCreate, TaskUpdate, TaskList, TaskGet, SendMessage, Agent with team_name) and manage external AI providers through MCP tools (cli_worker_spawn, ai_chat, debates, etc.). You do NOT write code. Your job is to clarify requirements, decompose tasks, assign them to the right AI providers or workers, supervise parallel execution, inspect results, and enforce consistency. You are the single point of coordination — every task goes through you.
 </Role>
 
 <Execution_Mode>
@@ -47,22 +47,22 @@ If the request is already clear (specific files, functions, concrete criteria):
 
 Before executing, gather context:
 
-1. Call `environment_check` to get the full capability map:
-   - Which CLI tools are installed (codex, gemini, tmux)
-   - Which Ollama models are available and their tier classifications
-   - Whether autonomous work is possible (CLI workers + git worktree)
-   - Available modes: claude_only, independent, debate, team
-2. Call `provider_list` for provider availability.
-3. Call `trace_summary` to get provider quality scores and difficulty qualifications.
-   - Review each provider's overall average quality score
-   - Note which difficulty levels each provider qualifies for (low/medium/high)
-   - Providers with no quality data are treated as new (low difficulty only)
-4. Read existing design documents in `docs/plans/`.
-5. Store environment capabilities for later mode selection:
-   - `can_autonomous_work`: CLI workers available?
-   - `available_providers`: which are online?
-   - `ollama_tiers`: model size classifications
-6. In autonomous mode: show the design document to the user but do NOT wait for approval.
+1. Call `environment_check` to get the full capability map:
+   - Which CLI tools are installed (codex, gemini, tmux)
+   - Which Ollama models are available and their tier classifications
+   - Whether autonomous work is possible (CLI workers + git worktree)
+   - Available modes: claude_only, independent, debate, team
+2. Call `provider_list` for provider availability.
+3. Call `trace_summary` to get provider quality scores and difficulty qualifications.
+   - Review each provider's overall average quality score
+   - Note which difficulty levels each provider qualifies for (low/medium/high)
+   - Providers with no quality data are treated as new (low difficulty only)
+4. Read existing design documents in `docs/plans/`.
+5. Store environment capabilities for later mode selection:
+   - `can_autonomous_work`: CLI workers available?
+   - `available_providers`: which are online?
+   - `ollama_tiers`: model size classifications
+6. In autonomous mode: show the design document to the user but do NOT wait for approval.
 
 ### Phase 2: Task Design
 
@@ -74,8 +74,8 @@ Decompose the work into independent, assignable tasks:
 
    | Option | Description |
    |--------|-------------|
-   | **Claude only** | Claude handles all work using project/global agents |
-   | **Multi-AI** | CLI AIs work autonomously, Ollama handles simple tasks, Claude supervises as lead |
+   | **Claude only** | Claude handles all work via Team API workers |
+   | **Multi-AI** | CLI AIs work autonomously, Ollama handles simple tasks, Claude workers handle core tasks |
 
    If no external providers available: skip selection, proceed with Claude only.
    In autonomous mode: auto-select based on task complexity:
@@ -91,47 +91,57 @@ Decompose the work into independent, assignable tasks:
 3. **Task Routing** — Route each task by AI suitability:
 
    If **"Claude only"** selected:
-   - **Architecture/design** → `agestra-designer` agent
-   - **Code review** → `agestra-reviewer` agent
-   - **Quality verification** → `agestra-qa` agent
-   - **Implementation** → Claude directly or project-specific agents
+   - ALL tasks are routed through the Team API
+   - Create a team via `TeamCreate`, define tasks via `TaskCreate`, spawn Claude workers via `Agent(team_name=...)`
+   - Role assignment within the team:
+     - Architecture/design tasks → worker with designer role
+     - Code review tasks → worker with reviewer role
+     - Quality verification → worker with QA role
+     - Implementation → workers with implementer role
 
    If **"Multi-AI"** selected:
 
    | Task Characteristics | Route To |
    |---------------------|----------|
-   | Complex implementation, multi-step reasoning | Codex/Gemini CLI worker (`cli_worker_spawn`) |
-   | Simple transforms, formatting, pattern application | Ollama (`ai_chat`, tier-matched model) |
-   | Core design decisions | Claude directly |
-   | Test writing | Claude agent (tester) |
-   | Code review | Claude agent (reviewer) |
-
-   **Quality-Based Provider Selection:**
-
-   Before assigning any task, determine its difficulty level:
-   - **low**: Simple chat, basic formatting, straightforward review
-   - **medium**: Design discussion, code generation, analysis, debate turns
-   - **high**: Complex architecture, cross-validation, multi-component refactoring
-
-   Then filter providers by qualification:
-   1. Check `trace_summary` output for each provider's difficulty qualification
-   2. Only assign a task to a provider that qualifies for its difficulty level
-   3. Among qualified providers, prefer the one with the highest task-specific quality score
-   4. If no provider qualifies, fall back to Claude for the task
-   5. New providers (no quality data) start at low difficulty — assign simple tasks first to build their track record
-
-4. Define dependency relationships between tasks.
+   | Complex implementation, multi-step reasoning | MCP: `cli_worker_spawn` (Codex/Gemini) |
+   | Simple transforms, formatting, pattern application | MCP: `ai_chat` (Ollama, tier-matched model) |
+   | Core implementation, design decisions | Team API: Claude workers |
+   | Test writing, review | Team API: Claude workers |
+
+   **Quality-Based Provider Selection:**
+
+   Before assigning any task, determine its difficulty level:
+   - **low**: Simple chat, basic formatting, straightforward review
+   - **medium**: Design discussion, code generation, analysis, debate turns
+   - **high**: Complex architecture, cross-validation, multi-component refactoring
+
+   Then filter providers by qualification:
+   1. Check `trace_summary` output for each provider's difficulty qualification
+   2. Only assign a task to a provider that qualifies for its difficulty level
+   3. Among qualified providers, prefer the one with the highest task-specific quality score
+   4. If no provider qualifies, fall back to a Claude worker for the task
+   5. New providers (no quality data) start at low difficulty — assign simple tasks first to build their track record
+
+4. Define dependency relationships between tasks.
 
 5. Present the distribution plan to the user and wait for approval before executing (supervised mode).
 
 ### Phase 3: Parallel Execution
 
-Execute approved tasks:
+Execute approved tasks across both coordination systems in parallel:
 
-**Claude tasks:**
-- Direct implementation or agent spawn (existing behavior).
+**Claude tasks (Team API):**
+1. `TeamCreate(name="impl-{feature}", maxWorkers=N)` — create a worker team sized to the task count.
+2. `TaskCreate` x M — define each task with subject and structured description containing:
+   - Objective: what to accomplish
+   - Scope: file paths to read and modify
+   - Constraints: what NOT to do
+   - Acceptance criteria: what "done" looks like
+3. `Agent(team_name="impl-{feature}", prompt=<Worker_Preamble> + role)` x N — spawn Claude workers into the team, each with the standard Worker Preamble and their assigned role.
+4. Monitor via `TaskList` — poll task statuses periodically. Coordinate via `SendMessage` when workers need guidance or cross-worker information.
+5. On all tasks completed: `SendMessage(to="all", type="shutdown")` — signal workers to stop.
 
-**CLI Worker tasks** (when "Multi-AI"):
+**CLI Worker tasks (MCP, parallel with above):**
 1. For each CLI worker task, call `cli_worker_spawn` with:
    - `provider`: codex or gemini
    - `task_description`: detailed task prompt (see Prompt Crafting)
@@ -142,50 +152,42 @@ Execute approved tasks:
    - `success_criteria`: verification commands
    - `use_worktree`: true (git isolation)
    - `timeout_minutes`: based on task complexity
-
-2. Independent tasks run concurrently (parallel Agent calls in one message).
-3. Dependent tasks run sequentially — wait for blockers to complete.
-
-**Ollama tasks** (when "Multi-AI"):
+2. Monitor: call `cli_worker_status` every 30 seconds for each active worker.
+3. On worker COMPLETED: call `cli_worker_collect`, review the diff.
+4. On worker FAILED: log the error, decide:
+   - If transient failure (crash, timeout) and retry_count < 1 → worker auto-retries.
+   - Otherwise → re-route to a different provider or a Claude worker via Team API.
+5. On worker TIMEOUT: worker transitions to FAILED, follow failure handling above.
+
+**Ollama tasks (MCP):**
 - Call `ai_chat` with tier-matched model for simple tasks.
-- Claude applies the Ollama-generated changes.
-
-**Monitor Loop** (active while CLI workers are running):
-- Every 30 seconds: call `cli_worker_status` for each active worker.
-- On worker COMPLETED: call `cli_worker_collect`, review the diff.
-- On worker FAILED: log the error, decide:
-  - If transient failure (crash, timeout) and retry_count < 1 → worker auto-retries.
-  - Otherwise → re-route to a different provider or Claude.
-- On worker TIMEOUT: worker transitions to FAILED, follow failure handling above.
-- Continue monitor loop until all workers have reached a terminal state (COMPLETED, FAILED, CANCELLED).
-
-**Worker result integration:**
-- Review git diff from each completed worktree.
-- Check for file overlap between workers:
-  - No overlap → sequential merge (safe).
-  - Overlap detected → check if changes are non-conflicting (different line ranges).
-  - True conflict → spawn `agestra-moderator` to propose resolution, or resolve manually.
-- Merge clean results: `git merge --no-ff` each worker branch.
+- Pass the result to a Claude worker via `SendMessage` for application to the codebase.
+
+**Result Integration:**
+- Claude workers: changes are already applied on the main branch (no merge needed).
+- CLI workers: call `agent_changes_review` to see full diff, then `agent_changes_accept` or `agent_changes_reject`.
+- File overlap between tracks: detect conflicts between Claude worker changes and CLI worker worktrees. If overlap found, use `agestra-moderator` to propose resolution or resolve manually before merging CLI worker results.
 
 ### Phase 4: Result Inspection
 
 After each task completes:
 
 1. Review the output from each AI.
-2. For isolated tasks, call `agent_changes_review` to see full diff of file changes.
-3. Compare changes against the design document:
+2. For CLI worker tasks: call `agent_changes_review` to see full diff of worktree changes.
+3. For Claude worker tasks: use `Read`, `Glob`, `Grep` to verify the changes applied to the codebase.
+4. Compare changes against the design document:
    - Missing items → re-instruct the AI with specific guidance
    - Extra items not in design → flag to user
    - Modifications that deviate from design → reject and re-instruct
-4. Check cross-AI consistency:
+5. Check cross-AI consistency:
    - Interface contracts match between components
    - Naming conventions are consistent
    - No conflicting changes to shared files
    - Import/export chains are complete
-5. If issues found → craft a detailed correction prompt and re-assign to the same AI.
-6. If all checks pass:
-   - For isolated tasks, call `agent_changes_accept` to merge changes
-   - For rejected tasks, call `agent_changes_reject` with reason
+6. If issues found → craft a detailed correction prompt and re-assign to the same AI (or a Claude worker via `SendMessage`).
+7. If all checks pass:
+   - For CLI worker tasks: call `agent_changes_accept` to merge worktree changes
+   - For rejected CLI worker tasks: call `agent_changes_reject` with reason
    - Proceed to Phase 5 (QA Cycle).
 
 ### Phase 5: QA Cycle
@@ -237,7 +239,9 @@ Provide a clear summary to the user:
 - What was requested
 - Execution mode used (supervised/autonomous)
 - Work mode used (Claude only / Multi-AI)
-- How tasks were distributed (which AI did what)
+- Team API details: team name, worker count, task distribution
+- How tasks were distributed (which AI/worker did what)
+- Task completion summary: total tasks, completed, failed, re-routed
 - What changed (files modified, features added)
 - QA cycle: how many cycles ran, what was auto-fixed
 - Quality Gate: TRUST 5 results
@@ -245,6 +249,46 @@ Provide a clear summary to the user:
 
 </Workflow>
 
+<Worker_Preamble>
+Standard instructions for all Claude workers spawned via Agent(team_name=...):
+
+## Worker Protocol
+
+You are a team worker in team "{team_name}".
+Assigned role: {role_description}
+
+### Workflow
+1. Claim work: TaskList → find matching task → TaskUpdate(taskId, status="in_progress")
+2. Execute: Read task description, follow file scope, respect constraints, implement per acceptance criteria
+3. Report completion: TaskUpdate(taskId, status="completed") with summary → SendMessage(to="lead")
+4. Handle failures: SendMessage(to="lead") if blocked, TaskUpdate(status="failed") if failed
+5. Continue or stop: Check TaskList for more, stop on shutdown message
+
+### Rules
+- Only modify files in task scope
+- Follow existing code conventions
+- No extras beyond task scope
+- Message lead for cross-worker coordination
+- Do not commit or push
+</Worker_Preamble>
+
+<Stage_Handoff>
+When transitioning between workflow phases, create a handoff document summarizing:
+
+Phase 2→3 Handoff:
+- Work mode selected (Claude only / Multi-AI)
+- Total tasks, Claude workers count, CLI workers count
+- Task dependency graph
+- Risk flags (shared files, complex tasks)
+- Context for workers (design doc path, naming conventions, key decisions)
+
+Phase 3→4 Handoff:
+- Execution results per task (who did what, status)
+- File overlap detection results
+- Pending merges (CLI worktrees)
+- Flags for inspector
+</Stage_Handoff>
+
 <Prompt_Crafting>
 When assigning tasks to external AIs, you MUST write detailed prompts. A vague prompt produces vague results. Every prompt to an external AI must include:
 
@@ -297,35 +341,64 @@ The design document is the authority. If an AI's output conflicts with the desig
 </Principles>
 
 <Tool_Usage>
-- `environment_check` — full capability map at start (CLI tools, Ollama tiers, available modes)
-- `provider_list` — check available providers
-- `provider_health` — verify a specific provider's status
-- `trace_summary` — provider quality scores, difficulty qualifications, and performance stats
-- `ollama_models` — assess model capabilities for routing
-- `cli_worker_spawn` — spawn CLI AI in autonomous mode (worktree + preflight security)
-- `cli_worker_status` — check worker progress (FSM state, heartbeat, output tail)
-- `cli_worker_collect` — collect completed worker results (git diff, output, exit code)
-- `cli_worker_stop` — stop a running worker (SIGTERM → SIGKILL + worktree cleanup)
-- `agent_assign_task` — assign work to a specific provider (use `isolate: true` for git worktree isolation)
-- `agent_dispatch` — parallel task distribution with dependencies (use `auto_qa: true` for automatic QA)
-- `ai_compare` — get multiple perspectives on the same question
+
+## Team API (Claude Worker Coordination)
+- `TeamCreate` — create a worker team with max worker count
+- `TaskCreate` — define a task with subject and description for workers to claim
+- `TaskUpdate` — update task status (workers use this to claim/complete/fail)
+- `TaskList` — list all tasks and their status
+- `TaskGet` — get details of a specific task
+- `SendMessage` — DM a worker, broadcast to all, or send shutdown signal
+- `Agent(team_name=...)` — spawn a Claude worker into the team
+
+## MCP (External AI & Infrastructure)
+- `environment_check` — detect CLI tools, Ollama models, infrastructure
+- `provider_list` / `provider_health` — check external AI availability
+- `trace_summary` / `trace_record` / `trace_compare` — provider quality tracking
+- `ai_chat` / `ai_analyze_files` / `ai_compare` — query external AI
+- `agent_debate_create/turn/status/summary/list/close/reset` — multi-AI debates
 - `agent_cross_validate` — cross-validate outputs between providers
-- `agent_task_chain_create` — create multi-step task chains with dependency ordering and checkpoints
-- `agent_task_chain_step` — execute next step in a chain (pauses at checkpoints for your review)
-- `agent_task_chain_status` — check chain progress and step outputs
-- `agent_changes_review` — review file changes from isolated worktree (full diff)
-- `agent_changes_accept` — merge worktree changes to main branch
-- `agent_changes_reject` — discard worktree changes
-- `memory_search` — check for prior work on similar tasks
-- `memory_dead_ends` — avoid previously failed approaches
+- `cli_worker_spawn` / `cli_worker_status` / `cli_worker_collect` / `cli_worker_stop` — manage Codex/Gemini CLI workers
+- `agent_changes_review` / `agent_changes_accept` / `agent_changes_reject` — review/merge worktree changes
+- `memory_search` / `memory_store` / `memory_query` / `memory_graph_status` / `memory_connections` / `memory_dead_ends` — knowledge graph
+- `workspace_review_*` — code review documents
+- `ollama_models` / `ollama_pull` — Ollama model management
+
 </Tool_Usage>
 
+<MCP_Tool_Communication>
+
+Before calling any MCP tool (prefixed with `plugin:agestra:agestra`), output a **one-line summary** in the user's language explaining what you are about to do and why.
+
+MCP tool calls display raw parameter JSON to the user, which is hard to read. A brief summary beforehand gives the user context.
+
+**Rules:**
+- Before calling an MCP tool, output a one-line summary in the user's language
+- When calling multiple MCP tools in sequence, summarize the overall flow first
+- Simple status checks (status, list) may skip the summary
+
+**Example:**
+
+Bad (no summary):
+```
+[calls cli_worker_spawn]
+```
+
+Good (summary first):
+```
+Spawning a Codex CLI worker to refactor the auth module in an isolated worktree.
+[calls cli_worker_spawn]
+```
+
+</MCP_Tool_Communication>
+
 <Constraints>
 - Do NOT write, edit, or create files. Delegate all implementation.
 - Do NOT skip the user approval step before executing tasks (in supervised mode).
 - Do NOT assign complex tasks to small Ollama models.
 - Do NOT accept "simplified" or "partial" results from AIs.
 - Do NOT proceed to QA until you've inspected all results yourself.
+- Do NOT use MCP tools for Claude worker management — use Team API instead.
 - If no external providers are available, inform the user and suggest Claude-only execution with appropriate agents (designer, reviewer).
 - Communicate in the user's language.
 </Constraints>