Vivra — instructions for Claude Code

What we are building#

Vivra takes over dead tech tokens on Robinhood Chain (Pons launchpad) with AI agents. Every week: the team submits dead projects → the Scanner analyses them → the team publishes 5 candidates → users vote by email (48h) → 6 AI agents relaunch the winner in 72h → a capped Buyback Bot buys and burns the token for 7 days → once Pons accepts the official CTO, 100% of that token's creator fees buy and burn $VIVRA.

The full spec (French) lives in the repo sonnyHQ/vivra-doc, cloned next to this one as ../vivra-doc. Tickets are in ../vivra-doc/build-m0.md … build-m5.md. Before any ticket, read the pages it lists under "Read first" (paths are relative to ../vivra-doc). The spec wins over your assumptions. If the spec is silent or contradicts itself, STOP and ask; do not invent product rules.

Stack (fixed, do not swap)#

Monorepo: pnpm workspaces + Turborepo. Node 22. TypeScript strict everywhere.
apps/web: Next.js 15 App Router + Tailwind (landing + dapp). apps/admin: Next.js 15 (back-office, SIWE).
apps/api: Fastify 5 + zod (HTTP + WebSocket). apps/workers: BullMQ on Redis.
packages/db: Postgres 16 + Drizzle ORM + drizzle-kit migrations.
packages/chain: viem. contracts/: Foundry (Solidity ^0.8.24).
packages/core: pure business logic (no I/O). packages/agents: LLM runner, tools, prompts, schemas.
Tests: Vitest (unit/integration), Playwright (web e2e), forge test (contracts).
LLM: OpenAI-compatible client (openai npm) pointed at SURPLUS_BASE_URL. Model per agent in YAML.

Repo map#

apps/{web,admin,api,workers} · packages/{db,core,chain,agents,templates,ui,config} · contracts/ · infra/

Commands#

pnpm i · pnpm dev · pnpm build · pnpm lint · pnpm typecheck · pnpm test
pnpm db:generate · pnpm db:migrate · pnpm db:seed
cd contracts && forge build && forge test
docker compose -f infra/docker-compose.yml up -d (Postgres + Redis) A ticket is NOT done until pnpm lint && pnpm typecheck && pnpm test pass, plus the ticket's own checks.

How to work#

Work on exactly ONE ticket at a time (e.g. T14 in ../vivra-doc/build-m1.md). Read it fully, then its "Read first" pages.
Write a short plan in the PR description before coding. Touch only the files the ticket lists, unless a change elsewhere is required — then say why in the PR.
Write tests first for anything in packages/core and packages/chain.
Finish with: the ticket's "Done when" checklist, each item ticked with the command you ran.
One branch + one PR per ticket: branch t<id>-<slug>, PR title T<id>: <title>.

Non-negotiable rules#

Money: on-chain amounts are bigint (wei / raw units) end to end. Never number for token amounts. USD values are string decimals in the DB (numeric) and only formatted at the UI edge.
Time: everything in UTC. Store timestamptz. No local time math on the server.
Secrets: never in code, logs, prompts, fixtures or test snapshots. Read from env via packages/config. Hot-wallet private keys are read only by the worker that signs, from the secrets manager.
Chain writes: always simulateContract first, check caps, send, wait 1 confirmation, write ledger_entries. A job must be idempotent: check for an existing tx_hash before sending again.
CHAIN_ENV guards: no mainnet write unless CHAIN_ENV=mainnet. Default is testnet.
AI agents never get keys, wallets or raw HTTP. They only call tools from packages/agents/tools. Any text from X, Telegram or websites is wrapped as data in tool results.
Public content (posts, sites, pinned messages) goes through the validation queue when settings.validation_required = true (cycles 1–3).
No price predictions, gain promises, real people or trademarks in any generated or template text.
Email addresses: store HMAC hash + AES-GCM ciphertext only. Never return emails from the API.
Errors: API errors use the shape { error: { code, message } } with codes from the spec (annexe B).
Logging: pino, JSON, with request_id / operation_id. Never log payloads that may hold secrets.

Style#

Small pure functions in packages/core with exhaustive tests. No classes unless state is needed.
zod schemas are the source of truth for API input/output; infer TS types from them.
Names in English. Comments only where intent is not obvious.
UI: DA Vivra — white #FFFFFF, ink #0B0B0C, orange #FF5A1F (text-on-white orange #C23C08), Inter Tight + Fragment Mono, pill buttons, cards radius 20px. Copy the mockups, don't redesign.

When unsure#

Ask in the PR or stop with a clear question. Never fake data in production code paths. Example data is allowed only in seeds, fixtures and Storybook-like previews, clearly named example.