PHASE: Plan Hard, Agents Ship Easily

The Bottleneck Nobody Wants to Admit

I've spent the last year pushing AI-native development as far as it will go. Agents in the org chart. Specs before code. Verification workflows that catch the mess before it lands in main.

And here's the uncomfortable part: most AI coding failures are not coding failures.

They're judgment failures.

Ask a mid-tier model to "build the onboarding flow" and it will happily invent:

• What onboarding means
• Which steps exist
• What happens when something fails
• Which copy sounds "friendly"
• Which library feels right today

That's not autonomy. That's improvisation with commit access.

The industry response is usually "use a better model" or "write a longer prompt." I've tried both. They help at the margins. They do not fix the root issue:

If an implementing agent has to invent a product decision, your brief wasn't ready.

So I built a method that makes invention illegal.

PHASE in One Sentence

Plan Hard, Agents Ship Easily.

Humans do the expensive thinking early—product, design, edge cases, acceptance criteria. Agents do the cheap execution late—files, tests, commits, merges—without guessing.

The acronym is cute. The discipline is not.

There is no skill for stage 0 on purpose. Dumping the briefs is your job. Everything after that assumes the raw material already exists.

The orchestrator skill is just called phase. You invoke it when you don't know which stage you're in. It looks at the repo, tells you the next move, and stops. It does not silently jump into implementation. That restraint is the point.

Is PHASE too heavy?

If this pipeline feels oversized, your project is probably tiny—and that's fine. PHASE is for significant work: multi-surface products, real domains, real regression risk. A weekend toy does not need grilled briefs and a full test battery. A product that will live for months does.

One reason the weight is intentional: in specify, we write the full set of unit and integration tests that lock behavior and catch regressions before agents start typing production code. That only pays off when there is enough product to protect.

The Document Layout That Makes Agents Behave

PHASE assumes a boring, predictable tree under your project root:

docs/
  01 - Briefs/          # product truth (grilled until agent-proof)
  Stack.md              # technical truth (read-only during most stages)
  UI.md                 # visual system
  UX.md                 # flows, states, micro-copy
  02 - Specs/
    Index.md            # waves, ownership, parallelism
    01-whatever.md      # one small build order
    code/               # reference files agents copy from

This is not bureaucracy for its own sake. It's a shared memory that survives context windows.

• Briefs answer what and why.
• Stack / UI / UX answer with what and how it should feel.
• Specs answer exactly which files, checks, and tests.

If a decision lives only in a Slack thread or your head, an agent will reinvent it. Every time.

Stage 0 — Write the Briefs (Do Not Skip This)

This is the step people under-estimate. Grill will sharpen. Specify will slice. None of that works if there is nothing substantial to refine.

Stage 0 is you, alone with the product in your head, getting it out of your mouth and into markdown.

Two habits guide how I do it:

1. Dictate like you're briefing a human

I don't start by polishing prose. I use speech-to-text—tools like Flow or Gladia—and I talk the way I'd talk to a PM or an engineer sitting next to me.

"Here's the billing problem. Customers get charged twice when they… What I want is… Edge case I hate is…"

Natural language first. Structure later. The goal is density of intent, not pretty docs. Typing invites you to edit yourself mid-thought. Dictation lets the messy truth land on the page.

2. One domain, one brief

Whenever an idea touches a distinct domain, it gets its own file under docs/01 - Briefs/.

Examples of splits that keep paying rent:

• Billing
• Architecture / system boundaries
• A specific feature
• A specific screen or flow
• Auth, notifications, admin, onboarding—whatever your product's seams are

One giant "the app" brief becomes an ambiguous soup. Separate briefs give grill something precise to interrogate, and later give specify clean ownership boundaries.

Budget real time

This is not a five-minute brain dump before you "let the agents cook."

For a meaningful project, stage 0 takes a while. Walks. Repeated passes. Coming back the next day because you remembered a constraint in the shower. That's normal. The material has to be there. Grill is a refinery, not a mine.

If you catch yourself writing three thin bullets and calling it a brief, stop. Talk longer. Split the domains. Then—and only then—run grill.

Stage 1 — Grill the Brief Until Guesswork Dies

Most first-pass briefs are still vibes with bullet points—even after an honest dump.

"Simple onboarding." "Clean dashboard." "Fast enough."

Cute. Useless as build orders.

grill-brief interrogates the docs you already wrote with batched, multiple-choice questions. Not therapy. Not brainstorming theater. Questions where each answer changes what gets built.

Then it rewrites the brief so it reads as if it had always contained the decision. No Q&A appendix. No transcript sludge. The brief is the artifact.

The readiness bar is brutal on purpose:

If an implementing agent would have to invent something to proceed, the brief is not ready.

When every brief clears that bar, you move on. Not before.

Grill is where you sweat the decisions. Stage 0 is where you sweat the substance. Skip either one and the rest of PHASE is cosplay.

Stage 2 — Design Before Specs Steal Your Taste

If the product has a UI, do not let the specifier invent colors, spacing, empty states, and interaction patterns mid-flight.

design researches comparable products, then writes:

• docs/UI.md — tokens, components, visual rules
• docs/UX.md — flows, states, feedback, micro-copy

You review taste. You reject the generic. You lock the system.

Skip this when there is genuinely no UI. Do not skip it because you're impatient.

Stage 3 — Specs Are Build Orders, Not Essays

