Quick Start & Installation

Install the skill package into every agent harness the installer detects on your machine, with one command:

git clone https://github.com/belajarcarabelajar/vivera.git
cd vivera
./install.sh

A plain ./install.sh runs the standard tier (see Prerequisites) and does this:

Look before you install, and check afterwards:

./install.sh --dry-run   # prints what it would do, writes nothing
./install.sh --check     # reports whether the install is current, changes nothing
./install.sh -h          # lists every flag

--check prints check: CURRENT and exits 0 when every selected target is in order, exits 1 when it found a problem, and exits 2 when no selected target has skills and no sprite directory can be checked (for example --only codex with --tier minimal, or on a machine without bun; with bun present, --only codex checks the sprite directory and exits 1 if it is missing). A machine with nothing installed exits 1. A bad flag, an unknown target id or an unset HOME exits 2.

Install channels

The git clone is the one route that was run end to end. The others exist in the repository, and the Status column says how far each one was tested. "Verified" means run on Linux x86_64 (Arch Linux, Bun 1.4.2) on 2026-10-11 in a throwaway home, with the exit code checked.

What the bootstrap checksum proves: it is served from the same release origin as the archive, so it detects a corrupted download or a swapped archive. It does not detect a compromised release, because whoever can replace the archive can replace the checksum.

Why the marketplace is parked. A spike on 2026-10-11 ran claude plugin validate, marketplace add, install and details on an isolated home. The packaging works: validation passed and 8 skills were listed. It was parked for three reasons:

• The master skill loads its phase skills by bare name (sucp-rules, sucp-plan) and stops if one cannot be loaded. The docs show plugin skills with the plugin name as a prefix (/vivera:sucp-rules). Whether the model's Skill tool accepts the bare name is not documented, and no live session was run, so it is unverified.
• The fallback path ~/vivera/skills/<name>/SKILL.md does not exist on a machine that has only the plugin.
• A plugin rooted at the repository installs about 498 MB of dependencies into the cache, against 720 KB for a skills-only copy.

It becomes a build if one live session on an isolated home shows the bare name loading, or if the owner teaches the master skill both names.

Why the Antigravity plugin waits. agy plugin validate accepted a copy of the skills (8 processed), but nothing was installed. Where a CLI install lands, whether staging keeps the symlinks of the skill package, and how an update works were not measured. A plugin would add a channel and would not replace the links into the Antigravity skills directories.

Prerequisites

Choose a tier with --tier minimal|standard|full (default standard). The tool list is scripts/install/tiers.tsv, which install.sh and scripts/validate-skill.mjs both read, so the installer and the validator cannot disagree about a tier.

The tools, from scripts/install/tiers.tsv:

• A required tool that is missing exits 1. That is git and bun at standard, plus gh and tgrep at full.
• An optional tool that is missing warns. At standard and full, a tool the chosen tier does not require prints one warning that names what is lost, and the run goes on. The installer finds a tool on PATH, then in ~/.local/bin, then in ~/.bun/bin.
• --check and --uninstall ask for no tool, at any tier. The sprite agent directories are checked and removed only when bun is present: without it --check skips them and --uninstall keeps the files and says to delete the marked ones by hand.
• Bun >= 1.1.0 (bun.sh) is the runtime for this repository's scripts and tests, and package.json pins bun@1.4.2. All dependency installation uses bun install / bun add, and all JS/TS execution uses bun test / bun run. npm install, npm test, yarn, and pnpm are strictly prohibited. Install it with curl -fsSL https://bun.sh/install | bash. ./install.sh itself needs no bun install first: a tree with no node_modules installed and rendered the sprites.
• Node.js is not needed to install, or to run the Bun scripts. It is needed to render Mermaid diagrams (scripts/render-diagrams.sh and the Mermaid part of scripts/validate-skill.mjs): mmdc from @mermaid-js/mermaid-cli starts with #!/usr/bin/env node, and package.json asks for Node >= 22.13.0. The only lockfile is bun.lock.
• ripgrep (rg) & tgrep: Primary code search uses rg (v15.2+ direct binary with smart-case). tgrep (microsoft/tgrep) is used for trigram-indexed search in indexed repositories and shell pipe filtering. Raw GNU grep is strictly prohibited. tgrep is required only at tier full: at standard install.sh prints one warning when it is missing (none at minimal) and the skill's search rule (skills/sucp-rules/SKILL.md) accepts rg or tgrep, so rg alone satisfies it.

