Trunk flow

The development cycle at code level 1 and up, and the tp command that makes each move. It is trunk-based development in its short-lived-branch style: one long-lived branch, main; a branch per story that lives for days and reaches main by a pull request on a green build; and a release made from main, as a separate act. What the words mean is in the method; which level asks for what is the maturity ladder; the way it replaces is the batch; who takes each step at level 3 is agent flow.

The development cycle: plan, story branch, main, and what is published, with the tp command for each move

The cycle

From To Command Who What it does
idea roadmap item tp roadmap add TITLE either files an issue labelled roadmap and adds the line to ROADMAP.md
roadmap item story tp story new TITLE, tp story issue NNN agent scaffolds docs/stories/NNN-slug.md; files its issue and stamps the number on the heading
story story branch git switch -c story/<issue>-<slug>, or tp wt start for a worktree agent cuts the branch from main
work build green task check agent the build: format, vet, tests, documentation rendered; changes no tracked file
build green pull request tp story land agent merges main in, builds, pushes, opens the pull request into main
pull request landed merge on the forge human the story is on main, with no version; its branch is deleted
landed shipped tp release on main human gathers the fragments into a release/vX.Y.Z pull request, merges it, tags the merge, closes the stories' issues, publishes
shipped running the project's deploy human puts the release onto a running system

An agent takes the steps that publish nothing; a human merges and runs anything that tags.

Asking and checking

These read the repository and the forge and change nothing. Run the query before acting and do what it says.

Command Run Tells you
tp story query on a story branch where the story stands (unbuilt, behind main, in conflict, in a pull request, landed) and the one next step
tp release query on main, or anywhere what has landed since the last tag, the version it makes, the one next step and who takes it
tp check anywhere in the project whether task-plus.yml, the Taskfile, the changelog, the roadmap and the forge settings agree with the declared level
tp maturity anywhere in the project the declared levels, whether main is protected, and whether a release is in flight
tp roadmap check anywhere in the project whether ROADMAP.md and the forge's roadmap issues agree

What is not built yet

The cycle above is the specification; task-plus does not yet do all of it. Missing today: publishing the documentation on landing (the dashed edge). The order things come in is the roadmap.