architecture notes · software factory

From a vague idea to a proven pull request

A field note on designing an agentic software factory: the architecture, the lessons that shaped it, and one request traced from intent to evidence.

The useful unit is not an agent. It is a controlled flow of intent, work, and proof.
— the design constraint behind this repository

01 · the architecture

Keep meaning, coordination, execution, and proof separate

The system has four boundaries. Product files define what should exist. A deterministic roadmap defines what may start. Isolated workers change code. Tests and an independent audit produce proof before delivery.

Design choice: models propose and implement inside boundaries; small programs own state transitions, dependency calculation, ports, and handoffs.

watch · then argue with me

The idea in motion

A useful provocation before the architecture: why skip a development process that already works? The player includes sound and the native timeline, so jump to the part you want.

Andrej Karpathy and Stephanie Zhan on From Vibe Coding to Agentic Engineering. Use the timeline to skip ahead.

02 · follow one request

A small interactive sequence of the data flow

Select a step. The highlighted message shows what moves, who owns it, and why the next boundary exists.

Step 1 — intent: the product owner’s request becomes a durable PRD. Later agents read the same meaning instead of reconstructing it from chat history.

03 · the support layer

Programmatic support is the point

Agentic work becomes useful when the surrounding system handles the boring certainty. A model can reason about a bounded task. A program can dispatch that task, enforce its prerequisites, isolate its files, record its state, and decide what happens next.

Architecture · the control plane around the agents

Dispatch the right work

The roadmap is a DAG, not a model’s suggestion. A dispatcher starts only tickets whose prerequisites are complete, then gives each builder a clean worktree and the relevant context.

Make state observable

Ready, running, testing, blocked, and done are program states. They survive a context window, support retries, and make it possible to see where a request actually is.

Let agents stay agentic

Agents spend their attention on judgment and implementation. Scripts handle ports, handoffs, rebases, tests, and evidence. The machine carries the clipboard so the agent can do the thinking.

04 · what changed my thinking

Lessons applied, not merely cited

Context is a resource

Research and planning happen before implementation. Builders receive a small, relevant context slice. This applies the RPI pattern and avoids asking one context window to hold the whole project.

Control flow belongs in code

The roadmap script computes prerequisites. Agents do not invent dependency edges in prompts. This makes parallel work safe and makes the state machine inspectable.

Proof needs another reader

A builder’s self-test is necessary but not sufficient. An independent tester checks criteria and event chains. Confidence comes from correlated evidence, not from a successful generation.

Vibe coding raw is certainly… a choice

Software development life cycle (SDLC) is the old, boring, unkillable term for "how software actually gets from idea to production": requirements, design, build, test, deploy, maintain. It's been the known-working system for decades. Somewhere in the last two years, a chunk of the industry decided the large language model (LLM) era means skipping every step of it and just typing vibes into a chat box until something compiles.

That's fine for a weekend toy. It is not fine for a codebase you'll still be reading in six months. The people who actually run agents at scale for a living say the same thing, on the record, with receipts:

Andrej Karpathy

Co-founder, OpenAI · ex-Tesla AI · coined the term

"There's a new kind of coding I call 'vibe coding', where you fully give in to the vibes... and forget that the code even exists."

Dex Horthy

Founder/CEO, HumanLayer

"Own your prompts. Own your context window. Own your control flow."

Dex Horthy, again

on brownfield codebases specifically

"The more you use the context window, the worse outcomes you get."

The pipeline, stage by stage (click one)

This is the actual lifecycle this repo runs, taken straight from its own README. Every card below is the same shape: what happens, why it's built that way, and what the raw-vibes version of that same step usually looks like.

01 Product interview ▸

What happens

Before any code, the coordinator interviews you for the real product requirements document (PRD) and outcomes. It gets written to docs/product/PRD.md as the one source of truth every later agent reads from.

The wisdom

This is Horthy's RPI loop's "Research" step, forced out of your head and into a file. It matters because of the Dumb Zone: dump a vague idea straight into an agent's context and by the time you're 60% through the window, recall is already degrading. Write the distilled version once, and every downstream builder reads that instead of the mess.

Raw vibe coding"Build me a dashboard" typed into a chat box. No PRD to check a bug report against later, so every disagreement becomes a fresh feature debate.

