Build pack: building Vivra with Claude Code

The other parts of this GitBook explain what to build. This section explains how to have Claude Code build it, ticket by ticket, with completion criteria verified by commands.

All pages in this edition are in English. The build instructions, conventions, and tickets retain their original technical identifiers. Product rules remain authoritative. The setup examples below preserve the original source repository layout; this GitBook stores those pages in content/.

What the pack contains#

Page	Purpose
CLAUDE.md	File to place at the code repository root: context, fixed stack, commands, non-negotiable rules.
Conventions	Folder structure, naming, errors, tests, security, PR format.
M0 · Foundations	Monorepo, database, chain, API, workers.
M1 · Project analysis	On-chain reads for a submitted token, target, safety, recovery score, back-office.
M2 · Agents	LLM client, runner, tools, orchestrator, approval queue, six agents.
M3 · On-chain and money	BuybackBurner contract, Buyback Bot, treasury, ledger, Pons CTO tracking.
M4 · Product	Email sign-in, cycles and voting, dapp, landing, automated posts.
M5 · Launch	Alerts, full-cycle fork rehearsal, launch checklist.

Each ticket follows the same format:

Goal: the outcome in one sentence.
Depends on: tickets to finish first.
Read first: specification pages to read before coding.
Build: files to create or edit.
Steps: ordered steps with exact interfaces.
Done when: checklist, with every item verifiable by a command or test.
Out of scope: work excluded from the ticket.

One-time setup#

Create the private vivra code repository and clone the two repositories side by side:

mkdir vivra-workspace && cd vivra-workspace
git clone [email protected]:sonnyHQ/vivra-doc.git
git clone [email protected]:<org>/vivra.git

Copy CLAUDE.template.md to vivra/CLAUDE.md and commit it.
Create vivra/.env from .env.example (ticket T00), using the keys from Appendix F. Never commit it.
Start Claude Code in vivra/: claude.

Workflow for each ticket#

Open a Claude Code session in vivra/ and provide this prompt, changing the ticket number:

Implement ticket T14 from ../vivra-doc/build-m1.md.
Read the ticket and every page listed in "Read first" before writing code.
Start by writing your plan (files, functions, tests). Then implement it,
run the "Done when" checks, and open a PR named "T14: <title>" with the checklist ticked.
If anything in the spec is unclear or contradictory, stop and ask me.

Review the plan before implementation; this is the earliest opportunity to catch mistakes.
When implementation finishes, rerun pnpm lint && pnpm typecheck && pnpm test and the ticket's checks yourself.
Review the PR, merge, then move to the next ticket.

Working rules:

One ticket per session. A fresh session for each ticket keeps context clear.
Order matters. Tickets in a milestone often depend on earlier ones (the Depends on field).
Tickets marked 🔒 affect money or keys. Require line-by-line human review and testnet checks before merging.
Tickets marked ⚠️ Pons depend on an unconfirmed ABI or Pons response (open questions). The implementation must stop at those points and ask.

Milestones and exit gates#

Milestone	Tickets	Exit gate
M0	T00–T04	`pnpm dev` starts everything locally, migrations work, CI passes
M1	T10–T16	a submitted testnet address produces a full analysis in under 10 min
M2	T20–T29	a complete simulated operation on a testnet token, every output in the approval queue
M3	T30–T33	23 slices executed and burned on testnet, ledger exact to the wei
M4	T40–T44	complete testnet cycle: publication, email voting, closing, operation created
M5	T50–T52	a full mainnet-fork cycle rehearsal without a blocking incident