sprite-model-router · Claude Code mod

README

Vivera: Ultimate All-in-One AI Coding Agent Pipeline

<img alt="Vivera, the project's mascot: a smiling short-haired girl in a blue cyberpunk maid outfit with a holographic apron, holding a glowing clipboard tablet in a rainy neon city street." src="docs/images/vivera.jpg" width="100%"> Vivera, a fictional name inspired by Elli from Harvest Moon: Back to Nature.

A skill pipeline that guides AI coding agents through the whole software engineering lifecycle: Idea -> Design -> Plan -> Human Approval Gate -> TDD -> Systematic Debugging -> Subagent Orchestration -> Verification -> Finishing -> Session-Close Debt Sweep.

Four gated components. Brainstorming → Writing Plans → TDD → Verification, with a human approval gate between each one, plus a Deep Research path that runs only when a decision depends on information the codebase does not contain. The sub-agent pipeline that carries out the work is mandatory, not a recommendation.
One source of truth. Super Ultra Code Plan Implementation.md keeps contextual invariants, safety constraints, and human-approval gates in view for the whole run.
Verification is the last gate, not the last step. Once the plan is Done 100% and the evidence is green, the agent harvests every noticed-but-unclosed item from the session, ranks 3-5 follow-ups that can be finished right now, and asks them as multi-select checkboxes in the harness's own prompt widget. The session ends with zero unexamined coding debt.

Install

git clone https://github.com/belajarcarabelajar/vivera.git
cd vivera
./install.sh           # installs into every agent harness it detects
./install.sh --check   # prints check: CURRENT and exits 0 when the install is in order

Run ./install.sh --dry-run first to see what it would do without writing anything. Tiers, flags, and the other install channels are in Quick Start & Installation.

The Harvest Sprites

Vivera is a fictional name inspired by Elli, one of the characters in Harvest Moon: Back to Nature. The vocabulary around the pipeline borrows from the same game: skills are crops, pull requests are Blue Feather proposals, subagents are the seven Harvest Sprites (watering is keep-alive, animal care is long-lived assets, harvesting is shipping), and the PR registry is the shipping bin. The flavor is cosmetic; every command, path, and behavior in this document is literal. See The Vivera Glossary.

<table align="center"> <tr> <td align="center"><a href="docs/guide/reference-harvest-sprites.md"><img src="docs/images/sprites/chef.png" alt="Chef, the red Harvest Sprite" width="72"></a> Chef</td> <td align="center"><a href="docs/guide/reference-harvest-sprites.md"><img src="docs/images/sprites/nappy.png" alt="Nappy, the orange Harvest Sprite" width="72"></a> Nappy</td> <td align="center"><a href="docs/guide/reference-harvest-sprites.md"><img src="docs/images/sprites/hoggy.png" alt="Hoggy, the yellow Harvest Sprite" width="72"></a> Hoggy</td> <td align="center"><a href="docs/guide/reference-harvest-sprites.md"><img src="docs/images/sprites/timid.png" alt="Timid, the green Harvest Sprite" width="72"></a> Timid</td> <td align="center"><a href="docs/guide/reference-harvest-sprites.md"><img src="docs/images/sprites/aqua.png" alt="Aqua, the light blue Harvest Sprite" width="72"></a> Aqua</td> <td align="center"><a href="docs/guide/reference-harvest-sprites.md"><img src="docs/images/sprites/staid.png" alt="Staid, the dark blue Harvest Sprite" width="72"></a> Staid</td> <td align="center"><a href="docs/guide/reference-harvest-sprites.md"><img src="docs/images/sprites/bold.png" alt="Bold, the purple Harvest Sprite" width="72"></a> Bold</td> </tr> </table>

Each sprite is a named subagent with one fixed role: Chef, Nappy, and Hoggy implement, Timid and Aqua research, Staid reviews, and Bold debugs. The Harvest Sprites has their portraits, game traits, and roles.

This documentation is also published at vivera.belajarcarabelajar.com/docs, and team workshops have their own page at vivera.belajarcarabelajar.com/workshop.

Guide

The rest of the documentation lives in docs/guide/ and in docs/, one file per docs site page, in site order. A page too long for one file is split at its subsections into numbered parts.

Source 1 files

hooks/register.ts 36 lines

1import type { Register } from 'claude-code'
2
3// Mirror of agents/crew.json; vivera's scripts/sprite-model-router.test.mjs fails when they drift.
4export const ROSTER: Record<string, string> = {
5  chef: 'implementer',
6  nappy: 'implementer',
7  hoggy: 'implementer',
8  timid: 'researcher',
9  aqua: 'researcher',
10  staid: 'reviewer',
11  bold: 'debugger',
12}
13
14// Roles that never edit files, so a wrong answer costs a re-check, not a broken tree.
15export const READ_ONLY_ROLES = new Set(['researcher', 'reviewer'])
16
17// Only ever routes down: a parent already on Sonnet or Haiku keeps its model.
18const EXPENSIVE_PARENT = /opus|fable/i
19
20export const register: Register = (on, options) => {
21  const target = String(options.readOnlyModel ?? 'sonnet')
22
23  on('agent.spawn', async ($, e, next) => {
24    if (target === 'off') return next(e)
25    // An explicit model from the caller, a fork, a resumed run, a workflow
26    // agent or a teammate is someone else's decision.
27    if (e.model || e.fork || e.resume || e.workflow || e.isTeammate) return next(e)
28    const sprite = e.subagentType.trim()
29    const role = ROSTER[sprite]
30    if (!role || !READ_ONLY_ROLES.has(role)) return next(e)
31    if (!EXPENSIVE_PARENT.test(e.parentModel)) return next(e)
32    $.ui.log(`${sprite} (${role}) → ${target}, parent ${e.parentModel}`)
33    return next({ ...e, model: target })
34  })
35}
36