Continuing development (agent playbook)

Instructions for a third-party coding agent picking up this repository cold. Scope, constraints, and safe next work.

How an agent should work here

Read CLAUDE.md and this page before large edits.
Treat meeting notes (docs/meeting-notes.md) and the product brief as product-context authoritative for workflow and scope.
Prefer changing data (sections, field definitions, rules, vocabulary, catalogue groups) over hard-coding UI enums.
Keep AI behind server/ai/; validate with Zod; route new terms to SuggestedTerm.
Put business rules in services; Prisma only in repositories.
Add unit tests for domain logic you touch; run lint, typecheck, and tests before reporting completion.
Do not modify terraform/. Infra changes go through config.yml only.
Application code that must ship in the container belongs under src/web/.

Good next increments (examples)

Wire real ALB OIDC into current-user.ts without changing call sites of requireCapability.
Replace MaRLay mock with HTTP while keeping the same client surface.
Add further sections (operational metadata, assay parameters, protocol) via seed + field definitions — avoid schema redesign for simple fields. FUTURE sections already reserve protocol, instruments and data outputs.
Expand catalogue groups with real templates beyond ADME when sources exist.
Improve LLM extraction prompts / merge policy; keep ranking deterministic.
Richer ontology mapping UX; bulk import of terms with steward review.
Keep docs screenshots current after major UI changes (npm run docs:screenshots).

Do not

Build a separate frontend/backend split without a new ADR.
Let the LLM approve templates or activate vocabulary terms.
Store execution/run data, raw instrument files or processed results in AssayLink tables.
Collect experimental numbers (Fold Induction of 12, Ct, peak area) as metadata fields — those names are expected-readout terms.
Put reusable subtypes in the primary demo UX — use Template Version and Project Assay Link.
Hard-code assay format/type options in React components.
Put package.json or Prisma above src/web/.
Claim “done” without lint/typecheck/tests when you changed code.

Definition of done (code change)

cd src/web
npm run lint
npm run typecheck
npm test
# optional: npm run test:e2e
# optional: npm run docs:screenshots   # if UI changed meaningfully

Domain language (use these names)

Term	Meaning
Assay Template	Reusable assay definition; has versions
Assay Template Version	Immutable-once-approved metadata snapshot
Project Assay Link	Project’s use of a version + context; not a run
MaRLay	External project master data; six-digit ids
Vocabulary / Term	Governed controlled list / concept
Metadata Field Definition	Field in the assay metadata model
Metadata Section	Steward-named group of fields; wizard pages by these
Metadata Rule	When/then logic: show, require, restrict vocabulary terms
Metadata Quality Score	Completeness, vocabulary compliance, rule consistency — not experimental results
Template Review	Steward decision on a submitted version
Suggested Term	Candidate awaiting steward approval

Assay subtypes are out of the primary demo UX (ADR-0003). Use Template Version and Project Assay Link / Project Usage. A reusable variant concept remains future-direction documentation only.

← Technical hub · User guide