You Don't Have an Architecture Problem.
You Have an Artifact Problem.

The artifact was never designed for this

For the past 40 years, the documents we built around software — specs, PRDs, architecture diagrams, user stories, README files, system contracts — had one job: helping humans communicate intent to other humans.

A product requirements document existed so a PM could explain to a developer what needed to be built. An architecture diagram existed so a senior engineer could hand context to a new team member. A user story existed to be read in a sprint planning meeting, then largely forgotten.

These artifacts were written for humans. They were measured by readability. They decayed slowly — and that was fine, because a human developer could infer, fill gaps, ask a question, apply judgment.

The artifact is now load-bearing infrastructure. It was never designed to be.

That design assumption is now broken.

What changes when machines join the loop

When a single AI agent reads your spec, you have a prompting problem. Improve the instructions, iterate on the output, move on.

When N agents and sub-agents read that same spec — each one building on decisions made by the last, each one making locally rational moves based on partial context — you have a fundamentally different problem.

Researchers studying multi-agent system failures in 2025 identified the primary failure mode clearly: actions carry implicit decisions, and conflicting decisions carry bad results — and the orchestrating layer aggregates outputs but cannot detect conflicts it cannot see. The system doesn't fail because the code is wrong. It fails because two agents, reading the same under-specified instruction, made different assumptions about what it meant. Both were locally correct. The system is globally incoherent.

When teams diagnose this, they look at the wrong layer. They tune the orchestration. They swap models. They extend the context window. They rebuild the prompts.

Almost nobody asks: was the artifact designed to be read by a distributed system of processors?

Almost always, the answer is no. Because nobody designed it that way. Because until very recently, nobody had to.

The coherence layer that doesn't exist yet

Here's the honest map of where the industry is right now.

None of these conversations is asking the question that sits underneath all of them:

What is the design discipline for creating artifacts that are simultaneously human-editable and machine-executable — coherent across N processors — carrying shared intent that survives a model upgrade?

That question doesn't have an answer yet. It barely has a name.

We're calling it the coherence layer. Not because we've solved it. Because we think naming it is the first step.

Why this matters right now, not in 18 months

You might be thinking: this is a problem for teams running sophisticated multi-agent systems. We're building an MVP. This doesn't apply yet.

It applies already — just in a smaller form.

Every time you give a spec to Claude Code, Cursor, or any AI coding agent and it builds something that technically works but violates an assumption you held in your head, you experienced a version of this failure. The artifact didn't carry the full intent. The machine filled the gap with its best guess. The gap was invisible until production.

Now multiply that by the number of AI touchpoints in your SDLC. Multiply again by the number of agents you'll be running in 18 months.

The teams building architecture today that accounts for this will absorb new capabilities gracefully. The teams that don't will hit walls — not because their code is bad, but because their instruction layer was designed for a world where only humans were reading it.

What we think "artifact-first" design looks like

We want to be clear: we haven't solved this. Nobody has fully solved this yet. We're building specshop.dev inside this transition, not after it. The SDLC we're describing doesn't exist in complete form anywhere — including in how we work right now.

But here's what we believe is directionally true.

The spec is the only layer with permanence.

Code is the current implementation of intent. Models get replaced. Stacks get updated. Agents get swapped. The spec is the thing that should survive all of that — but only if it's designed to.

Artifacts need dual legibility. Readable by humans — editable, maintainable, owned. Parseable by machines — structured, unambiguous, executable. These are not the same design constraints. A Confluence page written for a developer handoff is not the same artifact as an instruction set that a sub-agent can execute and propagate downstream without introducing drift.

Guardrails are architectural components, not afterthoughts. In a multi-agent system, a guardrail isn't a rule you add to a prompt. It's a contract shared across every node that touches that part of the system. It needs to be versioned, maintained, and treated with the same seriousness as an API contract or a database schema.

Coherence is designed, not inferred.

When a sub-agent makes a decision that contradicts what the orchestrator assumed, the system needs somewhere to return to — a ground truth. If that ground truth lives in someone's head, or in a Slack thread, or in a document nobody updates, the system has no recovery path. Coherence has to be a first-class design concern, not a hoped-for emergent property.

The SDLC is still changing — including ours

Here's what the provocateur position usually leaves out: the people making the argument are also inside the transition they're describing.

We are.

When we built Beta Launch over nine years and 120+ products — for clients in five countries, across USAID, fintech, logistics, healthcare — our spec was the thing that survived client changes, team changes, and technology changes. We learned that the hard way more than once. The spec was always more important than we treated it.

Then AI arrived. And slowly, and then all at once, everything the spec was communicating to humans, it now also had to communicate to machines.

We don't have the final workflow. The industry doesn't have the final workflow. What we have is a decade of evidence that the spec — not the code, not the architecture diagram, not the PR — is the document that needs to outlast everything else. And a strong conviction that designing it for dual legibility, for machine coherence, for shared intent across N processors, is the design discipline that most teams are about to desperately need.

That's why we built spec-first. That's why spec2web exists. That's why The Spec is the entry point to everything we do.

Not because it's good process. Because it's the only coherent ground truth in a distributed system.