BubbleBuffer/use-superpawers-subagents

Use SuperPawers Subagents

Overview

Never dispatch OpenCode's built-in agent types (explore, general). Always use SuperPawers subagents (superpawers-researcher, superpawers-implementer, superpawers-reviewer, superpawers-verifier) which have properly configured models and don't inherit the caller model.

Core principle: Generic agents inherit the caller model — exploding token consumption. SuperPawers agents have their own model configs — safe, predictable cost, focused context.

Background: Each superpawers agent has its model set in its configuration file (.opencode/agents/superpawers-*.md) at install time. When you dispatch with the correct subagent_type, OpenCode uses that agent's model — not yours.

<HARD-GATE> Do NOT dispatch agent types `"explore"` or `"general"`. Do NOT do subagent-worthy work inline (research, review, implementation, verification). Always dispatch the correct superpawers agent type. The cost of the wrong model dwarfs any "convenience" of inline work or generic agents. </HARD-GATE>

When This Triggers

digraph when_triggers {
    "About to act?" [shape=diamond];
    "Action is research, review, implement, or verify?" [shape=diamond];
    "About to dispatch subagent?" [shape=diamond];
    "Using explore or general type?" [shape=diamond];
    "Trivial inline task?" [shape=diamond];
    "STOP. Dispatch superpawers subagent." [shape=box];
    "Proceed." [shape=box];

    "About to act?" -> "Action is research, review, implement, or verify?" [label="yes"];
    "Action is research, review, implement, or verify?" -> "Trivial inline task?" [label="yes"];
    "Trivial inline task?" -> "Proceed." [label="single file, <10 lines"];
    "Trivial inline task?" -> "About to dispatch subagent?" [label="no"];
    "About to dispatch subagent?" -> "Using explore or general type?" [label="yes"];
    "Using explore or general type?" -> "STOP. Dispatch superpawers subagent." [label="yes"];
    "Using explore or general type?" -> "Proceed." [label="no (correct type)"];
}

Trivial = single file, <10 lines, no integration concerns, no test changes. Everything else requires a subagent.

Agent Mapping

| Instead of... | Use... | Why | |---------------|--------|-----| | subagent_type="explore" | subagent_type="superpawers-researcher" | Own model, bounded context | | subagent_type="general" for research | subagent_type="superpawers-researcher" | Own model, bounded context | | subagent_type="general" for implementation | subagent_type="superpawers-implementer" | Own model, follows TDD | | Inline file exploration / codebase research | subagent_type="superpawers-researcher" | Focused context, doesn't burn yours | | Inline code review | subagent_type="superpawers-reviewer" | Fresh eyes, own model | | Inline implementation (>10 lines) | subagent_type="superpawers-implementer" | Isolated context, TDD | | Inline test/lint/typecheck verification | subagent_type="superpawers-verifier" | Independent verification |

Dispatch format:

Task(
  "Brief description of work",
  subagent_type="superpawers-[researcher|implementer|reviewer|verifier]",
  prompt="[task specification + relevant context]"
)

Never use:

Task(
  "Brief description",
  subagent_type="explore",    ← WRONG: inherits parent model
  prompt="..."
)

The Iron Law

NEVER DISPATCH GENERIC SUBAGENTS. NEVER DO SUBAGENT-WORTHY WORK INLINE.

Violating the letter of this rule is violating the spirit of this rule.

No exceptions:

• Not for "just a quick explore"
• Not for "general works fine for this"
• Not for "I can do this faster inline"
• Not for "explore is the right tool for codebase search"
• Not for "this is too small to justify a subagent" (if >10 lines)

Red Flags — STOP

These thoughts mean you're about to violate this rule:

| Thought | Reality | |---------|---------| | "explore is what I'm supposed to use for codebase search" | No. Use superpawers-researcher. | | "I'll just read the files myself, it's faster" | It's also token-expensive and unfocused. Dispatch. | | "This is just a small review, I can do it inline" | Reviewer has fresh eyes and its own model. Dispatch. | | "general agent works fine" | It inherits YOUR model. Token cost is identical. | | "I'm already in context, dispatching loses that" | You construct exactly what context the subagent needs. You don't lose — you curate. | | "The task is trivial" | >10 lines, multiple files, or test changes → not trivial. Dispatch. | | "I'll verify the tests myself" | Verifier runs independently. You might miss something. Dispatch. |

All of these mean: Dispatch the correct superpawers subagent. Now.

Common Mistakes

| Mistake | Fix | |---------|-----| | Using explore for codebase research | Dispatch superpawers-researcher | | Reading 5+ files inline to "understand the codebase" | That's research. Dispatch superpawers-researcher. | | Reviewing a PR/diff inline instead of dispatching reviewer | Dispatch superpawers-reviewer | | Running tests/lint inline instead of dispatching verifier | Dispatch superpawers-verifier | | Using general agent for implementation | Dispatch superpawers-implementer (follows TDD) |

Project Guidelines

When constructing a task prompt for any subagent, include relevant sections from AGENTS.md / CONTRIBUTING.md that apply to the agent's role. For implementers: code conventions, style, testing rules. For reviewers: quality standards to check against. For researchers: what patterns to look for. Keep it focused — don't dump the whole file.

Integration

Entry gate: superpawers:using-superpawers — the router invokes this skill before any subagent dispatch or inline research/review/implementation/verification decision.

Used by every workflow skill:

• superpawers:subagent-driven-development — already dispatches superpawers subagents; this skill ensures the correct types
• superpawers:systematic-debugging — Phase 1 evidence gathering → superpawers-researcher, not explore
• superpawers:dispatching-parallel-agents — parallel investigation → superpawers-researcher for each
• superpawers:brainstorming — codebase exploration → superpawers-researcher

Complements:

• superpawers:verification-before-completion — this skill ensures the verifier subagent is used; that skill governs when
• superpawers:requesting-code-review — this skill ensures the reviewer subagent is used; that skill governs how

The Bottom Line

Generic agents inherit your model → token explosion. SuperPawers agents have their own models → safe, predictable cost, better results.

Never dispatch explore or general. Never research, review, implement, or verify inline when a subagent should do it. Always use the right superpawers subagent type.