Platform matrix

"Verified" is the same definition as in Install channels: run on Linux x86_64 (Arch Linux, Bun 1.4.2) in a throwaway home, exit code checked. Anything else is "not verified".

• macOS: the bootstrap script says it runs on bash 3.2, but the installer was never run on bash 3.2 or on BSD tools.
• "Not verified" means untested, not known to fail.
• A HOME that is read-only makes install exit 1 and write nothing (verified on Linux).

Supported Harnesses & Target Paths

The installer has 10 targets, listed here in install order. The first two are always installed. Every other target is installed only when its harness is detected, or when you name it with --only.

Every skills directory above except ~/.config/ai holds super-ultra-code-plan/ (SKILL.md, templates/, examples/ and the two Mermaid configs) next to the seven phase skills, sucp-<name>/SKILL.md. Runs on Linux in a throwaway home checked the directory-based and the CLI-based detection and the skills and sprite paths of all 10 targets, using stub CLIs for detection.

Gemini CLI (gemini) is not a target. Google stopped serving it to free, AI Pro and Ultra accounts on 2026-06-18 and replaced it with Antigravity CLI (agy), which the antigravity-cli target covers (https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/). It remains available under a Code Assist Standard or Enterprise licence or with a paid API key; those users can link the skill package into ~/.gemini/skills/ themselves. An earlier revision of this installer had a gemini-cli target; --only gemini-cli now exits 2 as an unknown target.

• Detected, not installed. A target that is absent after a successful ./install.sh means its harness was not detected, not that the install failed. The installer does not create an empty config tree for a harness you do not have. ./install.sh --dry-run lists the targets your machine qualifies for. A bare home gets only ~/.config/ai and ~/.agents/skills.
• Naming a target. --only ID,ID installs exactly those ids, detected or not, and does not add the two always-installed targets (--only claude installs claude and nothing else). --skip ID,ID removes ids and wins over --only. Both flags can repeat and accumulate, and an unknown id exits 2. Older versions of the installer created the OpenCode and Antigravity targets even when the harness was absent; --only opencode,antigravity,antigravity-cli,antigravity-builtin brings that back.
• Two Antigravity skills directories. The antigravity target (~/.gemini/config/skills) is where Antigravity 2.0 and the IDE read skills, and the CLI reads ~/.gemini/antigravity-cli/skills (the antigravity-cli target), according to the Antigravity docs read for the agy plugin research. Neither path was confirmed by loading a skill.
• Codex, Cursor and Copilot have no skills target. The installer takes their skills to come from ~/.agents/skills, which was not checked against those three harnesses. They get sprite agents only.
• Sprite agents are rendered, and only OpenCode is confirmed to list them (no harness was run with a model prompt). Six harnesses get them (Claude Code, OpenCode, Codex, Cursor, Copilot and the antigravity target). antigravity-cli and antigravity-builtin get none, and tier minimal renders none. OpenCode v2.0.24 listed all seven sprites in opencode debug agents. Antigravity 1.3.3 was not confirmed: agy agents lists only agents written with mainAgent: true, and the sprites are written with mainAgent: false. Claude Code 2.1.296 has no non-interactive lister of subagent definitions (claude agents --json lists background sessions and printed [] with the sprites installed), and Codex, Cursor and Copilot were never run.

Flags

./install.sh -h prints this list. The source of truth for the targets is the table above, and for the tiers scripts/install/tiers.tsv.

A plain install says which harnesses it left out, with [INFO] not detected, skipped: <ids> (name one with --only to install anyway). For codex, cursor and copilot it says [INFO] <id>: no skills target of its own (its skills come from ~/.agents/skills); installing its sprite agents only. Tier minimal, --check and --uninstall print no warnings about optional tools.

Backup, restore, update, check and uninstall

