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

Loading

Agent	Model	Effort	Role
main session	claude-opus-5-5	high	Plan, decide design and security, final review, merge and push
opus-deep	claude-opus-5-5	xhigh	Security audits, architecture decisions with several valid options
sonnet-worker	claude-sonnet-5-5	high	Code, edits, debugging, tests; local branch and commits
verifier	claude-sonnet-5-5	medium	Reviews risky diffs against the brief
haiku-reader	claude-haiku-4-5	medium	Finds files and patterns, summarizes, runs tests

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.

Delegation brief (what Opus sends to sonnet-worker)

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>

Response block (what every worker returns)

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.

Git rules

Who	Allowed	Forbidden
sonnet-worker	checkout -b, add, commit, diff, status	push, merge, rebase, reset --hard, deleting branches, unapproved installs
verifier, haiku-reader, opus-deep	diff, log, status	Any write
Opus (main session)	Everything	—

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