The setup

You are building a feature. Let's say a session manager for a service. You open your agent in the project directory and initialise the harness. Two minutes later you have the constitution, the requirements, the architecture. The agent derived them from the code and docs that already exist.

Gate 1: Design, before any code

You ask the agent to define the feature. It produces a single spec file that has the requirements, the design decisions, the file layout, the task list, and the acceptance criteria. Then it stops.

This is the first gate. You read the spec. You spot that the agent missed the idempotency requirement so that retries are safe. You add it. You say "approved."

Nothing was implemented yet. The one change you made just saved you a rework cycle later. That's the point of the gate. Catch the wrong assumption while it's still one line in a spec, and not when it is a hundred lines of code.

The build with one commit per task

Now the agent works. It follows the approved task list in order. One commit per task. No improvising, no adding features, no "I also noticed this other thing."

If a task fails three times, it stops and escalates instead of thrashing. You're not watching it type. You're reviewing a series of small, traceable commits, each tied to the approved plan.

Gate 2: The evidence, before release

The agent runs the evidence contract. The tests, acceptance criteria, the verification report. It marks the release as pending. Then it stops again.

You read the report. You approve. The agent merges, archives the feature, bumps the version, and records every decision in the build narrative.

Why this scales

Nothing here requires you to be a hero. The two gates take minutes. The agent does everything else. And because every decision is recorded, you don't have to hold the project in your head. Six months later, git log tells you what happened and why.

That's a human gate. Not ceremony. The two moments where a person looks at the work and decides, before it's too late and maybe too expensive to change.

The honest part

No harness guarantees the agent will follow it. The agent may skip steps, forget to update the log, or drift from the approved design. The harness makes the right path clear. It can't force the agent to walk it. Deterministic enforcement is the engine's job, not the protocol's. The protocol is the method, the engine is the paid layer.

So, you still have to watch, correct, and decide. A status command shows you where you are and what the agent should do next, without touching your working tree. But the human stays responsible. That's not a flaw in the harness. That's the whole point. A process that removes the human isn't more reliable, it's just less accountable.

FAQ

What is a human gate?

A point where the agent stops and a person approves before work continues.

What are the two human gates?

Gate 1: approve the plan and spec before any code. Gate 2: approve the evidence before the release.

Do human gates slow the agent down?

No. The two gates take minutes, and they catch wrong assumptions before they become code.

Can the agent approve its own work?

No. The agent cannot approve its own release. That decision is the human's.

The workflow is free. Bring any agent. Keep your standards. github.com/oystro/oystro-oss

Level 0: Manual driving

The AI does autocomplete. You write every line. The bottleneck is typing speed. This was most of "AI coding" in 2022. Feels primitive now.

Level 1: Lane assist and cruise control

The AI handles discrete tasks. You direct what to do. The bottleneck is how fast you can assign tasks. Copilot in 2023. Useful, but you're still doing most of the driving.

Level 2: The trap

The AI does whole features end to end. It feels transformative. Productivity is up, morale is high, the work is satisfying.

This is where most teams are. And it's a trap. In Shapiro's own words, the danger is that Level 2 feels so good that people stop here permanently. But you are still the rate-limiting factor. If you're not at the keyboard, nothing happens.

Level 3: Waymo with a safety driver

The agent works autonomously, but a human is still responsible and can take over. This is where harness engineering lives. The agent runs, the human gates. The agent builds one task at a time, the human approves the design and the release. You're supervising, not driving.

Level 4: Robotaxi

Full autonomy. No driver. This is the "dark factory" horizon. Interesting, but not where most teams are, and not where most teams should be aiming today. Getting to Level 4 safely means mastering Level 3 first.

Why the levels matter

The levels aren't a ladder that needs to be climbed. They are a diagnostic. Most teams think they're at Level 3 or 4 when they're actually at Level 2, because Level 2 feels like the destination.

