One agent, one job, one output. Combine concerns and you can't tell which one failed — and the agent can't tell which one to prioritize. Decomposition is how the system becomes improvable.

Principle

One Agent·One Prompt·One Purpose

Why it matters

When output is wrong, which job failed?

Same work. Two decompositions. One is evaluable — the other isn't.

Three jobs in one agent

/do_everything

① plan the feature② implement it③ write tests

💥output is wrong — but where?

Can't isolate. Was the plan thin? The implementation sloppy? The tests missing a case? The failure is tangled across three concerns. Every fix has to touch all three.

One job per agent

/plan → /implement → /test

① plan → spec.md② implement → code③ test → result.json

🎯test fails → stage 3 is the suspect

Failure has an address. Each artifact is evaluable. Each prompt is independently version-controllable and improvable. Fix stage 3 without touching stages 1 or 2.

The second reason

The agent optimizes for the average, not the best.

Context budget gets split across concerns. The last one to be addressed starves.

/do_everything — three jobs, one prompt100% context

PLAN · 45%

IMPL · 35%

TEST · 20%

/plan — one job, focused prompt100% context

PLAN · 100%

/implement — one job, focused prompt100% context

IMPL · 100%

/test — one job, focused prompt100% context

TEST · 100%

Each concern competes for the same budget. Smaller context → higher performance per concern.

A three-job agent delivers the average of three mediocre outputs, not three good ones.

The seductive instinct

"Fewer calls = cheaper" inverts at scale.

The assumption

"If I put everything in one prompt, I save a call."

saved: 2 API calls

saved: ~6s latency

→

What actually happens

Quality degrades. Re-runs pile up. Humans intervene.

cost: re-run to fix plan (~2 calls)

cost: manual edit to patch tests

cost: ambiguous failure takes 20min to diagnose

net: lost ≫ saved

The savings from combining prompts are less than the cost of lower-quality outputs.

Every "shortcut" creates a diagnostic debt that gets paid with interest.

The right shape

Composition is a sequencing wrapper — not a merged prompt.

The ADW pipeline. Each script wraps one single-purpose agent.

adw_plan.py

produces a spec

spec.md

→

adw_build.py

produces code

code changes

→

adw_test.py

produces a result

test-result.json

compositionadw_plan_build.py = adw_plan.py → adw_build.py

The wrapper sequences agents — each agent stays single-purpose.

This is how you get reduced round-trips without merging concerns into one prompt.

The decomposition boundary

One output artifact per agent.

A planning agent produces a plan.

An implementation agent produces code.

A validation agent produces a report.

✓ One agent when...

The work produces one artifact that a downstream step will consume. Internal steps inside that job are fine.

✗ Split when...

The work produces two or more unrelated artifacts. Different consumers, different evaluation criteria, different improvement cycles.

The discipline

Evaluable systems are built from attributable failures.

If you can't name which prompt produced the bad output, you can't improve anything. Decomposition isn't about elegance — it's the prerequisite for the feedback loop that makes the rest of the system improvable at all.