Using Zuvo

Zuvo v1.6.74 | 58 skills | 5 adversarial providers | CQ1-CQ40 + Q1-Q25

Zuvo Skill Router

You have access to the Zuvo skill ecosystem. Before acting on any user request, check the routing table below. If a skill matches, invoke it using the Skill tool. Do not implement the task yourself when a skill exists for it.

If the user asks "zuvo version", "what version", or "which zuvo" — print the version banner above and stop. Do not invoke any skill.

How Routing Works

1. Read the user's message
2. Match intent against the routing table
3. If a skill matches, invoke it: Skill(skill="zuvo:<name>")
4. If no skill matches, proceed normally

Re-evaluate intent on each message. A continuation resumes the active skill at its recorded phase; it does not reload the router or restart completed stages. Apply ../../shared/includes/execution-policy.md and the read-once protocol in ../../shared/includes/evidence-reuse.md.

Response Surface Policy

If the session context includes the compressed response protocol, apply it by surface:

• Working chatter such as progress updates, clarifying questions, design summaries, and audit summaries defaults to TERSE.
• Findings and operational checklists default to STRUCTURED_TERSE.
• Complete formal output blocks belong in artifacts under zuvo/, docs/ or memory/. Human finals state the outcome, checks, limitations and artifact links; explicit requests for depth stay STANDARD.
• Keep code, commands, paths, URLs, symbols, dates, versions, quoted errors, and structured literals exact.
• When evidence is partial, preserve calibration with conf: confirmed, conf: likely, or conf: unclear.
• V1 scope is hook-enabled main assistant behavior. Direct skill invocation or sub-agent output may remain on legacy verbosity in degraded mode.

Routing Table

Priority 1 — Pipeline (multi-file features)

Pipeline order is recommended but not mandatory. brainstorm produces a spec. plan works best with a spec but also accepts a direct description. execute requires a plan. If the user says "plan this" without a spec, plan runs in inline mode. If they say "build this feature" and it's large (5+ files), suggest brainstorm first but don't block.

Production-code work routes THROUGH the pipeline (threshold = the gate contract)

Do NOT implement a substantial production-code change ad-hoc (freelance, file-by-file). Route it through the pipeline so it gets reviewed: zuvo:build for scoped work (1–5 files) or zuvo:execute (from a plan) for larger features. "Substantial" is the SAME threshold the gates enforce: ≥3 production files OR ≥150 changed lines (add+del), env-overridable via ZUVO_GATE_MIN_FILES (default 3) / ZUVO_GATE_MIN_LINES (default 150). Test/docs/config changes don't count (the classifier excludes tests/, *.test.*, docs/, *.md, config).

This is the SOFT top layer — it sets intent. The actual enforcement is deterministic: the pre-push gate blocks pushing an unreviewed substantial change locally, and the CI gate fails it server-side (unbypassable — an agent cannot --no-verify or skip it). The commit-gate and Stop-gate surface an early nudge so you self-correct before you hit the push/CI block. Writing the same multi-file feature with raw Edit/Write and committing — without ever invoking zuvo:build/zuvo:execute — is exactly the freelance pattern these gates exist to catch: the review never happens, then the push/CI gate blocks it. Enter the pipeline up front instead. Escape (logged): ZUVO_ALLOW_ADHOC=1 locally, or the human-applied zuvo:adhoc-approved PR label in CI.

Priority 2 — Task (scoped work)

Priority 3 — Audit (analysis and reporting)

Priority 4 — Utility

Priority 5 — Release (post-code lifecycle)

Pipeline Enforcement

zuvo:brainstorm  -->  spec document   -->  zuvo:plan
zuvo:plan        -->  plan document   -->  zuvo:execute

• zuvo:brainstorm produces docs/specs/YYYY-MM-DD-<topic>-spec.md
• zuvo:plan uses a spec if available, otherwise plans from user description (inline mode).
• zuvo:execute requires a plan. If none exists, redirect to zuvo:plan.
• Each downstream skill checks for its prerequisite artifact automatically.
• The user can pass an artifact path explicitly: zuvo:plan docs/specs/my-spec.md

When to use pipeline vs task skills

• Pipeline (brainstorm -> plan -> execute): The work requires design decisions, touches many files, or the scope is unclear. The user says things like "build a feature", "implement this design", "add a new module".
• Task (build, debug, refactor, etc.): The scope is clear and bounded. The user says things like "add a utility function", "fix this bug", "refactor this service".

If uncertain, ask the user: "This could be handled as a scoped task with zuvo:build or through the full pipeline starting with zuvo:brainstorm. The pipeline adds design exploration and multi-agent review. Which approach fits?"

Priority Resolution

When a message could match multiple skills, use priority order:

1. Pipeline — If the user is mid-pipeline (spec or plan exists and they say "continue" or "next"), resume the pipeline.
2. Task — If the intent matches a specific task skill, use it.
3. Audit — If the user asks for analysis or a report, use the matching audit skill.
4. Utility — Backlog, docs, presentations, worktree management.
5. Release — Ship, deploy, monitor, document, reflect.

