Our Practice Engineering · 2026

Working With Agents

We build with agents — and stay in control.

Specs are first-class. Agents read them, humans validate them, code traces back to them.

High-level spec → API + UX spec → Technical spec → Code top-down · traceable

PART 01

First-Class
Artifacts

The specs are the asset. Everything else is derived from them.

The Spec Stack

Top-down, traceable back.

Versioned in Git Single source of truth Agents read, humans validate

derives ↓ traces up

High-level spec

OpenSpec · proposal.md · design.md

What & why — behavior and requirements

API spec

OpenAPI schema

API contract — frontend and backend build to it

UX spec

screens · interactions · prototype

Interaction contract — screens and behavior

→ lives in references/

Technical spec

OpenSpec · per endpoint, beside the code

How — implementation intent

—

Code & tests

Derived — and traceable back to every layer

Accountability

Know where every spec came from.

Trace any line of code

Code

↑Technical specOpenSpec

↑API spec · UX specthe contracts

↑High-level specOpenSpec

Provenance, on every OpenSpec spec

sourceextracted / authored / inferred

extracted_fromrepos + paths

extracted_atISO date

confidencehigh / medium / low

PART 02

Team
Workflow

Most stages pair a technique with the artifact it produces.

The Flow

From intent to implementation.

01 Clarify intent Humans align on the real problem. Human only

02 High-level spec Finalize it — PR to the spec repo, review.

03 Breakdown Into API + UX spec; start API and prototyping discussions.

04 Commit contracts Commit the API spec + UX spec.

05 Technical spec + build Per endpoint: generate the technical spec, then implement with tests.

Skills & Artifacts

Stage → skill → artifact.

Stage	Skill / technique	Artifact produced
Clarify intent	Humans only — no AI	Clarified intent, agreed scope
High-level spec	OpenSpec workflowextract-behavior PR + review	proposal.md · design.md
Breakdown	Derive contracts — API discussion + UX prototyping	API spec · UX spec · prototype
Commit contracts	openspec validate	Committed API spec + UX spec
Technical spec + build	Per endpoint: spec then implement, with tests	Per-endpoint technical spec · code + tests

PART 03

Individual
Workflow

How each of us drives a task, day to day.

Daily-Driver Skills

Three skills, three moments.

Clay marks what an individual drives.

brainstorming Before any code Turn a vague idea into a clear, agreed design before implementation starts.

code-reviewer Before merge Review changes across correctness, readability, architecture, security, and performance.

api-and-interface-review At the boundary Pressure-test API and interface contracts for stability and a clean shape.

UX Workflow

From spec to hand-offs that frontend and QA can use.

01 Brainstorm the interaction From the high-level spec, brainstorm and generate an OpenSpec of the interaction.

02 Prototype Build the interaction on our headless component system.

03 Showcase & iterate Show a colleague, collect feedback, then go back and refine. ↻ back to 02

04 Hand off to frontend Deliver the UX spec into the high-level spec's references/. → references/

05 QA-verifiable spec Convert the OpenSpec + references/ prototype into a spec QA can read and verify against. → QA verifiable

PART 04

Context
& Harness

What we feed the agents — and the loop we're automating.

What The Agent Reads First

Context before action.

CLAUDE.mdProject rules, conventions, and style

AGENTS.mdOpenSpec agent instructions (managed block)

hadlc.yamlNested HADLC domain map

project.mdTech stack, NFRs, constraints

MEMORY.mdPersistent memory across sessions

the specsThe first-class artifacts themselves

Good context in → fewer wrong assumptions, accurate output.

In progress

What We're Building

Closing the loop, end to end.

01 CI runner Triggers the loop on every change

→

02 Agent Picks up and does the work

→

03 Monitor Watches the live site & logs

→

04 Generate issues Files what it finds for triage

Humans triage the issues — the blast radius stays visible.

Why All This

Everything here serves four things.

01Agents move fast — we never lose our grip on the system.

02The blast radius of a mistake stays small and visible.

03We keep iterating the process itself.

04Specs are the source of truth. Code follows specs.

Read the spec first.

Questions & discussion