Viterbi is a lightweight meta-harness for agentic engineering — not an application, but the operating contract an agent follows to plan, execute, validate, adversarially review, and remember work across context limits and compaction. It runs on Thin Harness, Fat Skills: the harness only routes, records, validates, and protects, while reusable expert judgment lives in repo-local skills. Mission state is JSON-authoritative — the durable memory of record lives in .missions/, never in the chat context — so work survives compaction and resumes cleanly.

Install with your AI agent

Give this self-contained prompt to your coding agent in the target repo. It can use INSTALL.md when reachable, but does not depend on the repository being public:

If you can reach https://raw.githubusercontent.com/Dario-Arcos/Viterbi/stable/INSTALL.md, read and follow it; if not, follow the instructions below.
Work from the Git top-level. Before installing, run git rev-parse --show-toplevel, git rev-parse --verify HEAD, command -v node, command -v npx, and npx --yes viterbi@latest --version. Stop and report the exact command, exit code, and stderr if any prerequisite fails; never commit my work or create harness files by hand.
Interview me before running init: (1) committed or local .missions state, mapping to --state committed|local; (2) whether to add the GitHub CI gate, mapping yes to --ci github; (3) whether to activate the pre-commit gate, mapping yes to --hooks; and (4) whether to configure global runtime awareness and, if yes, exactly which installed runtimes from claude,codex,gemini,opencode to pass to --runtimes. One runtime is enough; do not assume I have another.
If local state is rejected because .missions is already tracked, report the CLI guidance and stop; do not untrack files without asking me.
If I have no preference, use project-only, --state committed, no CI, no hooks, and no global runtime writes.
Run npx --yes viterbi@latest init --scope project --root "$(git rev-parse --show-toplevel)" with the selected --state and only the integration flags I approved. If I approved global awareness, after the project install succeeds run npx --yes viterbi@latest init --scope global --runtimes <only-the-selected-runtime-keys>.
Existing AGENTS.md and CLAUDE.md are user-owned: preserve everything outside Viterbi's marker section. Never resolve a collision in an unattended run by adding --force or --adopt.
Run node .rules/validators/validate-harness.mjs and require HARNESS_VALIDATION_OK. If an existing install is drifted, run npx --yes viterbi@latest doctor --root "$(git rev-parse --show-toplevel)" and report its named files and repair actions; otherwise stop on failure and report the exact command, exit code, and stderr.
After success, read the installed AGENTS.md, tell me which state/integration/runtime choices were applied, and explain how to operate the repo from here.

The plugin is optional. npx --yes viterbi@latest init is the complete install path, and a user needs only the runtime they actually use.

Manual install

The agent interview above is the primary path. For a manual install using the conservative defaults:

npx --yes viterbi@latest init --scope project --state committed

This writes only the project scaffold. CI (--ci github), hook activation (--hooks), local-only mission state (--state local), and global runtime awareness (--scope global --runtimes <selected>) are explicit choices.

Validate

One command is the single source of truth for "is the repo valid" — it is the build, lint, and test in one:

node .rules/validators/validate-harness.mjs

It prints HARNESS_VALIDATION_OK, or HARNESS_VALIDATION_FAILED with FAIL lines. The same validator runs in GitHub CI only when --ci github installs (.github/workflows/validate-harness.yml). The project pre-commit hook is activated only when the user selects --hooks:

git config --local --get core.hooksPath

Architecture

Four cross-referenced pillars, all registered in .rules/manifest.json (the registry the validator walks):

• .rules/ — the soft harness: numbered rules (00–90) read selectively per task, plus JSON schemas, canonical templates, and the validator engine.
• .missions/ — durable project memory: index.json (registry), active.json (current mission), per-mission contracts (mission.json, tasks.json, loops, reviews, evidence, events.jsonl), and the cross-mission learning ledger lessons.jsonl.
• .agents/skills/ — the fat layer: git-tracked, runtime-neutral skills dispatched through RESOLVER.md (Claude Code loads them via a .claude/skills symlink onto the same source).
• .rules/validators/ — validate-harness.mjs and its kernels, which make the "is it valid" rules executable: evidence gates, loop stage gates, mission closure, and cross-file consistency.

Start with AGENTS.md for the runtime-agnostic operating contract and CLAUDE.md for Claude Code mechanics and the repo architecture in depth.

How it works, from zero

docs/como-funciona.html is the step-by-step explainer (Spanish, self-contained, brand-styled): the Loop Engine's consequence ladder with one real use case per rung, how the Sonar is operated command by command, its first real run as a case study, and the honest story of what the evals do and do not prove. Open it directly in a browser.

The product site

viterbi-landing/ holds the Viterbi landing page (a self-contained WebGL + GSAP site) and its brand assets — logo.svg, logo.png, and the og.png social card. It is a separate product artifact, out of scope for harness work unless a mission explicitly includes it.