Why the next leap in AI engineering is not a smarter model. It is a quieter discipline about which model gets which tokens.

https://leanpub.com/clarityforge


Monday Morning, Eight Hours Later

You opened your coding agent on Monday morning. You typed eleven words: “add multi-tenancy to the billing service.”

You came back from lunch. You came back from another meeting. You came back from the standup where someone asked you if the agent was almost done, and you said yes because you wanted it to be true.

Eight hours later, the agent has touched forty-three files. Half the test suite is yellow. The other half is green for reasons you cannot fully reconstruct. Your tech lead pings you on Slack: “can you walk me through what changed?”

You cannot. Not honestly.

The code, line by line, looks fine. The diff is even, on average, plausible. But there is no document anywhere that says why the tenant boundary was put at the Account model instead of the Workspace model. No artifact you can point at that explains why the migration is forward-only. No record of the moment when the agent silently picked a strategy that contradicts an ADR your team wrote eleven months ago.

The code is real. The intent is gone.

If you have lived this Monday — and I think you have — the rest of this article is for you.

The Comforting Lie We Tell Ourselves About Skill Packs

The market’s answer to this problem is to sell you more stuff.

More skills. More plugin bundles. More MCP servers. More “47 must-have prompts” PDFs. More YAML in .claude/ than you have functions in src/. The premise, never said out loud but always implied, is that if you just install the right combination of community-curated capabilities, the Monday-morning failure stops happening.

It does not.

I have watched teams install eleven skills in a week and ship the same broken Monday three weeks later. The skills are not wrong. They are real capabilities. They simply do not address the failure mode. The failure mode is not insufficient capability. The failure mode is unresolved intent.

A skill pack is a costume. The thing underneath the costume is unchanged. If the underlying engineer is feeding an ambiguous fuzzy desire to a model and accepting whatever comes back, the model will still produce something that runs, still produce something that looks fine, still produce something whose why evaporated three seconds after the diff was applied.

The fix is not a bigger toolbox. The fix is a smaller, more disciplined sequence of moves, and a deliberate choice about which model sees which step.

The Two Models in Your Stack — and Which Tokens Belong to Each

There are, in any honest AI-engineering workflow, two distinct jobs being done.

Job one is deciding what to build. This job is approximately 5–10% of the tokens you spend, and 90% of the leverage. It is the job of asking, what does “multi-tenancy” actually mean in this codebase, given that we already have a workspace model, an ADR about row-level security, a half-migrated legacy permissions table, and a customer contract that says tenants cannot see each other’s audit logs? It is the job of pinning ambiguity down to the point where the question “is the diff right?” has a non-vibes answer.

Job two is producing the diff. This is approximately 90% of the tokens, and — when job one has been done properly — 10% of the leverage. The hard thinking is already over. The acceptance check is already written. The relevant spec is already loaded. The model is now translating a small, precise instruction into a small, precise change.

The mistake almost every engineer makes — and almost every “AI coding workflow” tutorial implicitly endorses — is using one model for both jobs.

You hand the entire problem to Claude Opus, or to GPT-5, or to Sonnet 4.6, and you let it both decide and execute. The frontier model is brilliant at deciding, but you are now paying frontier rates for thousands of tokens of pure execution. Worse, the same context window is now juggling architectural reasoning and line-level diff production. The reasoning gets diluted. The execution drifts. You end up with both a high bill and a soft spec.

Or — the symmetric failure — you hand the problem to a cheap local model from the start. The execution is fine. The decisions are catastrophic, because nobody asked the load-bearing questions before code started flowing.

Both failures share a root cause: you did not separate the two jobs, so the two kinds of tokens were never routed to the right kind of model.

The Architect / Contractor Split

The pipeline I am about to argue for — and that I have written a book around — names these two roles explicitly.

The Architect is a frontier model. Opus. GPT-5. Sonnet 4.6+. Whatever sits at the top of the leaderboard the week you are reading this. The Architect is expensive per token, and that is fine, because the Architect’s tokens are the load-bearing ones. The Architect interviews you about what you actually want. The Architect grills the proposal until every soft claim has a measurable acceptance check or is explicitly listed as out of scope. The Architect reconciles the new idea against the codebase’s existing constitution — the domain language, the ADRs, the invariants. The Architect emits a small, tight, durable artifact: a one-page proposal, a flat list of small tasks, a spec delta the next engineer can read in five minutes.

The Architect does not write your code.

The Contractor is a local open-weight model. Gemma 4 27B. Qwen 3. Whatever runs comfortably on your hardware, in your network, on your data. The Contractor is cheap, private, fast — and most importantly, the Contractor receives a problem that has already been disambiguated. The Contractor is handed exactly one task at a time, plus the minimum subset of the spec needed to execute it, plus the acceptance check that closes it.

The Contractor does not decide anything load-bearing. It cannot. The decision was already made upstream.

This is the entire trick: you let each model do the job it is actually good at, and you build a small set of durable artifacts in between so that no decision has to be re-derived inside the Contractor’s context window.

Why This Is Not “Just Use a Cheaper Model to Save Money”

I want to head off a misreading.

This is not about cost. Cost is a side effect.

If you frame this as “use a cheaper model to save money,” you will route the wrong work to the wrong model and you will ship the same Monday-morning failure for half the price. Cheaper bad code is not the win.

The frame is token routing as a discipline.

Frontier tokens are for the irreversible. Architectural decisions. Boundary placement. Invariant changes. Anything where being wrong means a multi-quarter cleanup. You spend Opus tokens here because Opus is the model that catches the question you did not know to ask.

