tp story
Development-method stories (see the method): one file per
story in docs/stories/NNN-slug.md, tracked by one issue on the release
remote's Forgejo.
| Command | Does | Prints |
|---|---|---|
tp story new TITLE... |
writes the next story from the template, status proposed |
the new file's path |
tp story issue NNN |
creates the story's issue and stamps (#N) onto its heading |
#N url |
tp story offer |
at code level 3, on a story branch: the story is written and ready for the human. Commits the story file alone if it has changed and pushes the branch, once its acceptance has no blank cell | #N offered, then the story's page on the forge |
tp story accept |
at code level 3, on a story branch: labels the story's issue defined once its acceptance has no blank cell |
#N defined |
tp story review CONCERN pass|fail [-body FILE|-] |
at code level 3, on a story branch: records a review of the story's change as a comment on its issue | #N CONCERN: pass (change ID) |
tp story call [-undefined] REASON... |
at code level 3, on a story branch: comments the reason on the story's issue and labels it called |
#N called |
tp story answer [TEXT...] |
takes called off, with TEXT as a comment |
#N answered |
tp story land [-dry-run] |
under trunk flow (maturity.flow: trunk, or code level 3), on a story branch: merges the remote base branch in when it has moved, runs the checks, pushes and opens the pull request into the base branch, titled by the story's fragment; at code level 3 it then merges the pull request once its reviews pass |
each step, then the pull request and Next step (human): merge it; at level 3 the reviews wanting, or Story #N has landed |
tp story query [-offline] |
under trunk flow, on a story branch or in its worktree: reads the repository and the forge and changes nothing | the story, where it stands, Next step with who takes it, and Not ready |
tp story tidy |
at code level 3, in any checkout of the repository: removes the worktree and the local branch of every story that has landed on the base branch | each landed story, with what was removed or why it was kept |
Numbering — one above the highest NNN-*.md in docs/stories/,
starting at 001. The slug is the title's lower-case words joined by
hyphens, cut at a word boundary to 50 characters.
At code level 3 a story takes its issue's number instead (story 051),
padded to three digits: tp idea story 261 writes 261-slug.md, headed
# 261 — TITLE (#261), and tp idea story 7 writes 007-slug.md. The
forge hands issue numbers out, so two stories scaffolded before either
lands cannot share one. The highest number in docs/stories/ is not
read; a file that already has the number is refused by name, to be
renamed. Stories numbered before story 051 keep their numbers: a story
is found by the (#N) on its heading, whatever its file's number.
The issue is titled Story NNN: <title>. Its body is the first
paragraph of the story's Why section and a link to the file on the
current branch — push the story for the link to resolve. The file is the
source of truth; the issue is only ever written from it. issue refuses a
story that already has an issue or has no Why paragraph, and leaves the
file untouched if the forge call fails. Forge and token are resolved as
for tp issue.
At code level 3 new and issue are refused: a story is the issue of
the idea it came from, written by tp idea story N, with
no **Status:** line (story 043).
Accepting a story (story 043)
A defined story can be built without a conversation: no blank cell in
its acceptance, and its soft acceptance already judged by a human
(agent flow).
tp story accept records the human's acceptance as the label defined
on the story's issue, beside story. It can check the first half only;
run it when the human has accepted the story. The story is the one in
docs/stories/ whose heading carries the branch's issue.
| Branch | Story file for #n | Acceptance | Issue #n | Outcome |
|---|---|---|---|---|
| any | — | — | — | below code level 3: error |
not story/<n>-<slug> |
— | — | — | error: run it on the story's branch |
| story | none | — | — | error naming tp idea story |
| story | present | a blank cell, or no table | any | error naming the file; the forge not asked |
| story | present | every cell of every table filled | labelled story |
defined added |
| story | present | filled | labelled defined already |
says so; nothing changed |
| story | present | filled | not labelled story, or closed |
error |
Offering a story (story 280)
A story is written in its worktree, and until tp story land the
forge has none of it, so the human can read it only where it was
written. tp story offer is the agent saying "this is ready for you":
it puts the story on the forge, where tp overview
links it from its card and offers to accept it. No label is written: a
story is offered when its file, on its branch on the forge, has its
acceptance filled. Offer again after the story changes.
| Branch | Story file for #n | Acceptance | The file, against the branch on the remote | Outcome |
|---|---|---|---|---|
| any | — | — | — | below code level 3: error |
not story/<n>-<slug> |
— | — | — | error: run it on the story's branch |
| story | none | — | — | error naming tp idea story |
| story | present | a blank cell, or no table | any | error naming the file; nothing committed, nothing pushed |
| story | present | filled | untracked or changed | the file alone committed, "Story n: offered"; the branch pushed; the story's URL printed |
| story | present | filled | committed, the branch not on the remote or behind | the branch pushed; the URL printed |
| story | present | filled | the branch on the remote where the local one is | says it is offered already; the URL printed |
| story | present | filled | any, the push refused | error; the commit stands |
Other files, staged or not, are neither committed nor touched. The push is of the branch, so work already committed on it goes too.
Calling for a human (story 045)
An agent works alone only while the story holds. When it does not, it
calls: it stops, and says why
(when an agent calls).
tp story call records the call where an overview reads it: the reason
as a comment on the story's issue, Called: REASON, then the label
called. The comment is written first, so a called story is never
without its reason. When to call is the agent's judgement; tp only
records it. tp story answer is run once the human has answered; the
human can answer from the story's card on
tp overview instead, which does
the same against the forge and starts an agent to carry on.
| Command | Issue #n | Outcome |
|---|---|---|
call REASON... |
open, labelled story |
the comment; called added |
call -undefined REASON... |
open, labelled story |
the same, and defined removed: the acceptance was wrong, and the story goes back to refinement until tp story accept |
call REASON... |
labelled called already |
a second comment; the label stays |
call with no reason |
any | error; nothing written |
call REASON... |
not labelled story, or closed |
error; no comment |
answer [TEXT...] |
labelled called |
called removed; TEXT, when given, commented as Answered: TEXT |
answer |
not labelled called |
error; nothing changed |
| either | below code level 3, or on a branch not story/<n>-<slug> |
error |
A called story is not abandoned and not merged. tp story query
reports it as called with the next step the human's, in place of the
step that would land it.
Landing a story (story 032)
tp story land is the story's half of trunk flow
(ADR 0008):
it integrates, and decides no version. The release is a separate run on
the base branch
(release workflow).
| Branch | State | Outcome |
|---|---|---|
| any | code level 1 without maturity.flow: trunk, or code level 0 |
error naming the key |
| the base branch | any | error: land runs on a story branch |
not story/<n>-<slug> |
any | error naming the form |
| story | working tree dirty | error |
| story | release on the remote |
error: a batch is in flight |
| story | no changes/<n>.<kind>.md |
error naming the file to add |
| story | CHANGELOG names an untagged version | error: land takes no release commits |
| story | already in the base branch | says so; nothing pushed |
| story | its last pull request closed without merging | error: reopen it or close the story |
| story | its pull request open into another branch | error: retarget or close it |
| story | base has moved, conflicts | the merge is left in progress and the files named; resolve, commit, run again |
| story | otherwise | base merged in if it has moved; checks; push; the pull request into the base opened, or reused when open |
Checks that modify a tracked file fail, naming the files (story 036): nothing is pushed, and the changes stay in the working tree, since they are usually what the story should have committed.
The checks are skipped when the pull request is open and the branch tip
is the one they last passed on. merge_wait is not read: the run ends
at the open pull request.
Review and the agent's merge (story 046)
At code level 3 no human is needed between a defined story and its
landing
(ADR 0011):
a reviewing agent passes the change and tp story land merges it. The
review is a comment on the story's issue, where a call's reason is too,
so the issue is the story's one thread. tp story review writes it;
its first line is what tp story land reads back:
Review story: pass — change 3f9a1c0b7d2e4a51 at 1a2b3c4d5e6f
Every row of the acceptance is met; the docs name the new flag.
The concerns are reviews: in task-plus.yml, a list of names; absent,
it is [story], the change against its story, so a level 3 project is
never merged unreviewed. The latest review of a concern is the one that
counts.
A review stands while the story's change is the one it reviewed: the diff from where the branch left the base branch to its tip, read without line numbers. Merging the base in cleanly leaves that diff as it was, so one story landing does not send every other back to review; new work, or a conflict resolved, changes it. A change next to the story's own lines changes it too. The checks run again on the merged tip either way.
tp story review CONCERN pass|fail |
Outcome |
|---|---|
CONCERN in reviews:, the tree clean, pass |
the comment on #n, with the -body findings when given |
the same, fail with findings |
the comment, with fail |
fail with no findings |
error: a fail says what is wrong |
CONCERN not in reviews:; a verdict neither pass nor fail |
error; no comment |
| uncommitted changes | error: a review is of what is committed |
| no change against the base | error: nothing to review |
below code level 3; not a story branch; the issue closed or not a story |
error; no comment |
tp story land at code level 3, after the rows of
Landing a story:
| Issue #n | Reviews | Outcome |
|---|---|---|
labelled called |
any | error: it waits for a human; nothing merged in, pushed or opened |
not labelled defined |
any | error naming tp story accept; nothing pushed or opened |
defined, not called |
every concern's latest review passes and stands | checks, push, pull request, then the pull request merged: Story #n has landed on main |
defined, not called |
a concern not reviewed, failed, or stale (its pass was of another change) | checks, push, pull request; not merged; each concern wanting is named with tp story review |
defined, not called |
pass and stand, the forge refusing the merge | error naming the pull request, which stays open |
| any | any, -dry-run |
says whether it would merge; nothing pushed, opened or merged |
tp is the only writer of a review by convention, as of the labels:
developer and reviewer share a token, so the forge cannot tell a review
from a comment typed to look like one.
Where a story stands (story 039)
tp story query is the story's query, as tp release query is the
release's
(release workflow);
neither reads the other's facts. Run it before acting and do what it
says. It fetches the release remote first; -offline skips the fetch
and the forge. The report is Mode, Story: #n on story/<n>-<slug>
with its open pull request, Stands, Next step and Not ready. The
first matching row wins:
| State | Stands | Next step | Who |
|---|---|---|---|
not named story/<n>-<slug> |
— | rename the branch | agent |
| in the base branch with its fragment committed, released in vX | released in vX |
tidy: git switch main && git branch -d the branch; at code level 3 tp story tidy, run from the main checkout |
agent |
| in the base branch with its fragment committed, untagged | landed on main |
the same: its release is not the story's step | agent |
at code level 3, its issue labelled called (story 045; the forge not asked with -offline) |
called |
answer the call on #n, then tp story answer |
human |
at code level 3, its issue not labelled defined (story 048; the labels not read with -offline, or when the issue is not open) |
not defined |
accept the story on #n: on tp overview, where tp story offer puts it, or with tp story accept |
human |
in the base branch, no changes/<n>.<kind>.md committed: just cut from it |
not begun |
commit the story's work and its fragment | agent |
| its CHANGELOG names an untagged version | — | revert the release commits | agent |
no changes/<n>.<kind>.md |
— | add the fragment | agent |
| its pull request open into another branch | — | retarget or close it | human |
| not on the remote | not pushed |
tp story land |
agent |
| commits not pushed | N commit(s) not pushed |
tp story land |
agent |
| no pull request | not in a pull request |
tp story land |
agent |
| the base has moved and conflicts with it | in conflict with main |
tp story land: merges the base in and stops at the conflicts |
agent |
| the base has moved, no conflict | behind main by N |
tp story land: merges the base in, runs the checks, pushes |
agent |
| the tip is not the commit the checks last passed on | unbuilt |
tp story land: runs the checks |
agent |
| at code level 3, its pull request open, a concern not reviewed, failed or stale (story 046) | in review: CONCERN: not reviewed |
review the change and record it with tp story review |
agent |
| at code level 3, its pull request open, every review passing and standing | reviewed |
tp story land: merges it |
agent |
| its pull request open | in pull request #p |
review and merge it | human |
pushed, the forge not asked (-offline) |
pushed |
review and merge its pull request | human |
A story behind the base goes back through tp story land, so that what
is merged was built on the current trunk. The commit the checks passed
on is recorded by tp story land in the repository's git config, so a
fresh clone of a built branch reads as unbuilt until it is landed again.
Not ready: a dirty tree, release on the remote, a hand-edited
[Unreleased], a .tp-release-comment, a missing fragment, commits not
pushed.
| Run | Outcome |
|---|---|
| on the base branch | error: run it on a story branch or in its worktree |
code level 1 without maturity.flow: trunk, or code level 0 |
error naming the key |
Tidying landed stories (story 053)
At code level 3 a story is written and built in a worktree of its own,
which tp idea story makes.
tp story tidy removes what the stories that have landed left on this
machine: it fetches the release remote and, for every local
story/<n>-<slug> branch that is in the remote base branch with its
fragment committed, removes the branch's worktree and deletes the
branch. It is run in any checkout or worktree of the repository and
reads no forge. The remote branch is the forge's to remove, when the
pull request merges.
| Story's branch | Its worktree | Outcome |
|---|---|---|
| in the remote base | clean | the worktree removed, the local branch deleted; the story named |
| in the remote base | uncommitted or untracked changes | kept, and named with why |
| in the remote base | the one the command is run in | kept, and named with the main checkout to run it from |
| in the remote base | none: a branch in the main checkout, not checked out | the local branch deleted |
| in the remote base | none: the branch the main checkout has out | kept, and named with the switch to the base branch that frees it |
| in the remote base | its directory deleted by hand | kept, and named with git worktree prune, after which the branch has no worktree; the stories after it are still tidied |
| not in the remote base | any | untouched, not named |
| in the remote base, no fragment committed: just cut from it | any | the same: it has not landed |
| none landed | — | says so |
"Clean" is what git status reports: no uncommitted and no untracked
change. Ignored files do not count, so a landed worktree that holds
only ignored files, build output for one, is removed with them.
The sandbox .claude/settings.json that tp idea story writes is kept
out of git status by a line in the repository's info/exclude. Git
reads that file from the repository, not from each worktree, so the
line applies in every checkout of it, the main one included.
Below code level 3 it is refused: there the tidy step is the one
tp story query names.
What is not built yet
The manual's trunk flow page is
the specification of the cycle; tp does not yet do all of it.
| Planned | Does | Until then |
|---|---|---|
| publishing on landing (#221) | the documentation is published from the tip of main once a story's pull request merges |
tp pages deploy by hand, or the next tp release |