First run

This page sets expectations for completion signals, artifacts, and common pauses. Lamina commands (/lamina-init, /lamina-design, /lamina-verify) run in agent chat. Implementation and fixes use ordinary coding prompts outside those commands.

Quick path

Agent chat — /lamina-init (~1–2 minutes)
Agent chat — /lamina-design (~3–10 minutes for one bounded flow)
Ordinary coding mode — your agent implements (time varies widely by stack and scope)
Start the product and confirm the URL in a browser
Agent chat — /lamina-verify guest checkout at http://localhost:3000 (~2–5 minutes)
Ordinary coding mode — apply fix.md when product findings remain; agent chat — re-verify the same bounded flow and URL until zero open product or contract findings

Lamina commands alone typically take minutes. A full first cycle including implementation can take much longer — that time is outside Lamina’s control.

Example prompts

Start with one flow, not the whole product:


/lamina-init Short-term rental marketplace for property hosts

/lamina-design Guest checkout with inventory hold, payment, and cancellation

For a full marketplace reference, see Demo: HavenStay.

What appears in `.lamina/`

After `/lamina-init`

Success state: Lamina produces and validates both project-level artifacts.

File	Purpose
`business-context.md`	Domain charter — problem, scope, constraints
`personas.json`	Actor cast — roles, goals, permissions

Next action: /lamina-design <one bounded flow>

After `/lamina-design`

Success state: run.json status is ready_to_build.

File	Purpose
`runs/<id>/run.json`	Machine contract (`status: ready_to_build`)
`runs/<id>/run.md`	Readable rendering of the contract
`runs/<id>/implement.md`	Build handoff for your coding agent

report.md is a verify artifact, not a design output.

Next action: switch to ordinary coding mode and implement from implement.md.

After `/lamina-verify`

Success state: verification complete; open findings listed in run.json.

File	Purpose
`runs/<id>/run.json`	Updated with `findings[]` and status
`runs/<id>/report.md`	Verification narrative
`runs/<id>/fix.md`	Fix brief (written even when no product fixes remain)
`runs/<id>/walkthrough/`	Optional screenshots and live-app evidence

Next action: apply product fixes from fix.md, return to /lamina-design for contract gaps, or note fix_target: ops observations in report.md; then re-verify the same bounded flow and URL.

What `ready_to_build` means

When run.json status is ready_to_build, the contract is complete enough for your agent to implement:

Actors and roles are defined
Entities, states, and transitions are specified
Workflows cover primary and alternate paths
Scenarios enumerate edge cases and recovery
Dependencies map feature reachability
Invariants state rules that must always hold

You do not need a perfect spec — you need a contract your agent can implement and Lamina can verify against.

Expected timeline

Step	Context	Time	Notes
`/lamina-init`	Agent chat	1–2 min	More if domain is complex or brownfield
`/lamina-design`	Agent chat	3–10 min	Scales with scope; start with one flow
Agent implements	Ordinary coding mode	30 min – hours	Depends on stack and scope — dominates total time
Start product + confirm URL	Shell / browser	Minutes	Required before verify
`/lamina-verify`	Agent chat	2–5 min	Requires bounded flow + running dev server URL
Fix + re-verify	Coding mode + agent chat	5–30 min per loop	Repeat until zero open product or contract findings

Common pauses and retries

Pause	What it means	Next action
Init asks business questions	Consequential unknowns need answers	Answer blocking questions; retry init if needed
Design asks for clarification	Scope lacks a usable user, outcome, or boundary	Narrow to one coherent flow
Init gate blocks design or verify	Missing or invalid `.lamina/business-context.md`	Run `/lamina-init`; do not bypass
Agent edits app source during a Lamina command	Lamina/coding mode boundary lost	Stop app edits; finish the Lamina artifact, then issue a separate coding prompt
Verify cannot reach the product	Connection errors, or `report.md` shows weak grounding/coverage for the named flow	Start the product, confirm URL in browser, retry with bounded flow + URL
Verify passes but experience is broken	Contract or actor coverage may be too shallow	Return to `/lamina-design` with missing flow or constraint

Tips for beginners

Start small — design guest checkout before the entire marketplace
Run init first — successful init produces and validates both business-context.md and personas.json; design and verify are blocked without a valid .lamina/business-context.md
Label your contexts — shell install, agent chat commands, ordinary coding for app edits
Name the flow at verify — include the bounded target and URL, for example /lamina-verify guest checkout at http://localhost:3000
Start your dev server before verify — persona walks need a live, browser-reachable URL
Check the exit condition — zero open product and contract findings; fix_target: ops in report.md does not block exit

Tips for advanced users

Reference dependency ids in workflows, not free-text preconditions
Use fix_target: contract findings to trigger scoped re-design
Validate contracts: node .claude/skills/lamina-orchestrator/lib/validate-run.mjs .lamina/runs/<id>/run.json
Preserve .lamina/ between runs — Lamina reuses existing artifacts

Next steps

Contracts and runs — full artifact model
Troubleshooting — symptom-based recovery
Personas — how verify walks work