Multi-model orchestration and advisor routing: tri-model review and canonical advisor routing.

version
0.6.3
GitHub stars
9

Install

/plugin install agentic-systems@agent-powerups

Run it inside Claude Code after adding the marketplace with /plugin marketplace add yeaight7/agent-powerups.

Contents

Discovered from source

Skills 5

Agent Harness Design

Use when designing or improving how an agent invokes tools, handles errors, and decides when to stop.

When to Use

  • Designing tool definitions for a new agent or subagent
  • Observing high retry rates or ambiguous tool invocations
  • Agent is failing silently or completing without verifying outcomes
  • Reviewing an existing agent harness for quality issues

Tool Design Rules

Naming

  • Use explicit, stable names: read_file, run_tests, apply_patch
  • No generic names: do_action, execute, handle
  • One tool per distinct operation; do not overload parameters to compensate

Schema

Keep tool inputs narrow:

  • Required fields only; no optional fields that change behavior
  • Use enums for mode/type values — never free-text strings that require parsing
  • Validate at the boundary; reject malformed input with a clear error, not a fallback
{
  "name": "run_tests",
  "parameters": {
    "path": { "type": "string", "description": "Path to test file or directory" },
    "filter": { "type": "string", "description": "Optional test name filter" }
  }
}

Output Shape

Every tool response must include:

  • status: "success" | "warning" | "error"
  • summary: one-line result (human-readable)
  • next_actions: list of follow-up steps the agent should consider
  • artifacts: file paths or IDs produced (empty list if none)

Catch-All Tools

Avoid run_bash / shell_exec style catch-all tools unless:

  • The task is genuinely open-ended and the toolset cannot be pre-defined
  • You explicitly document the risk and add an allowlist or preflight check

If you must use a catch-all, add a PreToolUse validation hook for dangerous patterns.

Error Path Rules

Every tool must define what happens on failure:

CaseRequired response
Invalid inputReject immediately with status: "error" and exact field name
Transient failureInclude retry_after hint and idempotency note
Non-recoverableState stop: true and describe the manual resolution step

Do not return partial success with no indication that something failed.

Retry and Stop Conditions

Define retry limits in the harness, not inside tool implementations:

max_retries: 2
stop_conditions:
  - tool returns status: "error" with stop: true
  - same tool called with identical inputs twice in a row
  - completion signal received

Never retry indefinitely. Declare a hard ceiling.

Context Budget

  • Keep system prompt fixed and minimal — it is loaded on every turn
  • Put large reference material (schemas, docs) in skills loaded on demand
  • Compact at phase boundaries (after research, after planning, after debugging)
  • Do not pass growing tool-call history to subagents; summarize into a context bundle

Granularity Guide

Risk levelTool granularity
High (deploy, migrate, permissions)Micro — one action, one confirmation
Medium (edit, read, search)Standard — composite is fine
Low (format, report, list)Macro — batch operations acceptable

Benchmarks to Track

  • Completion rate (task finished without escalation)
  • Retries per task
  • Pass@1 rate (completed on first attempt)
  • Cost per successful task

Anti-Patterns

  • Overlapping tool semantics (agent cannot choose between them)
  • Tool returns only on error — no output on success
  • No explicit stop condition — agent loops indefinitely
  • Context overload — every tool call inlines full file contents

Verification

  • Every tool has an explicit, stable name and exactly one distinct operation
  • Schemas use required fields and enums — no free-text mode strings, no behavior-changing optionals
  • Every tool response carries status, summary, next_actions, and artifacts
  • Every tool defines its invalid-input, transient-failure, and non-recoverable paths
  • Retry ceiling and stop conditions are declared in the harness, not inside tools
  • Any catch-all tool is documented with its risk and guarded by an allowlist or preflight check

Purpose

Route a prompt through a local provider CLI and persist the result as an artifact. The execution path is process-first: always go through the canonical apx ask-* wrappers rather than hand-assembled raw provider commands, so routing and artifact capture stay consistent.

