A plan document and an agent prompt are the same file. Humans can live with vague specs because they can ask. Agents can't. Every ambiguity becomes a guess.

Principle

The Plan is the Prompt

Why this matters

Humans have a clarification loop. Agents don't.

👤

Human engineer

reads the spec

1.read spec

2.spot ambiguity

3.ask: "did you mean X or Y?"

4.get answer

5.implement

Ambiguity is tolerable. It gets resolved in the loop before code is written.

🤖

Agent

reads the same spec

1.read spec

2.spot ambiguity

3.ask a question

4.get answer

5.guess + implement

No loop. Every ambiguity collapses into a guess. The aggregate of guesses is the gap between what you asked for and what you got.

A human spec tolerates ambiguity.

An agent spec amplifies it.

The insight

One artifact. Two audiences. Same file.

👤

Human planner

structures thinking:

what to build, why, how

→

📄

/feature

Plan ≡ Prompt

→

🤖

Implementation agent

reads the same file

as its direct input

The same document organizes the human's thinking and feeds the agent's execution.

When the plan is sharp, the agent is sharp. When the plan is vague, the agent guesses.

What "sharp" looks like

Four dimensions. Specific or useless.

Vague planagent guesses

files

"update the auth module"

acceptance

"make it work"

anti-requirements

— (none)

read first

— (none)

which module? → guess

what's "work"? → guess

scope? → drift

context? → read everything (or nothing)

Sharp planagent executes

files

Modify src/auth/middleware.py to add validate_session_token()

acceptance

Returns True iff token is unexpired + signed; rejects malformed JWTs with 401

anti-requirements

Do NOT touch login_flow.py. No new deps.

read first

src/auth/*.py, tests/auth/*.py

The structural enforcement

If the plan is under 800 characters, it isn't a prompt yet.

Task description length gate

enforced at the planning pipeline

✗ BLOCKED✓ PASSES

0800 chars∞

A description under 800 chars is too short to be self-contained.

A plan that requires follow-up questions is not yet a prompt.

One level up

A prompt that writes prompts.

The planning commands themselves are prompts. Their output is also a prompt.

📝

/feature

meta-prompt

(writes prompts)

→

📄

feature-plan.md

plan ≡ prompt

→

🤖

/implement

reads the plan,

produces code

Systematizing planning is systematizing prompting.

The skills system is the meta-prompt layer: prompts that produce the inputs to other prompts.

The discipline

Prompt engineering and software planning are the same job.

Stop writing specs "for humans who'll figure it out" and plans "for agents to execute." The document is one thing. Its quality is your output's quality.