This factoryOne interview, one file, every agent from here on reads the same requirements instead of re-guessing them.

02 Whole architecture ▸

What happens

docs/architecture/overview.md gets drawn once against the full PRD, before any feature work starts.

The wisdom

"Own your context window" — one of Horthy's 12 factors. Architecture decided once and referenced by every feature, instead of re-decided inside whatever context window happens to be open that day.

Raw vibe codingArchitecture gets re-derived every session. Day 40's structure quietly disagrees with day 4's.

This factoryOne architecture doc, Git-tracked, that every feature's implementation view has to agree with.

03 Feature views + parseable roadmap ▸

What happens

Each feature gets its own mini-PRD and architecture note. roadmap.json encodes the dependency graph as a directed acyclic graph (DAG), computed by a script, not guessed by a model.

The wisdom

"Own your control flow." Ordering is deterministic code, so it cannot hallucinate a dependency that doesn't exist or forget one that does.

Raw vibe codingFeatures ship in whatever order feels productive, and it's on you to remember which ones quietly depended on each other.

This factorybin/roadmap-sync computes the DAG and refuses to sync a roadmap that doesn't resolve.

04 Ready builder, isolated worktree ▸

What happens

bin/kanban-dispatch spins up one low-cost builder subagent per ready ticket, each in its own Git worktree, running in parallel up to a concurrency cap.

The wisdom

Isolation is the exact guardrail Horthy's failed "dark factory" experiment was missing. Parallel agents stepping on the same files is how a codebase measurably degrades over three to six months, even with strong prompts. Worktrees make interference structurally impossible instead of policy-enforced.

Raw vibe codingOne shared branch, one context window, every parallel idea fighting over the same files.

This factoryN builders, N worktrees, zero shared mutable state until integration.

05 Self-test + correlated logs + optional AAR ▸

What happens

The builder writes structured observability and runs its own deterministic tests against the live app before it's allowed to signal done. It can also write an after-action review (AAR) flagging what to optimize next time.

The wisdom

Anything with an objective pass/fail belongs to the agent that wrote the code, with evidence correlated to the exact commit, not to a person's memory of "yeah I clicked through it and it seemed fine."

Raw vibe coding"Looks like it works" after one manual click-through. No artifact proves it, no note for future-you about what almost broke.

This factoryLogs and test results tied to the commit that produced them, checked before the next stage even starts.

06 Programmatic rebase + post-rebase test ▸

What happens

bin/prepare-for-test rebases the candidate onto current main and reruns the whole-project check (bin/project-test) after the rebase, not before.

The wisdom

This structurally rules out "worked in isolation, broke on integration" — the same failure Horthy names as the reason lights-off factories rot: nobody re-checks after the world underneath them moved.

Raw vibe codingMerge conflicts get resolved by whoever's prompting that day; tests, if they exist, ran before the merge.

This factoryRebase first, then test against what main actually looks like right now.

07 Independent criterion/event audit ▸

What happens

A separate validator worker checks the builder's claimed criteria and events, without touching product code and without reading the builder's own tests.

The wisdom

The auditor never wrote the code it's auditing, so it's structural independence instead of trust in a self-report. This is Horthy's leverage-point factory in one stage: automate the check, keep a real verification step that isn't graded by the thing being graded.

Raw vibe codingYou are your own reviewer, in the same context window that wrote the code, grading your own homework.

This factoryA second worker, with no memory of writing it, re-derives whether the criteria actually hold.

08 Optional subjective user test ▸

What happens

For anything that needs a human reaction rather than a pass/fail, execution pauses in the browser UI and hands you a scenario card: setup, what to do, what to judge, what's already verified.

The wisdom

Objective checks are automatable. "Does this feel right" is not. Encoding that split instead of asking a model to guess at your taste is the whole point of this stage.

Raw vibe codingEither the agent rubber-stamps itself, or you re-review every line by hand because nothing separates provable from felt.

This factoryYou only get pulled in for the part that actually needs your judgment.

09 Push exact candidate + GitHub pull request ▸

What happens

bin/ticket-integrate pushes the literal commit that passed every prior check, not a re-generated one, and opens the pull request (PR) automatically.

The wisdom

Horthy calls the PR "a batch artifact from the email-patch era" and wants it dead in favor of real-time review. This factory keeps the PR — audit trail and compliance still matter — but automates everything upstream of it, so review collapses toward his ~20-minutes-not-hours number instead of vanishing entirely.