When to Use

  • You want a focused second opinion, review, or plan from a local provider
  • You are about to invoke a provider CLI directly and want a consistent entry point
  • The response needs to be saved to disk for later reference, not just printed
  • A previous wrapper run misbehaved and you are debugging the routing

Inputs

  • A clear prompt describing the task for the advisor
  • The chosen provider (codex, gemini, or claude) installed and authenticated locally

Workflow

  1. Pick the provider and frame the prompt. Choose ask-codex, ask-gemini, or ask-claude based on the task, and write a single self-contained prompt string.

  2. Invoke the canonical wrapper. Run the prompt through the apx ask-* command. Do not manually assemble raw provider CLI commands unless you are debugging the wrapper itself.

    apx ask-codex "review this patch from a security perspective"
    apx ask-gemini "suggest UX improvements for this flow"
    apx ask-claude "draft an implementation plan for issue #123"
    
  3. Confirm prerequisites if the call fails. Verify the selected local CLI is installed and authenticated before retrying; a missing or unauthenticated CLI is the usual cause.

  4. Persist the response as an artifact. Write the result to the standard artifact location so it can be reviewed later. The path is .agent-powerups/artifacts/ask/ with a filename of the form provider-slug-timestamp (Markdown extension).

  5. For multi-turn or session work, defer to the relay skills. When the task needs cross-turn context rather than a one-shot answer, route through the relay siblings (relay-codex, relay-gemini, relay-claude) instead of repeated ask-* calls.

Output

  • The provider's response written under .agent-powerups/artifacts/ask/ with a provider-slug-timestamp Markdown filename
  • A consistent, reproducible routing path that other agents can follow

Verification

  • The provider was invoked through an apx ask-* wrapper, not a hand-built raw command
  • The selected local CLI was installed and authenticated before the call
  • The response was written to the standard .agent-powerups/artifacts/ask/ location
  • The artifact filename follows the provider-slug-timestamp pattern

Failure Modes

  • Bypassing the wrapper — assembling raw provider CLI commands by hand outside of debugging, which loses consistent routing and artifact capture.
  • Unauthenticated CLI — invoking a provider whose local CLI is not installed or signed in, so the call fails before producing any artifact.
  • Lost response — reading the answer from stdout only and never writing it to the artifact location, leaving nothing to review later.
  • Wrong tool for the job — using one-shot ask-* for work that needs cross-turn context instead of the relay siblings.

Context Retrieval Loop

Gather the right codebase context before making changes or spawning subagents. Prevents acting on incomplete information.

When to Use

  • Starting work on an unfamiliar area of a codebase
  • Spawning a subagent that needs targeted file context
  • Failing to find a relevant file on the first search pass
  • Unsure which files are in scope for a task

The 3-Cycle Loop

Each cycle builds on the previous. Stop early when you have enough context. Do not exceed 3 cycles.

Cycle 1 — Broad Search

# Find files by keyword
rg "<primary-keyword>" --type ts --type js -l
rg "<primary-keyword>" --glob "*.py" -l

# Find by filename pattern
find . -name "*<keyword>*" -not -path "*/node_modules/*" -not -path "*/.git/*"

Collect: file paths, key terms, naming conventions seen.

Stop here if: 3 or more directly relevant files found with no critical gaps.

Cycle 2 — Exact Source and Tests

Read the most relevant files from Cycle 1 in full. Then:

# Find tests for those files
rg "<filename-stem>" --glob "*.test.*" --glob "*.spec.*" -l
rg "import.*<module-name>" -l

# Find call sites
rg "<function-name>|<class-name>" --type ts --type js -l

Collect: imports used, function signatures, test patterns, adjacent files referenced.

Stop here if: You can describe the change needed and its blast radius.

Cycle 3 — Docs and Setup

# Check project-specific docs
ls docs/ README.md AGENTS.md CLAUDE.md .claude/ 2>/dev/null

