Batuta

batuta

Model-tiered delegation for Claude Code. Opus thinks and decides, Sonnet executes, Haiku only reads.

Your usage limit goes further when Opus stops doing routine work. batuta keeps the main session on Opus for planning, design and security, and hands execution to cheaper models through subagents, with a fixed brief, a checklist-based response and one escalation step back to Opus.

How it works

flowchart TD
    U([Task]) --> O{"Opus<br/>classifies"}
    O -->|"security audit,<br/>multi-option architecture"| D["opus-deep<br/>xhigh · read-only"]
    O -->|"security, design,<br/>migrations, unclear bugs"| OP[Opus does it]
    O -->|"clear spec, edits,<br/>debugging, tests"| C{"Paths<br/>known?"}
    C -->|no| H["haiku-reader<br/>mini brief"]
    H --> S
    C -->|yes| S["sonnet-worker<br/>task/... branch"]
    S -->|ESCALATE| OP
    S -->|DONE| R{"3+ files or<br/>tests/build?"}
    R -->|yes| V["verifier<br/>PASS / FAIL"]
    R -->|no| F
    V -->|FAIL| OP
    V -->|PASS| F["Opus final review<br/>merge and push"]
    OP --> F
    D -->|analysis| O

opus-deep, verifier and haiku-reader are read-only. Every agent preloads ponytail: YAGNI, reuse first, one-liners over fifty lines.

[!NOTE] Escalation is Sonnet → Opus, one attempt per level. A task never goes back to the same level twice; Opus picks it up on the same branch using the worker's notes.

Requirements

• Claude Code with access to claude-opus-5-5, claude-sonnet-5-5 and claude-haiku-4-5
• Main session on Opus (/model)
• The ponytail plugin
• Projects in a git repository (workers create branches and commits)

[!IMPORTANT] Without ponytail, the agents' ponytail:ponytail and ponytail:ponytail-review skills do not resolve. Install it first.

Install

/plugin marketplace add engelbertgm/Batuta
/plugin install batuta@batuta

Then add this to ~/.claude/CLAUDE.md so every session follows batuta:

# batuta
- Always follow the `batuta:batuta` skill: Opus plans and decides, delegates execution to batuta agents.
- Follow YAGNI principles, and prefer one-liner solutions.

[!TIP] Try it without installing: claude --plugin-dir <path-to-this-repo>, then ask "List the batuta subagent types you can spawn, with their models." to see the four batuta:* agents.

Usage

Work as usual; the skill routes each task. To force a level, say so:

"Do this with Opus."

A manual override always wins over routing.

OBJECTIVE: <what to achieve>
DONE WHEN: <verifiable criteria>
FILES: <paths, from the mini brief if any>
REUSE: <what to use instead of creating>
DO NOT TOUCH: <files or areas out of scope>
BRANCH: task/<clear-description>
CONTEXT: <decisions already made; notes from a previous attempt if escalating>

STATUS: DONE | ESCALATE
CHECKLIST:
  [x] covers every DONE WHEN criterion
  [x] applicable tests run and passing
  [x] no invented requirements or assumptions
  [x] APIs and libraries verified in code or docs
FILES: <changed files, or none>
BRANCH: <branch and last commit>
TRIED: <what you tried, if escalating>
REASON: <one line>
CONFIDENCE: 0-100

DONE counts only with every item checked. CONFIDENCE is informational.

Branches are task/<clear-description>; the first commit is WIP(task): <clear description>. Parallel tasks each get their own worktree.

Limitations

[!WARNING] Agent restrictions (git, installs, read-only) are enforced by instructions only. For hard blocks, add permissions.deny rules to your ~/.claude/settings.json.

• Model IDs are pinned; changing versions is your call.
• Usage logging and /ladder-stats are planned for phase 2.

The full design is in SPEC.md (Spanish).

Contributing

See CONTRIBUTING.md and the Code of Conduct. Report vulnerabilities privately as described in SECURITY.md.

License

Apache-2.0