agestra 4.7.0 → 4.8.0

package/README.md

@@ -1,14 +1,14 @@
-# Agestra
-
-[![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)
-
+# Agestra
+
+[![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 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 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 31 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, and quality-based provider routing — all through 25 MCP tools.
+
 ## Quick Start
 
 ### Claude Code
@@ -74,17 +74,17 @@ Available Gemini commands after setup:
 - `/agestra:design`
 - `/agestra:idea`
 - `/agestra:implement`
-
-### Prerequisites
-
-At least one AI provider must be installed:
-
-| Provider | Install | Type |
-|----------|---------|------|
-| [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 |
-
+
+### Prerequisites
+
+At least one AI provider must be installed:
+
+| Provider | Install | Type |
+|----------|---------|------|
+| [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 |
+
 Optional but recommended:
 - **tmux** — enables visible CLI worker panes during autonomous execution
 - **ripgrep (`rg`)** on Windows — if Codex resolves `rg` to its bundled Store-app path and fails with an "Access is denied" error, install ripgrep separately so a normal `rg.exe` is found first in `PATH`:
@@ -100,11 +100,11 @@ winget install BurntSushi.ripgrep.MSVC
 ```
 
 ---
-
-## Philosophy
-
-**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.
-
+
+## Philosophy
+
+**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.
+
 ## Host Workflows
 
 | Host | Natural entrypoint |
@@ -116,127 +116,121 @@ winget install BurntSushi.ripgrep.MSVC
 All three hosts drive the same MCP server and shared workflow specs from `commands/*.md`.
 
 ## Commands
-
-| Command | Description |
-|---------|-------------|
+
+| Command | Description |
+|---------|-------------|
 | `/agestra review [target]` | Review code quality, security, and integration completeness |
 | `/agestra idea [topic]` | Discover improvements by comparing with similar projects |
 | `/agestra design [subject]` | Explore architecture and design trade-offs before implementation |
+| `/agestra setup` | Initial AI provider selection and setup |
 | `/agestra implement [task]` | Execute implementation in Claude-only or Multi-AI mode |
-
-Each command presents a choice:
-
-| Mode | Description |
-|------|-------------|
-| **Claude only** | Plugin specialist agent works alone |
-| **각자 독립** (Independent) | Each AI works independently, moderator aggregates into unified document |
-| **끝장토론** (Debate) | Independent work + document review rounds until all AIs agree |
-
-## Agents
-
-| Agent | Model | Role |
-|-------|-------|------|
-| `agestra-team-lead` | Sonnet | Full orchestrator — environment check, quality-based provider routing, work mode selection, CLI worker supervision, QA loop |
-| `agestra-reviewer` | Opus | Strict quality verifier — security, orphans, spec drift, test gaps |
-| `agestra-designer` | Opus | Architecture explorer — Socratic questioning, trade-off analysis |
-| `agestra-ideator` | Sonnet | Improvement discoverer — web research, competitive analysis |
-| `agestra-moderator` | Sonnet | Multi-mode facilitator — debate with consensus detection, independent aggregation, document review, conflict resolution |
-| `agestra-qa` | Opus | QA verifier — design compliance, PASS/FAIL judgment |
-
-## Skills
-
-| Skill | Description |
-|-------|-------------|
-| `provider-guide` | Provider routing, mode reference, orchestration pipeline |
-| `worker-manage` | List, check, collect, and stop CLI workers |
-| `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 |
-
----
-
-## Architecture
-
-Turborepo monorepo with 9 packages:
-
-| Package | Description |
-|---------|-------------|
-| `@agestra/core` | `AIProvider` interface, registry with difficulty-based routing, config loader, CLI runner, atomic writes, job queue, secret scanner, worktree manager, task manifest, CLI worker manager |
-| `@agestra/provider-ollama` | Ollama HTTP adapter with model detection |
-| `@agestra/provider-gemini` | Google Gemini CLI adapter |
-| `@agestra/provider-codex` | OpenAI Codex CLI adapter |
-| `@agestra/agents` | Debate engine with consensus detection, turn quality evaluator, task dispatcher, cross-validator, task chain, auto-QA, file change tracker, session manager |
+
+When external providers are available, text commands (review, design, idea) go directly to debate mode (끝장토론) for multi-AI cross-validation. When no providers are detected, Claude works alone automatically.
+
+## Agents
+
+| Agent | Model | Role |
+|-------|-------|------|
+| `agestra-team-lead` | Sonnet | Full orchestrator — environment check, quality-based provider routing, work mode selection, CLI worker supervision, QA loop |
+| `agestra-reviewer` | Opus | Strict quality verifier — security, orphans, spec drift, test gaps |
+| `agestra-designer` | Opus | Architecture explorer — Socratic questioning, trade-off analysis |
+| `agestra-ideator` | Sonnet | Improvement discoverer — web research, competitive analysis |
+| `agestra-moderator` | Sonnet | Multi-mode facilitator — debate with consensus detection, independent aggregation, document review, conflict resolution |
+| `agestra-qa` | Opus | QA verifier — design compliance, PASS/FAIL judgment |
+
+## Skills
+
+| Skill | Description |
+|-------|-------------|
+| `provider-guide` | Provider routing, mode reference, orchestration pipeline |
+| `worker-manage` | List, check, collect, and stop CLI workers |
+| `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 |
+
+---
+
+## Architecture
+
+Turborepo monorepo with 9 packages:
+
+| Package | Description |
+|---------|-------------|
+| `@agestra/core` | `AIProvider` interface, registry with difficulty-based routing, config loader, CLI runner, atomic writes, job queue, secret scanner, worktree manager, task manifest, CLI worker manager |
+| `@agestra/provider-ollama` | Ollama HTTP adapter with model detection |
+| `@agestra/provider-gemini` | Google Gemini CLI adapter |
+| `@agestra/provider-codex` | OpenAI Codex CLI adapter |
+| `@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` | Workspace document manager for reviews, analysis notes, and aggregated reports |
-| `@agestra/memory` | GraphRAG — FTS5 + vector + knowledge graph hybrid search, dead-end tracking |
-| `@agestra/mcp-server` | MCP protocol layer, 31 tools, environment-aware tool filtering, dispatch |
-
-### Design Principles
-
+| `@agestra/mcp-server` | MCP protocol layer, 25 tools, environment-aware tool filtering, dispatch |
+
+### Design Principles
+
 - **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.
+- **Zero-config** — Providers are auto-detected at startup. No manual configuration required.
 - **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.
-- **Preflight security** — CLI worker spawning includes secret scanning and array-based process args to prevent injection.
-
-### Work Modes
-
-**Text work** (review, design, idea): Claude only → 각자 독립 → 끝장토론
-
-**Implementation work** (team-lead orchestration):
-- **Claude만으로** — Claude implements directly with project/global agents.
-- **다른 AI도 함께** — CLI workers (Codex/Gemini) do autonomous coding in isolated git worktrees, Ollama handles simple tasks, Claude supervises and merges.
-
----
-
-## Tools (31)
-
-### AI Chat (3)
-
-| Tool | Description |
-|------|-------------|
+- **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 and injected into future prompts.
+- **Preflight security** — CLI worker spawning includes secret scanning and array-based process args to prevent injection.
+
+### Work Modes
+
+**Text work** (review, design, idea): providers available → 끝장토론 (debate); no providers → Claude only
+
+**Implementation work** (team-lead orchestration):
+- **Claude만으로** — Claude implements directly with project/global agents.
+- **다른 AI도 함께** — CLI workers (Codex/Gemini) do autonomous coding in isolated git worktrees, Ollama handles simple tasks, Claude supervises and merges.
+
+---
+
+## Tools (25)
+
+### AI Chat (3)
+
+| Tool | Description |
+|------|-------------|
 | `ai_chat` | Chat with a specific provider (use `"auto"` for quality-based routing); optionally persist replies with `save_as_document` |
-| `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 (0)
-
-| Tool | Description |
-|------|-------------|
-| `agent_debate_start` | Start a multi-provider debate (non-blocking, optional quality loop + validator) |
-| `agent_debate_status` | Check debate status and transcript |
-| `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 |
+| `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 (0)
+
+| Tool | Description |
+|------|-------------|
+| `agent_debate_start` | Start a multi-provider debate (non-blocking, optional quality loop + validator) |
+| `agent_debate_status` | Check debate status and transcript |
+| `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 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 |
-| `agent_changes_accept` | Accept and merge changes from an isolated task |
-| `agent_changes_reject` | Reject changes and clean up the isolated worktree |
-
-### CLI Workers (4)
-
-| Tool | Description |
-|------|-------------|
-| `cli_worker_spawn` | Spawn a CLI AI (Codex/Gemini) in autonomous mode with git worktree isolation and preflight security |
-| `cli_worker_status` | Check worker FSM state, heartbeat, and output tail |
-| `cli_worker_collect` | Collect completed worker results (git diff, output, exit code) |
-| `cli_worker_stop` | Stop a running worker (SIGTERM → SIGKILL) and clean up worktree |
-
-### Environment (1)
-
-| Tool | Description |
-|------|-------------|
-| `environment_check` | Detect CLI tools, Ollama models with tiers, tmux, git worktree support, available modes |
-
+| `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 |
+| `agent_changes_accept` | Accept and merge changes from an isolated task |
+| `agent_changes_reject` | Reject changes and clean up the isolated worktree |
+
+### CLI Workers (4)
+
+| Tool | Description |
+|------|-------------|
+| `cli_worker_spawn` | Spawn a CLI AI (Codex/Gemini) in autonomous mode with git worktree isolation and preflight security |
+| `cli_worker_status` | Check worker FSM state, heartbeat, and output tail |
+| `cli_worker_collect` | Collect completed worker results (git diff, output, exit code) |
+| `cli_worker_stop` | Stop a running worker (SIGTERM → SIGKILL) and clean up worktree |
+
+### Environment (1)
+
+| Tool | Description |
+|------|-------------|
+| `environment_check` | Detect CLI tools, Ollama models with tiers, tmux, git worktree support, available modes |
+
 ### Workspace (7)
-
-| Tool | Description |
-|------|-------------|
+
+| Tool | Description |
+|------|-------------|
 | `workspace_create_review` | Create a code review document with files and rules |
 | `workspace_request_review` | Request a provider to review a document |
 | `workspace_review_status` | Check review completion status |
@@ -244,36 +238,25 @@ Turborepo monorepo with 9 packages:
 | `workspace_create_document` | Create a general-purpose workspace document with title, markdown content, and optional metadata |
 | `workspace_read` | Read document contents |
 | `workspace_list` | List all workspace documents |
-
-### Provider Management (2)
-
-| Tool | Description |
-|------|-------------|
-| `provider_list` | List providers with status and capabilities |
-| `provider_health` | Health check one or all providers |
-
-### Ollama (2)
-
-| Tool | Description |
-|------|-------------|
-| `ollama_models` | List installed models with sizes and tier classification |
-| `ollama_pull` | Download a model |
-
-### Memory (6)
-
-| Tool | Description |
-|------|-------------|
-| `memory_search` | Hybrid retrieval (FTS5 + vector + graph) |
-| `memory_index` | Index files/directories into memory |
-| `memory_store` | Store a knowledge node (fact, decision, dead_end, finding) |
-| `memory_dead_ends` | Search previous failures to avoid repeating them |
-| `memory_context` | Assemble relevant context within a token budget |
-| `memory_add_edge` | Create relationship edges between knowledge nodes |
-
-### Jobs (2)
-
-| Tool | Description |
-|------|-------------|
+
+### Provider Management (2)
+
+| Tool | Description |
+|------|-------------|
+| `provider_list` | List providers with status and capabilities |
+| `provider_health` | Health check one or all providers |
+
+### Ollama (2)
+
+| Tool | Description |
+|------|-------------|
+| `ollama_models` | List installed models with sizes and tier classification |
+| `ollama_pull` | Download a model |
+
+### Jobs (2)
+
+| Tool | Description |
+|------|-------------|
 | `cli_job_submit` | Submit a long-running CLI task to background |
 | `cli_job_status` | Check job status and output |
 
@@ -282,62 +265,61 @@ Turborepo monorepo with 9 packages:
 | Tool | Description |
 |------|-------------|
 | `qa_run` | Run automatic QA with detected build/test commands and a PASS/FAIL summary |
-
-### Trace / Observability (3)
-
-| Tool | Description |
-|------|-------------|
-| `trace_query` | Query trace records with filtering (provider, task, time range) |
-| `trace_summary` | Get quality stats, performance metrics, and difficulty qualification per provider |
-| `trace_visualize` | Generate a Mermaid diagram of a traced operation's flow |
-
----
-
-## Configuration
-
-### providers.config.json (Optional)
-
-Agestra auto-detects providers at startup. For manual control, create `providers.config.json` in the project root:
-
-| Field | Description |
-|-------|-------------|
-| `defaultProvider` | Provider ID when none specified |
-| `providers[].id` | Unique identifier |
-| `providers[].type` | `ollama`, `gemini-cli`, or `codex-cli` |
-| `providers[].enabled` | Load at startup |
-| `providers[].config` | Type-specific settings (host, timeout, etc.) |
-
-### Runtime Data
-
-Stored under `.agestra/` (gitignored):
-
-| Path | Purpose |
-|------|---------|
-| `.agestra/sessions/` | Debate and task session state |
+
+### Trace / Observability (3)
+
+| Tool | Description |
+|------|-------------|
+| `trace_query` | Query trace records with filtering (provider, task, time range) |
+| `trace_summary` | Get quality stats, performance metrics, and difficulty qualification per provider |
+| `trace_visualize` | Generate a Mermaid diagram of a traced operation's flow |
+
+---
+
+## Configuration
+
+### providers.config.json (Optional)
+
+Agestra auto-detects providers at startup. For manual control, create `providers.config.json` in the project root:
+
+| Field | Description |
+|-------|-------------|
+| `defaultProvider` | Provider ID when none specified |
+| `providers[].id` | Unique identifier |
+| `providers[].type` | `ollama`, `gemini-cli`, or `codex-cli` |
+| `providers[].enabled` | Load at startup |
+| `providers[].config` | Type-specific settings (host, timeout, etc.) |
+
+### Runtime Data
+
+Stored under `.agestra/` (gitignored):
+
+| Path | Purpose |
+|------|---------|
+| `.agestra/sessions/` | Debate and task session state |
 | `.agestra/workspace/` | Workspace documents (reviews, notes, reports) |
-| `.agestra/memory.db` | GraphRAG SQLite database |
-| `.agestra/.jobs/` | Background job queue |
-| `.agestra/.workers/` | CLI worker state, manifests, and output logs |
-| `.agestra/worktrees/` | Git worktrees for isolated CLI worker execution |
-| `.agestra/traces/` | Provider trace JSONL (auto-pruned after 30 days) |
-
----
-
-## Development
-
-```bash
-npm install        # Install dependencies
-npm run build      # Build all packages (Turborepo)
-npm test           # Run all tests (Vitest)
-npm run bundle     # Build single-file plugin bundle (esbuild)
-npm run dev        # Watch mode
-npm run lint       # Lint (ESLint)
-npm run clean      # Remove dist/
-```
-
-### Project Structure
-
-```
+| `.agestra/.jobs/` | Background job queue |
+| `.agestra/.workers/` | CLI worker state, manifests, and output logs |
+| `.agestra/worktrees/` | Git worktrees for isolated CLI worker execution |
+| `.agestra/traces/` | Provider trace JSONL (auto-pruned after 30 days) |
+
+---
+
+## Development
+
+```bash
+npm install        # Install dependencies
+npm run build      # Build all packages (Turborepo)
+npm test           # Run all tests (Vitest)
+npm run bundle     # Build single-file plugin bundle (esbuild)
+npm run dev        # Watch mode
+npm run lint       # Lint (ESLint)
+npm run clean      # Remove dist/
+```
+
+### Project Structure
+
+```
 agestra/
 ├── AGENTS.md               # Codex host instructions
 ├── GEMINI.md               # Gemini host instructions
@@ -356,48 +338,47 @@ agestra/
 │   ├── idea.md              # /agestra idea — improvement discovery
 │   ├── design.md            # /agestra design — architecture exploration
 │   └── implement.md         # /agestra implement — execution workflow
-├── agents/
-│   ├── agestra-reviewer.md  # Strict quality verifier (Opus)
-│   ├── agestra-designer.md  # Architecture explorer (Opus)
-│   ├── agestra-ideator.md   # Improvement discoverer (Sonnet)
-│   ├── agestra-moderator.md # Multi-mode facilitator (Sonnet)
-│   ├── agestra-qa.md        # QA verifier (Opus, no code writes)
-│   └── agestra-team-lead.md # Full orchestrator (Sonnet, no code writes)
-├── skills/
-│   ├── provider-guide.md    # Provider routing and mode reference
-│   ├── worker-manage.md     # CLI worker management
-│   ├── cancel.md            # Graceful operation cancellation
-│   ├── build-fix.md         # Build error auto-repair
-│   └── trace.md             # Execution timeline viewer
-├── hooks/
-│   └── user-prompt-submit.md  # Tool recommendation hook
-├── dist/
-│   └── bundle.js            # Single-file MCP server bundle
+├── agents/
+│   ├── agestra-reviewer.md  # Strict quality verifier (Opus)
+│   ├── agestra-designer.md  # Architecture explorer (Opus)
+│   ├── agestra-ideator.md   # Improvement discoverer (Sonnet)
+│   ├── agestra-moderator.md # Multi-mode facilitator (Sonnet)
+│   ├── agestra-qa.md        # QA verifier (Opus, no code writes)
+│   └── agestra-team-lead.md # Full orchestrator (Sonnet, no code writes)
+├── skills/
+│   ├── provider-guide.md    # Provider routing and mode reference
+│   ├── worker-manage.md     # CLI worker management
+│   ├── cancel.md            # Graceful operation cancellation
+│   ├── build-fix.md         # Build error auto-repair
+│   └── trace.md             # Execution timeline viewer
+├── hooks/
+│   └── user-prompt-submit.md  # Tool recommendation hook
+├── dist/
+│   └── bundle.js            # Single-file MCP server bundle
 ├── 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
-│   ├── provider-codex/      # Codex CLI adapter
-│   ├── agents/              # Debate engine, dispatcher, cross-validator
+│   ├── core/                # AIProvider interface, registry, security, workers
+│   ├── provider-ollama/     # Ollama HTTP adapter
+│   ├── provider-gemini/     # Gemini CLI adapter
+│   ├── provider-codex/      # Codex CLI adapter
+│   ├── agents/              # Debate engine, dispatcher, cross-validator
 │   ├── workspace/           # Workspace document manager
-│   ├── memory/              # GraphRAG: hybrid search, dead-end tracking
-│   └── mcp-server/          # MCP server, 31 tools, environment-aware filtering, dispatch
-├── package.json             # Workspace root
-└── turbo.json               # Turborepo pipeline
-```
-
-### Adding a Provider
-
-1. Create `packages/provider-<name>/` implementing `AIProvider`.
-2. Add a factory in `packages/mcp-server/src/index.ts`.
-3. `npm run build && npm test`
-
----
-
+│   └── mcp-server/          # MCP server, 25 tools, environment-aware filtering, dispatch
+├── package.json             # Workspace root
+└── turbo.json               # Turborepo pipeline
+```
+
+### Adding a Provider
+
+1. Create `packages/provider-<name>/` implementing `AIProvider`.
+2. Add a factory in `packages/mcp-server/src/index.ts`.
+3. `npm run build && npm test`
+
+---
+
 ## Uninstall
 
 Claude Code:
@@ -419,9 +400,9 @@ npm run uninstall:gemini
 ```
 
 If you also want to delete generated project data, remove the `.agestra/` directory manually.
-
----
-
-## License
-
-[GPL-3.0](LICENSE)
+
+---
+
+## License
+
+[GPL-3.0](LICENSE)