demoverse AGENTS.md

AGENTS.md: how a coding agent drives Demoverse

Demoverse is operated by a coding agent, not just a human. The deterministic TypeScript engine does all the mechanical, error-prone work; the agent does the judgment and the prose. This file is the contract for that handoff, readable by any agent tool (Claude Code, Codex, Cursor, Copilot, …). Three parts:

1. The engine contract. The split of responsibilities, and the generation-request protocol that is the core loop.
2. The onboarding playbook. Walking a new user from a fresh clone to a living world. /setup in Claude Code runs this; other agents follow it directly.
3. Per-tool notes.

---

Part 1: The engine contract

The split (don't cross it)

Deterministic engine (code)	Agent (you)
Ledger I/O, ids, referential integrity	Interpreting directives + nudges
Simulation clock, trend evaluation	Choosing nothing structural (the code already did)
Sampling the world (accounts/contacts/deals/competitors)	Writing the prose for each emitted request
Schema validation, coherence lint, reports	Editing state/directives.md + state/trends.json when direction changes
Reconcile (CRM/Drive/Slack upserts via the connector registry)	n/a

You never hand-edit state/world.json. Structure is the code's job. You only: (1) fill generation requests, and (2) when the operator sets new direction, update state/directives.md + state/trends.json.

The generation-request protocol (the core loop)

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.