Big News: Socket raises $60M Series C at a $1B valuation to secure software supply chains for AI-driven development.Announcement →
agestra - npm Package Compare versions
@@ -7,3 +7,3 @@ { | ||
| "metadata": { | ||
| "description": "Multi-AI orchestration plugin for Claude Code", | ||
| "description": "Multi-host MCP orchestration plugin for Claude Code", | ||
| "version": "1.0.0" | ||
@@ -15,4 +15,4 @@ }, | ||
| "source": "./", | ||
| "description": "Orchestrate Ollama, Gemini, and Codex for multi-AI debates, code review, and cross-validation", | ||
| "version": "4.13.3", | ||
| "description": "Multi-host MCP orchestration across Claude, Ollama, Gemini, and Codex for review, QA, and cross-validation", | ||
| "version": "4.13.4", | ||
| "author": { | ||
@@ -26,8 +26,12 @@ "name": "mua-vtuber" | ||
| "claude-code-plugin", | ||
| "mcp-server", | ||
| "mcp", | ||
| "multi-agent", | ||
| "multi-ai", | ||
| "ollama", | ||
| "local-llm", | ||
| "gemini", | ||
| "codex", | ||
| "ai-orchestration" | ||
| "ai-orchestration", | ||
| "agent-orchestration" | ||
| ], | ||
@@ -37,4 +41,6 @@ "category": "external-integrations", | ||
| "orchestration", | ||
| "multi-agent", | ||
| "debate", | ||
| "code-review", | ||
| "qa", | ||
| "cross-validation" | ||
@@ -41,0 +47,0 @@ ] |
| { | ||
| "name": "agestra", | ||
| "version": "4.13.3", | ||
| "description": "Claude Code plugin — orchestrate Ollama, Gemini, and Codex for multi-AI debates, code review, and cross-validation", | ||
| "version": "4.13.4", | ||
| "description": "Claude Code plugin — multi-host MCP orchestration across Claude, Ollama, Gemini, and Codex for review, QA, and cross-validation", | ||
| "mcpServers": { | ||
@@ -6,0 +6,0 @@ "agestra": { |
@@ -133,10 +133,10 @@ --- | ||
| - Which CLI tools are installed (codex, gemini, tmux) | ||
| - Which Ollama models are available and their tier classifications | ||
| - Which frontier and local models are available, including Ollama model tiers when present | ||
| - Whether autonomous work is possible (CLI workers + git worktree) | ||
| - Available modes: leader-host-only (`claude_only` or `leader_only` from legacy environment output), 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) | ||
| 3. Call `trace_summary` to check whether prior provider quality observations exist. | ||
| - Treat trace quality as optional evidence, not guaranteed knowledge. | ||
| - If present, use it as a tie-breaker between otherwise suitable providers. | ||
| - If absent, do not invent quality history; route by detected model capability, task risk, and execution policy. | ||
| 4. Read existing design documents in `docs/plans/`. | ||
@@ -146,3 +146,3 @@ 5. Store environment capabilities for later mode selection: | ||
| - `available_providers`: which are online? | ||
| - `ollama_tiers`: model size classifications | ||
| - `model_capabilities`: detected frontier/local model capability and tier classifications | ||
| 6. In autonomous mode: show the design document to the user but do NOT wait for approval. | ||
@@ -161,3 +161,3 @@ | ||
| | **Leader-host only** | The current host uses `agestra-implementer` and specialist agents/prompts; no external coding workers. QA routing still follows the configured-provider default unless host-only QA is requested | | ||
| | **Multi-AI** | CLI AIs work autonomously when suitable, Ollama handles simple proposal work, host-local agents handle scoped implementation/review/QA | | ||
| | **Multi-AI** | Work is distributed according to detected model capability, including frontier and local models. CLI AIs work autonomously when suitable, local/tool models may handle scoped read/write work when their execution policy allows it, and host-local agents handle implementation/review/QA that should stay on the leader host | | ||
@@ -201,4 +201,4 @@ If no external providers available: skip selection, proceed with Leader-host only. | ||
| |---------------------|----------| | ||
| | Complex implementation, multi-step reasoning | MCP: `cli_worker_spawn` (Codex/Gemini) | | ||
| | Simple transforms, formatting, repeated pattern application | MCP: `ai_chat` (Ollama, tier-matched model) for a patch plan or candidate diff; `agestra-implementer` applies it unless an edit-capable safe worker exists | | ||
| | Complex implementation, multi-step reasoning | High-capability detected model, usually MCP: `cli_worker_spawn` (Codex/Gemini) or host-local `agestra-implementer` | | ||
| | Simple transforms, formatting, repeated pattern application | Capability-matched local/tool model through MCP: `ai_chat` when available. With `workspace-write` / `full-auto`, it may apply scoped file edits through AgentLoop tools; with `read-only`, it returns a patch plan or candidate diff for `agestra-implementer` to apply | | ||
| | Core implementation, design-sensitive changes | `agestra-implementer` or a high-capability CLI worker | | ||
@@ -209,3 +209,3 @@ | Product/unit/integration test writing | `agestra-implementer` or a high-capability CLI worker | | ||
| **Quality-Based Provider Selection:** | ||
| **Capability-First Provider Selection:** | ||
@@ -218,7 +218,7 @@ Before assigning any task, determine its difficulty level: | ||
| 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 `agestra-implementer` for the task | ||
| 5. New providers (no quality data) start at low difficulty — assign simple tasks first to build their track record | ||
| 1. Check detected model capability, provider type, execution policy, and task risk. | ||
| 2. Only assign a task to a provider whose detected capability qualifies for its difficulty level. | ||
| 3. If `trace_summary` has relevant quality data, use it as a tie-breaker between otherwise qualified providers. | ||
| 4. If no provider qualifies, fall back to `agestra-implementer` for the task. | ||
| 5. Providers with no trace data are unknown, not bad; start them on lower-risk, tightly scoped assignments until evidence accumulates. | ||
@@ -256,5 +256,8 @@ 4. Define dependency relationships between tasks. | ||
| **Ollama tasks (MCP):** | ||
| - Call `ai_chat` with tier-matched model for simple tasks. | ||
| - Apply the result manually through `agestra-implementer` after inspection. | ||
| **Local/tool-model tasks (MCP `ai_chat`, currently Ollama-backed):** | ||
| - Distribute work according to detected model capability, including frontier and local models. Call `ai_chat` with a capability-matched local/tool model for scoped tasks when available. | ||
| - Respect the provider's `executionPolicy` from `provider_list` / setup config: | ||
| - `read-only` → the model receives read/search tools only and must return analysis, a patch plan, or a candidate diff. | ||
| - `workspace-write` / `full-auto` → the model may receive read/write AgentLoop tools and can make scoped workspace edits. | ||
| - After any write-enabled local/tool-model task, inspect the git diff before proceeding. If the diff exceeds the assigned files, touches risky surfaces, or looks incomplete, route correction to `agestra-implementer` or a higher-capability CLI worker. | ||
@@ -361,4 +364,4 @@ **Result Integration:** | ||
| Default participant policy: | ||
| - Include every configured and available review-capable provider by default, not only the "best" one. Use `trace_summary` to assign lenses and order attention, not to shrink the brigade unless a provider is unavailable, explicitly excluded, or clearly unqualified for the requested lens. | ||
| - Exclude `ollama` by default unless the user explicitly requested it for lightweight cross-checking. | ||
| - Include every configured and available review-capable provider by default, not only the "best" one. Use `trace_summary`, when populated, to assign lenses and order attention, not to shrink the brigade unless a provider is unavailable, explicitly excluded, or clearly unqualified for the requested lens. | ||
| - Include configured providers when their detected model capability qualifies for the assigned QA lens; use trace quality only as optional supporting evidence, and use read-only debate tools for QA/review so they do not modify source files during verification. | ||
| - Keep the host QA participant in the flow even when external providers are present, because executable evidence, E2E/runtime observation, and local command output are host-owned. In structured debate, this is the `claude-qa` compatibility participant when auto-injected or explicitly listed. | ||
@@ -368,2 +371,49 @@ - Assign distinct lenses so the output is not three copies of the same review. Suggested lenses: spec-to-code compliance, progress-table truthfulness, integration/regression risk, edge/error states, test adequacy, safety hygiene, and E2E artifact interpretation. | ||
| Scale and reliability controls: | ||
| - For whole-project, large-directory, or deep review/QA requests, create a bounded evidence packet before provider fan-out. Include changed files, key entry points, build/test evidence, relevant configs/docs, and explicit out-of-scope areas; do not expect every external CLI provider to discover a large repository from scratch inside one turn. | ||
| - Use `participant_timeout_ms` of at least `600000` for broad or deep structured debates, and raise it further only when the user accepts the wait. If participants still time out, split the task by subsystem and run multiple narrower debates. | ||
| - If Gemini reports a workspace trust issue, treat it as provider unavailable for that run, tell the user the project must be trusted in Gemini CLI, and continue with the remaining participants or retry after trust is fixed. Do not count trust failures as review disagreement. | ||
| #### 5M.0b Host specialist pre-injection (REQUIRED on Claude-Code host) | ||
| > Why this exists: the structured-debate engine cannot ask the Claude-Code host to call its own native subagents back through MCP — that would invert the dependency direction. Instead, when the leader host wants Claude specialist input (`claude-reviewer` / `claude-qa` / `claude-security`) inside a multi-AI debate, the leader runs the native subagent **before** starting the debate and supplies the result as a `source_documents` entry. The moderator engine then loads that document as the specialist's individual review and excludes the specialist from subsequent consensus rounds. External providers still fan out and debate normally. This is the Phase B routing contract; do not bypass it. | ||
| > | ||
| > When this applies: ANY structured debate (QA Brigade, multi-AI review, multi-AI security) on Claude-Code host that wants Claude specialist participation. If you only have external providers and no Claude specialist lens, skip this subsection entirely. | ||
| Procedure (run before `agent_debate_structured`): | ||
| 1. Decide which Claude specialists belong in the brigade — typically `agestra-qa` for QA Brigade, `agestra-reviewer` for multi-AI review, `agestra-security` for multi-AI security. You may include more than one (e.g., QA Brigade may also pull in `agestra-reviewer` as a supporting lens). | ||
| 2. For each chosen specialist, invoke it via the `Agent` tool with the same scope/files/design references the external providers will see. Wait for the result. | ||
| 3. Persist each specialist result as a workspace document via `workspace_create_document` (kind: `individual`). Capture the returned `document_id`. | ||
| 4. Build the `agent_debate_structured` arguments so they self-describe the pre-injection: | ||
| - `participants`: include the matching Claude specialist IDs (`claude-reviewer`, `claude-qa`, `claude-security`) alongside the external providers. The schema requires the `provider` field of every `source_documents` entry to be present in `participants`. | ||
| - `source_documents`: one entry per specialist — `{ "document_id": "<id from workspace_create_document>", "provider": "claude-reviewer" | "claude-qa" | "claude-security" }`. | ||
| - `auto_inject_specialists`: `false`. You already added the specialists manually; auto-inject would duplicate. | ||
| 5. Start the debate. The moderator will load each pre-injected document as the specialist's individual review, parse its `<proposals>` block into ledger items, and skip that specialist in every consensus round. External providers fan out and debate as usual; they may vote on specialist-proposed items. | ||
| Round-loop note (Phase C — host-turn handoff): pre-injected specialists still skip consensus rounds. Specialists that were NOT pre-injected (e.g. you let `auto_inject_specialists: true` add a Claude reviewer mid-debate, or you intentionally listed `claude-reviewer` in `participants` *without* a matching `source_documents` entry) now participate every round through the host-turn handoff protocol described in 5M.0c. Use 5M.0b when you only need a single up-front specialist read; use 5M.0c on top of it when you also want round-by-round specialist stances. | ||
| Multi-host note: on hosts that do not have a Claude specialist surface (Codex, Gemini, Ollama-only configurations), do not synthesize fake specialist documents. Either run the debate without Claude specialists or ask the user to add a host that exposes them. | ||
| #### 5M.0c Round-time specialist host-turn handoff (Phase C) | ||
| > Why this exists: when a Claude specialist participates in consensus rounds (rather than only contributing an upfront review), the moderator engine cannot call back into the host's native subagent. The engine instead parks the round, advertises the pending request through the persisted snapshot, and waits for the leader to dispatch the subagent and post the result. This keeps the dependency direction MCP-compliant on every host. | ||
| When this engages: any structured debate where a Claude specialist (`claude-reviewer` / `claude-qa` / `claude-security`) is in `participants`, the leader host is Claude-Code, and the participant is NOT covered by a `source_documents` entry. The engine activates the handoff per round — independently of 5M.0b pre-injection. | ||
| Polling loop (run alongside the existing 5M.2 polling): | ||
| 1. Call `agent_debate_status` until the snapshot reports `phase: awaiting-host-turn`. The structured response then carries a `pending_host_turns[]` array with one entry per specialist that owes a turn this round. Each entry exposes `participant_id`, `agent_name` (e.g. `agestra-reviewer`), `round`, `prompt`, optional `system_prompt`, optional `files`, and `requested_at`. | ||
| 2. For every entry, invoke the matching native subagent via the `Agent` tool with `subagent_type: <agent_name>`. Pass the entry's `prompt` verbatim — do not paraphrase, do not strip the JSON contract. Forward `files` if listed. The subagent must return its `<consensus_turn>` JSON exactly the way an external provider would. | ||
| 3. Post the verbatim subagent text back via `agent_debate_submit_turn` with `{ session_id, participant_id, content: <subagent text>, round }`. The tool acknowledges with the count of remaining pending turns. | ||
| 4. After every pending entry is submitted, the moderator round resumes automatically. The next `agent_debate_status` poll will report `phase: consensus-round` (or the next gate), and the round transcript will list the specialist's stance just like an external provider's. | ||
| Failure handling: | ||
| - Submit each specialist's response separately. If the subagent fails or refuses, do NOT submit a fabricated turn; let the gate time out so the moderator records the missing vote with `failureReason: "host-turn timeout"`. Re-running the specialist and submitting the next round is allowed. | ||
| - Round-mismatched submissions (`round` not equal to the pending entry's round) are rejected; align on the latest snapshot before re-trying. | ||
| - Duplicate submissions for the same participant in the same gate are rejected. If you need to revise a stance, wait for the next round. | ||
| - The handoff timeout defaults to `STRUCTURED_DEBATE_HOST_TURN_TIMEOUT_MS` (20 minutes). Tests override it through engine deps; production debates inherit the default. | ||
| Multi-host note: this handoff path is only meaningful when the leader host can natively invoke the specialist subagents (Claude-Code today). Other hosts continue to rely on 5M.0b pre-injection or omit the specialists entirely. | ||
| #### 5M.0a QA mapping onto the existing JSON ledger | ||
@@ -400,8 +450,9 @@ | ||
| - `scope` — concrete framing: file list, task description, design doc path, changed files, and host QA report/evidence path. | ||
| - `participants` — the provider/agent IDs the user specified, or all configured and available review-capable providers from `provider_list`, plus the host QA participant (`claude-qa` compatibility ID) through auto-injection or explicit listing. For QA, use `trace_summary` for lens assignment rather than narrowing by default. Exclude `ollama` unless explicitly requested for lightweight cross-checking. | ||
| - `source_documents` — optional pre-created individual documents, each as `{ "document_id": "...", "provider": "..." }`. For QA, pass the host QA report/evidence packet as source material for the matching host QA participant. The `provider` value must be present in `participants`. | ||
| - `auto_inject_specialists` — default `true`. When true, the moderator auto-adds host reviewer/QA/security specialists on top of `participants` based on topic heuristics (currently exposed as `claude-reviewer`, `claude-qa`, and/or `claude-security` for compatibility). When the user wants verbatim participants only, pass `false`. | ||
| - `participants` — the provider/agent IDs the user specified, or all configured and available review-capable providers from `provider_list`, plus the host QA participant (`claude-qa` compatibility ID) through auto-injection or explicit listing. For QA, use detected model capabilities for lens assignment; use `trace_summary` only when it has relevant observations. | ||
| - `source_documents` — pre-created individual documents, each as `{ "document_id": "...", "provider": "..." }`. **Required** when the brigade includes Claude specialists on Claude-Code host (see 5M.0b — host runs the native subagent first, persists the result, and supplies it here). The `provider` value must be present in `participants`. For QA, also pass the host QA report/evidence packet as source material for the matching host QA participant. Pre-injected providers skip the individual fan-out AND every consensus round. | ||
| - `auto_inject_specialists` — default `true` only when the leader has not pre-injected specialists. **Pass `false` whenever you supply specialist `source_documents`**, otherwise the moderator may add a duplicate specialist participant on top of the one you already injected. When the user wants verbatim participants only, also pass `false`. | ||
| - `exclude_participants` — participant IDs to never include, applied regardless of `auto_inject_specialists`. Use this when the user explicitly wants a provider (including Ollama — there is no automatic Ollama filter anymore) kept out. | ||
| - `leader` — omit unless you need to override the session-context leader. | ||
| - `max_rounds` — default `10`. Raise for contested topics, lower for quick smoke-debates. | ||
| - `participant_timeout_ms` — omit for normal scoped reviews; set at least `600000` for whole-project, large-directory, deep review, or provider timeouts. | ||
| - `individual_review_prompt` / `files` — optional framing for the individual-review fan-out. | ||
@@ -492,3 +543,3 @@ - `locale` — pass the locale resolved from `agestra.config.json` (fall back to providers.config locale). The moderator uses it for human-facing text; provider prompts remain English regardless. | ||
| - Work mode selected (Leader-host only / Multi-AI) | ||
| - Total tasks, host-implementer task count, CLI workers count, proposal-only provider task count | ||
| - Total tasks, host-implementer task count, CLI worker count, local/tool-model AgentLoop task count with read-only vs write-enabled policy | ||
| - Task dependency graph | ||
@@ -519,4 +570,4 @@ - Risk flags (shared files, complex tasks) | ||
| <Ollama_Routing> | ||
| When routing tasks to Ollama, check model size via `ollama_models` first: | ||
| <Model_Capability_Routing> | ||
| Distribute work according to the capabilities of detected models, including frontier and local models. For local Ollama models, check model size via `ollama_models` first: | ||
@@ -530,5 +581,9 @@ | Model Size | Suitable Tasks | | ||
| Do NOT assign tasks beyond a model's capability. When in doubt, use a cloud provider instead. | ||
| </Ollama_Routing> | ||
| Do NOT assign tasks beyond a detected model's capability. When in doubt, use a higher-capability frontier provider or host-local specialist instead. | ||
| For implementation tasks, also check the provider execution policy: | ||
| - `read-only`: assign only reading, searching, analysis, review, patch-plan, or candidate-diff work. | ||
| - `workspace-write` / `full-auto`: the model has the same workspace write permission class as other write-enabled providers. Keep tasks scoped to explicit files and inspect the resulting diff before continuing. | ||
| </Model_Capability_Routing> | ||
| <Principles> | ||
@@ -572,3 +627,3 @@ | ||
| - `provider_list` / `provider_health` — check external AI availability | ||
| - `trace_query` / `trace_summary` / `trace_visualize` — provider quality tracking and inspection | ||
| - `trace_query` / `trace_summary` / `trace_visualize` — optional provider quality observations from prior recorded runs | ||
| - `ai_chat` / `ai_analyze_files` / `ai_compare` — query external AI | ||
@@ -615,3 +670,3 @@ - `agent_debate_structured` — start a structured multi-AI debate in the background (individual/source material → clarification → JSON consensus rounds → aggregation → approval gate). It returns `status: running`; poll `agent_debate_status`. Supports `mode: "review" | "idea"`, optional `source_documents`, `auto_inject_specialists` (default `true`) to auto-add host reviewer/QA/security specialists (compatibility IDs: `claude-reviewer` / `claude-qa` / `claude-security`) based on topic, and `exclude_participants` as the escape hatch (also the way to keep Ollama or any other provider out — there is no automatic Ollama filter). | ||
| - Do NOT skip the user approval step before executing tasks (in supervised mode). | ||
| - Do NOT assign complex tasks to small Ollama models. | ||
| - Do NOT assign complex tasks to models whose detected capability does not qualify, including small local models. | ||
| - Do NOT accept "simplified" or "partial" results from AIs. | ||
@@ -618,0 +673,0 @@ - Do NOT proceed to QA until you've inspected all results yourself. |
@@ -100,3 +100,3 @@ --- | ||
| Direct execution from this command bypasses team-lead's quality-based routing (`trace_summary`), task design, and consistency enforcement. Always go through team-lead in Branch B. | ||
| Direct execution from this command bypasses team-lead's capability-based routing and optional trace-assisted signals (`trace_summary`), task design, and consistency enforcement. Always go through team-lead in Branch B. | ||
@@ -103,0 +103,0 @@ ## Step 3: Present the result |
+1
-1
@@ -90,3 +90,3 @@ --- | ||
| Direct execution bypasses team-lead's quality-based routing and consistency enforcement. Always go through team-lead in Branch B. | ||
| Direct execution bypasses team-lead's capability-based routing, optional trace-assisted signals, and consistency enforcement. Always go through team-lead in Branch B. | ||
@@ -93,0 +93,0 @@ ## Step 3: Present to the user |
@@ -54,6 +54,7 @@ --- | ||
| Routing guidance: | ||
| - Simple and repetitive, low-risk work → prefer Ollama for analysis or patch suggestions, then `agestra-implementer` applies the change. Do not assume Ollama can edit files autonomously. | ||
| - Complex or multi-file implementation → prefer Codex/Gemini CLI workers in isolated worktrees. | ||
| - Distribute work according to detected model capability, including frontier and local models. Use model tier, task risk, and execution policy first; use trace quality data only when it exists. | ||
| - Simple and repetitive, low-risk work → prefer a capability-matched local/tool model when available. If its `executionPolicy` is `workspace-write` or `full-auto`, it may use AgentLoop read/write tools through `ai_chat`; if it is `read-only`, use it for analysis, patch plans, or candidate diffs only. | ||
| - Complex or multi-file implementation → prefer high-capability frontier/CLI workers such as Codex/Gemini in isolated worktrees, or the host implementer when that is safer. | ||
| - Small but risky work → prefer `agestra-implementer` or a high-capability CLI worker, with QA/review after. | ||
| - If trace quality data exists, use it to pick between qualified providers. If no trace data exists, treat providers as unproven and start with lower-risk assignments. | ||
| - If trace quality data exists, use it only as a tie-breaker between otherwise qualified providers. If no trace data exists, do not invent quality history; start with lower-risk, tightly scoped assignments. | ||
@@ -110,3 +111,3 @@ ## Step 4: Ensure there is a design basis | ||
| - Dispatches CLI workers (`cli_worker_spawn`) for suitable Codex/Gemini tasks in isolated worktrees | ||
| - Uses Ollama only for proposal-quality work via `ai_chat` | ||
| - Uses capability-matched local/tool models through `ai_chat` with tools selected from their `executionPolicy`: read-only policies get read/search tools, while `workspace-write` / `full-auto` policies may perform scoped file writes. | ||
| - Reviews changes with `agent_changes_review` before merge | ||
@@ -113,0 +114,0 @@ - Runs Phase 5M structured QA debate (cross-validation across providers) |
+2
-1
@@ -72,4 +72,5 @@ --- | ||
| - **Report artifact path expectation:** `docs/reports/qa/YYYY-MM-DD-qa-[target].md` | ||
| - **Available providers:** from `environment_check`, exclude `ollama` unless explicitly requested for lightweight cross-checking | ||
| - **Available providers:** from `environment_check`; include configured providers when their detected model capability is suitable, using read-only QA/review tools so verification cannot modify source files | ||
| - **Requested providers:** explicit names captured from user wording; otherwise "all configured and available review-capable providers" | ||
| - **Specialist pre-injection (Claude-Code host):** when the brigade should include `claude-qa` (and optionally `claude-reviewer` / `claude-security` as supporting lenses), team-lead MUST follow `agents/agestra-team-lead.md` Phase 5M.0b — run the host specialist (`agestra-qa` etc.) via the `Agent` tool first, persist each result through `workspace_create_document`, then pass them as `source_documents` entries with `auto_inject_specialists: false`. The pre-injected host QA report itself doubles as the evidence packet for the matching `claude-qa` participant. Do NOT rely on `auto_inject_specialists: true` when a Claude specialist participant is wanted | ||
| - **Brigade lenses:** host executable evidence, spec-to-code compliance, implementation progress truthfulness, integration/regression risk, edge/error states, test adequacy, basic safety hygiene, and E2E artifact review when E2E ran | ||
@@ -76,0 +77,0 @@ - **JSON finding flow:** candidate findings become `ITEM-*` ledger items; participants use the existing `agree` / `disagree` / `opinion` / `revise` stance contract; only ledger-accepted items affect the final verdict |
@@ -85,4 +85,6 @@ --- | ||
| - **Report artifact path expectation:** `docs/reports/review/YYYY-MM-DD-review-[target].md` | ||
| - **Available providers:** from `environment_check`, exclude `ollama` unless explicitly requested for lightweight commentary | ||
| - **Available providers:** from `environment_check`; include configured providers when their detected model capability is suitable, using read-only review tools for code/document critique | ||
| - **Requested providers:** explicit names captured from user wording; otherwise "all available review-capable" | ||
| - **Specialist pre-injection (Claude-Code host):** when the brigade should include the `claude-reviewer` specialist lens, team-lead MUST follow `agents/agestra-team-lead.md` Phase 5M.0b — run `agestra-reviewer` via the `Agent` tool first, persist the result through `workspace_create_document`, then pass it as a `source_documents` entry with `auto_inject_specialists: false`. Do NOT rely on `auto_inject_specialists: true` when a Claude specialist participant is wanted — the structured-debate engine cannot call back into the Claude-Code host's native subagents | ||
| - **Scale controls:** if the target is a whole project, a large directory, or deep review, instruct team-lead to create a bounded review packet before fan-out: changed files, key entry points, relevant docs/config, and explicit exclusions. Do not ask external CLI providers to explore an unbounded large repository from scratch. Use `participant_timeout_ms: 600000` or higher for large/deep reviews, and split the review into narrower area debates if providers still time out. | ||
| - **Locale:** from `setup_status` | ||
@@ -103,3 +105,3 @@ - **Original user request:** preserve verbatim | ||
| Direct execution from this command bypasses team-lead's task design, quality-based routing (`trace_summary`), and consistency enforcement. Always go through team-lead in Branch B. | ||
| Direct execution from this command bypasses team-lead's task design, capability-based routing with optional trace-assisted signals (`trace_summary`), and consistency enforcement. Always go through team-lead in Branch B. | ||
@@ -106,0 +108,0 @@ ## Step 4: Present the final result |
@@ -62,4 +62,5 @@ --- | ||
| - **Report artifact path expectation:** `docs/reports/security/YYYY-MM-DD-security-[target].md` | ||
| - **Available providers:** from `environment_check`, exclude `ollama` unless explicitly requested for lightweight commentary | ||
| - **Available providers:** from `environment_check`; include configured providers when their detected model capability is suitable, using read-only security-review tools unless the user explicitly approves a separate implementation task | ||
| - **Requested providers:** explicit names captured from user wording; otherwise "all available security-capable" | ||
| - **Specialist pre-injection (Claude-Code host):** when the brigade should include the `claude-security` specialist lens, team-lead MUST follow `agents/agestra-team-lead.md` Phase 5M.0b — run `agestra-security` via the `Agent` tool first, persist the result through `workspace_create_document`, then pass it as a `source_documents` entry with `auto_inject_specialists: false`. The structured-debate engine cannot call back into the Claude-Code host's native subagents, so `auto_inject_specialists: true` is unsafe whenever a Claude specialist participant is wanted | ||
| - **Locale:** from `setup_status` | ||
@@ -66,0 +67,0 @@ - **Original user request:** preserve verbatim |
@@ -215,4 +215,4 @@ #!/usr/bin/env node | ||
| " 3. Present a task-to-provider routing table before spawning workers", | ||
| " 4. Use Ollama only for simple/repetitive proposal work unless a safe edit-capable path exists", | ||
| " 5. Use `agestra-implementer` or Codex/Gemini CLI workers for actual code edits", | ||
| " 4. Distribute work according to detected model capability, including frontier and local models", | ||
| " 5. Use safe edit-capable paths for actual code edits: `agestra-implementer`, Codex/Gemini CLI workers, or write-enabled local/tool models when policy and capability qualify", | ||
| "", | ||
@@ -219,0 +219,0 @@ "If user selects NO:", |
+9
-3
| { | ||
| "name": "agestra", | ||
| "version": "4.13.3", | ||
| "description": "Multi-host AI orchestration toolkit for Claude Code, Codex CLI, and Gemini CLI", | ||
| "version": "4.13.4", | ||
| "description": "Multi-host MCP orchestration for Claude Code, Codex CLI, Gemini CLI, and local models", | ||
| "type": "module", | ||
@@ -59,10 +59,16 @@ "packageManager": "npm@11.11.0", | ||
| "claude-code-plugin", | ||
| "mcp-server", | ||
| "codex-cli", | ||
| "gemini-cli", | ||
| "mcp", | ||
| "multi-agent", | ||
| "multi-ai", | ||
| "ollama", | ||
| "local-llm", | ||
| "gemini", | ||
| "codex", | ||
| "ai-orchestration" | ||
| "ai-orchestration", | ||
| "agent-orchestration", | ||
| "code-review", | ||
| "cross-validation" | ||
| ], | ||
@@ -69,0 +75,0 @@ "repository": { |
+47
-54
@@ -6,53 +6,31 @@ # Agestra | ||
| **Agent + Orchestra** — Claude Code、Codex CLI、Gemini CLI で共通利用できるマルチホスト・オーケストレーションツールキット。 | ||
| **Agent + Orchestra** — Claude Code、Codex CLI、Gemini CLI、ローカルモデルを調整するマルチホスト MCP オーケストレーションツールキット。 | ||
| [English](README.md) | [한국어](README.ko.md) | [日本語](README.ja.md) | [中文](README.zh.md) | ||
| Agestra は Ollama（ローカル）、Gemini CLI、Codex CLI を Claude Code にプラガブルなプロバイダーとして接続し、独立集約、合意形成ディベート、自律 CLI ワーカー、並列タスク配分、クロスバリデーション、品質ベースのプロバイダー選択を 44 個の MCP ツールで提供します。 | ||
| Agestra は Claude host/CLI、Ollama（ローカル）、Gemini CLI、Codex CLI をプラガブルなプロバイダーとして接続し、独立集約、合意形成ディベート、自律 CLI ワーカー、並列タスク配分、クロスバリデーション、任意の trace 根拠を参照する能力ベースのプロバイダールーティングを 45 個の MCP ツールで提供します。 | ||
| ## クイックスタート | ||
| ### Claude Code | ||
| まず作業するホストを選びます。ホストネイティブのコマンド/エージェントも入れる場合は `--assets` の経路を使い、サーバー接続だけでよい場合は MCP-only 登録を使います。 | ||
| ``` | ||
| /plugin marketplace add mua-vtuber/Agestra | ||
| /plugin install agestra@agestra | ||
| ``` | ||
| | ホスト | このリポジトリから | グローバル 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 では既存のプラグイン UX をそのまま維持します。Agestra は初回利用時に `environment_check` を通じて利用可能なプロバイダー（Claude host、Ollama、Gemini CLI、Codex CLI）を自動検出します。 | ||
| MCP-only 登録も利用できます: | ||
| ### Codex CLI | ||
| | ホスト | リポジトリパッケージ | チェックアウトからのグローバル登録 | | ||
| |--------|----------------------|------------------------------------| | ||
| | Codex CLI | `npm run install:codex` | `npm run install:codex:global` | | ||
| | Gemini CLI | `npm run install:gemini` | `npm run install:gemini:global` | | ||
| ``` | ||
| npm run bundle | ||
| npm run install:codex:assets | ||
| ``` | ||
| Claude はネイティブのプラグイン UX を維持します。Codex は [AGENTS.md](AGENTS.md)、生成された custom agents、登録済みの `agestra` MCP サーバーを組み合わせます。Gemini は [GEMINI.md](GEMINI.md)、`.gemini/commands/agestra/`、生成された skills、project-scope 管理ファイルまたは user-scope native extension を組み合わせます。 | ||
| グローバル npm パッケージから使う場合: | ||
| 注: `npm run install:gemini:assets` はデフォルトで user scope を使います。チェックアウトから project-scope の Gemini 管理ファイルを入れる場合は `node scripts/install-host-mcp.mjs gemini --assets --scope project` を実行してください。 | ||
| ``` | ||
| npm install -g agestra | ||
| agestra-install codex --assets | ||
| ``` | ||
| Assets セットアップ後に利用できる Gemini コマンド: | ||
| Codex ではリポジトリ直下の [AGENTS.md](AGENTS.md) と、登録済みの `agestra` MCP サーバーを一緒に使います。生成済み Codex custom agent には `--assets` が必要で、`.codex/agents/` にインストールして Agestra host-asset manifest に記録します。custom agent なしで MCP 登録だけでよい場合は `npm run install:codex` または `agestra-install codex` を使ってください。 | ||
| ### Gemini CLI | ||
| ``` | ||
| npm run bundle | ||
| npm run install:gemini:assets | ||
| ``` | ||
| グローバル npm パッケージから使う場合: | ||
| ``` | ||
| npm install -g agestra | ||
| agestra-install gemini --assets --scope user | ||
| ``` | ||
| Gemini ではリポジトリ直下の [GEMINI.md](GEMINI.md)、[`.gemini/commands/agestra/`](.gemini/commands/agestra)、生成された skills を一緒に使います。project scope の `--assets` は管理ファイルを書き込み、user scope の `--assets` は Agestra Gemini native extension をインストールします。MCP 登録だけでよい場合は `npm run install:gemini` または `agestra-install gemini` を使ってください。`npm run install:gemini:assets` はデフォルトで user scope を使うため、チェックアウトから project-scope の管理ファイルを入れる場合は `node scripts/install-host-mcp.mjs gemini --assets --scope project` を実行してください。 | ||
| セットアップ後に利用できる Gemini コマンド: | ||
| - `/agestra:setup` | ||
@@ -72,2 +50,3 @@ - `/agestra:review` | ||
| |-------------|---------------|------| | ||
| | [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 | | ||
@@ -81,3 +60,14 @@ | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `npm install -g @google/gemini-cli` | Cloud | | ||
| - **tmux** — 自律実行中の CLI ワーカーペインを可視化できます | ||
| - **Windows の ripgrep (`rg`)** — Codex が Store app bundled path の `rg` を拾って "Access is denied" になる場合は、通常の `rg.exe` が `PATH` で先に見つかるように ripgrep を別途インストールしてください: | ||
| ``` | ||
| cargo install ripgrep | ||
| ``` | ||
| 代替: | ||
| ``` | ||
| winget install BurntSushi.ripgrep.MSVC | ||
| ``` | ||
| --- | ||
@@ -102,3 +92,3 @@ | ||
| ImplRoute -->|明確に並列化できる実装| CliWorkers[Codex / Gemini CLI ワーカー<br/>分離 worktree で実装] | ||
| ImplRoute -->|単純または反復的な補助作業| Ollama[Ollama などのローカル AI<br/>草案 / パッチ候補 / 反復提案] | ||
| ImplRoute -->|能力に合うスコープ付き作業| Ollama[ローカル / ツールモデル<br/>ポリシー許可時は読み書き] | ||
| ImplRoute -->|リスクが高い中核変更| HostImpl[ホスト実装エージェント<br/>リーダーが近くで監督] | ||
@@ -156,5 +146,5 @@ CliWorkers --> ReviewDiff[リーダーが状態 / 使用量 / diff を確認] | ||
| | `/agestra design [subject]` | 実装前にアーキテクチャと設計上のトレードオフを探索 | | ||
| | `/agestra implement [task]` | Claude only または Multi-AI モードで実装を進める | | ||
| | `/agestra implement [task]` | リーダーホスト単独または Multi-AI 分散モードで実装を進める | | ||
| 外部プロバイダーが利用可能な場合、review、QA、security、design、idea ワークフローは team-lead を通じてマルチ AI クロスバリデーションへルーティングされます。プロバイダーが検出されない場合、現在のホストのローカル specialist agent が自動的に処理します。 | ||
| 外部プロバイダーが利用可能な場合、review、QA、security、design、idea ワークフローは team-lead を通じてマルチ AI クロスバリデーションへルーティングされます。QA では、team-lead が設定済みプロバイダー集合から QA Brigade を基本構成し、moderator engine の既存 `ITEM-*` / JSON stance ledger に渡します。ホスト QA が実行可能な根拠を集め、プロバイダーは異なる検証レンズを担当し、候補 finding は取り込む前に反証され、統合文書は合意と異論を両方保持します。E2E/browser/runtime 実行は引き続きホスト所有で、外部プロバイダーはその根拠をレビューします。プロバイダーが検出されない場合、現在のホストのローカル specialist agent が自動的に処理します。実装リクエストはまずタスクを分類し、AI タスク分配の提案を行うか確認できます。 | ||
@@ -165,3 +155,3 @@ ## エージェント | ||
| |--------------|--------|------| | ||
| | `agestra-team-lead` | Sonnet | フルオーケストレーター — 環境チェック、品質ベースのプロバイダー選択、作業モード選定、CLI ワーカー監督、QA ループ | | ||
| | `agestra-team-lead` | Sonnet | フルオーケストレーター — 環境チェック、能力ベースのプロバイダールーティング、作業モード選定、CLI ワーカー監督、QA ループ | | ||
| | `agestra-implementer` | Sonnet | スコープ付き実装実行役 — コード変更、テスト更新、ローカル検証 | | ||
@@ -202,3 +192,4 @@ | `agestra-e2e-writer` | Sonnet | 永続 E2E テスト作成役 — 承認済みブラウザフローテストのみ作成 | | ||
| |------------|------| | ||
| | `@agestra/core` | `AIProvider` インターフェース、難易度ベースのルーティングレジストリ、設定ローダー、CLI ランナー、アトミック書き込み、ジョブキュー、シークレットスキャナー、worktree マネージャー、タスクマニフェスト、CLI ワーカーマネージャー | | ||
| | `@agestra/core` | `AIProvider` インターフェース、能力/難易度メタデータ付き provider descriptor、設定ローダー、CLI ランナー、アトミック書き込み、ジョブキュー、シークレットスキャナー、worktree マネージャー、タスクマニフェスト、CLI ワーカーマネージャー | | ||
| | `@agestra/provider-claude` | Anthropic Claude CLI アダプター | | ||
| | `@agestra/provider-ollama` | モデル検出付き Ollama HTTP アダプター | | ||
@@ -209,3 +200,3 @@ | `@agestra/provider-gemini` | Google Gemini CLI アダプター | | ||
| | `@agestra/workspace` | レビュー、分析メモ、統合レポート向けのワークスペース文書マネージャー | | ||
| | `@agestra/mcp-server` | MCP プロトコル層、44 ツール、環境依存のツールフィルタリング、ディスパッチ | | ||
| | `@agestra/mcp-server` | MCP プロトコル層、45 ツール、環境依存のツールフィルタリング、ディスパッチ | | ||
@@ -230,7 +221,7 @@ ### 設計原則 | ||
| - **リーダーホストのみ** — 現在のホストの `agestra-implementer` がスコープ付きのコード変更を行います。QA は明示的な host-only 指定がない限り、設定済みプロバイダーに応じて QA Brigade を使えます。 | ||
| - **提案型 AI 分散** — リーダーが作業表を提案して承認を得た後、Codex/Gemini CLI ワーカーが分離 worktree で明確な実装作業を担当し、Ollama は単純・反復作業の草案やパッチ候補を出します。リーダーが状態、使用量、diff を監督して統合します。 | ||
| - **提案型 AI 分散** — リーダーが作業表を提案して承認を得た後、フロンティアモデルとローカルモデルを含む検出済みモデルの能力に応じて作業を分配します。Codex/Gemini CLI ワーカーは適切な自律コード編集を担当し、ローカル/ツールモデルは `executionPolicy` に応じて読み取り専用または読み書き AgentLoop ツールを受け取れます。リーダーが状態、使用量、diff を監督して統合します。 | ||
| --- | ||
| ## ツール (44) | ||
| ## ツール (45) | ||
@@ -241,7 +232,7 @@ ### AI チャット (3) | ||
| |--------|------| | ||
| | `ai_chat` | 特定のプロバイダーと対話（品質ベースのルーティングには `"auto"` を使用）。必要に応じて `save_as_document` で応答を文書保存可能 | | ||
| | `ai_chat` | 特定のプロバイダーと対話（観測値がある場合の trace 補助ルーティングには `"auto"` を使用）。必要に応じて `save_as_document` で応答を文書保存可能 | | ||
| | `ai_analyze_files` | ディスク上のファイルを読み込み、質問と一緒にプロバイダーへ送信 | | ||
| | `ai_compare` | 同じプロンプトを複数プロバイダーに送り、応答を比較 | | ||
| ### エージェントオーケストレーション (14) | ||
| ### エージェントオーケストレーション (15) | ||
@@ -251,3 +242,3 @@ | ツール | 説明 | | ||
| | `agent_debate_start` | 複数プロバイダーによるディベートを開始（非ブロッキング、品質ループ + バリデーターは任意） | | ||
| | `agent_debate_status` | ディベートの状態とトランスクリプトを確認 | | ||
| | `agent_debate_status` | レガシーディベートまたは構造化セッションの進捗、phase、参加者 activity、文書パスを確認 | | ||
| | `agent_debate_create` | ターン制ディベートセッションを作成（debate ID を返す） | | ||
@@ -260,2 +251,3 @@ | `agent_debate_turn` | 1 プロバイダー分のターンを実行。`provider: "claude"` で Claude の独立参加も可能 | | ||
| | `agent_debate_reject` | 構造化ディベートセッションを却下し、却下版の統合文書を書き出します。必要に応じて issue 文書も作成 | | ||
| | `agent_debate_submit_turn` | 構造化ディベートの status が `phase: awaiting-host-turn` を報告したとき、ネイティブホスト専門エージェントの turn を送信します。保留中の全 turn が届くとワークフローは自動再開します | | ||
| | `agent_debate_review` | 文書を複数プロバイダーへ送り、独立したレビューを依頼 | | ||
@@ -280,3 +272,3 @@ | `agent_cross_validate` | 出力をクロスバリデーション（agent-tier validators のみ） | | ||
| |--------|------| | ||
| | `environment_check` | CLI ツール、ティア分類付き Ollama モデル、tmux、git worktree 対応、利用可能モードを検出 | | ||
| | `environment_check` | CLI ツール、ローカルモデル tier、tmux、git worktree 対応、利用可能モードを検出 | | ||
@@ -342,3 +334,3 @@ ### ワークスペース (7) | ||
| | `trace_query` | trace レコードを条件付きで検索（プロバイダー、タスク、期間） | | ||
| | `trace_summary` | プロバイダー別の品質統計、性能指標、難易度資格を取得 | | ||
| | `trace_summary` | プロバイダー別の任意の過去品質観測値と性能指標を取得 | | ||
| | `trace_visualize` | 追跡した操作フローの Mermaid 図を生成 | | ||
@@ -352,3 +344,3 @@ | ||
| `/agestra setup` が生成します。単一のプラグイン範囲の場所に保存されます（解決順: `AGESTRA_CONFIG_PATH` 環境変数 → `$CLAUDE_PLUGIN_ROOT/providers.config.json` → `~/.agestra/providers.config.json`）。リポジトリには置かない方針で、gitignore 済みです。 | ||
| `/agestra setup` が生成します。デフォルトの保存先はホスト共有の `~/.agestra/providers.config.json` です。解決順は `AGESTRA_CONFIG_PATH` 環境変数 → 既存の `~/.agestra/providers.config.json` → 既存のレガシー `$CLAUDE_PLUGIN_ROOT/providers.config.json` → 新規書き込み用の `~/.agestra/providers.config.json` です。プロジェクトリポジトリに置くものではなく、gitignore 済みです。 | ||
@@ -362,3 +354,3 @@ | 項目 | 説明 | | ||
| | `providers[].enabled` | 起動時に登録するか — `false` は明示的オプトアウト | | ||
| | `providers[].executionPolicy` | `read-only` または `workspace-write` | | ||
| | `providers[].executionPolicy` | `read-only`, `workspace-write`, `full-auto`; Ollama はこの値に基づいて読み取り専用または読み書き AgentLoop ツールを受け取ります | | ||
| | `providers[].config` | タイプ別設定（host、timeout など） | | ||
@@ -454,2 +446,3 @@ | ||
| │ ├── core/ # AIProvider、レジストリ、セキュリティ、ワーカー | ||
| │ ├── provider-claude/ # Anthropic Claude CLI アダプター | ||
| │ ├── provider-ollama/ # Ollama HTTP アダプター | ||
@@ -460,3 +453,3 @@ │ ├── provider-gemini/ # Gemini CLI アダプター | ||
| │ ├── workspace/ # ワークスペース文書マネージャー | ||
| │ └── mcp-server/ # MCP サーバー、44 ツール、環境依存フィルタリング、ディスパッチ | ||
| │ └── mcp-server/ # MCP サーバー、45 ツール、環境依存フィルタリング、ディスパッチ | ||
| ├── package.json # ワークスペースルート | ||
@@ -463,0 +456,0 @@ └── turbo.json # Turborepo パイプライン |
+20
-16
@@ -6,7 +6,7 @@ # Agestra | ||
| **Agent + Orchestra** — Claude Code, Codex CLI, Gemini CLI에서 공통으로 쓰는 멀티 호스트 오케스트레이션 툴킷. | ||
| **Agent + Orchestra** — Claude Code, Codex CLI, Gemini CLI, 로컬 모델을 함께 조율하는 멀티 호스트 MCP 오케스트레이션 툴킷. | ||
| [English](README.md) | [한국어](README.ko.md) | [日本語](README.ja.md) | [中文](README.zh.md) | ||
| Agestra는 Claude 호스트, Ollama(로컬), Gemini CLI, Codex CLI를 플러그형 공급자로 연결합니다. 독립 취합, 합의 토론, 자율 CLI 워커, 병렬 작업 분배, 교차 검증, 품질 기반 공급자 라우팅을 44개 MCP 도구로 제공합니다. | ||
| Agestra는 Claude 호스트/CLI, Ollama(로컬), Gemini CLI, Codex CLI를 플러그형 공급자로 연결합니다. 독립 취합, 합의 토론, 자율 CLI 워커, 병렬 작업 분배, 교차 검증, 선택적 trace 근거를 참고하는 능력 기반 공급자 라우팅을 45개 MCP 도구로 제공합니다. | ||
@@ -50,2 +50,3 @@ ## 빠른 시작 | ||
| |--------|------|------| | ||
| | [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) | `npm install -g @anthropic-ai/claude-code` | 클라우드 | | ||
| | [Ollama](https://ollama.com/) | `curl -fsSL https://ollama.com/install.sh \| sh` | 로컬 LLM | | ||
@@ -90,3 +91,3 @@ | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `npm install -g @google/gemini-cli` | 클라우드 | | ||
| ImplRoute -->|명확한 병렬 구현| CliWorkers[Codex / Gemini CLI 작업자<br/>격리 worktree에서 구현] | ||
| ImplRoute -->|쉽고 반복적인 보조 작업| Ollama[Ollama 등 로컬 AI<br/>초안 / 패치 후보 / 반복 제안] | ||
| ImplRoute -->|능력에 맞는 범위 작업| Ollama[로컬/도구 모델<br/>정책 허용 시 읽기 / 쓰기] | ||
| ImplRoute -->|위험하거나 핵심 변경| HostImpl[호스트 구현 에이전트<br/>가까운 감독 아래 수정] | ||
@@ -144,5 +145,5 @@ CliWorkers --> ReviewDiff[리더가 상태 / 사용량 / diff 검토] | ||
| | `/agestra design [주제]` | 구현 전 아키텍처 및 설계 트레이드오프 탐색 | | ||
| | `/agestra implement [작업]` | Claude only 또는 Multi-AI 모드로 실제 구현 진행 | | ||
| | `/agestra implement [작업]` | 리더 호스트 단독 또는 Multi-AI 분산 모드로 실제 구현 진행 | | ||
| 외부 공급자가 있으면 review, QA, security, design, idea 워크플로우는 team-lead를 통해 멀티 AI 교차 검증으로 라우팅됩니다. 공급자가 없으면 현재 호스트의 로컬 specialist agent가 자동으로 처리합니다. | ||
| 외부 공급자가 있으면 review, QA, security, design, idea 워크플로우는 team-lead를 통해 멀티 AI 교차 검증으로 라우팅됩니다. QA의 경우 team-lead가 기본적으로 설정된 공급자 집합에서 QA Brigade를 구성하고 moderator engine의 기존 `ITEM-*` / JSON stance ledger로 넘깁니다. 호스트 QA는 실행 가능한 근거를 수집하고, 공급자들은 서로 다른 검증 관점을 맡으며, 후보 finding은 포함 전에 반박 검토를 거치고, 종합 문서는 합의와 이견을 함께 보존합니다. E2E/browser/runtime 실행은 계속 호스트가 소유하고 외부 공급자는 그 근거를 검토합니다. 공급자가 없으면 현재 호스트의 로컬 specialist agent가 자동으로 처리합니다. 구현 요청은 먼저 작업을 분류하고 AI 작업 분배 제안 여부를 물을 수 있습니다. | ||
@@ -153,3 +154,3 @@ ## 에이전트 | ||
| |----------|------|------| | ||
| | `agestra-team-lead` | Sonnet | 풀 오케스트레이터 — 환경 체크, 품질 기반 공급자 라우팅, 작업 모드 선택, CLI 워커 감독, QA 루프 | | ||
| | `agestra-team-lead` | Sonnet | 풀 오케스트레이터 — 환경 체크, 능력 기반 공급자 라우팅, 작업 모드 선택, CLI 워커 감독, QA 루프 | | ||
| | `agestra-implementer` | Sonnet | 제한된 구현 실행자 — 코드 수정, 테스트 갱신, 로컬 검증 | | ||
@@ -190,3 +191,4 @@ | `agestra-e2e-writer` | Sonnet | 지속 E2E 테스트 작성자 — 승인된 브라우저 플로우 테스트만 작성 | | ||
| |--------|------| | ||
| | `@agestra/core` | `AIProvider` 인터페이스, 난이도 기반 라우팅 레지스트리, 설정 로더, CLI 러너, 원자적 쓰기, 작업 큐, 시크릿 스캐너, 워크트리 관리자, 태스크 매니페스트, CLI 워커 관리자 | | ||
| | `@agestra/core` | `AIProvider` 인터페이스, 능력/난이도 메타데이터가 포함된 공급자 descriptor, 설정 로더, CLI 러너, 원자적 쓰기, 작업 큐, 시크릿 스캐너, 워크트리 관리자, 태스크 매니페스트, CLI 워커 관리자 | | ||
| | `@agestra/provider-claude` | Anthropic Claude CLI 어댑터 | | ||
| | `@agestra/provider-ollama` | Ollama HTTP 어댑터 (모델 자동 감지) | | ||
@@ -197,3 +199,3 @@ | `@agestra/provider-gemini` | Google Gemini CLI 어댑터 | | ||
| | `@agestra/workspace` | 리뷰, 분석 메모, 통합 보고서를 위한 워크스페이스 문서 관리자 | | ||
| | `@agestra/mcp-server` | MCP 프로토콜 레이어, 44개 도구, 환경별 도구 필터링, 디스패치 | | ||
| | `@agestra/mcp-server` | MCP 프로토콜 레이어, 45개 도구, 환경별 도구 필터링, 디스패치 | | ||
@@ -218,7 +220,7 @@ ### 설계 원칙 | ||
| - **리더-호스트 전용** — 현재 호스트의 `agestra-implementer`가 제한된 코드 변경을 수행합니다. QA는 요청이 없으면 설정된 프로바이더 기준으로 QA Brigade를 사용할 수 있습니다. | ||
| - **제안된 AI 분산** — 리더가 작업표를 제안하고 승인받은 뒤, Codex/Gemini CLI 워커가 격리된 git worktree에서 명확한 구현 작업을 맡고 Ollama는 단순·반복 작업의 초안/패치 후보를 냅니다. 리더가 상태, 사용량, diff를 감독하고 병합합니다. | ||
| - **제안된 AI 분산** — 리더가 작업표를 제안하고 승인받은 뒤, 감지된 모델(프론티어와 로컬 모델 포함)의 능력에 따라 업무를 분배합니다. Codex/Gemini CLI 워커는 적합한 자율 코드 수정 작업을 맡고, 로컬/도구 모델은 `executionPolicy`에 따라 읽기 전용 또는 읽기/쓰기 AgentLoop 도구를 받을 수 있습니다. 리더가 상태, 사용량, diff를 감독하고 병합합니다. | ||
| --- | ||
| ## 도구 (44개) | ||
| ## 도구 (45개) | ||
@@ -229,7 +231,7 @@ ### AI 채팅 (3개) | ||
| |------|------| | ||
| | `ai_chat` | 특정 공급자와 채팅 (품질 기반 자동 라우팅: `"auto"`); 필요하면 `save_as_document`로 응답을 문서로 저장 | | ||
| | `ai_chat` | 특정 공급자와 채팅 (`"auto"`는 관측 기록이 있을 때 trace 보조 라우팅 사용); 필요하면 `save_as_document`로 응답을 문서로 저장 | | ||
| | `ai_analyze_files` | 파일을 디스크에서 읽어 공급자에게 질문과 함께 전송 | | ||
| | `ai_compare` | 같은 프롬프트를 여러 공급자에 보내 응답 비교 | | ||
| ### 에이전트 오케스트레이션 (14개) | ||
| ### 에이전트 오케스트레이션 (15개) | ||
@@ -247,2 +249,3 @@ | 도구 | 설명 | | ||
| | `agent_debate_reject` | 구조화 토론 세션을 거절하고 거절 종합 문서를 작성하며, 필요하면 별도 issue 문서도 작성 | | ||
| | `agent_debate_submit_turn` | 구조화 토론 상태가 `phase: awaiting-host-turn`을 보고할 때 네이티브 호스트 전문 에이전트 턴을 제출; 모든 대기 턴이 도착하면 워크플로우가 자동 재개됨 | | ||
| | `agent_debate_review` | 문서를 여러 공급자에게 독립적으로 리뷰 요청 | | ||
@@ -267,3 +270,3 @@ | `agent_cross_validate` | 출력 교차 검증 (에이전트 등급 검증자만 가능) | | ||
| |------|------| | ||
| | `environment_check` | CLI 도구, Ollama 모델 티어, tmux, git worktree 지원 여부, 사용 가능 모드 탐지 | | ||
| | `environment_check` | CLI 도구, 로컬 모델 티어, tmux, git worktree 지원 여부, 사용 가능 모드 탐지 | | ||
@@ -329,3 +332,3 @@ ### 워크스페이스 (7개) | ||
| | `trace_query` | 조건별 추적 레코드 조회 (공급자, 작업, 기간) | | ||
| | `trace_summary` | 공급자별 품질 통계, 성능 지표, 난이도 자격 확인 | | ||
| | `trace_summary` | 공급자별 선택적 과거 품질 관측값과 성능 지표 확인 | | ||
| | `trace_visualize` | 추적된 작업 흐름의 Mermaid 다이어그램 생성 | | ||
@@ -348,3 +351,3 @@ | ||
| | `providers[].enabled` | 시작 시 등록 여부 — `false`면 강제 제외 | | ||
| | `providers[].executionPolicy` | `read-only` 또는 `workspace-write` | | ||
| | `providers[].executionPolicy` | `read-only`, `workspace-write`, `full-auto`; Ollama는 이 값에 따라 읽기 전용 또는 읽기/쓰기 AgentLoop 도구를 받음 | | ||
| | `providers[].config` | 타입별 설정 (host, timeout 등) | | ||
@@ -440,2 +443,3 @@ | ||
| │ ├── core/ # AIProvider 인터페이스, 레지스트리, 보안, 워커 | ||
| │ ├── provider-claude/ # Anthropic Claude CLI 어댑터 | ||
| │ ├── provider-ollama/ # Ollama HTTP 어댑터 | ||
@@ -446,3 +450,3 @@ │ ├── provider-gemini/ # Gemini CLI 어댑터 | ||
| │ ├── workspace/ # 워크스페이스 문서 관리자 | ||
| │ └── mcp-server/ # MCP 서버, 44개 도구, 환경별 필터링, 디스패치 | ||
| │ └── mcp-server/ # MCP 서버, 45개 도구, 환경별 필터링, 디스패치 | ||
| ├── package.json # 워크스페이스 루트 | ||
@@ -449,0 +453,0 @@ └── turbo.json # Turborepo 파이프라인 |
+18
-14
@@ -6,7 +6,7 @@ # Agestra | ||
| **Agent + Orchestra** — A multi-host orchestration toolkit for Claude Code, Codex CLI, and Gemini CLI. | ||
| **Agent + Orchestra** — Multi-host MCP orchestration for Claude Code, Codex CLI, Gemini CLI, and local models. | ||
| [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, and quality-based provider routing — all through 44 MCP tools. | ||
| Agestra connects the Claude host/CLI, 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 capability-based provider routing with optional trace evidence — all through 45 MCP tools. | ||
@@ -50,2 +50,3 @@ ## Quick Start | ||
| |----------|---------|------| | ||
| | [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 | | ||
@@ -90,3 +91,3 @@ | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `npm install -g @google/gemini-cli` | Cloud | | ||
| ImplRoute -->|Clear parallel implementation| CliWorkers[Codex / Gemini CLI workers<br/>isolated worktrees] | ||
| ImplRoute -->|Simple or repetitive support| Ollama[Ollama or local AI<br/>drafts / patch candidates / repeated suggestions] | ||
| ImplRoute -->|Capability-matched scoped work| Ollama[Local/tool models<br/>read / write if policy allows] | ||
| ImplRoute -->|Risky or core change| HostImpl[Host implementer<br/>close leader supervision] | ||
@@ -152,3 +153,3 @@ CliWorkers --> ReviewDiff[Leader monitors status / quota / diff] | ||
| |-------|-------|------| | ||
| | `agestra-team-lead` | Sonnet | Full orchestrator — environment check, quality-based provider routing, work mode selection, CLI worker supervision, QA loop | | ||
| | `agestra-team-lead` | Sonnet | Full orchestrator — environment check, capability-based provider routing, work mode selection, CLI worker supervision, QA loop | | ||
| | `agestra-implementer` | Sonnet | Scoped implementation executor — code edits, test updates, local verification | | ||
@@ -189,3 +190,4 @@ | `agestra-e2e-writer` | Sonnet | Persistent E2E test writer — creates approved browser-flow tests without changing product behavior | | ||
| |---------|-------------| | ||
| | `@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/core` | `AIProvider` interface, provider descriptors with capability/difficulty metadata, config loader, CLI runner, atomic writes, job queue, secret scanner, worktree manager, task manifest, CLI worker manager | | ||
| | `@agestra/provider-claude` | Anthropic Claude CLI adapter | | ||
| | `@agestra/provider-ollama` | Ollama HTTP adapter with model detection | | ||
@@ -196,3 +198,3 @@ | `@agestra/provider-gemini` | Google Gemini CLI adapter | | ||
| | `@agestra/workspace` | Workspace document manager for reviews, analysis notes, and aggregated reports | | ||
| | `@agestra/mcp-server` | MCP protocol layer, 44 tools, environment-aware tool filtering, dispatch | | ||
| | `@agestra/mcp-server` | MCP protocol layer, 45 tools, environment-aware tool filtering, dispatch | | ||
@@ -217,7 +219,7 @@ ### Design Principles | ||
| - **Leader-host only** — `agestra-implementer` applies scoped code changes; the team lead still routes QA through the QA Brigade by default, with host-only review/QA available on request. | ||
| - **Suggested AI distribution** — the team lead proposes a routing table, asks for approval, then dispatches Codex/Gemini CLI workers for suitable code edits and Ollama for simple/repetitive proposal work. | ||
| - **Suggested AI distribution** — the team lead proposes a routing table, asks for approval, then distributes work according to the capabilities of detected models, including frontier and local models. Codex/Gemini CLI workers handle suitable autonomous code edits, and local/tool models may receive read-only or read/write AgentLoop tools according to their `executionPolicy`. | ||
| --- | ||
| ## Tools (44) | ||
| ## Tools (45) | ||
@@ -228,7 +230,7 @@ ### AI Chat (3) | ||
| |------|-------------| | ||
| | `ai_chat` | Chat with a specific provider (use `"auto"` for quality-based routing); optionally persist replies with `save_as_document` | | ||
| | `ai_chat` | Chat with a specific provider (use `"auto"` for trace-assisted routing when observations exist); 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 (14) | ||
| ### Agent Orchestration (15) | ||
@@ -246,2 +248,3 @@ | Tool | Description | | ||
| | `agent_debate_reject` | Reject a structured-debate session; writes a rejected synthesis document and optionally an issue document | | ||
| | `agent_debate_submit_turn` | Submit a native host-specialist turn when structured debate status reports `phase: awaiting-host-turn`; the workflow resumes after all pending host turns arrive | | ||
| | `agent_debate_review` | Send a document to multiple providers for independent review | | ||
@@ -266,3 +269,3 @@ | `agent_cross_validate` | Cross-validate outputs (agent-tier validators only) | | ||
| |------|-------------| | ||
| | `environment_check` | Detect CLI tools, Ollama models with tiers, tmux, git worktree support, available modes | | ||
| | `environment_check` | Detect CLI tools, local model tiers, tmux, git worktree support, available modes | | ||
@@ -328,3 +331,3 @@ ### Workspace (7) | ||
| | `trace_query` | Query trace records with filtering (provider, task, time range) | | ||
| | `trace_summary` | Get quality stats, performance metrics, and difficulty qualification per provider | | ||
| | `trace_summary` | Get optional prior quality observations and performance metrics per provider | | ||
| | `trace_visualize` | Generate a Mermaid diagram of a traced operation's flow | | ||
@@ -347,3 +350,3 @@ | ||
| | `providers[].enabled` | Whether to register this provider at startup — hard opt-out when `false` | | ||
| | `providers[].executionPolicy` | `read-only` or `workspace-write` | | ||
| | `providers[].executionPolicy` | `read-only`, `workspace-write`, or `full-auto`; Ollama uses this to choose read-only vs read/write AgentLoop tools | | ||
| | `providers[].config` | Type-specific settings (host, timeout, etc.) | | ||
@@ -439,2 +442,3 @@ | ||
| │ ├── core/ # AIProvider interface, registry, security, workers | ||
| │ ├── provider-claude/ # Anthropic Claude CLI adapter | ||
| │ ├── provider-ollama/ # Ollama HTTP adapter | ||
@@ -445,3 +449,3 @@ │ ├── provider-gemini/ # Gemini CLI adapter | ||
| │ ├── workspace/ # Workspace document manager | ||
| │ └── mcp-server/ # MCP server, 44 tools, environment-aware filtering, dispatch | ||
| │ └── mcp-server/ # MCP server, 45 tools, environment-aware filtering, dispatch | ||
| ├── package.json # Workspace root | ||
@@ -448,0 +452,0 @@ └── turbo.json # Turborepo pipeline |
+51
-58
@@ -6,53 +6,31 @@ # Agestra | ||
| **Agent + Orchestra** — 一个可在 Claude Code、Codex CLI 与 Gemini CLI 中共用的多宿主编排工具包。 | ||
| **Agent + Orchestra** — 面向 Claude Code、Codex CLI、Gemini CLI 和本地模型的多宿主 MCP 编排工具包。 | ||
| [English](README.md) | [한국어](README.ko.md) | [日本語](README.ja.md) | [中文](README.zh.md) | ||
| Agestra 将 Ollama（本地）、Gemini CLI 和 Codex CLI 作为可插拔提供方接入 Claude Code，通过 44 个 MCP 工具提供多 AI 编排、独立汇总、共识辩论、自主 CLI Worker、并行任务分发、交叉验证和基于质量的提供方路由。 | ||
| Agestra 将 Claude host/CLI、Ollama（本地）、Gemini CLI 和 Codex CLI 作为可插拔提供方接入，通过 45 个 MCP 工具提供多 AI 编排、独立汇总、共识辩论、自主 CLI Worker、并行任务分发、交叉验证，以及可选参考 trace 证据的能力型提供方路由。 | ||
| ## 快速开始 | ||
| ### Claude Code | ||
| 先选择你要使用的宿主。需要安装宿主原生命令/代理时使用 `--assets` 路径；只需要服务器连接时使用 MCP-only 注册。 | ||
| ``` | ||
| /plugin marketplace add mua-vtuber/Agestra | ||
| /plugin install agestra@agestra | ||
| ``` | ||
| | 宿主 | 从本仓库安装 | 从全局 npm 安装 | `--assets` 会添加 | | ||
| |------|--------------|----------------|-------------------| | ||
| | Claude Code | `/plugin marketplace add mua-vtuber/Agestra` 后执行 `/plugin install agestra@agestra` | 同样的插件流程 | 插件包、命令、代理、hooks 和 MCP server | | ||
| | 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 保持现有插件安装体验不变。Agestra 会在首次使用时通过 `environment_check` 自动检测可用的提供方（Claude host、Ollama、Gemini CLI、Codex CLI）。 | ||
| 也可以只注册 MCP: | ||
| ### Codex CLI | ||
| | 宿主 | 仓库包 | 从 checkout 注册全局包 | | ||
| |------|--------|------------------------| | ||
| | Codex CLI | `npm run install:codex` | `npm run install:codex:global` | | ||
| | Gemini CLI | `npm run install:gemini` | `npm run install:gemini:global` | | ||
| ``` | ||
| npm run bundle | ||
| npm run install:codex:assets | ||
| ``` | ||
| Claude 保持原生插件 UX。Codex 会结合 [AGENTS.md](AGENTS.md)、生成的 custom agents 和已注册的 `agestra` MCP server。Gemini 会结合 [GEMINI.md](GEMINI.md)、`.gemini/commands/agestra/`、生成的 skills，以及 project-scope 受管文件或 user-scope native extension。 | ||
| 使用全局 npm 包时： | ||
| 注意：`npm run install:gemini:assets` 默认使用 user scope。如果要从 checkout 安装 project-scope Gemini 受管文件，请运行 `node scripts/install-host-mcp.mjs gemini --assets --scope project`。 | ||
| ``` | ||
| npm install -g agestra | ||
| agestra-install codex --assets | ||
| ``` | ||
| Assets 安装后可用的 Gemini 命令： | ||
| Codex 会结合仓库根目录下的 [AGENTS.md](AGENTS.md) 与已注册的 `agestra` MCP 服务一起工作。生成 Codex custom agent 需要使用 `--assets` 路径，它会在 `.codex/agents/` 下安装 agent，并写入 Agestra host-asset manifest。不安装 custom agent、只注册 MCP 时，请使用 `npm run install:codex` 或 `agestra-install codex`。 | ||
| ### Gemini CLI | ||
| ``` | ||
| npm run bundle | ||
| npm run install:gemini:assets | ||
| ``` | ||
| 使用全局 npm 包时： | ||
| ``` | ||
| npm install -g agestra | ||
| agestra-install gemini --assets --scope user | ||
| ``` | ||
| Gemini 会结合仓库根目录下的 [GEMINI.md](GEMINI.md)、[`.gemini/commands/agestra/`](.gemini/commands/agestra) 和生成的 skills 一起工作。project scope 的 `--assets` 会写入受管文件，user scope 的 `--assets` 会安装 Agestra Gemini native extension。只注册 MCP 时，请使用 `npm run install:gemini` 或 `agestra-install gemini`。`npm run install:gemini:assets` 默认使用 user scope；如果要从 checkout 安装 project-scope 受管文件，请运行 `node scripts/install-host-mcp.mjs gemini --assets --scope project`。 | ||
| 安装后可用的 Gemini 命令： | ||
| - `/agestra:setup` | ||
@@ -72,2 +50,3 @@ - `/agestra:review` | ||
| |--------|------|------| | ||
| | [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 | | ||
@@ -81,3 +60,14 @@ | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `npm install -g @google/gemini-cli` | Cloud | | ||
| - **tmux** — 让你在自主执行期间可视化查看 CLI Worker 面板 | ||
| - **Windows 上的 ripgrep (`rg`)** — 如果 Codex 解析到 Store app bundled path 的 `rg` 并出现 "Access is denied"，请单独安装 ripgrep，让正常的 `rg.exe` 在 `PATH` 中优先被找到： | ||
| ``` | ||
| cargo install ripgrep | ||
| ``` | ||
| 替代方式： | ||
| ``` | ||
| winget install BurntSushi.ripgrep.MSVC | ||
| ``` | ||
| --- | ||
@@ -102,3 +92,3 @@ | ||
| ImplRoute -->|清晰可并行的实现| CliWorkers[Codex / Gemini CLI Worker<br/>隔离 worktree 中实现] | ||
| ImplRoute -->|简单或重复的辅助任务| Ollama[Ollama 等本地 AI<br/>草稿 / 补丁候选 / 重复建议] | ||
| ImplRoute -->|能力匹配的有范围任务| Ollama[本地 / 工具模型<br/>策略允许时可读 / 写] | ||
| ImplRoute -->|高风险或核心改动| HostImpl[宿主实现代理<br/>负责人近距离监督] | ||
@@ -156,5 +146,5 @@ CliWorkers --> ReviewDiff[负责人监控状态 / 用量 / diff] | ||
| | `/agestra design [subject]` | 在实现前探索架构与设计取舍 | | ||
| | `/agestra implement [task]` | 以 Claude only 或 Multi-AI 模式执行实现 | | ||
| | `/agestra implement [task]` | 以领导者宿主单独模式或 Multi-AI 分发模式执行实现 | | ||
| 当外部提供方可用时，review、QA、security、design、idea 工作流会经由 team-lead 进入多 AI 交叉验证。当未检测到提供方时，当前宿主的本地 specialist agent 会自动处理。 | ||
| 当外部提供方可用时，review、QA、security、design、idea 工作流会经由 team-lead 进入多 AI 交叉验证。对于 QA，team-lead 默认会从已配置的提供方集合中组建 QA Brigade，然后交给 moderator engine 现有的 `ITEM-*` / JSON stance ledger：宿主 QA 收集可执行证据，提供方承担不同验证视角，候选 finding 在纳入前会被挑战，综合文档会保留共识与异议。E2E/browser/runtime 执行仍归宿主所有，外部提供方会审查这些证据。当未检测到提供方时，当前宿主的本地 specialist agent 会自动处理。实现请求会先分类任务，并可询问是否提出 AI 任务分配方案。 | ||
@@ -165,3 +155,3 @@ ## 代理 | ||
| |------|------|------| | ||
| | `agestra-team-lead` | Sonnet | 全局编排者：环境检查、按质量路由提供方、选择工作模式、监督 CLI Worker、驱动 QA 循环 | | ||
| | `agestra-team-lead` | Sonnet | 全局编排者：环境检查、能力型提供方路由、选择工作模式、监督 CLI Worker、驱动 QA 循环 | | ||
| | `agestra-implementer` | Sonnet | 有范围的实现执行者：代码修改、测试更新、本地验证 | | ||
@@ -202,3 +192,4 @@ | `agestra-e2e-writer` | Sonnet | 持久 E2E 测试作者：只编写已批准的浏览器流程测试 | | ||
| |----|------| | ||
| | `@agestra/core` | `AIProvider` 接口、基于难度的路由注册表、配置加载、CLI runner、原子写入、任务队列、密钥扫描、worktree 管理、任务清单、CLI Worker 管理器 | | ||
| | `@agestra/core` | `AIProvider` 接口、带能力/难度元数据的 provider descriptor、配置加载、CLI runner、原子写入、任务队列、密钥扫描、worktree 管理、任务清单、CLI Worker 管理器 | | ||
| | `@agestra/provider-claude` | Anthropic Claude CLI 适配器 | | ||
| | `@agestra/provider-ollama` | 带模型检测的 Ollama HTTP 适配器 | | ||
@@ -209,3 +200,3 @@ | `@agestra/provider-gemini` | Google Gemini CLI 适配器 | | ||
| | `@agestra/workspace` | 用于评审、分析笔记和汇总报告的工作区文档管理器 | | ||
| | `@agestra/mcp-server` | MCP 协议层，44 个工具，按环境过滤工具并动态分发 | | ||
| | `@agestra/mcp-server` | MCP 协议层，45 个工具，按环境过滤工具并动态分发 | | ||
@@ -230,7 +221,7 @@ ### 设计原则 | ||
| - **仅负责人宿主** — 当前宿主的 `agestra-implementer` 执行有范围的代码修改。除非明确要求 host-only，QA 仍可根据已配置提供方使用 QA Brigade。 | ||
| - **建议式 AI 分工** — 负责人先提出任务分配表并取得批准，然后让 Codex/Gemini CLI Worker 在隔离 worktree 中处理清晰的实现任务；Ollama 用于简单、重复任务的草稿或补丁候选。负责人持续监督状态、用量和 diff，并负责合并。 | ||
| - **建议式 AI 分工** — 负责人先提出任务分配表并取得批准，然后根据检测到的模型能力分配工作，包括 frontier 模型和本地模型。Codex/Gemini CLI Worker 处理适合的自主代码修改，本地/工具模型可根据 `executionPolicy` 获得只读或读写 AgentLoop 工具。负责人持续监督状态、用量和 diff，并负责合并。 | ||
| --- | ||
| ## 工具（44） | ||
| ## 工具（45） | ||
@@ -241,7 +232,7 @@ ### AI Chat（3） | ||
| |------|------| | ||
| | `ai_chat` | 与指定提供方对话（使用 `"auto"` 可启用基于质量的路由）；如有需要，可通过 `save_as_document` 将回复保存为文档 | | ||
| | `ai_chat` | 与指定提供方对话（有观测记录时可用 `"auto"` 启用 trace 辅助路由）；如有需要，可通过 `save_as_document` 将回复保存为文档 | | ||
| | `ai_analyze_files` | 从磁盘读取文件并连同问题一起发送给提供方 | | ||
| | `ai_compare` | 将同一提示发送给多个提供方并比较结果 | | ||
| ### Agent Orchestration（14） | ||
| ### Agent Orchestration（15） | ||
@@ -251,3 +242,3 @@ | 工具 | 说明 | | ||
| | `agent_debate_start` | 启动多提供方辩论（非阻塞，可选质量循环 + 验证者） | | ||
| | `agent_debate_status` | 查看辩论状态与转录 | | ||
| | `agent_debate_status` | 查看 legacy 辩论或结构化会话的进度、phase、参与者活动和文档路径 | | ||
| | `agent_debate_create` | 创建回合制辩论会话（返回 debate ID） | | ||
@@ -260,2 +251,3 @@ | `agent_debate_turn` | 执行某个提供方的一回合；支持 `provider: "claude"` 让 Claude 独立参与 | | ||
| | `agent_debate_reject` | 拒绝结构化辩论会话；写入拒绝版综合文档，并可按需写入 issue 文档 | | ||
| | `agent_debate_submit_turn` | 当结构化辩论状态报告 `phase: awaiting-host-turn` 时提交原生宿主专家 turn；所有待处理宿主 turn 到齐后工作流会自动继续 | | ||
| | `agent_debate_review` | 将文档发送给多个提供方进行独立审查 | | ||
@@ -280,3 +272,3 @@ | `agent_cross_validate` | 对输出进行交叉验证（仅限 agent-tier validators） | | ||
| |------|------| | ||
| | `environment_check` | 检测 CLI 工具、带分层信息的 Ollama 模型、tmux、git worktree 支持与可用模式 | | ||
| | `environment_check` | 检测 CLI 工具、本地模型分层、tmux、git worktree 支持与可用模式 | | ||
@@ -333,4 +325,4 @@ ### Workspace（7） | ||
| | Tool | Description | | ||
| |------|-------------| | ||
| | 工具 | 说明 | | ||
| |------|------| | ||
| | `qa_run` | 自动检测 build/test 命令并运行 QA，输出 PASS/FAIL 摘要 | | ||
@@ -340,6 +332,6 @@ | ||
| | Tool | Description | | ||
| |------|-------------| | ||
| | 工具 | 说明 | | ||
| |------|------| | ||
| | `trace_query` | 按条件查询 trace 记录（提供方、任务、时间范围） | | ||
| | `trace_summary` | 获取各提供方的质量统计、性能指标和难度资格 | | ||
| | `trace_summary` | 获取各提供方可选的历史质量观测值和性能指标 | | ||
| | `trace_visualize` | 生成某次追踪操作流程的 Mermaid 图 | | ||
@@ -353,3 +345,3 @@ | ||
| 由 `/agestra setup` 生成。文件存放于单一的插件范围位置（解析顺序：`AGESTRA_CONFIG_PATH` 环境变量 → `$CLAUDE_PLUGIN_ROOT/providers.config.json` → `~/.agestra/providers.config.json`）。不随仓库一起提交，已加入 gitignore。 | ||
| 由 `/agestra setup` 生成。默认保存位置是宿主共享的 `~/.agestra/providers.config.json`。解析顺序为 `AGESTRA_CONFIG_PATH` 环境变量 → 已存在的 `~/.agestra/providers.config.json` → 已存在的 legacy `$CLAUDE_PLUGIN_ROOT/providers.config.json` → 用于新写入的 `~/.agestra/providers.config.json`。它不应放在项目仓库中，并已加入 gitignore。 | ||
@@ -363,3 +355,3 @@ | 字段 | 说明 | | ||
| | `providers[].enabled` | 启动时是否注册 — `false` 为强制跳过 | | ||
| | `providers[].executionPolicy` | `read-only` 或 `workspace-write` | | ||
| | `providers[].executionPolicy` | `read-only`、`workspace-write` 或 `full-auto`；Ollama 根据该值选择只读或读写 AgentLoop 工具 | | ||
| | `providers[].config` | 类型相关配置（host、timeout 等） | | ||
@@ -455,2 +447,3 @@ | ||
| │ ├── core/ # AIProvider 接口、注册表、安全、worker | ||
| │ ├── provider-claude/ # Anthropic Claude CLI 适配器 | ||
| │ ├── provider-ollama/ # Ollama HTTP 适配器 | ||
@@ -461,3 +454,3 @@ │ ├── provider-gemini/ # Gemini CLI 适配器 | ||
| │ ├── workspace/ # 工作区文档管理器 | ||
| │ └── mcp-server/ # MCP Server，44 个工具，按环境过滤并分发 | ||
| │ └── mcp-server/ # MCP Server，45 个工具，按环境过滤并分发 | ||
| ├── package.json # 工作区根目录 | ||
@@ -464,0 +457,0 @@ └── turbo.json # Turborepo pipeline |
+1
-1
@@ -130,3 +130,3 @@ --- | ||
| Direct execution from this skill bypasses team-lead's quality-based routing (`trace_summary`), task design, and consistency enforcement. Always go through team-lead in Branch B. | ||
| Direct execution from this skill bypasses team-lead's capability-based routing and optional trace-assisted signals (`trace_summary`), task design, and consistency enforcement. Always go through team-lead in Branch B. | ||
@@ -133,0 +133,0 @@ When team-lead returns, present the synthesis to the user in the user's language. Preserve each provider's rationale on disputed positions. |
+1
-1
@@ -121,3 +121,3 @@ --- | ||
| Direct execution from this skill bypasses team-lead's quality-based routing (`trace_summary`), task design, and consistency enforcement. Always go through team-lead in Branch B. | ||
| Direct execution from this skill bypasses team-lead's capability-based routing and optional trace-assisted signals (`trace_summary`), task design, and consistency enforcement. Always go through team-lead in Branch B. | ||
@@ -124,0 +124,0 @@ When team-lead returns, present the synthesis to the user in the user's language. Preserve each provider's rationale on disputed positions. Treat `.agestra/workspace/` as the internal research/debate workspace; the user-facing decision record belongs under `docs/ideas/`. |
@@ -71,5 +71,5 @@ --- | ||
| Small is not the same as simple: | ||
| Small is not the same as simple. Distribute work according to detected model capability, including frontier and local models: | ||
| - **Small but hard/risky:** one-line auth, security, concurrency, data-loss, or release logic. Keep with `agestra-implementer` or a high-capability CLI worker plus QA. | ||
| - **Large but simple:** repeated safe pattern across many files. Prefer Ollama for a patch plan or candidate transform, then `agestra-implementer` applies it unless a safe edit-capable worker is available. | ||
| - **Large but simple:** repeated safe pattern across many files. Prefer a capability-matched local/tool model for a patch plan, candidate transform, or scoped edit when execution policy allows; otherwise have `agestra-implementer` apply it. | ||
@@ -95,6 +95,6 @@ ## CLI Workers | ||
| |---|---| | ||
| | Simple repetitive proposal work (formatting, pattern matching) | Ollama local model preferred for suggestions; implementer applies | | ||
| | Moderate (code review, summarization) | Ollama >= 3 GB or cloud | | ||
| | Complex implementation (multi-file, multi-step) | CLI worker (Codex/Gemini) | | ||
| | Complex analysis (architecture, refactoring) | Cloud providers (Gemini, Codex) via ai_chat | | ||
| | Simple repetitive proposal work (formatting, pattern matching) | Capability-matched local/tool model or host implementer | | ||
| | Moderate (code review, summarization) | Local model tier that qualifies, or a frontier provider | | ||
| | Complex implementation (multi-file, multi-step) | High-capability CLI worker (for example Codex/Gemini) or host implementer | | ||
| | Complex analysis (architecture, refactoring) | Highest-capability detected model, usually a frontier provider | | ||
| | No providers available | Handle directly — do not suggest agestra tools | | ||
@@ -181,3 +181,3 @@ | ||
| Phase 2: Task Design (team-lead — work mode selection, decompose, route by AI capability) | ||
| Phase 3: Parallel Execution (team-lead — implementer + CLI workers + Ollama proposal work, monitor loop) | ||
| Phase 3: Parallel Execution (team-lead — implementer + CLI workers + capability-matched local/tool model work, monitor loop) | ||
| Phase 4: Result Inspection (team-lead — review diffs, check consistency, merge) | ||
@@ -196,3 +196,3 @@ Phase 5: QA Cycle (qa — spec-to-code map, verify, classify failures → team-lead auto-fixes, max 5 cycles) [host-local mode] | ||
| - `Leader-host only`: `agestra-implementer` implements, no external workers | ||
| - `Multi-AI`: CLI workers + Ollama proposal work for parallelized execution; team lead supervises and merges | ||
| - `Multi-AI`: CLI workers + capability-matched local/tool model work for parallelized execution; team lead supervises and merges | ||
@@ -199,0 +199,0 @@ **QA domain:** |
+1
-1
@@ -108,3 +108,3 @@ --- | ||
| Direct execution from this skill bypasses team-lead's task design, quality-based routing (`trace_summary`), and consistency enforcement. Always go through team-lead in Branch B. | ||
| Direct execution from this skill bypasses team-lead's task design, capability-based routing with optional trace-assisted signals (`trace_summary`), and consistency enforcement. Always go through team-lead in Branch B. | ||
@@ -111,0 +111,0 @@ ### Phase 4: Review Verdict |
Sorry, the diff of this file is too big to display
New alerts
URL strings
Supply chain riskPackage contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.
Found 1 instance in 1 package
Fixed alerts
AI-detected potential code anomaly
Supply chain riskAI has identified unusual behaviors that may pose a security risk.
Found 1 instance in 1 package
URL strings
Supply chain riskPackage contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
1244060
2.69%- Lines of code
4795
1.2%- Number of lines in readme file
480
0.84%- Number of low supply chain risk alerts
14
-6.67%No dependency changes