
agentic-systems
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-powerupsRun it inside Claude Code after adding the marketplace with /plugin marketplace add yeaight7/agent-powerups.
Contents
Discovered from sourceSkills 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 considerartifacts: 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:
| Case | Required response |
|---|---|
| Invalid input | Reject immediately with status: "error" and exact field name |
| Transient failure | Include retry_after hint and idempotency note |
| Non-recoverable | State 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 level | Tool 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, andartifacts - 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
-
Pick the provider and frame the prompt. Choose
ask-codex,ask-gemini, orask-claudebased on the task, and write a single self-contained prompt string. -
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" -
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.
-
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).
-
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 repeatedask-*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)
| Tier | Typical examples | Task profile |
|---|---|---|
| Fast | Haiku, GPT-4o-mini, Gemini Flash | Mechanical, deterministic, narrow |
| Standard | Sonnet, GPT-4o, Gemini Pro | General implementation and review |
| Deep | Opus, o1, Gemini Ultra | Architecture, 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
| Tier | Use when |
|---|---|
| Fast | Deterministic, single-file, low blast radius (rename, format, classify) |
| Standard | Multi-file implementation, refactor, bounded code review — default |
| Deep | Architecture, security audit, root-cause analysis, pre-release verification |
Required Output
- Recommended tier and why
- Confidence: high / medium / low
- Escalation condition: what would cause you to move up one tier
- Budget note (if
--budgetwas 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- codebase-intelligencev0.6.3
- codebase-maintenancev0.6.3
- connected-appsv0.6.3
- context-efficiencyv0.6.3
- data-engineeringv0.6.3
- debugging-diagnosticsv0.6.3
- dev-vitalsv0.6.3
- documentation-systemsv0.6.3
- github-opsv0.6.3
- machine-learning-opsv0.6.3
- mcp-developmentv0.6.3
- memory-optimizationv0.6.3
- quality-gatesv0.6.3
- security-guardrailsv0.6.3
- skill-authoringv0.6.3
- software-engineeringv0.6.3
- spec-driven-developmentv0.6.3
- spec-quality-gatesv0.6.3
- tool-integrationsv0.6.3
- agent-evaluation-labv0.6.3