tp idea
The manual's agent flow
before the build, at code level 3: a thought is captured as an issue
labelled idea, and an interview ends by moving that issue on. An
idea, its roadmap item and its story are one issue, relabelled as it
goes, so a piece of work keeps one number from the thought to the
release, and the labels are where its phase is read from.
| Command | Does | Prints |
|---|---|---|
tp idea add TEXT... |
capture: files an issue titled TEXT and labelled idea, creating the label when the repository lacks it |
#N url |
tp idea adopt N... |
take in: labels each open issue N that carries none of the flow's labels idea, leaving its title, body and other labels as they were |
#N url for each |
tp idea roadmap N [--epic NAME] [TEXT...] |
not now: lands - [ ] #N TEXT under the epic in ROADMAP.md, the last one by default, on the remote base branch, by a pull request from roadmap/<N> it cuts, checks and merges in the one run; then takes idea off issue N and labels it roadmap |
#N url, then the epic it went under and the pull request merged |
tp idea story N [TITLE...] |
ready: cuts story/<N>-<slug> from the remote base branch in a new worktree beside the main checkout, writes the story for idea or roadmap item N there, (#N) on its heading and no **Status:** line, and relabels the issue story |
the story's path |
An idea that does not stand up is closed: tp issue close N. Forge and
token are resolved as for tp issue, and tp issue list
shows the labels.
The labels
| Label | Means | Written by |
|---|---|---|
idea |
captured, not yet interviewed | tp idea add, tp idea adopt; "to idea" on tp overview, for a story not yet defined |
roadmap |
interviewed and kept for later, with a line in ROADMAP.md |
tp idea roadmap |
story |
being made ready, or being built | tp idea story |
defined |
a story that can be built without a conversation, beside story |
tp story accept |
called |
an agent has stopped and asks for a human, the reason in a comment | tp story call; taken off by tp story answer |
tp alone writes them. Nothing stops a label being changed on the
forge by hand; the commands refuse an issue whose labels are not the
ones their step starts from, which is how a hand edit shows.
Capture (story 042)
ROADMAP.md is not touched.
maturity.code |
Command | Outcome |
|---|---|---|
| 3 | tp idea add TEXT... |
the issue, labelled idea |
| 3 | tp idea add with no text |
error; no issue |
| 3 | the issue made, the forge refusing the label | error naming the issue and the label |
| 0, 1 | any tp idea subcommand |
error naming tp roadmap add: a project sees none of agent flow until it declares level 3 (maturity) |
| 3 | tp roadmap add |
error naming tp idea add: nothing reaches the roadmap except through an interview |
Taking in an open issue (story 049)
An issue that was open before the project declared level 3 carries none
of the flow's labels, and the commands that move an issue on refuse it.
tp idea adopt puts it where a captured thought is; the interview then
closes it, keeps it for later or makes it a story. An issue is adopted
by its number, so that a dead one is closed and not carried in.
The flow's labels are the five above. Each N is judged alone, in the order given: a refused N is reported and the ones after it are still adopted.
maturity.code |
Issue N | Outcome |
|---|---|---|
| 3 | open, no label | labelled idea, the label created when the repository lacks it; #N url printed |
| 3 | open, labels that are none of the flow's (bug) |
labelled idea; the others kept |
| 3 | open, labelled idea |
error: it is an idea already; nothing changed |
| 3 | open, any other flow label | error giving its labels; nothing changed |
| 3 | closed, or does not exist | error; nothing changed |
| 3 | not a number | error; the forge not asked for it |
| 3 | several, some refused | each as its own row; the command fails, naming every refused N |
| 3 | none given | usage error; the forge not asked |
| 3 | the forge refusing the label | error naming the issue and the label |
| 0, 1 | any | the error every tp idea subcommand gives below level 3 |
Not now: a roadmap item (story 043)
TEXT is what the roadmap says about the item, bounded by the interview; without it the line takes the issue's title. The issue's title is left as it was.
| Issue N | Epic | Outcome |
|---|---|---|
open, labelled idea |
named and present, or none named | its line appended; relabelled roadmap |
open, labelled idea |
named, not in ROADMAP.md |
error naming the epic; nothing changed |
not labelled idea |
any | error giving its labels; nothing changed |
| closed, or does not exist | any | error; nothing changed |
The line lands itself (story 052)
A roadmap line is a change like any other, and at level 3 nothing moves
the base branch but a pull request. So the line reaches it the way a
story does, by the same worktree and the same landing, and without a
second conversation: the human decided in the interview and tp writes
the one line, so the run is automatic once it is started.
tp idea roadmap N fetches the release remote, cuts roadmap/<N> from
its base branch into a worktree of its own, <repo>-roadmap-<N> beside
the main checkout, appends the line there and commits it, then lands it
by the steps tp story land takes: the checks, the push,
the pull request, the merge. Then it relabels the issue and removes the
worktree and the branch, local and remote.
No defined label, fragment or review is asked of a roadmap line: its
change is the one line tp wrote, and the interview is its acceptance.
The epic is looked for in the remote base branch's ROADMAP.md, not
the checkout's, and ROADMAP.md below is that one. The checkout the
command is run in is not written to, and its base branch is not moved:
git pull brings the line in.
| Issue N | Run from | The landing | Outcome |
|---|---|---|---|
open, labelled idea |
the base branch, clean | checks pass, the forge merges | - [ ] #N TEXT under the epic on the remote base; the issue relabelled roadmap; the worktree and roadmap/<N> gone, local and remote; prints #N url, the epic, and the pull request merged |
open, labelled idea |
a story branch, or a tree with uncommitted changes | the same | the same; the branch checked out, its tree and its ROADMAP.md are as they were |
open, labelled idea |
any | the epic named is not in ROADMAP.md |
error naming the epic; no branch, no worktree, the issue still idea |
open, labelled idea |
any | a check fails | error giving the check; nothing pushed; the issue still idea; the worktree removed |
open, labelled idea |
any | the forge refuses the merge | error naming the pull request, which stays open; the issue still idea; the worktree removed |
open, labelled idea |
any | the line merged, the forge refusing the label | error naming the issue and the label; the line stays |
open, labelled idea, a pull request from roadmap/<N> open from a run that stopped |
any | the forge merges | carries on from that pull request: merged, the issue relabelled; no second line |
open, labelled idea, its line on the remote base from a run the label stopped |
any | — | the issue relabelled; no second line, no pull request |
not labelled idea; closed; does not exist |
any | — | the errors above; nothing cut |
open, labelled idea, an open pull request from roadmap/<N> that goes into another branch, or whose change is not the one line - [ ] #N … added to ROADMAP.md |
any | — | error naming the pull request; nothing merged; the issue still idea |
open, labelled idea, a pull request merged and no line for #N on the remote base |
any | — | error naming the pull request and the issue; the issue still idea |
The label is written only once the line is seen on the fetched base, on
every path, so after a run that lands
tp roadmap check passes there. Only what tp
wrote is merged unreviewed: a pull request is carried on from when it
goes into the base branch and its change against the base is that one
added line, and nothing else.
A run that stopped
Running the command again finishes a run that stopped at a failed
check, at a merge the forge refused for the moment, or at a refused
label. Three stops it does not finish, and tp removes nothing of
them itself; the error gives the commands:
| What the stopped run left | Error | Remove, then run again |
|---|---|---|
| the pull request, which the forge refuses on every run: the base gained a line where this one goes | names the pull request | close the pull request; git push <remote> --delete roadmap/<N> |
the worktree <repo>-roadmap-<N> or the local branch roadmap/<N>: the run was killed |
names each that is there | git worktree remove --force <repo>-roadmap-<N>; git branch -D roadmap/<N> |
roadmap/<N> on the remote with no open pull request |
names the branch | git push <remote> --delete roadmap/<N> |
Ready: a story (story 043)
TITLE names the story and its file; without it the issue's title does.
The file takes the issue's number, padded to three digits (story 051):
docs/stories/<N>-slug.md, headed # <N> — TITLE (#N), its slug made
as tp story new makes it. A roadmap item that becomes a story loses the roadmap label and keeps
its line, which tp roadmap check accepts at
level 3.
docs/stories/ below is the remote base branch's, which the story's
worktree is cut from.
| Issue N | docs/stories/ |
Outcome |
|---|---|---|
open, labelled idea or roadmap |
no file numbered N | the story file written in its worktree; the issue relabelled story |
open, labelled idea or roadmap |
a file numbered N, a story of another issue or of none | error naming the file to rename; no file, no worktree; the issue's labels unchanged |
open, labelled idea or roadmap |
a file numbered N, headed (#N) |
error: it is a story already; no file, no worktree; the issue's labels unchanged |
labelled story |
any | error: it is a story already; no file |
| labelled none of the three | any | error giving its labels; no file |
| closed, or does not exist | any | error; no file |
The story's worktree (story 053)
Several stories are in flight at once at level 3, so a story is written
and built in a worktree of its own and no checkout is switched from
story to story. tp idea story N fetches the release remote, cuts the
branch story/<N>-<slug> from its base branch into a new worktree,
<repo>-<N>-<slug> beside the main checkout, and writes the story file
there, with the sandbox .claude/settings.json that
tp wt start writes (a project that tracks its own
keeps it). The slug is the story file's. The path it prints is the file
in the worktree: write the story there, and build it there once it is
defined. tp story tidy
removes the worktree once the story has landed.
"Beside the main checkout" holds from wherever the command is run, another story's worktree included.
| Run from | story/<N>-<slug> and <repo>-<N>-<slug> |
Outcome |
|---|---|---|
| the main checkout, on the base branch, clean | neither exists | the worktree made on the branch, cut from the remote base's tip; the story file and the sandbox settings in it; the issue relabelled story; the path printed |
| the main checkout, its base branch behind the remote | neither exists | the same: cut from the remote's tip, the local base not moved |
| a story's worktree, or a tree with uncommitted changes | neither exists | the same; where it was run is as it was |
| any | the branch exists, local or on the remote | error naming it; no worktree, no file, the issue's labels unchanged |
| any | the directory exists | error naming it; the same |
| any | neither exists, the fetch failing | error; the same |
| any | the worktree made, the forge refusing the label | error naming the worktree, the file and the label; the worktree stays |
The worktree is made and the file written before the issue is relabelled. The checkout the command is run in is not written to.
What is not built yet
| Planned | Does | Until then |
|---|---|---|
| the reviewer | a role or skill that reads the change against its story and calls tp story review |
a review is run by hand or by an agent told to |