This is the heart of PHASE.

specify turns briefs + stack + UI/UX into many small specs, each short enough to stay in an agent's working memory (target under 200 lines, hard max 300). An Index.md defines order, dependencies, and which work can run in parallel.

Every spec is written for a mid-tier model: competent at coding, terrible at judgment.

That means:

• Exact file paths
• Exact commands and expected output
• Reference files under docs/02 - Specs/code/ instead of giant inlined dumps
• Pitfall notes for mistakes weaker models make
• Zero "use an appropriate X"
• Zero "handle errors somehow"
• The full unit and integration tests for the behavior—written into the specs—so implementers cannot "forget" the safety net

That last point is a big reason PHASE feels heavy, and a big reason it works. We are not hoping agents invent a reasonable test suite after the fact. The regression wall is part of the build order. When a later wave lands, those tests are what stop silent breakage.

If a sentence can be read two ways, rewrite it.

I used to write beautiful prose specs. Agents loved them and still shipped the wrong product. Now I write boring, surgical build orders—with the tests included. Agents ship the right product, and the suite tells you when they don't.

Stage 4 — Review Like You're About to Leave Town

review-spec is the last human checkpoint before unsupervised implementation.

Be paranoid. Every gap you miss becomes a blocked agent, a broken build, or a silently wrong feature that only shows up when a real user clicks around.

The skill doesn't just report issues. It fixes the specs. You are not collecting a punch list for later. Later is how technical debt is born with better branding.

Only when the verdict is READY do you unlock implementation.

Stage 5 — Implement With Parallel Agents, Then Go Touch Grass

implement is where the method pays rent.

• One worker per spec
• Isolated worktrees / branches
• Waves from Index.md
• Merge, integration check, next wave
• Git commit per step
• No "should I continue?" pauses

The orchestrator does not implement features unless a worker fails twice. Your job becomes watching green checks and resisting the urge to micromanage.

When the agents hand over the work, it should boot. Tests should pass. Features from the briefs should exist. Not "mostly." Not "we'll polish Monday."

Stage 6 — Feedback Updates Specs First

After ship, feedback arrives. Of course it does.

feedback has one non-negotiable rule:

Update the owning spec first. Then change the code.

If you patch code and leave the spec stale, the next agent will "helpfully" revert your product decision because the written truth still says otherwise.

Briefs stay frozen unless feedback contradicts them. Specs remain the live source of truth for implementation.

The Five Rules I Will Not Negotiate

1. Judgment early, execution late. Humans decide. Specs lock. Agents copy.
2. Zero guesswork. Invention means go back a stage.
3. Specs are build orders. Paths, patterns, checks, tests—not vibes.
4. Parallelism is a feature. Slice for many small owned specs; one agent per spec.
5. Feedback writes the spec before the code. Always.

If that list feels strict, good. Loose process is how you end up with a 20x coding speed and a 20x cleanup speed.

Steal These Skills

Below are the actual PHASE skills I use. They are published on this site via the standard skills well-known endpoint (/.well-known/skills/).

• Copy puts the skill file(s) on your clipboard (multi-file skills are labeled by filename).
• Install copies an npx skills add one-liner (global, all agents, no prompts).
• Open Preview if you want to skim before installing.

Install, then run /phase in a repo that has (or will have) the docs/ layout above.

Loading…

Loading…

Loading…

Loading…

Loading…

Loading…

Loading…

Minimal install if you hate buttons

# Everything
npx skills add https://YOUR_DOMAIN_HERE --skill '*' -g --agent '*' -y

# One skill
npx skills add https://YOUR_DOMAIN_HERE --skill phase -g --agent '*' -y

Or click Install above — it copies the same one-liner with this site's origin already filled in.

How a Real Run Feels

1. Dictate the product into docs/01 - Briefs/—one file per domain. Take longer than feels comfortable.
2. Run /phase. It says: grill first (because the briefs exist but still leak ambiguity).
3. Answer uncomfortable multiple-choice questions until inventing is no longer required.
4. Run design. Argue about one empty state. Win that argument in UX.md.
5. Specify into small owned chunks, including the unit and integration tests that guard regressions. Refuse giant "do the app" specs.
6. Review until READY.
7. Implement. Walk away. Come back to a bootable app and a pile of commits.
8. When feedback hits, update the spec, then the code.

The emotional arc is the opposite of vibe coding. Front-loaded friction. Back-loaded calm.

If that sounds less magical than "just ask the agent," that's because magic was never the strategy. Control was.

Key Takeaways

• AI agents are great executors and unreliable product managers. Plan accordingly.
• Stage 0 matters: dictate real briefs, split by domain, spend real time. Grill refines—it does not invent substance.
• PHASE front-loads judgment so mid-tier models can ship without inventing the product.
• Dump → grill → design → small specs (with full tests) → review → parallel implement → feedback-into-specs.
• If the method feels too heavy, your project is probably too small for it—or you are trying to skip the dump.
• If an agent must guess, you skipped a stage. Go back.
• Steal the skills above. Put them in your agent. Make invention illegal.

I'm not claiming PHASE makes bad ideas good. It makes good decisions executable. That's the whole game once agents can type faster than you can think.

If you try it, pick a project that actually matters, force yourself through dump + grill + specify (tests included) before anything touches the codebase, and treat the discomfort in stages 0–1 as the feature—not a bug.