The planning artifact and the agent's execution prompt are the same document — so the spec and the implementation describe the same system.

Pattern

Plan-as-Prompt

The core move

The plan and the prompt are literally one file.

Planwhat the human wrote

## READ FIRST

AGENT_SYSTEM.md,

05-tdd.output.md

## WORK ITEMS

Add validate_session_token(

token: str

) -> SessionTokenClaims

in src/auth/middleware.py

## VERIFICATION

pytest tests/test_auth.py

≡

Promptwhat the agent received

## READ FIRST

AGENT_SYSTEM.md,

05-tdd.output.md

## WORK ITEMS

Add validate_session_token(

token: str

) -> SessionTokenClaims

in src/auth/middleware.py

## VERIFICATION

pytest tests/test_auth.py

Same bytes. No copy. No paraphrase. Output matches spec because input matches spec — there's no interpretation gap between the two documents, because there aren't two documents.

The precision standard

Four axes. Each vague phrase leaves the plan in the prompt.

Files

"update the auth module"

src/auth/middleware.py

Symbols

"add session validation"

validate_session_token(token: str) -> SessionTokenClaims

Patterns

"follow existing patterns"

validate_api_key() at line 47

Acceptance

"works correctly"

raises AuthError on invalid token

Each left-column phrase is a plan the description should have contained. Derivation cost moved from plan-time to execution-time — and agent guesses accumulate.

The 800-character floor

Self-containment has a minimum size — below it, the description is incomplete.

plan/tasks/T-014-session-token.md

≥ 800 chars

## READ FIRST

AGENT_SYSTEM.md, 05-tdd.output.md §4.2

## CURRENT STATE

src/auth/middleware.py exists; validate_api_key() at line 47 is the reference pattern

## WORK ITEMS

Add validate_session_token(token: str) -> SessionTokenClaims following validate_api_key pattern

## ACCEPTANCE

function exists, correct signature, raises AuthError on invalid token

## VERIFICATION

grep -n "validate_session_token" src/auth/middleware.py

python -m pytest tests/test_auth.py

## OUT OF SCOPE

Do not modify validate_api_key; do not touch /login endpoint

## DEFINITION OF DONE

Tests pass; grep returns the new symbol; diff touches only middleware.py

800 chars is the rough floor to specify one file, one signature, one reference, one acceptance, one verification. Anything shorter leaves the agent to derive what the plan should have said.

Planning is prompting at every hop

Each step's output is the next step's prompt.

User

feature desc

→

Command

/feature

→

Artifact

spec.md

→

Command

/planning-products

Artifact

task.md

→

Command

/implement

→

Agent

builder

Command = meta-prompt templateArtifact = plan = next promptAgent consumes the artifact

A Command is a meta-prompt that generates prompts. Its output — the spec, the task — is the input to the next agent. At every hop, the plan IS the prompt for whoever executes next.

The anti-pattern

Separate spec and prompt — they diverge the moment the code ships.

Two documents, one system, guaranteed drift

spec.md — for humans

Auth hardening

add session support

follow existing patterns

handle errors cleanly

(intentionally flexible)

⚡

diverge

agent-prompt.md — for the bot

You are a builder agent.

See spec.md.

Implement section 3.

Do your best.

The agent builds to the prompt, not the spec. The prompt refers back to the spec without inlining it, so the spec's intent is filtered through the prompt's vagueness. The spec and the implementation end up describing different systems.

Two documents = two interpretations. The fix isn't a better prompt — it's one document. The planning artifact IS the briefing.

The discipline

Write the plan as if the next reader is an agent — because it is.

File paths, not concepts. Signatures, not intentions. Line numbers, not suggestions. Binary acceptance, not "works correctly." Every vague phrase is a plan the description should have contained — and the agent will derive it wrong.