Before it places anything, the installer judges each destination from what is on disk. No state file exists, so an install made by an older version, or by hand, is judged by the same rules.

--check verdicts:

Uninstall, per destination:

The closing line is ==> Vivera uninstalled: N link(s) removed, R restored, K kept, and it says link(s) or copy/copies when copies were removed. A restored link dangles if the checkout it pointed at was deleted in the meantime.

Copy mode

--copy copies the files instead of linking them, so an install keeps working when the checkout moves or goes away. The cost is that a copy does not follow the checkout: run ./install.sh --update --copy after you pull.

Every managed copy is judged against the source and against its recorded digest:

Other rules:

• Git Bash, MSYS and Cygwin default to --copy. There ln -s copies the file or fails unless symlinks are switched on, so a plain install would report links it did not make. The installer prints a [NOTE] and copies. This was seen only with a stub uname, not on Windows (not verified).
• .gitattributes forces LF for *.sh and scripts/install/tiers.tsv, because a Windows clone with core.autocrlf would turn every installer script into CRLF, and a carriage return after set -euo pipefail is not a valid bash command.
• A copy install must be checked with --check --copy. Without --copy, --check expects links, calls the copies [stale] and prints [hint] those are copies made by --copy: run ./install.sh --check --copy.
• install.ps1 always copies and follows the same identical, pristine and modified rule, with its own digests (ps-sha256 entries in the marker): a digest recorded by install.sh (sha256:) is never trusted, so such a copy counts as modified. One difference: behind a linked directory it leaves ANY link alone, including the installer's own, where install.sh in link mode still repoints its own links (install.sh --copy, the mode install.ps1 corresponds to, leaves them alone too). It was run under PowerShell 7.6.6 on Linux only, not on Windows.

Offline mode and the minimal tier

Known limits

The Harvest Sprites

The seven Harvest Sprites at work. Official Back to Nature artwork © its owners.

This section follows the PlayStation game Harvest Moon: Back to Nature (Victor Interactive Software, Japan 16 December 1999, English release by Natsume on 22 November 2000), not Friends of Mineral Town, whose sprites work differently (see the glossary). In it the seven Harvest Sprites (コロボックル, Korobokkuru) live in a small hut behind the Church. Talk to one twice to ask for help once it has at least 2 hearts of affection, then hire it for 1 day, 3 days, or a week, starting the next day, to water crops, harvest crops, or take care of animals. In Spring they only talk about their Tea Party, and you must talk to the same sprite five times to get any work out of it. They look identical except for the color of their hat and shirt, and the seven colors together span the rainbow. In Vivera each sprite is a named subagent: the name and the color stay, but a sprite gets a fixed role in agents/crew.json instead of a free choice of job.

Sprite	In the game (PlayStation)	Role in Vivera	Default affinity	What it does
Chef	Red. Birthday Fall 14. Loves to cook. In the fourth year he is found afraid of the dark, carrying a lantern.	implementer	harvesting	Implements one chunk of an approved plan, test first, inside the permitted files.
Nappy	Orange. Birthday Winter 22. The brothers live together in his house.	implementer	animal care	Same role as Chef, on a different chunk.
Hoggy	Yellow. Birthday Fall 10. Loves to sleep and is lazy about work.	implementer	harvesting	Same role as Chef, on a different chunk.
Timid	Green. Birthday Summer 16. Easily scared.	researcher	animal care	Investigates one narrow question about the code, the history, or the web, and edits no files.
Aqua	Light blue. Birthday Spring 26. Likes to dress nicely.	researcher	watering	Same role as Timid, on a different question.
Staid	Dark blue (sources also say blue or indigo). Birthday Spring 15.	reviewer	animal care	Audits a diff, a subagent report, or a completion claim against fresh evidence, and edits no files.
Bold	Purple. Birthday Spring 4. Brave, and scares others off with a battle cry.	debugger	watering	Isolates the root cause of one failing test or reproducible bug by hypothesis and probe, then fixes it at the shared cause.

Four things are worth knowing:

• The game tracks two numbers per sprite. Affection rises one heart per 25 points and drops by 2 for every day the sprite works for you. A hidden skill level per job starts at 0, rises by 1 each time it does that job, and tops out at 255.
• Need matters, weather does not. You cannot hire a sprite for a job that has nothing to do that day, but a hired sprite still comes in a hurricane or blizzard, which makes it useful for feeding animals during storms.
• Jobs are a default, not a rule. In the game any sprite can do any of the three jobs, one per request. In Vivera the role is fixed by the roster, while the affinity column is only the default for fan-out (watering is keep-alive work, animal care is long-lived assets, harvesting is shipping). The parent may send any sprite to any chunk. See The Vivera Glossary.
• Agent colors differ for two sprites. agents/crew.json gives Aqua blue and Staid cyan, while the game has Aqua light blue and Staid dark blue.

The sprite portraits in the table are Harvest Moon artwork from the Harvest Moon Wiki, © their respective owners. Game facts and their sources are listed in the glossary. Vivera is an independent project and is not affiliated with the Harvest Moon franchise.

Claude Code agents

The subagents are the seven Harvest Sprites. Claude Code labels a running subagent with its agent name, so a wave of parallel chunks sent to one shared role agent shows one name over and over. Each sprite is a named, colored copy of one of four role templates in agents/roles/, and agents/crew.json assigns the sprites to roles. Each role preloads the phase skill it works under, so a delegated chunk starts with the rules of its phase instead of discovering them.

bun run agents:gen renders the sprites into .claude/agents/; edit a template or the roster, never the generated files, which carry a # Generated by line in their frontmatter. bun run agents:check fails when they drift. ./install.sh renders the same crew into ~/.claude/agents/ when Claude Code is detected (~/.claude exists) or named with --only claude, and into five other harnesses in their own formats (see Sprite agents on six harnesses below). The sprites then exist in every project, with the hook path pinned to this repository because $CLAUDE_PROJECT_DIR in another project has no guard script. It writes and removes only files that carry the marker. Staid's color varies between sources (see docs/vivera-glossary.md), and Claude Code has no indigo, so cyan is a stand-in. Claude Code draws the agent name on its color with no padding, so each name: is the sprite wrapped in a no-break space (U+00A0), unquoted, which YAML keeps and plain spaces would lose. The label then reads chef instead of chef, and a call with plain chef still resolves.

Every role carries a frontmatter PreToolUse hook, .claude/hooks/block-git-writes.mjs, that exits 2 on the git subcommands that write state (commit, add, push, checkout, switch, merge, rebase, reset, and more), on the writing forms of mixed commands such as stash, branch, tag, remote and config, and on any gh call, including inside a && b chains. Read forms such as git stash list and git branch --show-current pass. It enforces the parent-only git rule from the subagent contract. The hook looks at the command word of each segment, matches git and gh by basename, and reads one level into sh -c strings, so /usr/bin/git commit and sh -c "git commit" are blocked. An alias, a command substitution that is not the value of an assignment (x=$(git commit) is blocked), a nested -c, eval, or script text piped into a shell still get past it: it is a second line behind the contract text, not the only one. It also does not stop a Bash call from writing ordinary files, so the "does not edit files" rule of the researcher and the reviewer is a contract, not an enforced limit.

Things that are easy to get wrong:

• There is no CLAUDE.md on purpose. Claude Code reads AGENTS.md itself only when no CLAUDE.md exists in the working directory or any directory above it. Adding one here would stop AGENTS.md from loading unless the new file imports it.
• The skills: names resolve from the skills Claude Code has installed, not from this repository's skills/ folder. Run ./install.sh first, or the preload is skipped with only a debug-log warning.
• Frontmatter hooks of project agents run only after the workspace trust dialog is accepted for this folder. Before that the agent still runs, without the guard.
• Claude Code ignores an unknown frontmatter field without any message, so maxTurn: instead of maxTurns: does nothing. bun run agents:check (also part of bun run ci) rejects it, and rejects a hook whose script path under $CLAUDE_PROJECT_DIR does not exist, since a typo there turns the guard off without any message. The allowed field list is pinned to the Claude Code documentation of 2026-10-10.

OpenCode agents

When OpenCode is detected or named with --only opencode, ./install.sh renders the crew into ~/.config/opencode/agents/ with gen-sprite-agents.mjs --target opencode, so OpenCode launches the same seven names instead of its built-in general. The format differs, and the differences were measured on OpenCode v2.0.24:

• OpenCode skips a Claude Code agent file without any message. A color name (color: red) or the legacy tools: field drops the whole agent, so the Claude Code files cannot be linked across. The OpenCode files use a hex color, mode: subagent, and steps in place of maxTurns.
• OpenCode ignores skills: and hooks:. The body starts with a line telling the agent to load its phase skill, and the git guard becomes shell permissions: every git and gh command is denied, then common read forms (git status, git diff, git log, git show, and more) are allowed again. The last matching rule wins and each command of an a && b chain is matched on its own. git -C is blocked, so the agent runs cd <dir> && git ... instead.
• The rtk plugin rewrites git x to rtk git x before the match, so every rule has an rtk form. Without it, a git commit* rule blocked nothing on this machine.
• Like the hook, the rules miss sh -c strings and aliases. The researcher and reviewer get edit: deny, so in OpenCode they cannot use the edit tools, but the shell can still write files.

Nothing of OpenCode's is committed: the files are rendered from the same templates at install time. The same holds for every harness below except Claude Code's own .claude/agents/ in this repository.

Sprite agents on six harnesses

scripts/gen-sprite-agents.mjs renders the seven Harvest Sprites for six harnesses, from the four role templates in agents/roles/ and the roster in agents/crew.json. Each harness is one file in scripts/sprite-agents/targets/. ./install.sh renders them for each harness that is detected or named with --only, and tier minimal renders none because the generator needs bun. antigravity-cli and antigravity-builtin get none.

• The read-only roles are timid, aqua and staid. chef, nappy, hoggy and bold have no tools key in their templates. They inherit the parent's tools on Claude Code, and get no edit rule on OpenCode, no sandbox_mode on Codex, no readonly on Cursor, and no tools line on Copilot and Antigravity.
• Read-only is a tool list or a flag, not a guarantee. Claude Code, OpenCode, Copilot and Antigravity keep a shell, so a shell command can still write a file. The Cursor and Codex flags were not tested.
• No hook means a prose guard. On Codex, Cursor, Copilot and Antigravity the file carries the comment # guard: instruction only, not enforced by this harness (in the frontmatter for Cursor, Copilot and Antigravity, at the top of the TOML file for Codex), and its body tells the sprite to leave git to the parent session. Nothing stops a sprite from breaking that rule.
• What an omitted tools key means is unverified. The Antigravity page documents an empty list as the default, so the four writer sprites may start with no tools there, and Copilot is taken to read a missing tools key as all tools. Neither was run.
• A YAML comment inside the frontmatter carries the # Generated by marker and the guard label. Bun's YAML parser accepted it in every rendered Markdown file, and agy accepted a # comment in the frontmatter of its control agent. Cursor and Copilot were not run, so it is unverified there.
• Turn limit and phase skill. maxTurns becomes steps on OpenCode and is dropped on the other four, whose pages list no such key. Claude Code preloads the phase skill from skills:; elsewhere the first line of the body tells the sprite to load it.
• The key names and directories of Codex, Cursor, Copilot and Antigravity come from the vendors' documentation pages read on 2026-10-11, and each of those target files names its page and date in a comment at the top. Claude Code's come from its docs of 2026-10-10, and OpenCode's from measurement on v2.0.24.

To render, check or remove one harness by hand:

bun scripts/gen-sprite-agents.mjs --target <id> --out <dir>           # render
bun scripts/gen-sprite-agents.mjs --target <id> --out <dir> --check   # exit 1 when the files differ
bun scripts/gen-sprite-agents.mjs --target <id> --out <dir> --clean   # remove the marked files

<id> is claude, opencode, codex, cursor, copilot or antigravity. Only claude has a default directory (this repository's .claude/agents); the others need --out, and --clean always needs --out. --hook-root is for claude only. The generator writes and removes only files that carry the # Generated by scripts/gen-sprite-agents.mjs line, and it refuses a hand-written file that has a sprite's name.