# Check config for feature flags, env vars, or schema
rg "<keyword>" .env.example *.config.* *.toml *.yaml -l 2>/dev/null

Collect: configuration constraints, environment requirements, anything that would block a change.

Stopping Conditions

Stop the loop (whichever comes first):

  • You have 3+ high-relevance files and understand the change scope
  • Cycle 3 complete
  • Each new cycle returns only files already seen

Output

After the loop, report:

Context gathered:
  <file-path> — <one-line reason for relevance>
  ...

Missing context (if any):
  <what is still unclear and why it matters>

If context is missing, state it explicitly. Do not proceed with guesses when a known gap exists.

Integration with Subagents

When dispatching a subagent, pass only the gathered file list — not the full conversation context:

Relevant files for this task:
  src/auth/tokens.ts — contains TokenService used by the bug
  src/auth/session.ts — session state management
  src/auth/tokens.test.ts — existing test patterns

Constraints

  • Max 3 cycles. Diminishing returns beyond that.
  • Do not read files speculatively. Read only files flagged as relevant.
  • Do not inline entire file contents into the subagent prompt; pass paths.
  • Report gaps rather than silently proceeding with incomplete context.

Verification

  • The loop stopped at a stopping condition — never past 3 cycles
  • Every gathered file is listed with a one-line relevance reason
  • Missing context is stated explicitly — no proceeding on guesses when a gap is known
  • Subagents received the file-path list, not inlined file contents
  • No speculative reads — only files flagged as relevant were opened

Model Routing

Choose the right model tier before starting a task. Overusing a capable model wastes cost and context. Underusing it produces lower quality on complex work.

When to Use

  • Selecting a model for a new task or subagent
  • Deciding whether to escalate after a failed attempt
  • Designing a multi-agent pipeline with mixed task complexity

Tier Definitions (vendor-neutral)

TierTypical examplesTask profile
FastHaiku, GPT-4o-mini, Gemini FlashMechanical, deterministic, narrow
StandardSonnet, GPT-4o, Gemini ProGeneral implementation and review
DeepOpus, o1, Gemini UltraArchitecture, security, root-cause, release

Use your provider's current recommended model for each tier. Do not hard-code model IDs in documentation or scripts; reference tiers instead.

Routing Table

Fast tier

Use when ALL of:

  • Single file or single operation
  • Output is deterministic (rename, format, classify, generate boilerplate)
  • No ambiguity in the task description
  • Low blast radius on failure (easy to retry or revert)

Examples: rename a variable, convert a data format, generate a changelog entry, classify issue severity.

Standard tier

Use when ANY of:

  • Multi-file change with known scope
  • Standard implementation task (add a feature, fix a bug, write tests)
  • Code review of a bounded change
  • Refactor with clear before/after contract

This is the default. When unsure, use Standard.

Deep tier

Use when ANY of:

  • Architecture or system design decision
  • Security audit or threat model
  • Root-cause analysis with no clear reproduction
  • Pre-release verification across a large surface
  • Task requires reasoning across many files simultaneously
  • Two Standard attempts failed with no clear progress

Do not use Deep speculatively. It is expensive and slower.

Escalation Rule

Try Standard first. Escalate to Deep only after Standard fails with a clear reasoning gap — not just a wrong answer. A wrong answer from Standard often means the task needs more context, not a more capable model.

Do not escalate because of anxiety about getting it right. Escalate because the attempt revealed a complexity that a smaller model cannot handle.

Session Discipline

  • Start a new session after a major phase transition (research → implement → test)
  • Compact context after finishing research before starting implementation
  • Do not carry debugging traces into an implementation session
  • Short-lived subagents default to Fast or Standard depending on task type

Cost Tracking

Record per task:

  • Tier used
  • Approximate token count
  • Number of retries
  • Success/escalated/failed

Use this to calibrate your routing decisions over time. If Standard succeeds > 90% of the time on a task type, that task does not need Deep.