The harness is what gets you from Level 2 to a real Level 3. The agent runs autonomously, but the human gates stay, the evidence stays, the decisions stay recorded. That's not slowing the agent down. It's what makes going faster safe.

FAQ

What are the five levels of AI-assisted development?

Level 0 manual, Level 1 lane assist, Level 2 whole features (the trap), Level 3 autonomous with a human gate, and Level 4 full autonomy.

What is the Level 2 trap?

Level 2 feels transformative, so teams stop there, still the rate-limiting factor, and still typing.

What level are most teams actually at?

Level 2, even though many believe they're at Level 3 or 4.

How do you get from Level 2 to Level 3?

A harness: the agent runs autonomously, but a human still gates the design and the release.

The workflow is free. Bring any agent. Keep your standards. github.com/oystro/oystro-oss

It feels magical. It feels like 10x leverage. Until month three.

The Entropy Trap: Speed Without Structure

Vibe coding optimizes for instant momentum, not long-term maintainability. When you ask an AI assistant to build an isolated greenfield script, it excels because the entire context fits within a single prompt window. But real production software does not live inside an afternoon chat session. It lives across quarters, hundreds of commits, evolving API contracts, and teams of engineers.

As the codebase expands, four critical failure modes inevitably emerge:

• The Ephemeral Reasoning Void: The crucial architectural decisions - why a specific database abstraction was chosen, what concurrency hazards were mitigated, why an alternative design was rejected - disappear the second the chat tab closes. The code remains, but the reasoning is gone forever.

• "Done" Without Receipts: The assistant announces that the task is finished. But did it actually run the regression suite? Did it check whether changing that shared struct broke a downstream consumer? In vibe coding, "done" is a polite promise until production breaks.

• Context Amnesia: Every new chat session starts completely from scratch. The assistant re-reads the entire repository and re-derives decisions it already made - often slightly differently - so patterns, style and behaviour drift. The token burn is a symptom; the lost accuracy is the real cost.

• Silent Drift Across Repositories: Modern products rarely live in one folder. A change in a contracts library quietly breaks the backend API, which silently breaks the CLI. Without cross-repo verification, team coordination collapses back into frantic Slack messages.

The core problem: AI coding assistants generate code exponentially faster than human engineers can read and verify it. Without an operating harness, AI assistants become firehoses of software entropy.

The Solution: Harness Engineering

The alternative to vibe coding is not going back to manually typing every line of boilerplate. The alternative is Harness Engineering.

Instead of letting an autonomous assistant run unconstrained and hoping for the best, Harness Engineering surrounds the AI with a deterministic, fail-closed operating harness governed by three non-negotiable principles:

1. Hard Human Checkpoints, Not Post-Hoc Reviews

Nothing gets built without plan approval. Nothing ships without evidence verification.

• Gate 1 (Pre-Build): The assistant is strictly prohibited from writing code until a human reviews and approves the architectural plan and test commitments.

• Gate 2 (Pre-Release): The assistant cannot finalize or push code without producing cryptographic, reproducible test receipts.

2. Persistent Project Memory

Your project needs a durable memory stored with the project - not trapped inside a vendor's proprietary web UI:

• A single live snapshot (handover.yaml) that records active tasks, open decisions, and the single next action.

• An append-only journal (SLICE_LOG.md) that documents why each change was made and what proved it.

A fresh assistant session reads six lines and resumes in seconds.

3. Proof Over Promises

"It compiled on my machine" is not evidence. A true harness executes the agreed verification checks, computes cryptographic hashes over the test outputs, and binds the verification receipt to the Git commit. If evidence is missing, pre-push hooks fail closed.

FAQ

Why does vibe coding break at scale?

Four failure modes emerge as a codebase grows: lost reasoning, "done" without receipts, context amnesia, and silent drift across repositories.

What is vibe coding?

Prompting an agent with vague intent and accepting the output without structured verification.

What's the alternative to vibe coding?

Harness engineering: hard human checkpoints, persistent project memory, and proof over promises.

Does vibe coding work for prototypes?

