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.
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.