BubbleBuffer/using-superpawers

<SUBAGENT-STOP> If you were dispatched as a subagent to execute a specific task, skip this skill. </SUBAGENT-STOP> <EXTREMELY-IMPORTANT> If a skill plausibly matches the task category or was explicitly requested, load it before acting.

Skills codify the workflow this project trusts. Do not shortcut around them, and do not rationalize your way past the entry router. </EXTREMELY-IMPORTANT>

Common Entry Points

Pick one, then invoke that skill first.

| Situation | Start with | |-----------|------------| | About to dispatch a subagent or do research/review/implementation/verification | use-superpawers-subagents | | New feature, behavior change, or vague request | brainstorming | | Multi-step or multi-file implementation request | writing-plans | | Approved plan or existing task list, ready to execute | subagent-driven-development | | Bug, test failure, or unexpected behavior | systematic-debugging | | Incoming human or external review feedback | receiving-code-review | | Need a review before merge or at a milestone | requesting-code-review | | Multiple independent investigations in parallel | dispatching-parallel-agents | | About to claim work is done, passing, or fixed | verification-before-completion | | All tasks complete, ready to merge/PR/discard | finishing-a-development-branch | | Creating or editing a skill | writing-skills |

Supporting technique skills (test-driven-development, using-git-branches, root-cause-tracing, defense-in-depth, condition-based-waiting) are invoked by the workflow skills above. You'll typically enter them through systematic-debugging or subagent-driven-development, not directly.

Instruction Priority

SuperPawers skills override default system prompt behavior, but user instructions always take precedence:

1. User's explicit instructions (AGENTS.md, direct requests) — highest priority
2. SuperPawers skills — override default system behavior where they conflict
3. Default system prompt — lowest priority

If AGENTS.md says "don't use TDD" and a skill says "always use TDD," follow the user's instructions. The user is in control.

How to Access Skills

Use the skill tool. When you invoke a skill, its content is loaded and presented to you—follow it directly. Never use the read tool on skill files.

Available Agents

SuperPawers defines these subagent types for dispatch via the Task tool:

| subagent_type value | Purpose | Configured in | |------------------------|---------|---------------| | "superpawers-researcher" | Explores codebase, gathers context, reports findings | .opencode/agents/superpawers-researcher.md | | "superpawers-implementer" | Implements tasks following TDD with isolated context | .opencode/agents/superpawers-implementer.md | | "superpawers-reviewer" | Reviews code quality, spec compliance, and production readiness | .opencode/agents/superpawers-reviewer.md | | "superpawers-verifier" | Runs tests, lint, and typecheck independently | .opencode/agents/superpawers-verifier.md |

Each agent's model is set in its configuration file at install time. Dispatch with explicit subagent_type:

Task(
  "Implement auth feature",
  subagent_type="superpawers-implementer",
  prompt="[task specification + relevant context]"
)

Using Skills

The Rule

If a skill plausibly matches the task category, invoke it before acting. Skills contain the project's workflow decisions; acting without them invites drift. If an invoked skill turns out to be the wrong one, abandon it and pick the right one — that is cheap. Skipping the router is not.

Skill Flow

digraph skill_flow {
    "User message received" [shape=doublecircle];
    "Plausible skill match?" [shape=diamond];
    "Invoke skill tool" [shape=box];
    "Announce: 'Using [skill] to [purpose]'" [shape=box];
    "Has checklist?" [shape=diamond];
    "Create todo per item" [shape=box];
    "Follow skill exactly" [shape=box];
    "Respond (including clarifications)" [shape=doublecircle];

    "User message received" -> "Plausible skill match?";
    "Plausible skill match?" -> "Invoke skill tool" [label="yes"];
    "Plausible skill match?" -> "Respond (including clarifications)" [label="clearly not"];
    "Invoke skill tool" -> "Announce: 'Using [skill] to [purpose]'";
    "Announce: 'Using [skill] to [purpose]'" -> "Has checklist?";
    "Has checklist?" -> "Create todo per item" [label="yes"];
    "Has checklist?" -> "Follow skill exactly" [label="no"];
    "Create todo per item" -> "Follow skill exactly";
}

Red Flags

These thoughts mean STOP—you're rationalizing:

| Thought | Reality | |---------|---------| | "This is just a simple question" | Questions are tasks. Check for skills. | | "I need more context first" | Skill check comes BEFORE clarifying questions. | | "Let me explore the codebase first" | Skills tell you HOW to explore. Check first. | | "I can check git/files quickly" | Files lack conversation context. Check for skills. | | "Let me gather information first" | Skills tell you HOW to gather information. | | "This doesn't need a formal skill" | If a skill exists, use it. | | "I remember this skill" | Skills evolve. Read current version. | | "This doesn't count as a task" | Action = task. Check for skills. | | "The skill is overkill" | Simple things become complex. Use it. | | "I'll just do this one thing first" | Check BEFORE doing anything. | | "This feels productive" | Undisciplined action wastes time. Skills prevent this. | | "I know what that means" | Knowing the concept ≠ using the skill. Invoke it. |

Skill Priority

When multiple skills could apply, use this order:

0. Subagent discipline first (use-superpawers-subagents) — before ANY subagent dispatch or inline research/review/implementation/verification. This gates every agent interaction.
1. Process skills next (brainstorming, systematic-debugging) — these decide HOW to approach the task.
2. Workflow skills after (writing-plans, subagent-driven-development) — these decide what to do and in what order.
3. Quality gates last (verification-before-completion, requesting-code-review, receiving-code-review) — these govern transitions and completion claims.

"About to dispatch a subagent" → use-superpawers-subagents first. "Let's build X" → brainstorming first. "Add X to settings, sidebar, and dashboard" → writing-plans (multi-file). "Fix this bug" → systematic-debugging first. "Implement these 4 tasks" → subagent-driven-development. "Review what I just wrote" → requesting-code-review. "Here's the reviewer's feedback" → receiving-code-review.

Skill Types

Rigid (TDD, debugging): Follow exactly. Don't adapt away discipline.

Flexible (patterns): Adapt principles to context.

The skill itself tells you which.

Repo Constraints Are Hard Rules

Never use git add -f or --force to bypass .gitignore. If a skill instructs you to commit a file that gitignore blocks, skip the commit — save the file to disk and move on. Use git check-ignore <path> if unsure.

User Instructions

Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows.