Zuvo Plugin — Project Guide

What this repo is

A Claude Code / Codex / Cursor / Antigravity / Kimi Code plugin. All skills are markdown files (SKILL.md). No TypeScript, no Python, no npm dependencies. package.json is metadata only (version field) — never run npm install.

Tech stack

Markdown. Shell scripts in scripts/. That's it.

How to update after making changes

For yourself (dev testing, no marketplace push)

./scripts/install.sh          # copies to Claude Code cache + Codex + Cursor + Antigravity + Kimi Code

Then restart Claude Code / Codex.

BUT — install.sh alone is NOT enough for Claude Code in all cases. Claude Code validates the plugin SHA from installed_plugins.json against the cache. If they don't match, skills may not load. To fully sync:

# Full local update (guaranteed to work):
./scripts/install.sh
claude plugin marketplace update zuvo-marketplace
claude plugin update zuvo@zuvo-marketplace
# Then restart Claude Code

One-command dev workflow (RECOMMENDED)

./scripts/dev-push.sh "description"

This does EVERYTHING in one command:

1. git add -A + commit with your message
2. git push origin main
3. Update marketplace SHA → push marketplace
4. Update installed_plugins.json SHA (fixes the stale SHA problem)
5. Copy files to Claude Code cache (all directories)
6. Build + install to Codex

After running: just restart Claude Code. No uninstall/install needed.

For end users (marketplace release)

./scripts/release.sh patch "description"

This does everything: version bump, commit, push, tag, marketplace SHA update. Users get it via claude plugin update zuvo.

Quick reference

Known gotcha: stale installPath after update (ROOT CAUSE — fixed 2026-05-31)

