Prototype specs

Every prototype should ship a spec: a small set of documents next to the code that lets any agent or developer understand the product and rebuild it as a real application. This page defines that harness: which files exist, what each one contains, where its facts come from, and which parts are generated from code. The decision is recorded in ADR-019.

The layout follows the per-module and per-feature tiers of the DeepWorkPlan documentation standard (§2 for AGENTS.md, §4 and §4.1 for nested docs/). A prototype is a self-contained sub-app with its own contracts (schema, policy, scenarios), so it qualifies for its own AGENTS.md and docs/ folder.

Status

Start a spec with pnpm protoyard spec <slug> --init, write the prose, and keep the facts current with --write (--check in CI or review). Update this table when the remaining tooling ships.

The files

prototypes/<slug>/
├── AGENTS.md              lean entry point for agents: what it is, rules, commands, doc index
├── README.md              short human intro: what it is, how to run it, links to docs/
└── docs/
    ├── SPEC.md            problem, users, capabilities, non-goals, honest boundaries, rebuild path
    ├── DATA_MODEL.md      tables, keys, indexes, relations, schema versions and migrations
    ├── FLOWS.md           user flows, each mapped to a service, a capability and the tables it writes
    ├── SCREENS.md         every route: purpose, data shown, actions, states, required capability
    └── PERMISSIONS.md     roles × capabilities matrix, record-level rules, personas

All six files are required for a prototype with "status": "ready". Others may start with AGENTS.md and docs/SPEC.md. The prototype README.md stays short and links into docs/ instead of repeating tables.

AGENTS.md (per prototype)

The same three roles as the root AGENTS.md, scoped to one prototype and kept under about 80 lines:

1. Index: one line per docs/ file.
2. Rules: only what is specific to this prototype (for example "money is

integer cents in accounts.balanceCents" or "reps edit only their own deals"). Link to the root rules; do not copy them.

1. Quick commands: pnpm protoyard dev <slug>,

pnpm vitest run prototypes/<slug>, pnpm protoyard validate <slug> --build, pnpm protoyard export <slug>.

docs/SPEC.md

docs/DATA_MODEL.md

Reserved platform tables (py_*) are listed once, as platform tables, not as domain tables.

docs/FLOWS.md

Entirely hand-written: there is no reliable way to infer intent from code. Each flow is a short numbered list that ends in the service layer:

### Move a deal to another stage
1. Pipeline → drag the card, or "Move to…" on the card.
2. Service: `deals.moveStage(id, stage)` in src/domain/services.ts
3. Capability: `deals:update` (reps: own deals only)
4. Writes (one transaction): `deals` (stage, probability, lostReason, closedAt, updatedAt), `activities` (a stage-change entry)
5. Failure states: permission denied, simulated offline (nothing written)

Every mutation in src/domain/services.ts should appear in at least one flow. That is the path agents follow when they rebuild the app: UI → service → session.assert → zod → environment.run → db.transaction.

docs/SCREENS.md

docs/PERMISSIONS.md

Generated regions

A generated region is fenced by an opening and a closing marker with the same id:

<!-- protoyard:generated:capability-matrix -->
| Capability | owner | admin | rep | viewer |
| --- | --- | --- | --- | --- |
| `deals:update` | ✓ | ✓ | ✓ |  |
<!-- /protoyard:generated:capability-matrix -->

Rules:

• Text between the markers belongs to the generator. A refresh replaces

it, and the check fails when it differs from what the code produces.

• Text outside the markers is hand-written and is never touched.
• Markers are not nested, and each id appears at most once per file.

Unbalanced or duplicate markers are an error, not something to repair silently.

• Generated content is deterministic: rows sorted by a stable key, no

timestamps, no machine paths. Regenerating twice gives identical bytes.

• Facts come only from the prototype definition (src/prototype.ts and what

it imports), loaded in a child process as validate does today. Nothing is scraped from compiled output.

Region ids:

Rebuild kit

pnpm protoyard spec <slug> --bundle writes artifacts/<slug>/<slug>-rebuild-kit.zip: one file to hand to a team or an agent building the prototype as a real app. It contains a generated REBUILD.md (contents with sizes and sha256, how to use the kit, and a starting prompt that asks before choosing any vendor), then AGENTS.md, README.md, docs/**/*.md, protoyard.json, src/prototype.ts, src/routes.ts, src/database/schema.ts, and the .ts, .md and .json files under src/domain/ and src/scenarios/ (tests excluded). Nothing outside that allow-list is read: no screens, components, assets, tests or environment files. The command prints the ZIP's sha256. The same files give the same bytes.

The kit is refused, and nothing is written, when the spec is missing or stale, when a symlink leaves the prototype folder or sits on the allow-list, or when a file matches the repository's public-hygiene rules (secret shapes, personal paths, private emails). Findings are reported as path:line rule, never with the matched text. The kit lives under artifacts/, never in dist/, so it is not part of any hosted build.

Honest boundaries

SPEC.md names every simulated part plainly. A prototype has no backend:

Rebuild as a real app

This section of SPEC.md is the hand-off to a team or an agent building the production version. For each row below, it states what the prototype does and what a real implementation needs. It never names a vendor as if it were already chosen:

Writing a spec

1. pnpm protoyard spec <slug> --init creates AGENTS.md and the docs/

files that are missing (existing files are never overwritten), with TODO prompts for the prose and the generated regions already filled.

1. Replace the TODOs. Move long tables out of README.md into docs/ and

link to them.

1. After changing the schema, policy, scenarios or routes, run

pnpm protoyard spec <slug> --write; --check fails (exit 4) while a region is stale.

1. Check that every relative link resolves and every command shown runs.

The crm-demo README already contains most of the facts a first spec needs (screens, routes, data model).