The job description is becoming a spec file

Open a job description for a role you’ve hired before. “Owns the weekly revenue report.” “Strong communicator.” “Comfortable with ambiguity.” Now try to run it. You can’t. There’s nothing in there a machine could execute, nothing you could test, nothing that would tell you on a given Tuesday whether the job got done. A job description is a wish list written to a human, and it works only because the human silently fills in the thousand details it leaves out.

The moment you try to hand that same role to an agent, the wish list collapses. And what replaces it looks a lot like a file an engineer would commit.

For an agent, a role becomes a versioned, testable spec, and that changes how you design every job, including the human ones.

What a job description quietly assumes

A job description is the most casually written document in the company, and we get away with it because of one assumption: the reader is a person who already knows how the world works.

“Owns the weekly revenue report” assumes the reader knows what revenue is, where the numbers live, what “weekly” means at this company, who needs the report, what counts as a good one, and what to do when a number looks wrong. None of that is on the page. It’s all carried in by the human, for free.

That free import is the whole trick. It’s also the reason job descriptions don’t compose, don’t transfer, and quietly rot. Two people read the same line and do the job two different ways. Someone leaves, and the half of the role that lived only in their head leaves with them. You can’t diff a job description against last quarter’s, because there was never a precise version to diff against.

A job description is a contract written in a language only humans can run, and only badly.

We tolerate all of this because, for a person, it mostly works. People are astonishingly good at filling gaps. Hand a competent new hire a vague paragraph and they’ll reconstruct the intent, ask around, watch what others do, and converge on something reasonable within a few weeks. The vagueness isn’t a bug for humans. It’s a feature we lean on.

The naive way: hand the agent the same paragraph

So here’s the obvious first move, the one almost everyone tries. You have an agent now. You have a job description. Hand one to the other.

It fails, and it fails in a way that teaches you exactly what was missing.

The agent does not know what “good” means, so it produces something plausible and confidently wrong. It doesn’t know where the numbers live, so it guesses or asks forty questions. It doesn’t know that “weekly” means Monday 9am before the leadership sync, so it runs on Friday. It has no opinion about what to do when a figure looks off, so it either silently ships the bad number or stops and waits. Every gap the job description left for a human to fill, the agent leaves empty, and an empty gap is a defect.

This is the same failure every team hits the first week they try to delegate real work to an agent. The instinct is to blame the model: it’s not smart enough, it hallucinated, it didn’t “get it.” But the model isn’t the thing that’s underspecified. The role is. You handed it a document engineered for a reader who fills gaps to a reader who doesn’t, and then acted surprised when the gaps showed.

The fix is not a smarter agent. The fix is a better document.

The better document is a spec

Watch what you actually do to make the agent succeed, and you’ll find you’re not writing a job description anymore. You’re writing a spec.

You stop saying “owns the weekly revenue report” and start saying what the report is: these inputs, from these sources, transformed this way, delivered to these people at this time, in this format. You write down what makes one good, the checks it must pass before it ships, the numbers that must reconcile, the things that should never appear. You write down what to do at the edges: if a source is late, if a figure jumps more than some threshold, if two systems disagree. The vague paragraph becomes a precise object with inputs, outputs, acceptance criteria, and failure handling.

That object has a name in engineering. It’s a spec.

And the instant the role is a spec, it inherits everything specs already have. You can version it, last month’s role and this month’s role are two commits, and you can read the diff. You can test it, run the agent against a known input and check the output against the acceptance criteria, the same way a unit test checks a function. You can review it before it ships, because it’s a written artifact a second person can read and sign off on. You can reuse it, the spec for “weekly revenue report” at one company is a starting point for the next, instead of tribal knowledge that walks out the door.

The naive job description had none of these properties. Not one. We just never noticed, because the human reader was quietly supplying all of them in their head, re-deriving the intent, holding the edge cases, judging their own output, carrying the version history as memory. Move the work to an agent and that hidden machinery has to become explicit. The spec is what it looks like when it does.

The key idea is simple. For an agent, a role becomes a versioned, testable spec, and the act of writing that spec is the act of finally saying what the job actually was.

The spec is alive, not a one-time form

There’s a trap here, and it’s worth naming before anyone falls into it. A spec sounds like more paperwork, a longer, stricter job description you write once and file away. That’s not it, and a filed-away spec is a dead one.

The reason a spec beats a job description is that it runs in a loop. The agent does the work against the spec. You read the output. When the output is wrong, you don’t retrain a person over six months, you edit the spec and rerun. The acceptance criteria that the agent failed becomes a new test. The edge case nobody anticipated becomes a new branch in the failure-handling section the moment it bites you once.

A job description is written at hiring time and then frozen, drifting further from reality every month until it’s fiction. A spec is the opposite. It gets more accurate over time, because every surprise the work throws at it gets folded back in. The role you can’t quite describe on day one becomes, fifty corrections later, a role you’ve described with precision, and the description is executable.

This is why “the job description is becoming a spec file” is not a metaphor. It’s a literal change in the kind of document a role is, and in what you can do with it. You don’t manage a spec by giving feedback in a quarterly review. You manage it the way you manage any living artifact under version control: you edit, you test, you ship, you watch, you edit again.

What this does to the human jobs

Here’s the part that surprised us, and it’s the reason we think this matters beyond agents.

Once you’ve written a real spec for the agent half of a role, the human half of that same role suddenly looks under-defined by comparison. You’ve just proven you can say precisely what good output is, what the inputs are, what to do at the edges. So why was the human version ever a vague paragraph? Specifying the agent forces a clarity that, it turns out, the humans deserved all along.

This doesn’t mean turning people into machines that run a spec. It means the opposite. When the mechanical, specifiable part of a role, the part you can write down as inputs, outputs, and acceptance criteria, is captured in a spec an agent can run, what’s left in the human’s hands is the part that was never specifiable to begin with. Judgment about which numbers actually matter this quarter. Taste about what “good” should mean as the company changes. The decision to throw out the spec entirely because the situation changed underneath it. The relationships, the context-reading, the knowing-when-the-rule-is-wrong.

The spec captures the part of a job you can write down. The point of capturing it is to free the part you can’t.

For an agent, a role becomes a versioned, testable spec. For a human, the role becomes everything that isn’t in the spec, and that’s a better job than the one they had, because the lowest-leverage parts of it just moved off their plate.

The turn: the org chart was always a draft

We used to think a company was a set of people in boxes. We don’t anymore. A company is a set of roles, and the people are how we currently run them. The org chart isn’t the company, it’s one implementation of it, the way a job got staffed this year.

When roles were vague paragraphs, you couldn’t see that. The role and the person were welded together, because the role only existed in the person’s head, executed in the person’s particular way. Make the role a spec and the weld breaks. The role becomes a thing in its own right, written down, testable, improvable, that a person runs today and might be run differently tomorrow. The human stops being the role and starts being the author of it: the one who decides what the spec should say, judges whether it’s still right, and rewrites it when the world moves.

That’s not a demotion. It’s the most leveraged thing a person in a company can do, own the spec for how the work works, instead of being the only place the work is written down. The job stops being be the role and becomes design the role. And designing a role well, deciding what “good” means and when the rule should bend, is exactly the work no spec can do for you. It’s the work worth keeping.

The job descriptions in your drawer were always drafts of something more precise. We just never had a reader strict enough to force us to finish them.

---

That’s what we’re building at Apollo Space, an operating system where roles are written down well enough to run, so the people who used to be the job get to design it instead. The first spec you write for an agent will feel like extra work. Then you’ll read it back and realize it’s the first honest description of the job you’ve ever had.