Claude Code loads hooks + skills from the installPath field in installed_plugins.json, NOT from gitCommitSha. The original dev-push.sh step 5 updated only gitCommitSha and left installPath/version frozen — so every "release" copied files into a new cache/.../zuvo/<new-version>/ dir while Claude Code kept loading the OLD <installPath> dir. Symptom: new hooks/skills never take effect no matter how many restarts (the 2026-05-31 watchdog saga — three releases, zero hook firings, because installPath was stuck at 1.3.107 while gitCommitSha advanced to 1.3.111's commit).

dev-push.sh now updates installPath + version + gitCommitSha together, so future releases are fixed. To check if it ever recurs:

python3 -c "import json; d=json.load(open('$HOME/.claude/plugins/installed_plugins.json')); [print(x['installPath'], x['version']) for n,e in d['plugins'].items() if 'zuvo' in n.lower() for x in e]"

installPath/version must match the latest cache/.../zuvo/<version>/ dir that holds your changes. If stale, re-run dev-push.sh or clean reinstall:

claude plugin uninstall zuvo@zuvo-marketplace && claude plugin install zuvo

Claude Code also creates multiple cache dirs (by version AND by SHA); install.sh syncs all of them, but installPath is the one that actually loads.

Codex gotcha: the app indexes skills at LAUNCH — restart AFTER install finishes (found 2026-07-18)

The Codex app snapshots ~/.codex/skills/ into memory when it starts (its marker: ~/.codex/skills/.system/.codex-system-skills.marker — the mtime is the LAST index time). Running install.sh while the app is open changes the files on disk but NOT what running/new sessions read. The 2026-07-17 failure: the app indexed at 20:58, the v1.6.10 install finished 21:09 — every session that evening (64 of them, 575 thread-spawns) ran on the pre-fix snapshot even though the user had "restarted Codex" (before the install completed). Rule: finish install.sh first, THEN restart the Codex app; verify uptake by checking the marker mtime is newer than the install, and that a fresh zuvo run explicitly reads the installed files and records their hashes against the built package. The removed single-agent banner is not an uptake check. Note: zuvo is NOT a codex [plugins.*] entry — Codex loads it via ~/.codex/skills/ (the legacy path install.sh writes).

Claude Code gotcha: a release can leave the plugin DISABLED and still report success (2026-08-12)

Same class as the Codex one above, different file. dev-push.sh Step 7 runs claude plugin enable and prints ✓ Plugin enabled — but a Claude Code that was running through the release owns ~/.claude/settings.json and can persist its own older view afterwards, undoing the CLI's write. Observed three times in one day: releases reported success, claude plugin list showed Status: ✘ disabled in BOTH scopes, and all 57 skills were invisible. Nothing detected it — the user did, by noticing the skills were gone.

First check on "skills are not visible" is claude plugin list, not the SHA/installPath dance above. The two look identical from the outside and have opposite fixes:

claude plugin list | grep -A3 zuvo          # Status: ✘ disabled  → enable it
claude plugin enable zuvo@zuvo-marketplace

A SessionStart hook now self-heals this: hooks/zuvo-plugin-enable-guard.sh (installed GLOBALLY to ~/.claude/hooks/, not plugin-scoped — a plugin hook does not run while its own plugin is off, which is the state it must fix). install.sh stamps ~/.zuvo/plugin-enable-state; the guard heals that one stamp once, so a clobber is repaired but a deliberate claude plugin disable sticks on the second try. Hard opt-out: touch ~/.zuvo/no-auto-enable. Decisions are logged with reasons to ~/.zuvo/plugin-enable-guard.log.

Two consequences worth knowing: the guard runs at session START, so it cannot undo a clobber inside an already-running session — it fixes it at the next start and asks for a restart. And a release whose push is BLOCKED by the pipeline-entry gate dies before tagging and before install.sh, so neither the tag nor the guard lands; the run still prints its earlier ✓ lines. Verify a release by its tag and claude plugin list, never by the absence of an error.

What install.sh does

Claude Code cache gotcha: Claude Code creates TWO cache directories — one named by version (1.0.0/) and one named by git SHA (564a269.../). It may load from EITHER. install.sh syncs to ALL directories. Never copy manually to just one.

Codex requires a BUILD step because it uses different paths (~/.codex/ not ../../shared/) and needs TOML agent registration files.

Kimi Code: the one non-Claude target that is NOT degraded

Kimi Code (verified against v0.34.0) is effectively a Claude Code superset for zuvo's purposes, so build-kimi-skills.sh deliberately does not apply the degradations the Cursor and Antigravity builds must:

• Sub-agents survive. Kimi's Agent tool takes prompt/description/subagent_type/ run_in_background; builtin types are agent, coder, explore, plan. zuvo's 48 agents install as custom profiles. Cursor/Antigravity rewrite spawn blocks to "Execute inline: …"; doing that here would silently turn every multi-agent audit into a single-agent one while still reporting success — tests/hooks/test-kimi-build.sh (2) exists to catch exactly that.
• AskUserQuestion and plan mode survive — Kimi has both.
• Agents are FLAT in ~/.kimi-code/agents/: Kimi resolves profiles by a byName map, so subdirectories load nothing and the two duplicate-name pairs (cq-auditor, spec-reviewer) would silently collide. Names are skill-prefixed, as in the Cursor build.
• model: becomes model_preference:, a closed enum — exactly primary or secondary, anything else is a hard parse error. opus/sonnet → primary, haiku → secondary.
• Hooks are TOML, a flat [[hooks]] array of event/matcher/command/timeout in config.toml — not the nested JSON shape. Kimi has every event zuvo uses including StopFailure, so the API-error rewake path works here (Cursor/Antigravity must drop it). install.sh rewrites a marker-delimited block and refuses to write a config.toml that would not parse — a corrupt one would break the CLI itself.
• AGENTS.md, not CLAUDE.md, is the project instruction file.
• Kimi's native plugin registry ($KIMI_CODE_HOME/plugins/installed.json) is deliberately not used — it is the same central-registry staleness trap as the installed_plugins.json gotcha above. Auto-discovery dirs have no registry to go stale.

Both ~/.kimi-code/skills/ and ~/.kimi-code/agents/ are SHARED user roots, so installs are provenance-keyed: skill dirs carry a .zuvo-owned marker and flat agents are tracked in a .zuvo-agents manifest. zuvo never deletes or overwrites what it did not install.

Cursor requires a BUILD step because it uses flat agent files in ~/.cursor/agents/ with Cursor v3 frontmatter (model: inherit, readonly: true/false) instead of Claude Code's tools: list.

How to release (for end users via marketplace)

./scripts/release.sh patch "description"
./scripts/release.sh minor "description"

This does: version bump → commit → push → tag → update marketplace SHA → push marketplace. Users get it via claude plugin update zuvo.

File structure

skills/<name>/SKILL.md          — skill definitions (58 total)
skills/<name>/agents/<name>.md  — sub-agent instructions (51 agent files, 49 unique names:
                                    cq-auditor and spec-reviewer each exist TWICE with DIFFERENT
                                    content — refactor/ vs review/, brainstorm/ vs execute/.
                                    Same name ≠ same file; never "sync" one onto the other.
                                    Derive both numbers; nothing gates them:
                                      find skills -path '*/agents/*.md' | wc -l
                                      find skills -path '*/agents/*.md' -exec basename {} .md \; | sort -u | wc -l
                                    The manifests' "26 specialized agents" is stale by ~2x and is
                                    tracked in memory/backlog.md, not fixed in passing)
shared/includes/*.md            — shared procedural includes (91 files):
                                    gate-registry.md (SSOT for all 124 CQ/Q/CAP/AP gates; E2E-Q by reference)
                                      E2E-Q is registered there, not defined: the authoritative table
                                      is skills/write-e2e/references/quality-gates.md, and the
                                      generator does not parse those rows
                                    knowledge-prime.md, knowledge-curate.md (knowledge store)
                                    session-state.md (session recovery)
                                    report-output-location.md (canonical zuvo/ output dir)
                                    severity-vocabulary.md (unified severity mapping)
                                    terminal-state.md (no completion over a live process / pending check)
                                    adversarial-loop.md, adversarial-loop-docs.md (evidence enforcement)
                                    drive-by-findings.md (backlog what a run noticed OUTSIDE its fence:
                                      SEC/BUG/SIZE/DUP/CPLX/PERF/DEAD/READ; receipt ~/.zuvo/log-drive-by)
                                    quality-gates.md, env-compat.md, codesift-setup.md, run-logger.md
                                    + registries, schemas, protocols
rules/*.md                      — code quality rules (20 files: cq-patterns, testing, security, file-limits, etc.)
scripts/install.sh              — local install to Claude + Codex + Cursor + Antigravity + Kimi
scripts/install.d/*.sh          — the installer's code, one module per target (output, copy, hooks,
                                  claude, zuvo-home, claude-home, codex, cursor, antigravity, kimi).
                                  install.sh keeps the guards, the dispatch and the summary, and sources
                                  these in a fixed order. Not runnable alone; shipped only beside the
                                  install.sh that install_claude copies into each Claude plugin cache dir.
                                  install.d/claude_settings.py is the ONE settings.json hook merge all four
                                  ~/.claude registrations use (ownership by resolved path + matcher, a lock
                                  in ~/.zuvo/locks, write-through for a symlinked settings.json).
                                  A test that reads the installer's TEXT must read it through
                                  tests/lib/installer-sources.sh — install.sh alone no longer holds it.
scripts/release.sh              — release to marketplace
scripts/build-codex-skills.sh   — build Codex distribution (called by install.sh)
scripts/build-cursor-skills.sh  — build Cursor v3 distribution (called by install.sh)
scripts/build-antigravity-skills.sh — build Antigravity distribution (called by install.sh)
scripts/build-kimi-skills.sh    — build Kimi Code distribution (called by install.sh)
scripts/lib/model-subprocess.sh — THE shared reviewer runner (zms_*): Codex host detection, isolated
                                  codex/claude runs (own CODEX_HOME, neutral cwd, empty MCP, timeout +
                                  process-group reap), auth-stub and CLI-version guards. Sourced by
                                  adversarial-review.sh, reviewer-model-route.sh and reviewer-preflight.sh
                                  (sibling lib/ → flat → ~/.zuvo, every consumed zms_* checked after
                                  sourcing); install.sh and every build ship scripts/lib/ beside each
                                  installed driver. Missing library = codex/claude lanes `no-runner`,
                                  router fail-closed sentinel — never a silent fallback.
scripts/lib/adversarial-*.sh    — the adversarial driver's twelve modules (cli, ledger, input, prompt,
                                  providers, lanes, lanes-http, dispatch, run, blind-audit, agreement, report).
                                  scripts/adversarial-review.sh keeps the bootstrap and Main, the phases
                                  in the order they run. The driver loads them all-or-nothing from ONE
                                  directory beside it (lib/ → flat; NO ~/.zuvo fallback) and exits 2 when
                                  it cannot. install.sh (install.d/copy.sh: install_adv_module_stamp) writes
                                  adversarial-modules.cksum beside every set it installs, last — the cksum of the driver and its modules, so an old
                                  driver never runs new modules; the driver skips a set that does not match its stamp
                                  (waiting ZUVO_ADV_MODULE_STAMP_WAIT s for an install still copying), so a
                                  set half old, half new never runs. A test that reads the driver's TEXT or copies the driver
                                  goes through tests/lib/adversarial-driver.sh — the driver file alone
                                  no longer holds the program, and an absence check against it passes
                                  vacuously.
scripts/zuvo-home/backlog-add   — THE single write path for a finding (→ ~/.zuvo/backlog-add): one call
                                  per finding, one lock; admission bars, dedupe over both backlog files
                                  and the findings ledger, then the backlog entry and/or the ledger
                                  record. Never append to memory/backlog.md by hand. Contract:
                                  shared/includes/backlog-protocol.md § "Persisting a finding".
                                  Its modules, all in scripts/zuvo-home/ (no shebang, no +x):
                                  zuvo_backlog_add.py (the command: lock, both writes, verdicts),
                                  zuvo_backlog_admit.py (bars, validation, identity; pure functions),
                                  zuvo_backlog_findings.py (ledger location, segments, append, fold),
                                  zuvo_backlog_vcs.py (work-tree anchor, default branch, [pr:N]/[branch:]
                                  tag, changed lines), zuvo_backlog_entry.py (the line it writes, the
                                  in-place bump), zuvo_backlog_lookup.py (fail-closed lookup over
                                  backlog-archive.py). End-to-end smoke: tests/hooks/test-backlog-add-e2e.sh.
memory/backlog.md               — open findings (memory/backlog-done.md: the archive). The intake tickets
                                  every open entry, so only backlog-add writes here.
memory/findings/                — the findings ledger beside the REAL backlog: append-only JSONL segments,
                                  one per day, branch and host (<date>_<branch-slug>_<host>.jsonl),
                                  folded on read. Every finding at conf ≥ 26 is kept here; not production
                                  files for the pipeline-entry gate.
tests/lib/                      — shared test helpers: dist-build.sh (per-run build cache; `--fresh`
                                  forces a real build), hermetic-tools.sh (links real tools onto a
                                  narrowed PATH), installer-sources.sh (the installer's text),
                                  install-manifest.sh (runs install.sh in sandbox HOMEs and prints a
                                  diffable manifest of everything it wrote — the before/after check
                                  for any installer refactor), adversarial-driver.sh (the driver as one program
                                  text, copies that take its modules along). Never named test-*.sh
                                  (run-all globs those).
hooks/*.sh                      — hooks install.sh copies into ~/.claude/hooks/ and registers in
                                  ~/.claude/settings.json. These are GLOBAL, not plugin-scoped —
                                  they keep running when the plugin is disabled, which is what makes
                                  zuvo-plugin-enable-guard.sh (SessionStart) able to fix exactly that
                                  state. Also: pipeline-entry gates, skill-usage-logger, retro sweep.
docs/                           — documentation (skills.md, pipeline.md, competitive-analysis.md, etc.)
docs/runbook/testing.md         — HOW TO VERIFY THIS REPO: the 5 commands, per-change checklist,
                                  the quarterly deep-audit procedure, failure triage
docs/runbook/model-benchmark.md — HOW A LANE'S MODEL/EFFORT IS CHOSEN: the ~/.zuvo/bench harness,
                                  marginal coverage as the deciding number, ±10 run-to-run noise,
                                  and the pitfalls (freeze the driver, strict MCP, subscription limit)
docs/runbook/operating.md       — commands that look right and are not, AND measurements that
                                  read like knowledge and are not. Read BEFORE typing a
                                  pkill/pgrep, a heredoc through ssh, or a `grep -c` guard; before
                                  REPORTING ANY COUNT from a log or transcript (§10 — the same
                                  read-the-wrong-field defect produced ten wrong numbers in one
                                  day, seven of which reached the user); also why `install.sh` can
                                  leave the plugin disabled for the NEXT session and why editing a
                                  running driver corrupts it
.claude-plugin/plugin.json      — Claude Code plugin manifest
.codex-plugin/plugin.json       — Codex plugin manifest
package.json                    — version metadata only (no npm)

Skill conventions

Every SKILL.md follows this structure:

1. YAML frontmatter: name (kebab-case), description (one paragraph)
2. H1 heading: # zuvo:<name>
3. Argument Parsing table
4. Mandatory File Loading checklist (shared includes via ../../shared/includes/)
5. Numbered phases (Phase 0, 1, 2...)
6. Named output block (e.g., SHIP COMPLETE)
7. Run log append via ../../shared/includes/run-logger.md

Reference: skills/build/SKILL.md is the canonical template.

The retro learning loop (how zuvo improves itself)

Runs write retros → weekly mining turns them into digests → digests carry change proposals → proposals get surfaced, implemented, and marked done. Full runbook, including every dead end this loop already produced and how each was closed: docs/retro-learning-loop.md. Read it before touching anything under scripts/zuvo-home/ or ~/.zuvo/.

The two rules worth repeating here:

• After implementing a proposal, disposition it in the same session — ~/.zuvo/digest-proposals --mark applied --file <F> --section <S> --ref <version>. Skip this and the item re-surfaces forever; that exact gap left 57 finished proposals looking open.
• Never edit ~/.zuvo/<helper> directly — ./scripts/install.sh overwrites it from scripts/zuvo-home/<helper> on the next run. Edit the repo copy, then install.

~/.zuvo/ data (retros, digests, the disposition ledger) is HOME-local and NOT in git. Before a machine migration: tar czf ~/zuvo-state-$(date +%F).tgz -C "$HOME" .zuvo.

Output location convention (where reports/state are written)

Single source of truth: shared/includes/report-output-location.md. All project-local zuvo output goes into ONE visible folder at the project root, never scattered into a scoped subfolder:

ZUVO_DIR="${ZUVO_OUTPUT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)/zuvo}"

• zuvo/audits/ — all *-audit reports (.md + .json), incl. seo/geo/content/a11y/design-review/architecture-review
• zuvo/reports/ — non-audit outputs: canary, content-migration, benchmark, agent-benchmark, retro, release-docs
• zuvo/plans/, zuvo/contracts/, zuvo/context/ — pipeline state (plan/build/execute/refactor/review)
• zuvo/project-profile.json — project profile (read by hooks/session-start)

Anchored to git root (not $PWD/scope), visible (not hidden .zuvo/, which is invisible in macOS Finder), overridable via $ZUVO_OUTPUT_DIR. Readers (~/.zuvo/append-runlog, hooks/pre-commit-adversarial-gate.sh, fix skills) check zuvo/ first, then fall back to the legacy audits/, audit-results/, and .zuvo/ locations for projects mid-migration.

Distinct and unaffected: ~/.zuvo/ (HOME — global runs.log, retros.*, helper binaries) and docs/ (human-authored README/ADR/runbook/spec docs). When adding a report-writing skill, load report-output-location.md and write under $ZUVO_DIR/{audits,reports}/.

Pipeline-entry enforcement (stop agents shipping past the gates)

Production-code work must go through zuvo:build/zuvo:execute so it gets reviewed. The enforcement is deterministic (see docs/pipeline.md → "Pipeline-entry enforcement" for the full layer table + honest limits):

• CI gate (ci/zuvo-pipeline-entry.yml + scripts/zuvo-pipeline-entry-ci.sh) — THE GUARANTEE, fail-closed, unbypassable server-side. Enable: cp ci/zuvo-pipeline-entry.yml .github/workflows/.
• pre-push gate — primary local block (canonical pushed range).
• global git-dispatch layer (hooks/git-dispatch/ → ~/.claude/hooks, global core.hooksPath) — runs the repo-local hook (no exec) then ALWAYS chains the pipeline-entry + work gates in EVERY repo, so freestyle-agent pushes are gated even where no local hook exists. Limits: repo-local core.hooksPath overrides (Husky) bypass it; uninstall: git config --global --unset core.hooksPath.
• commit-gate + Stop-gate nudges — best-effort early warnings (bypassable by design).
• hooks/lib/pipeline-gate-lib.sh — single-source detection (range-arg, content-keyed review coverage via memory/reviews/<base7>..<head7>-<slug>.md, fail-open).
• Threshold = the contract: ≥3 production files OR ≥150 changed lines, override with ZUVO_GATE_MIN_FILES / ZUVO_GATE_MIN_LINES.
• Escapes (logged): ZUVO_ALLOW_ADHOC=1 locally; the human-applied zuvo:adhoc-approved PR label in CI (an agent cannot self-apply it). Hooks/tests live in hooks/ + tests/hooks/.
• BLOCKED at push? Read the per-file reason first — docs/pipeline.md → "BLOCKED at push — triage before you choose". Coverage is content-keyed per file, never per commit range, so per-task reviews DO cover a big later push; when they do not, it is usually a files: header split on spaces instead of commas, a missing <!-- zuvo-review --> marker, or an artifact that travelled without its zuvo/proofs/ pair. All three are seconds to fix. Choosing between ZUVO_ALLOW_ADHOC=1 and a multi-hour re-review without running ~/.zuvo/pg-uncovered-files "<base>..<head>" + ~/.zuvo/review-artifact-sync.sh --check is a false dichotomy.

Skill categories (58 total)

Common tasks

Adding a skill — the full checklist

validate-skills.sh catches most of this, but two test suites carry the count independently and only fail at release time. Every one of these bit on the 56th skill:

1. skills/<name>/SKILL.md — frontmatter, # zuvo:<name>, Argument Parsing, Mandatory File Loading, phases, named completion block, run-log append (template: skills/build/SKILL.md).
2. skills/using-zuvo/SKILL.md — a routing row and the | N skills | banner.
3. .claude-plugin/plugin.json, .codex-plugin/plugin.json (two strings), package.json — the "N skills and M agents" description.
4. docs/skills.md — the per-skill table row, the category-count table, and the **Total** row.
5. CLAUDE.md — "skill definitions (N total)", "## Skill categories (N total)", category table.
6. README.md — the "N skills, …" intro line (sat stale at 55 until 2026-08-01; now covered by count-consistency).
7. ./scripts/install.sh — builds all four targets; the Codex build fails on Claude-Code tool names (run_in_background, Task, …) that validate-skills.sh does not check.
8. bash scripts/validate-skills.sh → count-consistency: OK (N), then bash tests/run-all.sh — the release script runs it and will block on a stale count.

Counts in tests are now derived from skills/ rather than hardcoded, so (7) should stay green on its own; keep it that way if you touch those assertions.