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
01
PART 01

New First-Class Citizens
Multi-Level Artifacts

The specs are the asset. Everything else is derived from them.
02
First-Class Citizens

Beyond code — documents go first-class.

Code was always the one artifact we version, review, and trust as the source of truth. Now these documents earn the same standing:

High-level specthe what & why
API specthe service contract
UX specthe interaction contract
Technical specthe how, per platform
03
Multi-level spec stack

Top-down, traceable back.

derives
traces back
00
Intent
The problem to solve — a bug, a request, a refactor
From Jira / Confluence / Redmine
01
High-level spec
openspec · proposal.md · design.md
What & why — behavior and requirements
02
API spec
OpenAPI schema
API contract — frontend and backend build to it
UX spec
markdown — screens, layouts, interactions, flows
+ HTML prototype
Interaction contract — screens and behavior
→ lives in references/
03
Technical specs (in openspec format)
Backend
Web
iOS
Android
—
Code & tests
Derived — and traceable back to every layer
04
Accountability

Know where every spec came from.

Trace any line of code
Code
↑Technical specopenspec
↑API spec · UX specthe contracts
↑High-level specopenspec
↑IntentJira / Redmine
Open Knowledge Format · OKF
Google's vendor-neutral markdown + YAML. Every spec is one concept.
typerequired
titlehuman-readable name
descriptionone-line summary
resourcesource repos + paths
tagsdomain, capability
timestampISO date
05
PART 02

Team
Workflow

Most stages pair a technique with the artifact it produces.
06
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.
07
Skills & Artifacts

At each stage: a skill, an 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 · HTML 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
08
Team Workflow · Stage 01

Clarify intent

PO · PM · RD · UX · Architect·no AI
HumanPO presents the problem & contextdomain context
→
HumanTeam discusses to understand itfacilitation
→
HumanAgree scope: in / outscoping
→
OutputClarified intentagreed scope
No AI yet — humans agree on WHAT before agents touch HOW.
09
Team Workflow · Stage 02

High-level spec

PM · RD+coding agent
HumanHand off the refined intentintent
→
AgentFormalize into openspecopenspec workflow
→
AgentDraft proposal · design · specsextract-behavior
→
HumanValidate & PR reviewspec review
→
OutputHigh-level specproposal.md · design.md · specs/
AI proposes, human validates — loop until the spec holds.
10
Team Workflow · Stage 03

Breakdown

RD · UX+coding agent
AgentDerive the API contractOpenAPI
→
AgentDraft UX spec + HTML prototypeheadless components
→
HumanAPI & prototyping discussionapi-and-interface-review
→
OutputContractsAPI spec · UX spec · HTML prototype
Decomposition is where scope creep hides — discuss before committing.
11
Team Workflow · Stage 04

Commit contracts

RD+coding agent
AgentValidate the specsopenspec validate
→
HumanApprove & commitreview
→
OutputCommitted contractsAPI spec + UX spec
The contracts are frozen — downstream builds to them.
12
Team Workflow · Stage 05

Technical spec + build

RD+coding agent
AgentGenerate per-endpoint technical specopenspec
→
AgentImplement with testsTDD
→
HumanCode reviewcode-reviewer
→
OutputWorking codetechnical spec · code + tests
AI proposes, human validates — per endpoint, until each Task is done.
13
PART 03

Individual
Workflow

How each of us drives a task, day to day.
14
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.
15
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 an HTML prototype 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
16
PART 04

Context
& Harness

What we feed the agents — and the loop we're automating.
17
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.
18
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.
19
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
20