Within the same priority level, pick the most specific match. "Review my API endpoints" matches zuvo:api-audit (more specific) over zuvo:review (general code review).

Boundary: When NOT to Invoke a Skill

Do not route to a skill when:

• Simple questions — "What does this function do?", "Explain this error" -> answer directly.
• One-line fixes — "Change the port to 3001", "Fix the typo on line 42" -> fix directly.
• Git operations — "Commit this", "Push to origin", "Create a branch" -> do directly.
• File reading — "Show me the config", "Read package.json" -> read directly.
• Conversation — "What skills are available?", "How does zuvo work?" -> answer directly.

The threshold: if the task requires reading code to understand it, writing more than a trivial change, or producing a structured output, use a skill. If you can do it in one tool call without analysis, do it directly.

Rationalization Red Flags

You will be tempted to skip skills. Watch for these thoughts and override them:

The only valid reason to skip a skill is when the task falls within the boundary rules above (simple questions, one-line fixes, git ops, file reading, conversation).

Quality Gates (applies to ALL coding — with or without a skill)

Before writing ANY code, verify:

G5 lives here rather than only in env-compat.md because the skills that poll most are the ones that never load it: measured across 11,690 Codex poll calls, worktree (490), backlog (485) and this router itself (85) account for 9% — and none of the three references that include, so the rule could not reach them however well it was written. A poll re-sends the whole context (~108K tokens median) to learn one bit; the full parameter table and the measurements are in env-compat.md.

Tests are part of implementation, not a follow-up. NEVER ask "should I write tests?" — the answer is always yes. NEVER say "implementation complete" when test files = 0.

Additional rules:

• No direct EnterPlanMode for features touching 3+ files — use zuvo:build instead (includes planning WITH analysis sub-agents).
• CQ self-eval for direct coding (1-2 files, no skill): still run CQ1-CQ40 on each production file before writing tests.
• /review before push: after any non-trivial implementation, run zuvo:review before pushing.

Skill File Loading

When executing ANY skill that specifies a file loading checklist: Read each listed file from disk using the Read tool — "I already know the content" is NOT valid. Print the checklist with status before proceeding. If any REQUIRED file is missing, STOP.

Stack Detection

Detect the project's tech stack to know which rules to Read when writing code directly (without a skill):

When writing security-sensitive code (auth, input, API): Read ../../rules/security.md.

Session Startup

1. Project Setup Check (BLOCKING — first session action)

Check if CLAUDE.md exists in the project root. If it does NOT exist:

Tell the user:

This project doesn't have a CLAUDE.md yet. Zuvo needs it to enforce quality gates (tests, code review, skill routing). Without it, I might skip skills and write code without tests.

Want me to create one? It'll take 10 seconds.

If the user agrees, create CLAUDE.md with this content (adapt stack detection from package.json/tsconfig/pyproject.toml):

# [Project Name]

## Development Rules

- ALWAYS use zuvo skills for code changes. Never write production code directly.
  - 1-5 files: `zuvo:build`
  - 5+ files or unclear scope: `zuvo:brainstorm` → `zuvo:plan` → `zuvo:execute`
  - Bug fixes: `zuvo:debug`
  - Refactoring: `zuvo:refactor`
- Tests are mandatory. No production file without a corresponding test file.
- Run `zuvo:review` before pushing any changes.

## Tech Stack

[auto-detected from project files]

## How to run

- Dev: [detected from package.json scripts]
- Test: [detected from package.json scripts]
- Build: [detected from package.json scripts]

If the user declines, proceed but warn: "Without CLAUDE.md, quality gates are suggestions, not rules. Tests may be skipped."

Do NOT skip this check. Do NOT silently proceed without CLAUDE.md. A project without CLAUDE.md is the #1 reason agents skip tests and quality gates.

2. Knowledge Prime (session-level)

Check if the project has a knowledge base:

Glob("knowledge/*.jsonl")

If found: read ../../shared/includes/knowledge-prime.md and run a lightweight session prime — no specific WORK_FILES or WORK_KEYWORDS (session start doesn't know the task yet). Use:

WORK_TYPE = "research"
WORK_KEYWORDS = <project name>
WORK_FILES = <empty>

This surfaces the top project-level gotchas and anti-patterns at session start, before the user even asks for a task. Individual skills will run a focused prime with task-specific keywords later.

If no knowledge base found: skip silently. No log needed at session level.

3. Load Patterns

Read ../../rules/cq-patterns-core.md — defensive coding patterns (error handling, security, data integrity, resource safety). This is a lightweight summary; skills load the full version when needed.

Invocation Format

Use the Skill tool with the zuvo: namespace prefix:

Skill(skill="zuvo:brainstorm")
Skill(skill="zuvo:build")
Skill(skill="zuvo:review")
Skill(skill="zuvo:code-audit")

If the user explicitly names a skill (e.g., "run zuvo:security-audit"), invoke it directly without further routing analysis.

If the user uses a slash command (e.g., "/review", "/build"), map it to the corresponding zuvo skill and invoke it.