Yes. It breaks as the codebase grows and needs maintenance.

The workflow is free. Bring any agent. Keep your standards. github.com/oystro/oystro-oss

Lack of a cutting-edge model was never the bottleneck. Lack of a good harness is.

Why teams chase the wrong half

Most AI-engineering conversations revolve around models. Which one is smarter? Which one is bigger? Which one costs less per token? All of it is chasing the generation half of the problem.

But generation was never the hard half. Generating plausible code is easy. Generating code that's "right" for a specific project, with its specific constraints and history, is a completely different problem. And that's not solved by a better model. That's solved by structure around the model.

A harness is that structure. It's the difference between asking an agent to "build this" and giving it a process where the agent states its approach, you approve it, and it builds one task at a time with evidence. Same model. Completely different reliability.

The two halves of why harnesses matter

When people talk about harnesses, they focus on capability. Yes, a better harness makes an agent more capable, because it stops the agent from wandering and keeps it pointed at the approved plan.

But there's a second half that gets less attention. And that is about verification. A harness with gates and recorded decisions makes the agent's work "auditable". You can see what the agent assumed, what it approved against, and what actually shipped. On a project that runs for months, this second half is the one that matters. The risk isn't about "did the agent score 95%." The risk is "three weeks later, no one can explain why this exists."

Capability gets you speed. Verification gets you trust. A real harness gives you both.

The category is forming

The fact that Y Combinator is running a paper club on harnesses, and Uncle Bob Martin is doing video rants on "rethinking harnesses," tells you the conversation has tipped. Harness engineering is becoming a named category, the way DevOps did a decade ago.

This is a shift worth paying attention to. The teams that treat their harness as a first-class citizen, and not "just some prompts and scaffolding," will eventually be able to trust what their agents build.

FAQ

Why does the harness matter more than the model?

Generation was never the hard half; verification is. A harness makes the agent's work checkable and recorded.

What is a harness?

The structure around the model: the gates, the evidence, and the record of decisions.

Does a better model make a harness unnecessary?

No. Capability gets you speed; verification gets you trust. You need both.

What is harness engineering?

The emerging discipline of designing that structure, the way DevOps became a discipline a decade ago.

The workflow is free. Bring any agent. Keep your standards. github.com/oystro/oystro-oss

In harness engineering, the agent stops before it writes a single line of code. You review the design and approve the contract. Then it builds one task at a time, one commit per task, with evidence. Every decision is captured, reviewed, and recorded.

What's the difference? It's not about speed but who's in the driving seat.

Why vibe coding feels fine until it doesn't

Vibe coding gets a lot right. It's fast. It's satisfying. You describe what you want in plain language and watch code appear. For a prototype or a weekend project, that's often enough.

The problem pokes its head up in longer projects. In a longer build cycle, the agent makes numerous decisions. Each decision looks reasonable then but isn't written down for future reference. A few weeks later a feature ships, and nobody can say why it works the way it does, or what the assumptions behind it were.

We think it's a bug in the agent. No, it's the structure. When a decision is a conversation that's already gone, the decision never happened.

What a gate changes

A harness stops the work when it is important for a human to look at it before it proceeds.

Before a single line of code is written, the agent states its approach and its assumptions. You read them. You change what's wrong. You approve. That approved design becomes the contract the agent builds upon.

Then, before release, the agent shows you the evidence such as the tests, the acceptance criteria, the verification report. You read it. You approve.

Two gates. Everything in between, the agent handles without babysitting. But the two moments that matter are yours.

The same agent, two roles

The harness doesn't constrain the agent. It changes what the agent is asked to do at each stage.

During the define and design phase, the agent is a collaborator. It asks questions, finds gaps, challenges assumptions. It thinks with you.

During the build phase, the agent is a disciplined executor. It follows the approved task list in order. It commits after each task. It does not improvise.

Same agent, two jobs. The collaborator produces a better design. The executor produces reliable code. The gate between them is what keeps the two from falling over each other.

