agestra 4.13.2 → 4.13.4

package/agents/agestra-team-lead.md

@@ -130,19 +130,19 @@ Before executing, gather context:
 
 1. Call `environment_check` to get the full capability map:
    - Which CLI tools are installed (codex, gemini, tmux)
-   - Which Ollama models are available and their tier classifications
+   - 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/`.
 5. Store environment capabilities for later mode selection:
    - `can_autonomous_work`: CLI workers available?
    - `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.
 
 ### Phase 2: Task Design
@@ -156,7 +156,7 @@ Decompose the work into independent, assignable tasks:
    | Option | Description |
    |--------|-------------|
    | **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 |
 
    If no external providers available: skip selection, proceed with Leader-host only.
    In autonomous mode: auto-select based on task complexity:
@@ -195,14 +195,14 @@ Decompose the work into independent, assignable tasks:
 
    | Task Characteristics | Route To |
    |---------------------|----------|
-   | 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 |
    | Product/unit/integration test writing | `agestra-implementer` or a high-capability CLI worker |
    | Persistent E2E test writing | `agestra-e2e-writer` after user approval |
    | Review and QA | `agestra-reviewer` or `agestra-qa` |
 
-   **Quality-Based Provider Selection:**
+   **Capability-First Provider Selection:**
 
    Before assigning any task, determine its difficulty level:
    - **low**: Simple chat, basic formatting, straightforward review
@@ -210,11 +210,11 @@ Decompose the work into independent, assignable tasks:
    - **high**: Complex architecture, cross-validation, multi-component refactoring
 
    Then filter providers by qualification:
