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