Using Zuvo

---
name: using-zuvo
description: "ALWAYS LOADED — Zuvo skill router. Injected at session start. Determines which zuvo skill to invoke for the current task."
category: Utility
---

> **Zuvo v1.6.82** | 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)

| User intent | Skill | Notes |
|-------------|-------|-------|
| Build a feature, add major functionality, implement a design | `zuvo:brainstorm` | Start here for anything touching 5+ files or requiring design decisions |
| Plan implementation tasks | `zuvo:plan` | Uses spec from `docs/specs/*-spec.md` if available, otherwise plans from user description |
| Continue from approved plan | `zuvo:execute` | Requires plan artifact in `docs/specs/*-plan.md` |

**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)

| User intent | Skill |
|-------------|-------|
| Build a small feature (1-5 files, clear scope) | `zuvo:build` |
| Fix a bug, investigate an error, diagnose a problem | `zuvo:debug` |
| Refactor, extract, split, move, rename, simplify | `zuvo:refactor` |
| Review code, check changes, audit a PR | `zuvo:review` |
| Write unit/integration tests for existing code | `zuvo:write-tests` |
| Write end-to-end tests (Playwright) | `zuvo:write-e2e` |
| Fix systematic test anti-patterns across files | `zuvo:fix-tests` |
| Fix SEO audit findings, apply SEO fixes | `zuvo:seo-fix` |
| Fix GEO issues — fix schema, fix llms.txt, apply GEO fixes | `zuvo:geo-fix` |
| Fix content audit findings (encoding, markdown, artifacts) | `zuvo:content-fix` |
| Write an article, blog post, generate content from scratch | `zuvo:write-article` |
| Audit accessibility, WCAG compliance, keyboard navigation, screen reader, ADA, contrast | `zuvo:a11y-audit` |
| Find leads, discover companies, enrich contacts, prospect B2B emails, build cold-outreach list | `zuvo:leads` |

### Priority 3 — Audit (analysis and reporting)

| User intent | Skill |
|-------------|-------|
| Audit code quality | `zuvo:code-audit` |
| Audit test quality | `zuvo:test-audit` |
| Audit API endpoints | `zuvo:api-audit` |
| Audit security (OWASP, auth, secrets) | `zuvo:security-audit` |
| Run penetration test | `zuvo:pentest` |
| Audit performance | `zuvo:performance-audit` |
| Audit database (queries, schema, indexes) | `zuvo:db-audit` |
| Audit dependencies (outdated, vulnerable, unused) | `zuvo:dependency-audit` |
| Audit CI/CD pipelines | `zuvo:ci-audit` |
| Audit environment config and secrets | `zuvo:env-audit` |
| Audit server and infrastructure security (SSH, services, CVEs, misconfigs) | `zuvo:infra-audit` |
| Audit Dockerfile / docker-compose / container image security (root, :latest, baked secrets, docker.sock, CVEs) | `zuvo:container-audit` |
| Audit SEO and structured data | `zuvo:seo-audit` |
| GEO readiness audit — AI citation optimization, llms.txt, schema graph, generative engine visibility | `zuvo:geo-audit` |
| Audit content quality (encoding, links, formatting, CMS artifacts) | `zuvo:content-audit` |
| Expand article, add content, deepen thin sections, optimize quality | `zuvo:content-expand` |
| Compare old CMS page with new SSG page, fix parity gaps | `zuvo:content-migration` |
| Audit codebase structure and organization | `zuvo:structure-audit` |
| Which files to refactor next, refactor candidates, hotspot ranking, tech-debt targets, refactor queue | `zuvo:refactor-radar` |
| Review architecture, create ADR | `zuvo:architecture` |
| Review UI/UX consistency, visual design quality, component patterns | `zuvo:design-review` |
| Design new UI (components, layouts, systems) | `zuvo:design` |
| UI design with multi-agent team | `zuvo:ui-design-team` |
| Optimize test suite speed | `zuvo:tests-performance` |
| Run mutation testing (verify tests actually catch bugs) | `zuvo:mutation-test` |
| _(see Priority 2)_ | `zuvo:a11y-audit` |
| Benchmark providers, compare models, measure quality/speed/cost | `zuvo:benchmark` |
| Self-benchmark: YOU write code+tests, adversarial reviews, you fix — measures YOUR quality | `zuvo:agent-benchmark` |

### Priority 4 — Utility

