Start here

This is an implementation manual, not a catalogue. The bot library is frozen at 109; nothing new ships until the rails are at runtime-live. Your first five PRs are below.

operator UX mock

See where this work lands in the product

A high-fidelity re-skin of the eight live operator pages (Dashboard, Strategies, Risks, Bots, Decisions, Orders, Portfolios, Wallets) plus a new Pipeline page, showing exactly how the four-state promotion ladder, reason codes, envelope viewer, and V2-only rails surface to the operator. Each page is annotated with what changes vs. today.

Open the mock app → Jump to Pipeline Jump to Bots

first PR path

The first five PRs, in order.

Each step is one reviewable PR. Do not skip ahead. Do not start a strategy PR before the rails it depends on are merged.

PR 1 — Contracts. Land MarketSnapshot, OrderBookSnapshot, OrderIntent, ReportEnvelope, and the ReasonCode registry as TypeScript types in packages/contracts. No bot code yet. See typed schemas →
PR 2 — First risk bot. Implement risk.killswitch against the contracts from PR 1. KillSwitch is the smallest, most important bot. Use the Risk template. Add a fixtures/risk.killswitch/{normal,warning,hard,failure}.json pack. See KillSwitch spec →
PR 3 — Fixture pack format. Land the four-file fixture-pack convention used by verify.js. Document it in Test pack. From this PR forward, every bot PR ships its fixtures in the same shape.
PR 4 — Reporting envelope. Wire ReportEnvelope into the runner so every decide() emit lands a structured event. Free-text console.log is forbidden after this PR. See envelope spec →
PR 5 — Demo wiring. Add the bot to wired_bots.json and to the synthetic browser demo. The synthetic feed is the only feed; production data does not exist yet. Open the demo →

Open the Plan See the 11 stages How to implement a bot

what's next

Open work, before any new bot lands

Readiness taxonomy migration — replace legacy live/beta/planned labels with the five-state taxonomy (docs-complete / demo-wired / shadow-ready / runtime-live / production-live). Tracked as P0 #5.
Fixture packs for the 9 demo-wired bots — verify.js currently warns; once fixtures land it will fail-on-missing in CI.
Spec/registry alignment — risk.marketqualityguard aliases disc/marketqualityranker; risk.drawdownguard aliases risk/portfolioguard. Both need dedicated spec pages.
Atomic exposure — risk.portfolioguard currently checks open positions; needs to atomically include pending orders + partial fills before any second strategy ships.
Production-engine notes — idempotency, retry policy, monotonic clock, cancel-before-place, event sourcing. The runner today is a reference pipeline, not the production execution engine.

Read the full review Open issues

How to implement a bot

The same 7 steps for every bot, every class. Do not invent a different shape.

Pick the class. Discovery, Strategy, Risk, Execution, Governance. The class determines authority, mode ladder, and which template you copy. By Class →
Copy the template. The five class templates under /templates/<class>/ are the only approved starting point. Do not start from scratch. Templates →
Paste the spec into your README. Open the bot's spec page. Paste it into the bot package's README so any spec change is reviewable in the same PR as the code change.
Implement decide(ctx, intent). Everything else — interface, emit, explain, health — is already wired by the template. Your work is the decision function.
Write the fixture pack. Four files: normal.json, warning.json, hard.json, failure.json. Copy expected outputs from the spec's wire-examples section — do not hand-write them.
Run npm test. All four packages must stay green: contracts, synthdata, backtest, bots. The bots package runs verify.js: factory shape, decide() determinism, fixture-pack presence.
Open the PR. The promotion-gate checklist is the PR template. Mark the readiness state honestly: a bot with a passing fixture pack is shadow-ready, not production-live.

The seven questions, in case you forgot one

What do I build first? — Read the Plan. Phases 1–3 ship the shared rails; Phase 4 the risk gate; Phase 5 the execution rails; Phase 6 the first strategy. Skipping a phase means rebuilding it later under pressure.
Which class does my bot belong to? — Pick the class. Class determines authority, modes, and template.
Which template do I copy? — The five class templates. The single approved starting point.
Which schemas must I import? — All inputs and outputs come from the typed schemas. If the object isn't there, it isn't real yet.
Which test fixtures must pass? — Every fixture pack ships {normal,warning,hard,failure}.json. Your decide() must reproduce the expected outputs deterministically.
What counts as done? — demo-wired requires 27/27 on the per-bot documentation checklist (section 29) and a passing fixture pack and a clean run of verify.js. That is documentation completeness plus reference implementation — it is not readiness to trade. Promotion to production-live requires shadow mode, runtime envelopes, and change control.
How do I promote it? — Through the readiness ladder: docs-complete → demo-wired → shadow-ready → runtime-live → production-live. Never skip a state.

What does NOT belong on your machine

Production wallet keys. Use the staging signer; production keys live only in the signing service.
The live Polymarket API. Tests use the recorded CLOB v2 fixture set.
Free-text logging. Use the ReportEnvelope.
Hard-coded market IDs or contract addresses. They live in BotConfig.

If you only read one other page

Read the bot-interface page. It is the single most important contract in the system.