Agent flow

Code level 3: an idea becomes a story and a story becomes part of a release, with agents doing the work between and a human called only where judgement is needed. It is trunk flow underneath: a story still has its own branch, lands on main on a green build and is released by a separate act. What changes is who takes each step, and that the scarce thing being managed is the human's attention.

This page is the specification. None of it is built; the order it comes in is the roadmap. A project sees none of the tooling until it declares maturity.code: 3, which is how the level is brought in without disturbing level 1.

The life of an idea: captured, ideated into a story, refined, developed, reviewed, landed and released, with the points where a human is called

Phases

Phase Who acts Human needed Starts with Ends with
Capture human yes, for seconds a thought: a bug, a feature, a doubt an idea: an issue labelled idea, neither defined nor bounded
Ideation agent interviews the human yes an idea, or a roadmap item whose turn has come one of three: closed; a roadmap item; a story, defined or needing refinement
Refinement agent proposes, human judges, repeated yes a story whose outcome a human has to see to judge: a page, a diagram, a screen a defined story: its soft acceptance has been judged on a mock-up
Development agent no a defined story a green build, test-first against the acceptance table
Review reviewing agents, one per concern no a green build every review passed, or a call
Land agent no reviews passed the story on main, merged by the agent
Release human yes landed stories a tag, as at level 1

Capture is cheap on purpose. The idea is stored before anyone asks whether it is good, because a thought that waits to be made sharp is usually lost. Ideation is where it is tested: has it been done, does it make sense, what is the smallest thing that would answer it. It is light, a short interview, not a design session.

An interview has three ways to end, and the middle one is what keeps the others honest:

The idea is The issue becomes It waits Counts against the limit
already done, or does not stand up closed nowhere no
worth doing, but not now, or too big for one story a roadmap item: sharpened and bounded, placed in an epic, with no acceptance yet in ROADMAP.md, in order no
ready to be worked on a story in its worktree yes, until it is defined

Without the roadmap as a way out, an interview could end only in building the idea or dropping it, and whatever was worth keeping for later would either stay open, using up attention, or go back among the raw ideas with what the interview learned lost. A roadmap item is interviewed again when its turn comes, more briefly, and that interview ends in a story.

Nothing reaches the roadmap except through an interview: capture is the only way in, and everything on the roadmap has been sense-checked. An epic planned ahead is one interview that ends in several items.

Refinement is not a phase every story has. A story whose acceptance is all hard leaves ideation defined. A story of text may be nearly finished by the end of refinement, since the mock-up is the page.

From a defined story to the landing no human is needed, and the agent is free to merge. A story lives in a worktree of its own from the moment ideation produces it, so that refinement's mock-ups are on its branch and several stories can be open at once.

Vocabulary

Added to the method's:

Term Means Is not
Idea a captured thought, stored as an issue labelled idea a story: it has no acceptance and nothing is built from it
Ideation the interview that turns an idea into a roadmap item or a story, or closes it refinement: no mock-up is made
Roadmap item an idea that has been through ideation and is kept for later: bounded, placed in an epic, labelled roadmap a story: it has no acceptance. Nor a raw idea: those are not on the roadmap
Defined a story that can be built without a conversation: no blank cell in its acceptance, and its soft acceptance already judged finished
Call an agent stopping and asking for a human, with the reason on the issue a failure: calling is the agent doing its job
Dark a feature that has landed or shipped behind a flag that is off unfinished: it may be complete and waiting to be turned on
Overview the one place that shows every idea and story in flight and what each waits for a query: it covers the project, not one story

An idea, its roadmap item and its story are one issue, relabelled as it goes: idea, then roadmap if it waits, then story. So a piece of work keeps one number from the thought to the release, and a roadmap item that becomes a story keeps its line in the epic. An item too big for one story stays as the parent: its stories get issues of their own that link back to it, and it is done when they have all shipped.

Where the phase is recorded

The phase is not one field. Most of it can be read from the repository and the forge, as tp story query already reads where a story stands; only what cannot be read is recorded, as a label on the issue that tp alone writes.

