Zoka

The autonomous tech lead for your project.

You talk, Zoka builds. You describe a feature, it specs it out, codes it, tests it, and updates the documentation. You request an audit, it scans and fixes. You say nothing, it keeps the project clean.

One single command: /zoka.

Why Zoka

Without Zoka, Claude Code is a reactive tool: you ask, it does, end of story. No memory between sessions, no big picture, no guardrails.

With Zoka:

• You speak in natural language, the system understands what you want and picks the right mode
• Functional and technical documentation updates itself automatically
• Tests are mandatory for every feature and every bug fix
• A persistent backlog accumulates bugs, technical debt, and features to address
• Hooks block the session if the build or types are broken
• The interface is designed before the code (integrated design agent)

Installation

npx zoka-cli init

That's it. Then, in Claude Code:

/zoka.init

Zoka scans your project, detects the stack, generates the initial documentation, and creates a prioritized backlog.

Update

npx zoka-cli update

Updates scripts, templates, and commands without touching your backlog, config, or docs.

Usage

One single command for everything: /zoka

You describe what you want in natural language. Zoka detects your intent and acts.

Build

/zoka ajoute la gestion des congés avec validation manager
/zoka crée un dashboard pour les statistiques RH
/zoka modifie le formulaire d'inscription pour ajouter le téléphone

Fix

/zoka les congés marchent pas quand on est manager
/zoka erreur quand je valide une candidature
/zoka ça plante à la connexion

Maintain

/zoka mets le projet à jour
/zoka vérifie la sécurité
/zoka modernise les dépendances

Audit

/zoka vérifie la santé du projet
/zoka c'est en bon état ?
/zoka audit qualité

Code Review

/zoka revue de code
/zoka regarde mes changements avant commit

Refactor

/zoka renomme le module utilisateurs
/zoka simplifie le code de paiement
/zoka réorganise les dossiers

Manage the Backlog

/zoka quoi faire ?
/zoka continue
/zoka ajoute au backlog : corriger l'export PDF

Initialize (once)

/zoka.init

How It Works

The Intent Router

When you talk to Zoka, it automatically detects what you want:

| You say... | Zoka does... | |---|---| | "ajoute X", "crée Y" | Builds the feature (internal spec → code → tests → docs) | | "ça marche pas", "erreur" | Diagnoses and fixes | | "mets à jour", "upgrade" | Maintains dependencies | | "vérifie", "audit", "santé" | Scans the project | | "revue de code" | Analyzes changes | | "renomme", "simplifie" | Refactors without regression | | "backlog", "quoi faire" | Shows tasks | | "continue", "suivant" | Executes the next task |

If the request is ambiguous, Zoka asks one single question to clarify.

The Design Agent

When the request involves the interface (page, form, dashboard...), Zoka automatically analyzes the project's existing screens before coding:

• Identifies visual patterns (layout, components, spacing)
• Consults the design system documentation
• Reuses existing components
• Handles all states (empty, loading, error)
• Maintains visual consistency

The user sees none of this process — just a consistent result.

The Build Cycle

UNDERSTAND → PLAN → BUILD → VERIFY → CONCLUDE
   (silent)  (checkpoint)  (code + tests)  (validation)  (docs + backlog)

1. UNDERSTAND: Analyzes existing code, identifies what can be reused
2. PLAN: Presents the plan in plain language, waits for confirmation
3. BUILD: Implements the code and generates tests (mandatory)
4. VERIFY: Validates lint, types, tests, build — loops back to fix if needed
5. CONCLUDE: Updates documentation and backlog

The Backlog

Persistent file .zoka/backlog.md organized into 3 sections:

## Bugs      ← What's broken
## Qualité   ← Technical debt, missing tests, security, duplication
## Features  ← What you want to build
## Fait      ← History

Automatically fed by every Zoka action.

Hooks (Guardrails)

| Timing | Effect | |---|---| | Before creating a file | Warning if a similar file already exists | | After each modification | Silently records the modified file | | At session end | Warning if business code was modified without a test | | At session end | Blocking if lint or types are broken |

Living Documentation

3 auto-maintained files in .zoka/docs/:

| File | Content | Updated when | |---|---|---| | functional.md | What the app does, in product language | After each action | | technical.md | Architecture, routes, data model, dependencies | After a structural change | | test-map.md | Test map: which flows are tested and which are not | After each test modification |

The Doctrine

12 non-negotiable rules that the agent systematically follows:

1. Reuse before creating — Always look for existing code before writing new code
2. Framework conventions first — Use idiomatic patterns
3. Minimal changes — Touch as few files as possible
4. Test critical paths — Tests are mandatory for every feature
5. Never ship broken — Validation is mandatory before concluding
6. No premature abstraction — Simple code, no over-engineering
7. Trace decisions — Log significant choices
8. Keep memory up to date — Update standards, decisions, docs
9. Keep docs alive — functional.md, technical.md, test-map.md stay in sync
10. No hallucinated code — Verify that every import and API actually exists
11. No silent errors — Errors must be visible, never swallowed
12. Review before shipping — Code review is mandatory before commit

Supported Stacks

Automatic detection supports:

Languages: TypeScript, JavaScript, Python, Rust, Go, Ruby, PHP, Swift, Java

Frameworks: Next.js, Nuxt, SvelteKit, Remix, Astro, Vite, Express, Fastify, React, Vue, Svelte, Django, FastAPI, Flask, Actix-web, Axum, Rocket

Package managers: pnpm, bun, yarn, npm, pipenv, poetry, uv, pip, cargo, go, bundler, composer

Test runners: Vitest, Jest, Mocha, Ava, Playwright, Cypress, pytest, tox, cargo test, go test

ORM: Drizzle, Prisma, TypeORM, Sequelize, Knex, Mongoose, SQLAlchemy, Django ORM, Tortoise

Linters: ESLint, Biome, Ruff, Flake8, RuboCop, golangci-lint

License

MIT