/systems · the workflow, and the receipts
I build systems that write it for me. Here is the pipeline.
Typing was never the valuable part. The valuable part is deciding what to build, how it is structured, what “correct” means, and how you will know. Delegate the typing and that work does not shrink, it becomes the whole job. So the workflow treats generation as the cheap step and engineers everything around it.
Five stages after the problem, each feeding the next, each leaving an artifact you can inspect. Every specimen below is quoted from a working file.
- Problem
- Architecture
- Context
- Agents
- Validation
- Software
Before the pipeline · How I got here
How I got here
None of this arrived fully formed. I have used AI in some capacity since roughly 2022, and the pipeline above is where four years of handing over more of the work ended up. The work did not just get bigger; it changed in kind, twice. Once when the machine could finally see the repository instead of a pasted snippet, and again when prompting became specifying.
Five regimes of delegation, and what stays human in each, described:
- Five regimes of delegation, side by side, ordered by who establishes that the work is correct. Under each one: what the AI can reach, what I bring to it, and how the work is checked.
- Autocomplete completes the line I am already writing. It reaches the editor buffer. I bring every decision, continuously. It is checked by reading it as it appears.
- Generation produces a pattern I would recognize. It reaches a chat window. I bring knowing what to ask for. It is checked by recognizing wrong on sight.
- Delegation builds a unit I described. It still reaches only a chat window, by copy and paste. I bring the description and the review. It is checked by reviewing the diff carefully.
- Iteration tries, checks, and tries again. This is where it reaches the repository itself, which is the single biggest change in the sequence: the same size of task, but the machine can now run the checks. I bring the goal and the guardrails, and I judge the result.
- Specification works against written rules and specs, reaching the repository and the toolchain around it. I bring the constraints and the definition of done. It is checked by gates it cannot argue with.
- Two breaks matter. The first is when it can finally see the code, which is a change in reach rather than in task size. The second is when prompts become specifications, which is a change in method rather than in model.
- Running underneath all five, and still running: using it to learn. Research, explanation, and being tutored through unfamiliar ground. That is the one use that was never delegation.
- Current practice sits at the right-hand end: plan in one model, scrutinize in another, then implement against the specs that survive.
Sec. 01 · Architecture
Architecture
Before anything is generated, the system is designed: where the source of truth lives, who maintains it, what the output must be. The capabilities-demo generator is the clearest example: one Excel workbook, a Python generator, one self-contained HTML file, and non-technical colleagues maintaining all of it.
input · Excel workbook: the single source of truth
feature rows with Include flags · client master list · tech stack · domain tagging
process · Python generator
screenshots base64-inlined with caching · lightboxes · auto-appearing domain filters
output · one portable HTML file
self-contained capabilities demo · public/private chips · client cross-linking
— toggle Include rows in Excel → trimmed per-RFP versions
Sec. 02 · Context
Context
An agent is only as good as what it has been told. For new builds the documentation package comes first: positioning, voice, verbatim source content, requirements with decision-authority rules (what the agent may decide versus what it must escalate), design direction, IA, plus repo guidance and a kickoff prompt. The agents read all of it before writing a line. The clearest exhibit is the CrossFit MF package, fourteen docs plus a prompt, and the site it produced is its own case study.
Knowing what to specify is the actual skill. The package’s table of contents is not a template I found; it is years of watching projects fail at the seams, written down as the questions an agent has to have answered before it starts.
Sec. 03 · Agents
Agents
The package ends with a kickoff prompt: a standing instruction set for how to work, not just what to build. Decompose the build into workstreams and fan them out to subagents, including one whose only job is to adversarially review the others. Loop until done, where “done” is defined by the quality gates, never by the agent’s optimism. And when a fact is missing, track it in an open-items file instead of inventing something plausible.
The reviewer is often a different model. A plan gets drafted in one, torn apart in another, refactored against what survives, and only then implemented. Two models trained by different labs fail in different places, which is worth more than asking one of them to check its own work. The agents reach past the repository too, into GitHub, Vercel, Sentry and the project tools around them, so the loop closes on what actually shipped rather than on what was written.
Sec. 04 · Validation
Validation
Delegation without verification is just hope.
Every build loops on the same gates: build, typecheck and lint clean; accessibility and performance within budget; and zero claims that cannot be traced to a source document. On a product the gates have to survive other people and a year of Tuesdays, so they move into the repository where nobody can skip them:
# CI for apps/showcase — lint, drift rules, types, unit tests, build, e2e.
# Path-filtered to the showcase app + the shared packages it is built from,
# mirroring the headwaters spheros-ci.yml pattern (one workflow per app).
name: showcase-ci
on:
push:
branches: [main]
paths:
- "apps/showcase/**"
- "packages/**"
- "tooling/**"
- "rules/**"
- "sgconfig.yml"
[excerpt: the same path filter repeats for pull_request]
concurrency:
group: showcase-ci-${{ github.ref }}
cancel-in-progress: true
jobs:
checks:
name: lint · drift · types · unit · build
[excerpt: checkout, pnpm, node 22 with a lockfile-keyed cache]
- name: Lint
run: pnpm lint
- name: Drift rules (ast-grep)
run: pnpm lint:drift
- name: Typecheck
run: pnpm check-types
- name: Unit tests
run: pnpm test
- name: Build
run: pnpm build
e2e:
name: e2e (playwright)
needs: checks
[excerpt: same setup, then a chromium install]
- name: E2E tests
run: pnpm --filter showcase test:e2e
- uses: actions/upload-artifact@v4
if: failure()
with:
name: playwright-report
path: apps/showcase/playwright-report/
retention-days: 7The order is the argument: the cheapest failure runs first. Lint, then the eleven ast-grep drift rules that turn an architecture violation into a build failure, then types, then unit tests, then the build. End-to-end tests run only once all of that is green, and a failed run uploads its Playwright report, because a red check nobody can read gets retried rather than fixed. The same machinery carried the extraction that created the monorepo: 92 unit tests, then an exit gate of 27 end-to-end tests and a 398-route build. Those numbers do not exist because I typed the tests faster. They exist because the agents cannot merge past them.
The same discipline covers maintenance. Ordinary changes run as written tasks with guardrails and stop conditions (what to do, how to verify it, when to stop): one such task has Claude Code append eight clients to the capabilities-demo config workbook via a provided openpyxl script, regenerate the HTML, verify the counts, and stop on any anomaly (“if the workbook fails to open as a zip, stop — do not overwrite”). Ordinary maintenance, delegated safely.
The guardrails are the whole trick: a provided script rather than a described one, a verification step, and a stop condition that names the failure it fears.
Sec. 05 · Software
Software
The pipeline ends where it should: in shipped software. The portable capabilities demo colleagues maintain. The CrossFit MF rebuild, built end to end through this workflow.
Each of those systems gets the full case-study treatment, with context, decisions, and what stayed human:
Up next
That is how the software gets built. Who builds it, the years before code, and what I am looking for next are the other half of the story.