Local tokens are for the reversible. A function body. A migration file. A test case. A small refactor inside a tight boundary. You spend Gemma tokens here because the work is mechanical, the answer is checkable in sixty seconds, and the diff is throwaway if the spec is right.

The artifacts in between — the spec, the proposal, the tasks, the ADR — are how the cheap model knows what the expensive model decided. They are also how you know. And your tech lead. And the engineer who joins the team in nine months.

This is the part the skill packs cannot give you, no matter how many of them you install.

What This Looks Like in Practice (Without Spoiling the Whole Pipeline)

I am not going to walk you through every stage of the pipeline in this article. That is what the book is for. But I want to show you the shape of it, because the shape is what makes the token routing work.

Picture three surfaces.

The first surface is the spec. A small directory in your repo with a proposal, a task list, and a delta describing the post-change state of the capability you are touching. This is what the Architect produces. It is what the Contractor reads. It is what your tech lead reviews. It is what survives in the repo after the PR is merged.

The second surface is the config. The files that tell future agent sessions how this repo expects to be worked on. CLAUDE.md. AGENTS.md. Permissions. Conventions. When the current change introduces a new convention, the config gets updated in the same change. No drift. No “I’ll document it later.” Documentation theatre is not a real thing; you either update the config now or you ship a repo that lies to every future agent that opens it.

The third surface is the human-facing summary. The PR description. The Slack-pasteable TL;DR. The one-sentence acceptance check that the non-engineer stakeholder can read and confirm matches what they asked for. This is what makes the change legible to people who will never open the spec directory.

All three surfaces flow from the same upstream artifact. There is no separate “communication phase.” Communication is a projection of the spec onto three audiences.

Between these surfaces sit a small number of moves — the moves the Architect runs, the moves the Contractor runs, the moves you run to verify or escalate. Each move is small. Each one is a copy-paste prompt. None of them is clever. The cleverness is in the sequencing, not in any individual step.

That is the part I am not giving away here. The sequencing is the book.

The Quiet Killers

Three habits will destroy this pipeline faster than any tooling failure.

The first killer is the “let me just type the proposal myself” shortcut. You skip the interview because you know what you want. You do not. The interview is not the model figuring out your intent — it is the model forcing you to figure out your own intent. Skipping it produces proposals that look fine and execute badly.

The second killer is the “tasks.md is just for me” excuse. If the task list is informal, you cannot dispatch tasks discretely, which means you cannot verify discretely, which means the Contractor’s failures compound silently across files. The task list is the runbook. Either it is precise, or the pipeline degrades into the same vibe-coding loop it was supposed to replace.

The third killer is the “I’ll update the spec after the code” hope. You will not. Nobody does. Specs updated post-hoc are documentation theatre. The pipeline inverts the order on purpose: spec before code, archive after merge. Never code, then spec, then wishful thinking.

If you can name these three failure modes, you are already most of the way to operating the pipeline well, even before you read a single chapter.

What This Buys You, Concretely

Run this for a quarter, on real changes, and three things happen.

Your monthly frontier-token bill drops by an order of magnitude. Not because the frontier model got cheaper. Because you stopped using it for execution. The Architect spends a few thousand tokens on the part of the work that actually requires Opus-grade reasoning, and the Contractor — running on your box, on your data, on a model whose weights you control — handles the rest.

Your audit trail becomes legible. Every change has a spec. Every spec has a why. The PR description writes itself, because the human-facing summary was always one of the three artifacts you were producing. When the tech lead asks “why is the tenant boundary at Account instead of Workspace?” you do not say “because the agent decided.” You point at the section of the proposal where the choice was made, the line in the ADR that pinned it, and the acceptance check that closed it.

Your team stops shipping code nobody can defend. This sounds soft. It is not. It is the difference between an engineering organisation that compounds knowledge and one that produces ever more code while remembering ever less about why any of it exists. The intent stays recoverable from the artifacts, not reconstructed from git blame and three Slack threads from October.

The Smallest Possible Pitch

The pitch is this.

The next leap in AI engineering is not a smarter Opus. Opus is already smart enough. The next leap is the quiet discipline of deciding what to send to Opus and what to send to the model running on your laptop — and building the small set of durable artifacts that let the two cooperate without losing the intent on the way.

This is what I mean by clarity trading.

It is not a skill pack. It is the practice that makes every skill pack you already own actually pay off. It is what fixes the Monday morning where the code looked fine and the intent was gone.

The Book

I wrote The Clarity Forge: Local AI, Done Right because the same shape kept showing up across teams I worked with, and because the existing literature was selling them costumes instead of practice.

It is a mini-book. A weekend read. A Monday-morning toolkit. It contains the full pipeline, the copy-paste prompts that connect each stage, a worked example end to end, and a catalog of the anti-patterns I have watched destroy this discipline in real teams.

It is the companion to my longer book, The Clarity Engineer: Code Is the Side Effect, which names the underlying discipline — clarity trading, world models, intent documentation, agent identity, networked agentic organisations. The Clarity Engineer gives you the framework. The Clarity Forge gives you the working version of the pipeline on a single page.

If your Monday mornings have looked like the one at the top of this article — if the code looked fine and the intent was gone — the book is for you.

📖 The Clarity Forge — on Leanpub. 📖 The Clarity Engineer — on Leanpub and Amazon.

Stop vibe-coding.

Start clarity-trading.


Volodymyr Pavlyshyn writes and builds at the intersection of agent orchestration, AI engineering discipline, and the durable artifacts that make software teams legible to themselves.

Originally published on Sovereign Agentic AI on Substack.