-   1. Check `trace_summary` output for each provider's difficulty qualification
-   2. Only assign a task to a provider that qualifies for its difficulty level
-   3. Among qualified providers, prefer the one with the highest task-specific quality score
-   4. If no provider qualifies, fall back to `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.
 
 4. Define dependency relationships between tasks.
 
@@ -247,9 +247,12 @@ Execute approved tasks across available execution paths:
    - Otherwise → re-route to a different provider or complete the task through `agestra-implementer`.
 5. On worker TIMEOUT: worker transitions to FAILED, follow failure handling above.
 
-**Ollama tasks (MCP):**
-- Call `ai_chat` with tier-matched model for simple tasks.
-- 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.
 
 **Result Integration:**
 - Leader-host implementation: changes are already applied on the main branch (no merge needed).
@@ -351,12 +354,59 @@ Build the QA Brigade handoff before starting the moderator debate:
 | `agestra-e2e-writer` | Not a brigade reviewer. Use only after an approved `E2E_TEST_WORK_REQUEST` for persistent E2E test work |
 
 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.
 - 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.
 - Each brigade member must issue an independent PASS / CONDITIONAL PASS / FAIL recommendation with evidence and confidence in its individual source material. Disagreement is useful; preserve minority reports in the final synthesis.
 
+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
 
 Do not invent a separate QA adjudication schema. Use the moderator's existing structured-debate contract.
@@ -379,7 +429,7 @@ Ledger interpretation:
 - The moderator handles duplicate/merge/superseded state in the ledger. Participants may point out duplication in comments or propose a `revise`, but they do not manually merge markdown.
 - The leader does not decide item inclusion by hand. The leader inspects the JSON ledger and chooses approve / continue / reject at the approval gate.
 
-Run the structured-debate MCP flow. This is a **background lifecycle**: `agent_debate_structured` creates a durable session record immediately and returns `status: running`; the leader polls `agent_debate_status` until the moderator parks the session in `ready-for-approval`, `escalated`, or `error`. The moderator does NOT write the synthesis file on its own — approval must be explicit.
+Run the structured-debate MCP flow. This is a **background lifecycle**: `agent_debate_structured` creates a durable session record immediately and returns `status: running`; the leader polls `agent_debate_status` until the moderator parks the session in `ready-for-approval`, `escalated`, or `error`. The moderator does NOT write the synthesis file on its own — leader finalization must be explicit.
 
 #### 5M.1 Start the debate
 
@@ -388,12 +438,13 @@ Call `agent_debate_structured` with:
 - `topic` — short slug (used in file names under `.agestra/workspace/`), prefixed or framed as QA Brigade when useful.
 - `mode` — `"review"` for QA/review/security consensus, `"idea"` for exploratory design or option discovery.
 - `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.
 - `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.
 
@@ -417,7 +468,7 @@ Before deciding, read the on-disk outputs — the debate writes three folders un
 
 - `.agestra/workspace/individual/` — per-participant individual reviews (`individual_{participant}_{topic}_{date}_{seq}.md`). Includes auto-injected host specialists like `claude-reviewer` / `claude-qa` / `claude-security` when present.
 - `.agestra/workspace/debates/` — debate transcript (`debate_{topic}_{date}_{seq}.md`), consensus ledger (`{sessionId}.consensus.json`), and structured session record (`{sessionId}.session.json`). The session record remains after `approve` / `reject` for idempotent replays and audit.
-- `.agestra/workspace/synthesis/` — the final synthesis document, written only after `agent_debate_approve` succeeds.
+- `.agestra/workspace/synthesis/` — the final synthesis document, written after `agent_debate_approve` or `agent_debate_reject` succeeds.
 
 Use `Read` / `Grep` against these paths plus the in-result snapshot to judge whether the debate outcome matches the design.
 
@@ -436,7 +487,7 @@ Pick exactly one of the three follow-up tools, based on inspection:
 
 1. **Accept the outcome** → call `agent_debate_approve` with `session_id` and an optional `leader_note` (appended to the synthesis footer under "Leader approval notes"). The moderator writes the synthesis markdown, updates the session record to `approved`, and returns `synthesisDocPath`. If this is QA-only, proceed to Phase 7. If this is an implementation flow and the QA verdict is PASS or CONDITIONAL PASS, proceed to Phase 6 unless the debate explicitly included the post-implementation review lens. If this is an implementation flow and the QA verdict is FAIL, return to Phase 3 with targeted fixes or escalate to the user instead of claiming completion.
 2. **Need more deliberation** → call `agent_debate_continue` with `session_id` and `additional_rounds` (`3`, `5`, or `10` only). The handler returns `status: running`; poll `agent_debate_status` again until it reaches the approval gate. Use this when the debate was close but unresolved, or when `escalated` came too early.
-3. **Reject the outcome** → call `agent_debate_reject` with `session_id` and a `reason` (captured in the transcript footer). Optionally set `spawn_issue: true` to write a lightweight issue branch document into `individual/` listing non-accepted proposals for later handling. No synthesis is produced. The debate is closed.
+3. **Reject the outcome** → call `agent_debate_reject` with `session_id` and a `reason` (captured in the transcript footer and rejected synthesis). Optionally set `spawn_issue: true` to write a lightweight issue branch document into `individual/` listing non-accepted proposals for later handling. The moderator writes a rejected synthesis that summarizes accepted, excluded, and unresolved items, then closes the debate.
 
 All three tools are idempotent on terminal states — re-calling returns the cached outcome.
 
@@ -469,7 +520,7 @@ Provide a clear summary to the user:
 - What changed (files modified, features added)
 - Verification summary:
   - Host-only QA/review: QA depth, E2E status, QA report path, QA cycle count + what was auto-fixed, review report path, review verdict
-  - QA Brigade / configured-provider QA: host QA report path, E2E host-only status, participant list, assigned lenses, accepted ledger items, excluded ledger items, open/opinion items, consensus verdict, dissenting findings, structured debate outcome (`approved` / `rejected`, with round count), `auto_inject_specialists` state, final synthesis path (if approved) from `.agestra/workspace/synthesis/`, and links to the individual reviews under `.agestra/workspace/individual/` and the transcript under `.agestra/workspace/debates/`
+  - QA Brigade / configured-provider QA: host QA report path, E2E host-only status, participant list, assigned lenses, accepted ledger items, excluded ledger items, open/opinion items, consensus verdict, dissenting findings, structured debate outcome (`approved` / `rejected`, with round count), `auto_inject_specialists` state, final synthesis path from `.agestra/workspace/synthesis/`, and links to the individual reviews under `.agestra/workspace/individual/` and the transcript under `.agestra/workspace/debates/`
 - Any issues found and how they were resolved
 
 </Workflow>
@@ -479,7 +530,7 @@ When transitioning between workflow phases, create a handoff document summarizin
 
 Phase 2→3 Handoff:
 - 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
 - Risk flags (shared files, complex tasks)
 - Context for workers (design doc path, Implementation Progress rows, naming conventions, key decisions)
@@ -505,8 +556,8 @@ Bad: "Add a validation function to the user module"
 Good: "In `packages/core/src/user.ts`, add a `validateEmail(email: string): boolean` function that follows the same pattern as `validateUsername` on line 42. Must handle empty strings, return false for invalid format. Export from `packages/core/src/index.ts`. Do NOT modify existing functions."
 </Prompt_Crafting>
 
-<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:
 
 | Model Size | Suitable Tasks |
 |---|---|
@@ -515,8 +566,12 @@ When routing tasks to Ollama, check model size via `ollama_models` first:
 | 8-20 GB (~7-14B params) | Code generation, detailed analysis, multi-step reasoning |
 | > 20 GB (~14B+ params) | Complex refactoring, architecture analysis |
 
-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>
 
@@ -556,10 +611,10 @@ The design document is the authority. If an AI's output conflicts with the desig
 ## MCP (External AI & Infrastructure)
 - `environment_check` — detect CLI tools, Ollama models, infrastructure
 - `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
 - `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).
-- `agent_debate_approve` / `agent_debate_continue` / `agent_debate_reject` — leader-only finalization tools for a structured session at the approval gate. `approve` writes the synthesis under `.agestra/workspace/synthesis/`; `continue(additional_rounds=N)` accepts only `3`, `5`, or `10` and returns `running`; `reject(reason=..., spawn_issue?=true)` closes the session with no synthesis.
+- `agent_debate_approve` / `agent_debate_continue` / `agent_debate_reject` — leader-only finalization tools for a structured session at the approval gate. `approve` writes an approved synthesis under `.agestra/workspace/synthesis/`; `continue(additional_rounds=N)` accepts only `3`, `5`, or `10` and returns `running`; `reject(reason=..., spawn_issue?=true)` writes a rejected synthesis and can also write a follow-up issue document.
 - Low-level debate primitives — legacy / diagnostic use only; prefer the structured debate tools for review, idea, and design workflows.
 - `agent_cross_validate` — cross-validate outputs between providers
 - `cli_worker_spawn` / `cli_worker_status` / `cli_worker_collect` / `cli_worker_stop` — manage Codex/Gemini CLI workers
@@ -598,7 +653,7 @@ Spawning a Codex CLI worker to refactor the auth module in an isolated worktree.
 <Constraints>
 - Do NOT write, edit, or create files. Delegate all implementation.
 - Do NOT skip the user approval step before executing tasks (in supervised mode).
-- Do NOT assign complex tasks to small Ollama models.
+- Do NOT assign complex tasks to models whose detected capability does not qualify, including small local models.
 - Do NOT accept "simplified" or "partial" results from AIs.
 - Do NOT proceed to QA until you've inspected all results yourself.
 - Use MCP tools for external AI orchestration and change review.

package/commands/design.md

@@ -97,7 +97,7 @@ Team-lead owns the rest:
 - Spawn `agestra:agestra-moderator` or `agestra:agestra-designer` directly when external providers are involved
 - Build individual documents or hand-edit generated debate/synthesis Markdown
 
-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.
 
 ## Step 3: Present the result
 

package/commands/idea.md

@@ -87,12 +87,12 @@ Team-lead owns the rest:
 
 Writing the final project-facing idea decision record under `docs/ideas/` is allowed and expected after the user chooses or approves ideas. `.agestra/workspace/` is the internal research/debate workspace, not the user's primary browsing surface.
 
-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.
 
 ## Step 3: Present to the user
 
 When team-lead (or the host specialist in Branch A) returns:
-- Name the debate document, consensus JSON ledger, and final synthesis document if approved
+- Name the debate document, consensus JSON ledger, and final synthesis document when the structured session is finalized
 - Name the idea decision document under `docs/ideas/` after the user chooses or approves ideas
 - Show ideas grouped as Make Soon, Explore Next, and Inspiration Bank when available
 - Explain accepted, excluded, and still-open ideas in plain language

package/commands/implement.md

@@ -51,10 +51,11 @@ Use AskUserQuestion to present the recommended routing in the user's language, o
 If team mode is not available, skip the question and use Leader-host only.
 
 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.
 
 ## Step 4: Ensure there is a design basis
 
@@ -106,7 +107,7 @@ Team-lead owns the rest:
 **Multi-AI mode:**
 - Presents task-to-provider routing table for approval
 - 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
 - Runs Phase 5M structured QA debate (cross-validation across providers)
 

package/commands/qa.md

@@ -69,14 +69,15 @@ Hand off to `agestra:agestra-team-lead` with:
 - **E2E/runtime execution:** host-owned only; external providers cross-validate artifacts and findings, not browser/dev-server execution
 - **Design doc reference:** path under `docs/plans/`
 - **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
 - **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
 - **Locale:** from `setup_status`
 - **Original user request:** preserve verbatim
 
-Team-lead owns the QA Brigade handoff and leader approval gate. The moderator engine owns provider fan-out, `ITEM-*` creation, JSON stance turns, consensus ledger aggregation, minority/open items, and synthesis after approval. This command must not call `agent_debate_structured` directly. Do not ask for a separate multi-AI confirmation in Branch B; provider selection already came from setup. Honor explicit host-only wording.
+Team-lead owns the QA Brigade handoff and leader finalization gate. The moderator engine owns provider fan-out, `ITEM-*` creation, JSON stance turns, consensus ledger aggregation, minority/open items, and final synthesis after approval or rejection. This command must not call `agent_debate_structured` directly. Do not ask for a separate multi-AI confirmation in Branch B; provider selection already came from setup. Honor explicit host-only wording.
 
 ## Step 4: Present the final result
 

package/commands/review.md

@@ -82,8 +82,10 @@ Hand off to the `agestra:agestra-team-lead` agent with multi-AI mode **pre-selec
 - **Depth/tone/audience:** selected or inferred values
 - **Boundary:** this is critique/evaluation, not QA PASS/FAIL and not a deep security audit
 - **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`
 - **Original user request:** preserve verbatim
 
@@ -99,7 +101,7 @@ Team-lead owns the rest:
 - Spawn `agestra:agestra-moderator` or `agestra:agestra-reviewer` directly when external providers are involved
 - Build individual documents or hand-edit generated debate/synthesis Markdown
 
-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.
 
 ## Step 4: Present the final result
 

package/commands/security.md

@@ -59,8 +59,9 @@ Hand off to `agestra:agestra-team-lead` with:
 - **Risk surfaces:** explicit user selections or inferred surfaces
 - **Tool permission choices:** approved / declined / not asked, with exact approved commands if any
 - **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`
 - **Original user request:** preserve verbatim