Anti-Patterns

  • Pre-escalation: Using Deep on a task that hasn't been tried at Standard
  • Anxiety escalation: Using Deep because the task feels important, not because it's complex
  • Under-routing: Using Fast for a multi-file refactor and then retrying three times
  • Model pinning: Hard-coding specific model IDs in configs instead of tier references

Verification

  • Tier was chosen from the routing table before the task started — Standard by default when unsure
  • Deep was used only for a listed Deep criterion or after a Standard attempt exposed a reasoning gap
  • No specific model IDs were hard-coded — tier references only
  • Tier, retries, and outcome were recorded for future calibration

Tri-Model Review

Tri-model review routes through two external advisor CLIs, then synthesizes both outputs into one answer.

Use this when you want parallel external perspectives.

When to Use

  • Backend/analysis + frontend/UI work in one request
  • Code review from multiple perspectives (architecture + design/UX)
  • Cross-validation where different models may disagree
  • Fast advisor-style parallel input without full team runtime orchestration

Requirements

  • Ensure you have configured the appropriate apx ask-* wrappers.
  • If either wrapper is unavailable, continue with whichever provider is available and note the limitation.

How It Works

1. Decompose the request into two advisor prompts:
   - Analysis/architecture/backend prompt
   - UX/design/docs/alternatives prompt

2. Run both advisors via the canonical wrappers:
   - apx ask-codex "<prompt>"
   - apx ask-gemini "<prompt>"

3. Synthesize both outputs into one final response

Execution Protocol

When invoked, follow this workflow:

1. Decompose Request

Split the user request into:

  • Architecture prompt: correctness, backend, risks, test strategy
  • UX prompt: content clarity, alternatives, edge-case usability, docs polish
  • Synthesis plan: how to reconcile conflicts

2. Invoke advisors via Bash

Run both advisors via the Bash tool:

apx ask-codex "<architecture prompt>"
apx ask-gemini "<UX prompt>"

3. Synthesize

Return one unified answer with:

  • Agreed recommendations
  • Conflicting recommendations (explicitly called out)
  • Chosen final direction + rationale
  • Action checklist

Fallbacks

If one provider is unavailable:

  • Continue with available provider + synthesis
  • Clearly note missing perspective and risk

If both unavailable:

  • Fall back to a single-model answer and state external advisors were unavailable.

Verification

  • Request was decomposed into distinct architecture and UX prompts before invoking advisors
  • Both advisors were invoked via the canonical wrappers — or the missing provider was explicitly noted
  • Synthesis lists agreed recommendations, explicitly called-out conflicts, the chosen direction with rationale, and an action checklist
  • Any provider fallback was stated, including the missing perspective and its risk

Commands 2

Commands

Experimental agentic-systems commands.

/model-route — Model Tier Recommendation

Evaluate the current task and recommend the appropriate model tier.

Usage

/model-route [task-description] [--budget low|med|high]

Tier Routing

TierUse when
FastDeterministic, single-file, low blast radius (rename, format, classify)
StandardMulti-file implementation, refactor, bounded code review — default
DeepArchitecture, security audit, root-cause analysis, pre-release verification

Required Output

  1. Recommended tier and why
  2. Confidence: high / medium / low
  3. Escalation condition: what would cause you to move up one tier
  4. Budget note (if --budget was specified): whether the recommendation changes

Escalation Rule

Escalate only after the lower tier fails with a clear reasoning gap — not because the task feels important.

Arguments

$ARGUMENTS:

  • [task-description] — optional free-text description of the task
  • --budget low|med|high — optional cost constraint

Agents 1

Agents

Experimental agentic-systems agents.

Sponsors

Details

Marketplace
yeaight7/agent-powerups
Source
plugins/agentic-systems
Category
Developer Tools
License
Apache-2.0
Keywords
multi-agent, orchestration, routing, tri-model, advisor

More from yeaight7/agent-powerups

All 21