Skip to Content
ConceptsContracts & Runs

Contracts and runs

Lamina writes design artifacts to .lamina/ in your project root. This directory is never app source — it is the product design contract your agent implements and Lamina verifies against.

Quick path

  1. /lamina-init writes global files: business-context.md, personas.json
  2. /lamina-design creates .lamina/runs/<id>/ with run.json, run.md, and implement.md
  3. Your coding agent implements from implement.md
  4. /lamina-verify adds findings and fix.md

Directory structure

.lamina/
├── business-context.md       # Domain charter (/lamina-init)
├── personas.json             # Actor cast (/lamina-init)
├── decisions.md              # Conflict resolution log
└── runs/
    └── <run_id>/
        ├── run.json          # Machine contract
        ├── run.md            # Generated readable graph
        ├── implement.md      # Build handoff
        ├── fix.md            # Verification findings
        ├── report.md         # Verification narrative
        └── walkthrough/      # Optional live-app evidence

Advanced: run.json is the machine contract — not metadata. It contains entities, workflows, scenarios, dependencies, and findings. See run.json schema.

Global vs per-run artifacts

ScopeFilesWritten by
Globalbusiness-context.md, personas.json, decisions.md/lamina-init, updated across runs
Per-run (design)run.json, run.md, implement.md/lamina-design
Per-run (verify)Updated run.json findings, report.md, fix.md, optional walkthrough//lamina-verify

See Global artifacts and Per-run artifacts for field-level detail.

What is a contract?

A contract is the complete product behavior specification for one run:

  • run.json — machine-readable intent, decisions, entities, states, invariants, dependencies, workflows, scenarios, surfaces, traceability, and findings
  • implement.md — human and agent-readable build brief at ready_to_build

Your coding agent implements from implement.md. Lamina verifies the live build against run.json.

Contract status lifecycle

StatusMeaningSet by
draftContract in progress/lamina-design
needs_inputA consequential product decision blocks readiness/lamina-design
ready_to_buildSafe to implement/lamina-design
verifyingEvidence-backed graph verification in progress/lamina-verify
completeVerify finished/lamina-verify
/lamina-design → draft → ready_to_build
                                    ↓
                            [your agent implements]
                                    ↓
/lamina-verify → verifying → complete
                                    ↓
                    [findings? → fix → re-verify]

A run with status: complete may still have open findings. Zero open findings means the contract holds on the live build.

Init gate

/lamina-design and /lamina-verify require a valid .lamina/business-context.md from /lamina-init. Run init first — always.

Rules

  • Never treat .lamina/ as app code — it is design artifacts, like specs
  • One run per design scope — a new /lamina-design creates a new run id
  • Implement from implement.md — do not cherry-pick sections
  • Fix from fix.md — address product behavior, not styling
  • Preserve artifacts — Lamina reuses existing outputs before regenerating

Contract deltas

When verify finds a gap in the contract itself (not the app), the finding has fix_target: contract. Re-run /lamina-design with a scoped update instead of changing app code.

Next steps

Last updated on
The LoopPersonas