agent-workflow-kit · methodology

Plan big things without losing the small ones

The kit plans work at four altitudes and moves it through the same four phases every time — plan, execute, land, learn. Every altitude answers one question, produces one artifact, and hands a well-defined object to the level below, so a one-line idea and a ten-wave build program travel the same road.

Program Phase Wave Slice Gate / checkpoint
Level 0

The altitude model

Four sizes of intent, one containment chain. Nothing here is a new tool — each rung is an issue (a tracked unit of work in your issue tracker) or a field on one, with a fixed template. Colour follows altitude on every diagram on this page: the same blue-grey always means Program, the same amber always means Slice.

Program The whole undertaking. Described once, in one Program document with a wave plan attached. issue · type:program
contains 1 : n
Phase An acceptance bracket around a handful of waves. A board field and a checklist line — never its own issue. Optional. board field · P1 / P2 / …
brackets 1 : a few
Wave The working unit: one outcome, a small set of slices, one gate. Unchanged — exactly the wave you already build today. anchor issue · Wave N
ships as 1 : a few
Slice One build session, one pull request, one visible result. sub-issue · one PR

Phase is the only optional rung — plenty of programs run without one, and every feature that never needed a Program at all still ends at the same Wave → Slice bottom two rungs.

Level 1

The route map

There is no single front door. Work enters wherever it actually starts, and every door funnels toward the same shape. Below are the two roads that lead there — the everyday route almost everything takes, and the road for work too big to fit in one wave.

1a — One shape, many doors

A vague idea, a plan you already wrote, a backlog, or a raw issue — every entry funnels into the same shaped artefact: a PRD (a short planning document — Product Requirements Document) that, once sliced, becomes either one atomic issue or a wave anchor (a tracking issue with linked child slices). Grilling — a relentless interview that sharpens a fuzzy idea into a clear requirement — is optional and scales with the stakes.

idea/ plan/ backlog/ issue grill-with-docs to-prd to-issues (1 slice → atomic issue · several → wave anchor) gate — verify-spike / decision-gate (only if a slice hinges on an unknown) tdd wrapup retro

Sharpen only as deep as the work deserves: skip the grill for a mechanical change, run it lightly for a normal feature, escalate to a cross-model review for something hard to reverse. You approve the slice breakdown before anything is published — this funnel never writes to the board behind your back.

on-ramp

Work that doesn't start as an idea

Two doors sit outside the planning funnel and feed straight into the build layer instead:

bugs / requests piling up triage to-issues
something's broken diagnose (reproduce → isolate → fix → prove) tdd

1b — When the work outgrows one wave

The Program route is one strand within this map, not a separate system: it plans several waves at once, then hands each one down into the exact same build → land → learn spine as 1a. Use it only when the size is genuinely unclear — a new build, a big cross-cutting change, several independently-shippable stages.

top-down

You know it's big

scale-check asks a handful of plain-language questions and names the size. A big undertaking gets grilled once, written down once as a Program document with a wave plan attached, and unfolded into named, numbered waves — bracketed by phases where the program has real acceptance stages — after you approve a full preview in chat.

scale-check grill Program document preview gate to-waves phases stamped+ Wave 1…n + slices
execution rhythm

Then the rhythm takes over

Waves are built in plan order, one at a time — through the identical tddwrapupretro spine as 1a. Every wave ends at its own outcome gate; when the last wave of a phase lands, the matching phase gate is ticked on the Program document. The program issue closes last, by hand, once everything under it is done.

build Wave n wave gate next wave… phase gate P1 ✓ program Done
bottom-up

It grew on the board

Loose issues cluster into wave candidates. A candidate is not a commitment — it gets a real number only when you promote it. If a cluster of candidates starts looking like a program on its own, the kit says so and escalates instead of spraying out more small stubs.

board issues board-to-waves wave stub (a placeholder issue reserving a wave's number) your call promote
Both routes meet here: one wave anchor, a few slice sub-issues, one outcome gate — built, verified, and landed slice by slice, exactly like every wave always has been.
Level 2

How it stays honest

Six mechanics carry the promises above. Each folds open into the detail that backs the one-sentence claim next to it.

Gates — a decision lives at the level it can still change placement rule
Program / Wave shape settled during the grill
a single slice hinges on an unknown verify-spike / decision-gate tdd
IN PLAIN TERMS
Big decisions get made where they can still reshape everything; small decisions ride along with only the one slice they affect.

A gate slice does read-only research — it never writes code — and is sequenced before the build slice it blocks, so the build never waits on a moving target. A call that's genuinely hard to reverse escalates one step further, to a cross-model review, before it locks in.

Late binding — a wave's content is written just before it starts to-prd Mode B · self-critique
Program document (wave headlines, months ahead) wave stub (name + slice skeleton only) fresh write-up (the week the wave starts)
IN PLAIN TERMS
You never build from a stale spec — the plan names the destination early; the route is drawn right before you set off.

The wave's actual scope and acceptance criteria are authored fresh at start time, using everything learned since the plan was written. A self-critique pass runs on that write-up before anyone approves it, and a wave already known to be high-stakes gets a deeper pass than a routine one.

Drift propagation — what one wave learns reaches the others append-only · never silent
Wave 3 — an assumption flips Wave 7 (note waiting)+ Program document (note waiting)
IN PLAIN TERMS
A discovery in an early wave doesn't wait for someone to remember it later — it's already sitting there as a note when the later wave opens.

Notes are appended, never rewritten into a plan's tables. Only a genuine change to the wave plan itself — a wave added, scope moved between waves — takes the slower, structural path in the next mechanic. A wave's outcome gate is not considered cleared until any drift addressed to it has been read.

Revision loop — a stale stub stops loudly instead of building quietly wrong program-revision marker
wave stub — stamped r1vs. plan revised → r2 stop: refresh before building
IN PLAIN TERMS
If the plan changed after a stub was written, the kit stops you before you build the outdated version, instead of you finding out later.

Every wave stub is stamped with the Program document's revision number the day it's created. Revising the plan after that — inserting a wave, moving a scope item — re-unfolds only the difference (new waves added, existing ones matched, orphans flagged) and re-stamps every stub the change actually touches, so the marker and the plan agree again.

program-sync — the plan is a living table, not a snapshot status only · never rewinds
board — real status sync wave-plan table — status column
IN PLAIN TERMS
The plan document updates its own status column from what actually happened on the board, instead of drifting out of sync with a hand-typed guess.

Only the status column is regenerated, and only forward — a wave already marked done never reverts to open. The plan's own columns and any handwritten notes are left exactly as written. A dry run shows the change before anything is written, the same discipline the kit already uses to keep a wave anchor's slice table current.

Completeness — counted, not remembered coverage X of Y
scope items S1…Sn carried by ≥1 wave? [count]
wave → slice → gate chain closes without a gap? [count]
IN PLAIN TERMS
Nobody has to remember whether everything is covered — the tool counts it and shows the number before anyone approves.

Both counts appear at the same zero-write preview gate that shows the whole wave plan: how many scope items are carried by a wave (coverage), and whether every wave's chain down to a gated slice closes without a gap (rollup). Nothing is written to the board until both counts are shown and approved — the preview reads the plan, it never touches it.