Your Repo Is the Prompt Now

Point a coding agent at a goal and it now writes the code, reads your project, and edits files on its own. The catch nobody prepares for: it reads the repo the way you'd read a prompt — and most repos were never written to be read that way.

Sometime in the last year, the way software gets made quietly flipped. You can hand a coding agent a goal — "add a login flow," "wire this up to the payments API" — and walk away. It reads your project, works out a plan, and edits files across the codebase on its own, no human at the keyboard for long stretches. There's a name for this now: vibe coding. You describe the vibe; the machine writes the code.

It feels like magic the first few times — and for the right job, it is. Point the genie at a weekend prototype and you have a working thing by Sunday night. That works because a toy ends. It ships once, it does one thing, and if a corner of it is wrong, nobody is harmed. For a project with a finish line, the genie is exactly the right tool.

Enterprise software has no finish line. It's many crafts running at once — a front end and a back end, the data and the algorithms under them, deployment, tests, security, governance, and the years of maintenance that outlast whoever wrote the first version. It lives for a long time, and every shortcut you took on a vibe compounds quietly until someone trips over it. "It felt right" is not something you can say to a security review, or to the engineer who inherits the code three years later. That's the wall the magic hits — not one hard bug, but a toy-shaped process meeting a problem that never ends.

So the interesting version of vibe coding isn't magic at all. It's the same engineering discipline that always made software trustworthy — correctness, tests, some agreed definition of done — with a team of agents doing the typing. And it turns on one dull question almost nobody asks before starting.

What does an agent actually read?

When a person writes the code, the repository is where the code lives. When an agent writes the code, the repository becomes the thing it reads to decide what to do. The folder layout, the file names, a stray README, the one-line note you left in a config — all of it is signal the agent acts on. Your repo is the standing prompt, whether or not you wrote it as one.

And an agent starts cold. A fresh session carries none of the context your team keeps in its heads — no memory of yesterday's decision, no feel for which folder is load-bearing and which one is dead weight. It reads what the repo tells it, forms a plan, and moves. Fast.

That speed is the whole problem. A repo built for people is full of quiet gaps — the things a teammate just knows and fills in without being asked. A cold agent hits the same gap and fills it with a guess. Then it commits the guess, confidently, across a dozen files, before you've finished your coffee. The failure mode of this era isn't the slow, cautious mistake you can catch in review. It's a fast, sprawling, sure-of-itself one.

The starting line moved

We think about it as three eras — our own shorthand, not an industry label. In SW-1, humans write the software. In SW-2, humans write it with a copilot suggesting the next line. In SW-3, agents write it and you govern the result — the case we make in full in AI Solutions That Actually Run. Each era needs a different day one.

For SW-1 and SW-2, a repo shaped for people was exactly right — people were the ones reading it. SW-3 swaps out the reader, and that changes what day one has to contain. The fix isn't a smarter agent; you don't get to control that. It's a repo a cold agent can read and get right the first time: one that says out loud what the rules are, where the boundaries sit, and what "done" means.

That repo is the thing we set up before anything else. We call it the scaffold — Sprint 0. The foundation you pour before the first feature, not the reinforcement you bolt on once the walls are already cracking.

A walk through the repo

The scaffold is deliberately small. It isn't a framework — there's nothing to install and no runtime to inherit. It's a repository you clone, made mostly of plain text: instructions, a few templates and config files, and a runnable skeleton any agent can take in at a glance. It's open source, MIT-licensed, and public at github.com/SynaptixLabs/scaffold. Clone it and the top level tells you almost everything:

scaffold/
├── .claude/                # THE BRAIN — the one source of truth for how agents behave
│   ├── roles/              #   class contracts: cpto, ux-design, dev (mission, scope, done)
│   ├── agents/             #   personas: janus, aria, core (a name + voice on a class)
│   ├── policies/           #   binding doctrine: commandments, reuse-first, e2e, doc-locations
│   ├── skills/             #   process procedures: implement-feature, design-review, qa-gate
│   ├── commands/           #   slash-commands (/janus, /aria, /core, /gbu, /plan, …)
│   └── 00_INDEX.md         #   the router: a task → which agent to activate
├── AGENTS.md               # the thin spine — the open standard every coding tool reads
├── CLAUDE.md · GEMINI.md   # per-tool loaders (point back to the brain, never restate it)
├── .agents/skills/ · .cursor/ · .gemini/   # more thin adapters (Codex, Devin, Cursor, Gemini)
├── backend/                # a room + its own AGENTS.md: test-first, module boundaries
├── frontend/               # a room + its own AGENTS.md: design kit as-is, real-browser E2E
├── ml-ai-data/             # a room + its own AGENTS.md: reproducible, no real user data
├── shared/                 # a room + its own AGENTS.md: generic only, no product leakage
├── project-management/     # the project's memory (its own section below)
├── scripts/                # check_adapters.py — the drift guard, runs in CI
├── tests/                  # test root; screenshots/ is the real-browser evidence target
├── start.sh · start.cmd    # bring the skeleton up: backend + frontend, out of the box
└── LICENSE                 # MIT

