The repo is the prompt.
How I run engineering work with coding agents: one substrate of committed artifacts, skills and guardrails, and a growing set of workflows that ride on it. Requirements to design is the first one with numbers. The rules below are what let the next one be cheap.
Why believe it
00One method has numbers. Three facts say the practice does not depend on it.
A practice page built on one case study is a hypothesis. These are the parts of that case study that were never about wireframes.
Proof · 01 · schema parityTwo extractors, one shape.downstream tasks are source-agnostic
The extractor for the requirements tool and the extractor for Word documents emit the same five files. Every downstream task, from cross-reference to decomposition, reads that shape and never asks where a requirement came from.
Proof · 02 · agent-agnosticTwo agents, one skill set.swap the agent, keep the work
The repo carries configuration for two different command-line agents. Same skills, same guardrails, same artifacts. Swap either agent and the work survives, because the work is bound to files and git, not to a vendor.
Proof · 03 · second operatorSomeone else ran it.clone, one env var, run
A designer cloned the repo, set one environment variable, and drove the pipeline to produce twenty-odd traced screens against context and conventions they did not write. Replication is a result, not an assertion.
Rule · 01
Context comes from structure, not from a long prompt.
One authoritative instruction file. An index kept current on purpose. Config committed beside the work. The agent reads the tree, not a paragraph. Onboarding is a clone and one environment variable; nothing else is secret.
Shows up in: every repo I set up.
Rule · 02
Extract once, into a stable schema, in the repo.
One read-only capture lands a content-hashed artifact. Every later task reads that instead of re-querying the source. The artifact keeps every ID and link back to the system of record: it is a cache, not a fork. Extraction is expensive and one-time. Everything after it is cheap.
Shows up in: Requirements → Design, Traceability audit.
Rule · 03
The source of truth is never agent-writable.
By construction, not by convention. The HTTP method is hardcoded in the scripts the skill runs, so the skill's behaviour toward the source is deterministic: no prompt, no model and no caller can turn a read into a write. The design-system library is never a write target. That is what makes it safe to point at a live system of record.
Shows up in: every workflow that touches a system of record.
Rule · 04
Complexity lives in the skill, not the prompt.
The prompt that pulled a full specification section was three sentences. The skill behind it carries the traps found the hard way. Skills are committed, arrive by cloning, and are the interface a workflow exposes. If your prompts are getting longer over time, the complexity is in the wrong place.
Shows up in: every committed skill.
Rule · 05
Guardrails are scripts with tripwires, not instructions to be careful.
A naive pull returns most of a section, and the failure is silent until review. So the extraction stops instead of guessing when a boundary looks wrong, reconciles counts, and checks for the requirements that subtree matching drops. Verification is deterministic or human. Agent output is never graded by the same model family that produced it.
Shows up in: Requirements → Design, The Meter and the Judge.
Rule · 06
Capture direction as it is given.
Every mid-build correction is logged verbatim, typos intact, paired with what it produced. The opening brief is always boring; the corrections are the method, and fidelity gets ratcheted rather than specified up front. This is the same argument as extracting requirements to the repo, applied to intent.
Shows up in: design direction logs, demo build logs.
Rule · 07
Every number carries its provenance.
Nothing goes on a page that cannot be backed on request. An estimate is labelled an estimate in the same sentence it appears in. What did not survive the last hop is named before the room names it. This is not modesty. It is what lets the verifiable claims survive being questioned.
Shows up in: every scorecard on this site.
Rule · 08
Author, Operator, Consumer.
Few people need to construct context. Most need to invoke well-constructed context. Authors write skills and set guardrails. Operators run an existing skill against new input, from whatever interface fits them. Consumers read the artifact and never touch an agent. The mistake is trying to make everyone an Author.
Shows up in: how a workflow is handed off.
Rule · 09
Bind to the substrate, not the vendor.
Files, git, markdown. Every agent tool can read a repo, so that commitment costs nothing and forecloses nothing. A purpose-built platform binds you the day its model stops fitting your process.
Shows up in: tool choices, every time.
The cast
01Five stations. Two are read-only. One is me.
Every workflow is some path through these. The two stations marked read-only are sources of truth and are never written to. The dashed one is where the guarantees stop.
01 · source of recordRequirements systemread-only
Specs, use cases, work items, each with an ID. Read through a single GET-only helper.
02 · the promptThe repoartifacts · skills · config
Committed artifacts, skills, instruction file, config. Content-hashed. The map agents read.
03 · the handsAgentsClaude Code + one more
Claude Code plus a second CLI agent. Same skills, same guardrails. Interchangeable by design.
04 · the systemDesign-system libraryread-only
Components and tokens, read over MCP, never a write target. Output matches by construction.
05 · the outputsScreens · demos · docs · codeoutside the guarantees
Figma frames, operable demos, requirement documents, generated code. Auditable up to the last hop.
I am not a station. I am the one who decides what goes in, reads the reconciliation line before anything goes out, and signs.
How it scales
02It isn't the command line. It's addressability.
"Not everyone wants a terminal" is the right objection and the wrong diagnosis. What people lose when they leave the terminal is not tab-completion. It is being able to say path/to/file.md:142 and have it resolve identically for the person, the teammate and the agent. Keep that, and the interface is a per-audience choice.
| Tier | What they do | What they need | Interface | Demonstrated |
|---|---|---|---|---|
| Author | Writes skills, constructs context, sets guardrails | Full addressability | CLI or IDE | Yes · one or two people per repo |
| Operator | Runs an existing skill against new input | A trigger and a result | CLI, IDE, desktop app, scheduled job, chat | Yes · clone-and-operate by a second person |
| Consumer | Reads the artifact, never touches an agent | The artifact | Figma, Word, the requirements tool, this site | Yes · reviewers and leadership |
Bright lines
03What I never let an agent do.
Engineering bright lines, not design ones. Each is a rule I have watched a naive setup break.
Never · 01Write to the system of record.
Read-only is a property of the code path, not a line in the prompt. If an agent could write back, it eventually will.
Never · 02Grade its own family's output.
Same-family graders inflate pass rates. Use a different model family, a deterministic check, or a person.
Never · 03Put a number on a page without a source.
The page circulates without me attached. If I can't point at the file, it isn't a result yet, it's a claim.
Never · 04Present invented behaviour as specified.
An operable demo has to invent what the spec never said. Those inventions are the most persuasive part and the least agreed. Label them.
Never · 05Let the prompt carry what the skill should.
A prompt that grows is a skill that wasn't written. Move the knowledge to where it is versioned and shared.
Never · 06Sign off without reading the reconciliation.
Item count and stop item deserve two seconds of human attention every run. Those two seconds are the job.
The methods
04Six workflows run on this. One has a published scorecard.
Live means a method page with sourced numbers exists. In use means I run it on real work today and the write-up is not published yet. Nothing is listed that I do not run today.
Method · 01 · liveRequirements → Design pipeline19× smaller than the raw payload
Read-only extraction, committed schema, traced wireframes, operable demo. Five moves, four guardrails, and what did not survive the last hop.
Method · 02 · in useRequirements decompositionwrite-up pending
A change request or system-level use case in; convention-compliant subsystem requirements out, with the activity and sequence diagrams model-based engineering practice expects, in a document that follows the programme's documentation standards. Run routinely today.
Method · 03 · in useTraceability auditwrite-up pending
The same read-only scripts that build the repo also audit it. Link-walk analytics over the requirements tool's API: orphan detection, use-case gap assessment, coverage matrices. Rule 02 and rule 05, applied to the source itself.
Method · 04 · in useScreens → operable demowrite-up pending
Static screens as the only specification, a working application out. Already the artifact a customer reviewed, and the one they reacted to. Open item: labelling every invented behaviour as a candidate requirement, so the persuasive parts are also the agreed parts.
Method · 05 · in useTranscript synthesiswrite-up pending
Meeting transcripts synthesised beside the specs, so "what did the customer actually say about X" is answerable in-workspace, with the answer pointing back at the line it came from. A skill I run routinely.
Method · 06 · in useCustomer-facing markupswrite-up pending
Requirement validation during the requirements phase, done against a markup the customer can react to rather than a paragraph they have to imagine. Ties into the design workflow and has already validated real requirements.
Related case study: The Meter and the Judge is not a method. It is where rule 05 (never grade with the same family) was measured rather than asserted.
Honest scorecard
05What this page does not claim.
Not claimed · 01That it generalises beyond n=1 by measurement.
One workflow has a published scorecard. Five more are in routine use without sourced numbers yet. The generality argument rests on schema parity, agent parity, a second operator, and the same scripts serving both extraction and audit. Stated, not hidden.
Not claimed · 02A measured before-number.
The four-to-six-weeks baseline behind the pipeline's speed claim is a practitioner estimate from a working session. Every other number traces to a file. This one does not, and the method page says so.
Not claimed · 03That skills maintain themselves.
Skills are code without tests, and the cheap validation path (grade with the same model) is ruled out by rule 05. A silently degrading skill is expensive and nobody owns that yet.
Not claimed · 04That it works below the terminal.
Every artifact so far came from someone at a command line. The Operator-without-a-terminal tier is the adoption ceiling, and it is untested. The cheapest test is a scheduled coverage check that posts a report.