Init
Batuta's onboarding and reconfiguration. Use when the user invokes /batuta:init, wants to set Batuta up in a project, or wants to change an existing setup (lanes, models, profile answers, project map).From its SKILL.md
npx -y skills add franciscpd/batuta --skill initAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 4 stars4 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
9.9 KB, as published. Nobody here has run it
Batuta init — onboarding and reconfiguration
Two modes, decided by whether .batuta/profile.md exists in the project.
First run (no .batuta/profile.md)
-
Detect the stack (package.json, composer.json, go.mod, etc.) and suggest it as the default. Read
CLAUDE.md/AGENTS.mdif present — the profile must complement them, never duplicate what they already say. If they contradict the user's onboarding answers, flag the conflict to the user — never edit those files (executors like codex readAGENTS.mdon their own; an unflagged contradiction means conflicting instructions mid-task). Single exception: the marked discovery-pointer block of step 3.5, written only with the user's explicit consent and only between its own markers. -
Ask 6–7 short questions, all at once:
- Stack? (detected suggestion as default)
- Methodology: TDD or tests after? Conventional commits or free-form? Trunk-based or feature branches?
- Test command? Build command?
- Batch execution: sequential (default) or parallel? (how decomposed
multi-item requests run — see Step 1.5 of the cycle; the answer becomes
the profile's Execution line, written as a literal line, e.g.
Execution: sequential) - Worktree mode:
off,medium+(default) oralways? (whether the executor works in an isolated git worktree per task — see Steps 3–5 of the cycle; the answer becomes the profile's literal line, e.g.Worktree: medium+) - Install command? (optional — sets up the test environment inside a
worktree, e.g.
npm install; becomes the profile'sInstall:line, omitted when there is none) - Runtime? (only when the
compozyCLI is on PATH and its daemon responds — offerRuntime: compozyvsdireto(default); withcompozy, delegations run as managed sessions percompozy.md; omitted otherwise)
-
Save the answers to
.batuta/profile.md, referencing the matching stack template — catalog:templates/react.md,templates/nextjs.md,templates/react-native.md,templates/vue.md,templates/node-api.md,templates/nestjs.md,templates/python.md,templates/laravel.md,templates/generic.md. Most specific wins: detect the stack (lockfiles,composer.json,pyproject.toml, framework deps inpackage.json) and pick the most specific template that applies (Next.js > React > generic); when in doubt between parent and child, the child. Step 3.5 — Discovery pointer (opt-in). Offer to write a marked block to the project'sAGENTS.mdso any maestro session born in this project — including sessions started through the Compozy daemon — knows on session start that delegable work goes through Batuta. Fold the offer into the single confirmation question of step 6; declined → write nothing and do not re-offer automatically. Accepted → write exactly this block (createAGENTS.mdcontaining only the block when the file doesn't exist), flush left — the indentation below is only for legibility inside this document; nothing is indented in the actual write, or the## Batutaheading breaks:<!-- batuta:begin — managed by /batuta:init, edit via reconfigure --> ## Batuta This project delegates code tasks via the Batuta cycle. If you are the session talking directly to the user (the maestro), route delegable work through the `batuta` skill — classify, route via `.batuta/routing.md`, delegate, verify. If you received a delegated brief, IGNORE this section and follow your brief only. <!-- batuta:end -->The
batuta:begin/batuta:endmarkers make every write idempotent — but only when the write honors it: if the block already exists inAGENTS.md(first run finding a stale copy, or reconfigure's "add" path over an existing one), replace whatever sits between the markers in place; never append a second copy. Same rule for the reconfigure "rewrite" path. Updates and removals likewise touch only what sits between the markers, never the rest of the file. The block's last sentence is the anti-loop guard — executors readAGENTS.mdon their own, and without it an executor mid-brief could conclude it should delegate too; the brief always wins. -
Add a "Project map" section to the profile: 20–40 lines of prose — key directories, where routes/components/tests live, entry points, generated files not to touch. Defer this initial sweep to the end of onboarding, after step 6 below maps the lanes: delegate it to the Research lane's scout (see
skills/batuta/SKILL.md, "The scout"); if the user left that lane unmapped or the scout fails twice, sweep it yourself. The map says where to start looking, not everything: details stay with grep and git, which never go stale. -
Takeover: if artifacts from another framework exist (
.planning/,TODO.md, roadmaps…), offer a one-time import: in-progress/done work becomesWORK.mdlines, large remaining work becomes.batuta/plan-<slug>.md, relevant decisions become profile lines. Leave the old artifacts untouched — the user archives them if they want. -
Executor check and lane mapping: run the availability checks from each adapter referenced by the routing table (
command -v codex,opencode providers list, …) and show what was found. Only what the table references — never scan the machine for every CLI that might exist (cursor, copilot, kimi CLI, …); those adapters stay dormant until the user asks for one ("put cursor on the medium lane"), which is when its adapter gets read and its row gets written. Then propose a lane mapping built from what is actually installed — the default table assumes the full trio (opencode + codex + claude), but the user's real setup rules:- Full trio: default table; confirm the trivial-lane opencode model and
the complex-lane executor — codex + strong model (default) or a strong
Claude model via background instance (
claude -p --model opus, seeadapters/claude.md), whichever the user prefers for briefable heavy-logic work. - No codex (e.g. claude + opencode): opencode keeps trivial; suggest a mid-tier opencode model for medium; complex goes to a strong Claude model in background; critical stays with the session.
- claude only: lanes differentiate by Claude model via background
instances (
claude -p --model <model>, seeadapters/claude.md) — e.g. haiku for trivial, sonnet for medium, opus for complex, the session itself for critical. The same single confirmation question also covers the Research support lane (routing.md, Support lanes): suggest a cheap candidate from the discovery already run — filter tokimi|haiku|mini|nano|flash|free. Full trio or no-codex → a cheap opencode model orclaude -p --model haiku; claude only → haiku via background instance. The user has the final word on which CLI/provider/model owns each lane — present the proposal and let them adjust before writing anything. For multi-model CLIs, discover models yourself — the user never enumerates anything: run the discovery fromadapters/opencode.md(opencode modelsfiltered to cheap candidates) andadapters/codex.md(Model selection) and suggest 2–3 options per lane. Ask ONE confirmation question covering the whole mapping (lanes + models + the step 3.5 discovery pointer). Write the result as the project's.batuta/routing.md: the local copy is born here, with the exact executors and model IDs confirmed by the user. If an executor disappears later, tell the user which lanes collapse upward (unavailability rule) instead of letting them find out on the first delegation.
- Full trio: default table; confirm the trivial-lane opencode model and
the complex-lane executor — codex + strong model (default) or a strong
Claude model via background instance (
-
Create
WORK.mdat the project root if it doesn't exist (format in Step 5 of the cycle —skills/batuta/SKILL.md).
The user can edit the profile at any time; to revisit the setup with help,
run /batuta:init again — that is the reconfigure mode below.
Reconfigure (.batuta/profile.md exists)
- Re-run the availability checks of every adapter the project's routing table references — never scan the machine (dormant adapters rule; a new CLI enters only when the user asks for it).
- Show the current setup in a few lines: lane mapping (executor + model per row, Research included), profile answers, and how stale the Project map looks.
- Ask what to change — one question: lane/model ("codex is installed now",
"swap the Research model"), profile answers (test command, methodology),
the batch execution mode (sequential ↔ parallel, the profile's Execution line),
the worktree mode or Install command (the profile's Worktree and Install
lines), the Runtime line (turn
compozyon or off — turning it on should also offer the discovery pointer of first-run step 3.5 when the project doesn't already have it, same as first run), the discovery pointer (add, rewrite or remove theAGENTS.mdblock of first-run step 3.5 — when the block exists but a marker is missing or mangled, say so and offer to rewrite it; never rewrite without consent), or a fresh map sweep (delegated to the scout, like first-run step 4). - Rewrite only what changed (
.batuta/routing.mdand/or.batuta/profile.md), reusing first-run step 6's discovery and single confirmation question for any lane/model change. When the discovery pointer was part of what changed, the write also covers theAGENTS.mdblock from first-run step 3.5, scoped strictly to what sits between itsbatuta:begin/batuta:endmarkers — never touch the rest of the file. Never touchWORK.md.