Skip to content

The Route

The route takes a project from an intent to merged pull requests. Each phase writes a file, the next phase reads it, and a person approves the file before the route goes on, so no session has to stay alive across a gate.

Once, for the whole project

  1. 1 Requirements /etabli-spec stage A delivery/prd.md You approve
  2. 2 Design spine /etabli-spec stage B decision records, contracts You approve

Once per milestone

  1. 3 Cut /etabli-decompose decomposition summary, task files You approve

  2. Repeat until every task is merged

    A task starts once the tasks it depends on are merged. Up to three lanes run at once, and tasks that touch the same files run one after the other.

    1. 4 Build /etabli-implement/etabli-refine one lane per ready task, ending in a draft pull request Unattended
    2. 5 Review and merge a review skill, or the harness's each pull request, merged in dependency order. Merging frees the tasks that waited for it You merge
  3. 6 Milestone review /etabli-decompose the milestone review note You approve
  4. Another milestone to go? Back to 3, and cut it with what the review taught you.

Milestones are the default

A milestone is a slice of the project that works end to end and that you can run and test. Think of it as an MVP in the agile sense: some of its features may be very simple, stubbed or missing, but what exists runs. The first milestone is usually a walking skeleton that runs the riskiest parts, such as sign-in, a remote connector or the deployment, from one end to the other. Each next milestone adds to a product that already works.

The orchestrator plans milestones for every full route, and cuts the first one only. If it thinks they make no sense for your project, it tells you why and asks. The decision is yours alone, and it is written in the decomposition summary.

Keep the milestones

Without milestones, the route is one pass and is not incremental. The whole scope is cut into tasks and built before anyone has a working product in hand, so what you learn from a first running version cannot reshape the rest. You can still revise the requirements and cut again, but nothing in the route makes you stop, look at the result and adjust.

Decline them only for a project you can hold in your head, and say so when the orchestrator asks. To steer them, say it in your request, for example /etabli-orchestrator <what to build>, riskiest part first, and check the milestone plan when you approve the decomposition.

How a milestone runs:

  1. Planned up front. The milestone plan, in delivery/decomposition.md, lists every milestone with an exit criterion, which says what must work, and the requirement ids it targets. The requirements and the design stay whole, written for the project in full. Only decomposition and building are incremental.
  2. Cut one at a time. Only the current milestone is cut into epics and tasks, and the validator rejects tasks of a later one. Cutting is deferred on purpose, so what the first slice teaches can shape the second.
  3. Built and merged. Lanes build the tasks, and you review and merge their pull requests.
  4. Reviewed. A short note, delivery/milestones/<slug>.md, records whether the exit criterion held, what was learned, what is left of each requirement, and whether to continue or to revise the requirements or a decision first. Only a person running the slice can say it works, so the criterion is not checked by a machine. Approving the note closes the milestone.
  5. Next. The next milestone is cut with the note in hand.

How the work is cut

Project: one repository, one requirements document
Milestone 1: the current one, cut
Epic
a-001a-002a-003
Epic
b-001b-002
Milestone 2 Planned, not cut: no tasks yet.
Milestone 3 Planned, not cut: no tasks yet.

Each task is one branch, one lane and one pull request.

  • A project is a repository: one team, one set of requirements.
  • A milestone is an optional, ordered slice with an exit criterion.
  • An epic is a coherent group of work that one person can hold in their head. A group that delivers two separate outcomes is two epics.
  • A task is one unit of work: one branch, one lane, one pull request.

A project whose user decided against milestones has the same epics and tasks in one flat set. The definitions the agents apply are in the delivery conventions.

The artifacts

Every artifact lives under delivery/ at the repository root, except the decision records, which go in the decision record directory the repository already has (docs/adr/ or docs/decisions/), else in delivery/decisions/. No agent has to search for one: when a file is not at its path, it does not exist yet.

Artifact and path Written by What it is for
Requirements, the PRD
delivery/prd.md		 etabli-spec, stage A What must be true when the project is done, what must not change, and what is out of scope. Everything else is built from it.
Decision records (ADRs)
ADR-<nnn>-<slug>.md		 etabli-spec, stage B The choices that keep separately built parts compatible, with the alternatives that lost and why.
Contracts
delivery/contracts/<interface>.md		 etabli-spec, stage B The written shape of an interface two lanes must agree on, so lanes depend on a document and never on each other's unfinished code.
Decomposition summary
delivery/decomposition.md		 etabli-decompose The milestone plan (or the user's recorded decision against milestones), what each epic delivers, where the work runs in parallel or in series, and why it was cut this way.
Task files
delivery/tasks/<id>.md		 etabli-decompose, or the orchestrator on the direct path One unit of work: acceptance criteria, scope, dependencies, files it touches and its tier. A lane builds from it.
Milestone reviews
delivery/milestones/<slug>.md		 etabli-decompose, with you Whether the exit criterion held, what was learned, and whether to continue or revise. Read by the next cut.
Handoff report
.lane-report.md		 etabli-implement, extended by etabli-refine What changed, which validation ran, what was deferred and what the review fixed. It becomes the pull request body, so it is what you read first.
Review lenses
delivery/review-lenses.conf		 install-routing.sh seeds it, you edit it Which review skills the orchestrator suggests for a pull request. See Review the Pull Requests.
Tier mapping, optional
delivery/tiers.conf		 You What plan, build and chore mean for the team. See Choose Models with Tiers.

You approve the requirements, the design spine, the decomposition (summary and tasks), each merge, and each milestone review. The lanes between the decomposition and the pull requests run unattended.

Two ways through

The orchestrator investigates the request and the code before choosing how much of the route to use:

Path When What runs
Direct implement One well-understood change with obvious acceptance criteria one task file, then etabli-implement and etabli-refine in the ordinary checkout; no claim, no worktree, only the merge gate
Full route Several tasks, contracts to keep parallel work consistent, or a decision worth recording every phase and every gate, up to three lanes at once

How much of a full route runs in parallel is decomposition's finding, not a choice made up front; see Parallel or serial.

Requirement coverage

Requirements carry ids. Tasks name the requirement ids they cover, in full or in part, so etabli-status/scripts/coverage.sh can say what is left of each requirement. That is what makes a milestone review concrete: it starts from what each requirement still lacks, not from a feeling.