Phase Known from
idea label idea
roadmap item label roadmap, and its line in ROADMAP.md
story in ideation or refinement label story, without defined
defined label defined, set when the human accepts the story
development defined, and its branch has no pull request
review its pull request is open
called label called, with the reason in a comment
landed its pull request is merged
shipped its issue is closed by the release

The story file does not hold the phase. An idea has no file; a story's file is on its branch, not on main, until it lands, so an overview would have to visit every branch to read it; and a status line kept by hand goes out of date. So at level 3 a story has no **Status:** line. The labels also carry the time of each change, which is what tells a stale story from a moving one.

Soft acceptance moves forward

At level 1 soft acceptance is judged at the merge, by the human who merges. At level 3 an agent merges, so that judgement has to be made earlier, and refinement is where: the human judges the mock-up, and what they accepted is recorded in the story. Review then checks the build against what was accepted, which an agent can do.

So the test for whether a story needs refinement is whether it has soft acceptance. A story is not defined while a soft criterion is still waiting for a human.

When an agent calls

An agent works alone only while the story holds. It calls, and stops, when:

Condition Why a human
the build cannot be made green the story or the code under it is wrong in a way the agent has not found
a review finding cannot be resolved, or two reviews disagree a trade-off is being made that the story did not settle
the acceptance turns out wrong, or a cell is blank the story is no longer defined; it goes back to refinement
the work needs more than the story says scope is the human's to widen
main cannot be merged in without choosing between two stories the choice is between pieces of work, not inside one

A called story is not abandoned and not merged. It waits in the overview, at the front.

The human's review

The human is not asked to approve each landing, and mostly will not look at it. They are asked to keep looking at main: the project records the commit up to which a human last reviewed, and the overview shows what has landed since, how long ago the last review was, and which of those landings touched code the project has declared critical. A landing in critical code is still not blocked. It is put where it will be seen.

Review by agents comes before the landing and is by concern (security, whether the change makes sense against the story), each a role or skill of its own. Whether a feature lands behind a flag is decided earlier, in ideation or refinement, and written in the story.

Overview

The overview is where the human's attention is spent, so it is ordered by what needs them. It is one view across every project the person works on, not one per repository, because their attention is one pool:

Shows Why
called stories an agent is stopped until someone answers
stories not yet defined, counted with the called ones against the limit these are the phases that need the human; more open than they can attend to is work started that nobody can finish
raw ideas, and roadmap items in order what could be interviewed next; neither counts against the limit
stories in development or review no action needed; shown so that they can be seen to move
stuck and stale stories no change of phase for longer than the project allows
landings since the last human review, critical ones marked The human's review
dark features landed or shipped with the flag off, waiting to be turned on; and turned on, waiting for the flag to be removed

The limit is on the phases that need a human, not on stories. Agents can develop many stories at once; a person can hold only a few interviews and mock-ups in their head. New ideas can always be captured.

The limit
Belongs to the person, not the project: it is set in their own task-plus configuration, since no project can know what else they have open
Counts across every level 3 repository, read from the forges: stories not yet defined, and called stories
Does not count raw ideas, roadmap items, stories in development or review
At the limit starting an interview is refused, and the refusal names what is open
Never refused a call: it may take the count over the limit, and then nothing new is started until it is answered
Value 3 unless the person sets another

There is no way round the refusal but changing the number. Three is a guess; how long stories wait undefined, which the overview shows, is the evidence for changing it.

A flag has a life of its own that ends later than the story: off, on, removed. A feature is not finished until its flag is gone, and the overview is what keeps a flag from being left in for good.

What task-plus will provide

The deterministic parts, as in the tooling split: capturing an idea (tp idea add TEXT, which replaces tp roadmap add), moving the issue between labels, the worktree, the landing, the review record, the overview. The judgement parts are roles or skills that call tp: the interviewer, the developer, each reviewer.

Open questions

  • How a passed review is recorded. Probably on the pull request, one record per concern.
  • How a call reaches the human. A label and the overview, or a notification as well.
  • Critical code. How a project declares it, and whether a landing there should wait for a human after all.
  • Reviews. Which concerns every project has, and which a project adds.
  • Stale. How long without a change of phase, and whether it differs by phase.
  • Level 1. Whether level 3 replaces it once it has proved itself.