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