Raw vibe codingNo PR, or a PR nobody wants to open because there's no correlated evidence behind the diff.

This factoryA PR backed by test results, an audit, and a rebase that already happened.

10 Merge → fast-forward → next dispatch ▸

What happens

Once GitHub merges into remote main, local main fast-forwards and bin/github-sync automatically dispatches the next roadmap-ready ticket from the DAG.

The wisdom

The loop closes on its own. Throughput compounds because dispatch doesn't wait on a human to notice a ticket got unblocked — this is the automation Horthy credits for a 2–3x speedup once the upfront planning hour is paid.

Raw vibe codingSomeone has to remember to unblock the next task by hand, every single time, forever.

This factoryMerge triggers the next dispatch. Nobody has to remember anything.

What's next in the pipeline

None of this is done cooking. Here's what's getting wired into the factory next, not bolted on the side, actually dispatched through the same lifecycle above.

3-tier memory system core

The Dumb Zone is a memory problem, not a doc-layout problem, so it gets a memory-shaped fix: long-term memory for facts that don't expire, project memory for this roadmap's state, and working memory scoped to the current ticket only. No agent loads more context than the tier it's working in actually needs.

Graphify integration visibility

The roadmap DAG already exists as data in roadmap.json. Graphify turns it into an actual live graph in the project UI, so blockers, parallel tracks, and critical paths get seen instead of read line by line.

Brownfield refactoring measures hardening

Everything above assumes greenfield. Horthy's brownfield war story (a 300k+ line Rust codebase, handled with RPI instead of raw prompting) is the target case: dependency-mapping a module before any refactor touches it, and a regression boundary around legacy code that new agents can't quietly widen.

Quality-of-life skill roadmap tooling

Skills getting dispatched into the builder's own toolbelt next:

Ponytail — injects a "does this even need to exist" ruleset before the builder writes a line; benchmarked up to 94% less code for the same task. 21st.dev Magic MCP — Model Context Protocol (MCP) server that drops in production-grade UI components from a prompt instead of hand-rolling every button. Vercel agent-browser — browser automation CLI for the builder's own live-app tests — reportedly ~82% less context per run than Playwright MCP. Claude Code cybersecurity skills — Trail of Bits' security-research and audit skills, folded into the builder's own automated test pass instead of a separate pentest step.

Considerations: prior art already on the table

None of this is invented in a vacuum. There's a live cluster of open-source projects attacking "coordinate a fleet of coding agents" from different angles. Worth naming, so it's clear what's already adopted versus what's still being weighed.

Herdr already in use

herdr is the terminal multiplexer this factory's README already names as the supervision layer for its coordinator, builder, validator, logs, and UI panes. It's agent-native — a background Rust runtime that owns each agent's terminal session so work survives a closed laptop lid, and surfaces a single working/blocked/done attention queue instead of N terminal tabs.

Gastown evaluating

Steve Yegge's Gas Town coordinates fleets of coding agents through git-backed issue tracking ("beads") and a Bors-style merge queue, reportedly scaling to 20-30 concurrent agents. It overlaps with this factory's dispatch-and-worktree model; on the table for the day ticket volume outgrows the current concurrency cap.

Goose evaluating

Goose, Block's general-purpose agent (now under the Agentic AI Foundation), is Model Context Protocol (MCP)-native with 70+ extensions and a bring-your-own-key model. It isn't a pipeline by itself, so it's being weighed as an alternate execution backend for builder/tester roles, not a replacement for the DAG or the independent audit stage.

Buzz watching

I had this one mislabeled before: the project associated with Jack Dorsey is Buzz, not Hive. Built by Block and released under Apache 2.0, Buzz is a self-hostable workspace where humans and AI agents share the same rooms. Its relay-backed model gives people, agents, workflows, Git events, and project memory one place to coordinate; agents can also use buzz-cli for JSON-in, JSON-out tool calls. That makes Buzz relevant prior art for the human-facing collaboration layer around this factory, while this factory remains focused on deterministic task dispatch, isolated worktrees, and independent proof.

Read the code, not the pitch

Every claim above is a script or a doc path in this repo, not marketing copy. Start with the README, or go straight to the source.

View the repo →