| User intent | Skill |
|-------------|-------|
| View or manage tech debt backlog | `zuvo:backlog` |
| Write documentation | `zuvo:docs` |
| Create a presentation | `zuvo:presentation` |
| Respond to code review feedback | `zuvo:receive-review` |
| Isolate work in a git worktree | `zuvo:worktree` |
| Clean up accumulated / stale worktrees, or move nested `.worktrees/` out of the repo | `zuvo:worktree prune` |
| Incident response, postmortem, root cause analysis | `zuvo:incident` |
| Evaluate a zuvo SKILL against its eval corpus / compare skill versions (dev, needs `evals/`) | `zuvo:skill-eval` |

### Priority 5 — Release (post-code lifecycle)

| User intent | Skill |
|-------------|-------|
| Ship a release, push code, create PR, bump version | `zuvo:ship` |
| Deploy to production, merge PR, verify health | `zuvo:deploy` |
| Monitor production after deploy, check for regressions | `zuvo:canary` |
| Sync documentation with a release | `zuvo:release-docs` |
| Engineering retrospective, shipping velocity | `zuvo:retro` |
| Context health audit, include loading trends, setup bloat | `zuvo:context-audit` |
| Why was that session slow, where did the wall-clock go, session timing forensics | `zuvo:profile-session` |

---

## 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:

| What you might think | Why it is wrong | What to do instead |
|----------------------|-----------------|-------------------|
| "This is simple enough to do without a skill" | Skills enforce quality gates you will skip on your own. A "simple" refactor without `zuvo:refactor` skips CONTRACT verification. | Invoke the skill. |
| "I already know how to do this" | Knowing how is not the problem. The skill ensures you verify, test, and document. | Invoke the skill. |
| "The user just wants it done fast" | Fast without quality gates produces bugs. The skill IS the fast path because it catches issues before they ship. | Invoke the skill. |
| "I'll just do the quality checks manually" | You will forget at least one. Skills encode the full checklist. | Invoke the skill. |
| "This is just a small change" | Small changes without `zuvo:review` are the #1 source of regressions. | If it touches production code, invoke the skill. |
| "The user didn't ask for a skill" | Auto-activation means you route to skills by intent, not by explicit command. The user hired zuvo to enforce standards. | Match intent, invoke the skill. |

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:

| # | Gate | Trigger | Action |
|---|------|---------|--------|
| G1 | **New code → tests** | Any new `.ts`/`.tsx`/`.py`/`.php` file | Write tests BEFORE or WITH the code. Zero exceptions. |
| G2 | **3+ files → /build** | Feature touches 3+ files | Use `zuvo:build`, NOT direct coding. |
| G3 | **CQ self-eval** | Any production code written | Read `../../rules/cq-checklist.md`. Run CQ1-CQ40. Print score. |
| G4 | **Test self-eval** | Any test code written | Read `../../rules/testing.md`. Run Q1-Q25. Print score. |
| G5 | **Never poll a long command** | About to run something slower than the harness's default window | Let it BLOCK — `rt --wait`, `rt --light <cmd>`, `gh run watch --exit-status`, `until [ -f done ]; do sleep 30; done` — one round-trip whatever the duration. If it cannot block, size the FIRST call's window to the job rather than the follow-up polls; every harness has a knob for it and the per-harness table is in `../../shared/includes/env-compat.md`. Only then poll, never under 30 s. |

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):

| Signal | Rule to Read |
|--------|-------------|
| `tsconfig.json` or `.ts`/`.tsx` files | `../../rules/typescript.md` |
| `package.json` with `react` or `next` | `../../rules/react-nextjs.md` |
| `package.json` with `@nestjs/core` | `../../rules/nestjs.md` |
| `pyproject.toml`, `.py` files | `../../rules/python.md` |
| `composer.json` with PHP framework | `../../rules/php.md` |
| `composer.json` with `yiisoft/yii2` | `../../rules/yii2.md` (with php.md) |
| `package.json` with `express` (no Next/Nest) | `../../rules/express.md` |
| `astro.config.*` | `../../rules/astro.md` |
| `go.mod` | `../../rules/go.md` |
| `Cargo.toml` | `../../rules/rust.md` |
| `*.csproj` / `*.sln` | `../../rules/dotnet.md` |
| `Gemfile` | `../../rules/ruby.md` |

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):

```markdown
# [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.