Who's responsible

Here's what matters. If the output is wrong, the first question is "Did we review the design carefully?" and not "Did the agent fail?"

That's the shift. In vibe coding, you are downstream of the agent's decisions. In harness engineering, you are the one making them. The agent is fast and tireless. The harness makes its speed trustworthy by putting you in control.

Who this is not for

To be blunt. If you prefer vibe coding, that's a valid choice, and this isn't for you. If you want the agent to make all the decisions, again, not for you. If you think review gates are overhead, this will feel like friction you don't want.

The harness is not about team culture. It is about your standards.

FAQ

What is harness engineering?

A way of working where the agent stops for human approval at two points: the design before code, and the evidence before release. Every decision in between is recorded.

What's the difference between vibe coding and harness engineering?

In vibe coding the agent generates and you accept or reject after the fact. In harness engineering the agent stops before it writes code, so you approve the design first.

Does a harness slow the agent down?

No. It moves review earlier, where a wrong assumption is one line in a spec instead of a hundred lines of code.

When is vibe coding fine?

For prototypes and weekend projects you don't need to maintain or scale.

The workflow is free. Bring any agent. Keep your standards. github.com/oystro/oystro-oss

Why does every agent session start from zero?

When a team works on a long-running project, the context is not just in anyone's head. It has seeped into the codebase, the PR reviews, the decisions recorded in comments and commit messages. After a few weeks or months, a new person inducted into the project reads, absorbs and continues building based on what's there.

For an agent, every session starts cold. The model only sees your prompt and the files in front of it. The model is unaware of the past decisions you made, the constraints you discovered and the reasons why you did things in a certain way. Unless you type it again!

So we become the memory. The sole entity holding the thread.

This is a risk nobody accounted for. As the agent generates code, you try to absorb it. The context keeps on growing while your memory remains constrained.

We have experienced this and watched teams go through it too:

• Senior engineers spending time every day to reiterate a project's constraints.

• Relying on one person who has been there from the start and knows the whole architecture.

• The "quick resume" that turns into an endless rabbit hole because the summary has messed up.

You write a summary on Tuesday, it veers a bit by Thursday, and by Monday it misleads. So you stop trusting it and start reworking everything from scratch. It is not a tool problem but a process issue.

Why a better model isn't the fix

A better model doesn't remember the previous session. A bigger context window doesn't help either. It just lets you stuff more reminders. The fix is to make the process hold the context.

We have been experimenting with a simple approach. Even before the agent writes a single line of code, it has to write down its approach and assumptions. That is reviewed. Then the agent works one task at a time, one commit per task, and at each step it records what it did and why. The session can end anywhere. The thread is on a disk, not in someone's memory.

The effect was that we shifted the importance from holding things in memory to reviewing things properly. The agent keeps working, the context keeps accumulating, and you judge the work instead of reconstructing it.

You can't call this a productivity hack. It is moving from babysitting an agent to a reliable process on a long-running project.

The question we are seeking answers to

We are building this as an open-source harness that wraps any agent with these gates, so that you're not locked into any one tool. We want answers from people who have lived this:

Have you lost threads across agent sessions on long projects, or is that not an issue for how you work?

We are better off hearing that "this is a non-issue for us, and here's why" than "this looks cool". We are eager to hear what happens on your project when a session ends and a new one starts. That's what we want to know.

FAQ

What does "every agent session starts from zero" mean?

Every new session begins with no memory of earlier decisions. The model only sees your prompt and the files in front of it.

Why doesn't a better model fix this?

Remembering past decisions isn't a capability problem, it's a persistence problem. A bigger context window just lets you re-supply more context.

How do you keep context across agent sessions?

Write the approach and assumptions down before any code, work one task per commit, and record what changed and why. The thread lives in the repo, not in someone's memory.

Is this a tooling problem or a process problem?

A process problem. The context has to live somewhere durable, not in a chat that ends.

Repo: https://github.com/oystro/oystro-oss