Or skip the reading and click around it — the same tree, explorable:

The brain: .claude/. This is where the rules actually live, and it's one folder on purpose. Inside are roles/ — the class contracts, each one a role's mission, its scope, its hard boundaries, and its definition of done; policies/ — the binding doctrine every agent obeys, from reuse-first to the real-browser rule to where docs are allowed to live; skills/ — the step-by-step procedures for recurring work like implementing a feature or running a review; and 00_INDEX.md, a short router that reads a task and names the one agent to activate. Everything an agent needs in order to know how to behave is here, and nowhere else.

The spine and the adapters: AGENTS.md. Next to the brain sits AGENTS.md, a thin file written to the open agents.md standard that twenty-plus coding tools already read. It doesn't restate the rules — it points back to the brain. So do the smaller adapter files for the other tools: a CLAUDE.md, a GEMINI.md, an .agents/skills/ folder for Codex and Devin, a .cursor/ folder, a .gemini/ folder. Each one is a pointer plus a small local delta, never a copy of what the brain already says. The pointing is the whole trick: you change a rule once, in the brain, and every tool inherits it — no per-tool config to keep in sync by hand.

The four rooms: backend/, frontend/, ml-ai-data/, shared/. This is the skeleton — the rooms real software actually gets built in — and each one carries its own local AGENTS.md with that craft's rules, so a cold agent that opens a folder learns the room's constraints on the way in. The backend's file says write the failing test before the code, add an integration test for every endpoint, and never reach into another module's internals — call its documented entrypoint. The frontend's says consume the design kit as-is: the tokens flow one way, and you don't re-derive a color or a spacing value in app code. The data room sets reproducibility as the acceptance bar — a result isn't done until it re-runs from versioned data, code, and config and produces the same numbers — and forbids real user data in the repo or the tests; synthetic fixtures only. The shared room's rule is that nothing product-specific may leak in: shared code stays generic, and the product's own behavior lives in the room it belongs to.

The honesty check: scripts/. One script, check_adapters.py, is the drift guard the whole pattern leans on. It verifies that every named agent resolves to a real role, that every pointer lands on a file that actually exists, that the command sets across the different tools stay in lockstep, and — the load-bearing one — that no adapter has quietly pasted a policy's body instead of pointing at it. It runs in continuous integration on every push and pull request, in a job that's always on, and locally in a single command. Consistency you can test, instead of consistency you cross your fingers about. A companion script even proves the guard itself still fails when you feed it drift.

The rest. tests/ is the test root; its screenshots/ folder is where real-browser evidence lands — the scaffold ships with three actual screenshots already sitting in it. A pair of setup scripts, start.sh and start.cmd, bring the skeleton up: a minimal backend and a frontend wired to it, running out of the box. The LICENSE is MIT; pyproject.toml and .env.example are the ordinary bootstrap furniture.

The team that comes with it

The scaffold doesn't hand you an empty frame — it comes with a small crew: three named agents who carry the same roles into whatever tool you summon them from. JANUS sets direction — it turns a fuzzy ask into testable acceptance criteria, reviews the work good, bad, and ugly, and holds the release gate, so nothing ships on "it felt right." ARIA owns how it looks — the design kit, accessibility, and visual acceptance checked in a real browser, never a paragraph describing how a screen might look. CORE builds — reuse before writing something new, a failing test before the code, real evidence before calling anything done.

They hand off in a loop, and the loop is the point: JANUS frames and gates, CORE builds, ARIA judges the look, and no agent accepts its own work. Each one answers to a role, not a personality — the role is the binding contract, and it wins even when a name would rather cut a corner.

The project's memory

Underneath the code sits the part that's easy to skip and most expensive to skip: project-management/. It's two things at once — the project's knowledge base and its governance layer — and it's written for the agents, not filed away for an audit. It's the memory a cold agent opens to learn what's true: not what the code does, but the intent behind it.

