demoverse: Instructions file for Codex

AGENTS.md: how a coding agent drives Demoverse

Demoverse is operated by a coding agent. The deterministic TypeScript engine does the mechanical work; the agent does the judgment and the prose. This file is the contract for that handoff, for any agent tool (Claude Code, Codex, Cursor, Copilot, …): Part 1 is the engine contract and the core loop, Part 2 takes a new user from a fresh clone to a living world, Part 3 has per-tool notes.

Part 1: The engine contract

The split (don't cross it)

The engine owns everything structural: ledger I/O, ids and referential integrity, the simulation clock and trends, sampling accounts, contacts, deals and competitors, schema validation, the coherence lint, reports, and reconcile into CRM, Drive and Slack. You own two things: writing the prose for each emitted request, and, when the operator sets new direction, updating state/directives.md + state/trends.json. You never hand-edit state/world.json.

The generation-request protocol (the core loop)

By default this loop runs unattended: .github/workflows/pipeline-update.yml runs steps 1-4 weekly through Claude Code, then reconciles and commits itself (see docs/automation.md). Run it by hand for an extra week, a nudge, or a repo without Actions.

1. Plan. Run npm run pipeline for one living increment on demand (it equals npm run apply -- --weeks=1). Plain npm run apply generates only the periods the real calendar has produced, and -- --backfill covers the first big run. The engine advances the world: a couple of new deals, each open deal moved along its own cycle (usually one stage, more for a short deal, none at all for one that has gone quiet), closes for the deals whose cycle is up. Then it writes a request bundle holding only the touch points those events earned, 1–3 per deal. Never a deal's whole history; that is what --backfill-touchpoints is for.

   state/requests/<periodIndex>/manifest.json        # index of all requests
   state/requests/<periodIndex>/<artifactId>.prompt.md
   state/requests/<periodIndex>/results/             # ← you write here
   

2. Fill. Each .prompt.md is fully grounded in the exact ledger facts. For every request in manifest.json, read the prompt and write the result:
   • output: markdown → write results/<artifactId>.md (the artifact body).
   • output: slack_messages → write results/<artifactId>.json as {"messages":[{"personaHandle":"…","text":"…"}, …]}.
   • output: email_thread → write results/<artifactId>.json as {"emails":[{"from":"…","to":["…"],"subject":"…","body":"…","date":"YYYY-MM-DD","contactRef":"…"}, …]} (one object per message, in send order).
3. Ingest. Run npm run apply -- --ingest --reconcile. The engine validates each result, files markdown into state/content/, attaches Slack messages and email threads onto their artifacts, and reconciles into every connector that is enabled and has credentials. Anything that fails validation stays planned and reappears in the next bundle. Refill it and re-ingest.
4. Verify. Run npm run lint. Fix any error findings by editing the result and re-ingesting. The cause is usually a missing competitor name or win/loss reason in the prose.