Menu
ALWAYS LOADED — Zuvo skill router. Injected at session start. Determines which zuvo skill to invoke for the current task.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Architecture skill with three modes: review existing codebase architecture (A1-A9 dimensions), create Architecture Decision Records, or design new systems from requirements. Modes: --mode review [path], --mode adr, --mode design. Uses CodeSift for module discovery, dependency mapping, structural metrics, and temporal coupling detection.
Manage the project's tech debt backlog. Add, list, fix, wontfix, delete, prioritize, and suggest batch actions on tracked issues. Used by audit and review skills to persist findings, and directly by users to manage accumulated debt. Modes: list [category], add [description], fix B-{N}, wontfix B-{N} [reason], delete B-{N}, stats, prioritize, suggest.
Systematic bug investigation with a five-phase framework: reproduce, narrow, diagnose, fix, verify. Supports automated regression bisect via --regression flag. Produces a structured debug report with root cause analysis, regression test, and CQ/Q self-evaluations.
Engineering retrospective from git metrics. Reports deployment frequency, release cycle span, churn hotspots, backlog health. Outputs narrative report with 3+ actionable items. Flags: --since, --path, explicit range argument.
Structured code review with parallel audit agents, confidence-scored triage, and optional auto-fix. Examines uncommitted changes, staged diffs, commit ranges, or specific paths. Produces a tiered report (MUST-FIX / RECOMMENDED / NIT) backed by evidence, then optionally applies fixes with verification.
Codebase structure and organization audit across 13 dimensions (SA1-SA13): directory consistency, naming conventions, folder depth, colocation, barrel exports, separation of concerns, file size distribution, dead code, complexity distribution, duplication, root organization, documentation, hotspots. Tool-driven with CodeSift primary and CLI fallbacks (cloc, knip, dep-cruiser, jscpd, eslint, git mining). Flags: full (default), [path], --naming, --size, --dead-code, --duplication, --hotspots, --quick, --fix.
| name | using-zuvo |
| description | ALWAYS LOADED — Zuvo skill router. Injected at session start. Determines which zuvo skill to invoke for the current task. |
Zuvo v1.6.18 | 55 skills | 5 adversarial providers | CQ1-CQ29 + Q1-Q19
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.
Skill(skill="zuvo:<name>")Do this on every message. Not just the first one.
If the session context includes the compressed response protocol, apply it by surface:
TERSE.STRUCTURED_TERSE.## ... COMPLETE, repo-written artifacts under docs/, memory/, .interface-design/, and explicit user requests for depth stay STANDARD.conf: confirmed, conf: likely, or conf: unclear.| 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.
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.
| 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 |
| 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 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 |
| 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 |
| 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 |
| 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 |
| 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 |
zuvo:brainstorm --> spec document --> zuvo:plan
zuvo:plan --> plan document --> zuvo:execute
zuvo:brainstorm produces docs/specs/YYYY-MM-DD-<topic>-spec.mdzuvo: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.zuvo:plan docs/specs/my-spec.mdbrainstorm -> 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".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?"
When a message could match multiple skills, use priority order:
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).
Do not route to a skill when:
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.
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).
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-CQ29. Print score. |
| G4 | Test self-eval | Any test code written | Read ../../rules/testing.md. Run Q1-Q19. Print score. |
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:
zuvo:build instead (includes planning WITH analysis sub-agents).zuvo:review before pushing.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.
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 |
When writing security-sensitive code (auth, input, API): Read ../../rules/security.md.
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.
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.
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.
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.