Four documents hold the standing truth. The PRD states the problem, the users and the jobs they need done, what's in scope and what's explicitly out, and the acceptance criteria the work will be measured against — product truth, kept deliberately separate from implementation. The architecture doc carries the technical truth: the stack, the boundaries between modules, the interfaces other code depends on, and which changes are one-way doors. The module contracts file is the one stamped must-read-before-any-code — it fuses the reuse protocol (search before you build: use what exists, extend what's close, or build new and justify why in a line) with a registry of who calls what, which is how a codebase full of agents avoids growing three copies of the same thing. And the decisions log is append-only, on purpose: a settled call doesn't get relitigated by an agent that wasn't in the room when it was made, and any one-way-door decision gets written down before it ships.

The rest of the folder is run like a sprint board, because the work moves in sprints — this is agile, aimed at agents. Each sprint is its own node. Its index.md holds the goal, the bounded scope — what's in, what's explicitly out — and the definition of done. Around it sit four folders: todo/ for the task cards, reviews/ for the good-bad-and-ugly verdicts the direction role signs, reports/ for what each piece of work actually did, and acceptance/ — the one that matters most — where the evidence lands and the human owner signs off.

project-management/
├── 0k_PRD.md               # product truth: problem, users, scope, acceptance criteria
├── 01_ARCHITECTURE.md      # technical truth: stack, boundaries, interfaces, one-way doors
├── 03_MODULE_CONTRACTS.md  # MUST-READ before any code: reuse protocol + who-calls-what
├── 0l_DECISIONS.md         # append-only log of settled, one-way-door calls
└── sprints/
    └── sprint_01/
        ├── index.md        # goal · bounded scope (in / out) · definition of done
        ├── todo/           # the task cards
        ├── reviews/        # good-bad-ugly verdicts, signed by the direction role
        ├── reports/        # what each piece of work actually did
        └── acceptance/     # the evidence — where the human owner signs off

The definition of done is where the discipline bites. A sprint closes only when its acceptance criteria are met with evidence, user-visible work has a real-browser test and screenshots, nothing regressed, reuse-first was respected, and the founder's acceptance is recorded on the page. No gate closes on a claim.

That gives a sprint a real lifecycle:

open → scope → build → review → acceptance (evidence) → close

It opens by copying the last one and resetting the goal, the scope, and the definition of done. It runs as task cards move through todo/, work gets built, reviews land in reviews/, and reports accumulate. It closes on the evidence in acceptance/, with the sprint index pointing at its own closure so the trail stays navigable months later. The scaffold practices this on itself: its first sprint's reviews/ folder already holds two real ship-or-don't verdicts, each one ending — pointedly — "verified by running, not reading."

This is the answer to the problem enterprise software poses and a toy never does. Something that never ends has to stay governable by whoever picks it up next — human or agent, months later, with none of the context in their head. The knowledge base is where that governance lives: yesterday's reasoning on the page, the definition of done written down, and the acceptance trail a fresh session reads before it changes a single line.

Starting one

Three steps. Clone it, cut it loose from our git history, and let the setup script bring it up:

git clone https://github.com/SynaptixLabs/scaffold.git my-project
cd my-project && rm -rf .git && git init
./start.sh setup     # installs deps, writes .env, runs the drift guard — sprint-1 ready
./start.sh           # brings up the skeleton: backend on :8000, frontend on :5173

(On Windows the same steps run through .\start.cmd.) Then open the folder in whatever coding tool you already use, and point your first agent at the constitution: "Read AGENTS.md, then help me swap the placeholders for our real name and stack." From there you're building — on a foundation made for agents, not one retrofitted for them after the first thing breaks.

Where this goes

That's the whole scaffold from the air — the shape, the team, and the memory, all in one clone. Each of the next articles takes one part of it and goes deep on how it's actually used. The next one follows the crew — JANUS, ARIA, and CORE — and shows how one team stays itself across five different coding tools, with no rewrite when you switch from one to the next. The one after that goes into the project-management discipline: how the sprints, the decisions, and the acceptance gates keep a real project honest over time — and then we stop describing and build something with it, a memory game from empty repo to working game, so you can watch the whole plan, build, and govern loop run end to end.

Vibe coding turned everyone into someone who can start a project in an afternoon. The scaffold is about the part no one vibes their way through: the months and years after the afternoon — the security review, the cold agent that shows up next spring and has to get the whole thing right. Toys end. The things worth building don't. Clone it and see.

---

Part 1 of the series — the whole scaffold from the air. Grounded in the public github.com/SynaptixLabs/scaffold repo (v1.0, MIT). More writing from us lives in the SynaptixLabs library. Draft for founder review — not published.