tp overview
The manual's overview,
at code level 3: every open idea, roadmap item and story across the
level 3 repositories a person works on, on one page: a board with the
flow's phases left to right, and above it the count of what needs them.
tp story query says where one story stands; this says where all of
them do.
tp overview serves the page locally and prints its URL (port 8101, or
the next free one). Each load reads the forges afresh, and the page
refreshes itself. It runs anywhere, in a project or out
of one. Its icon in the browser's tab is a kanban board, to tell it
from the tabs beside it.
The forges
The forges are listed in the user config,
~/.config/task-plus/local.yaml, since the overview is the person's
and no project's:
overview:
- host: https://git.example
owner: NAME
token_env: FORGE_TOKEN
dir: ~/git/NAME
| Field | Is |
|---|---|
host |
the Forgejo's base URL |
owner |
the user or organisation whose repositories are read |
token_env |
the env var holding the API token, fetched as for tp issue; without it only public repositories are seen |
dir |
the directory that holds the checkouts of the owner's repositories on this machine, repository R at <dir>/R; a leading ~ is the home directory. Needed to interview an idea from its card, and to start the agent that carries on with a story answered from its card, in the worktree <dir>/R-<N>-<slug>, and to develop a story from its card, in that worktree |
Without the list the command stops and names the file. Forgejo only.
The list is read from the user config alone: a project's
task-plus.local.yaml neither adds to it nor replaces it.
The refresh
The page says when what it shows was read, and refreshes itself: 30 seconds after it was last brought up to date it reads the forges again. The board and the count are replaced only once the new ones have arrived; until then the page stays as it was, and can be read, scrolled and used.
| The refresh | The page |
|---|---|
| still being read | unchanged; no second one is asked for |
| arrived | the board and the count as just read, and when; the next 30 seconds on |
| arrived, a forge not read | the same, with the forge named as on a load: an arrival, not a failure |
failed: tp overview stopped, or answered with an error |
unchanged; says the refresh failed and when; the next 30 seconds on |
| arrived after a failure | as arrived; the failure no longer shown |
A page left open reads the forges every 30 seconds whether or not it is looked at, each open page for itself.
The limit
The manual's limit is on the stories that need the person, blocked or not yet defined, and it is theirs, so it too is read from the user config alone:
limit: 3
limit: |
Outcome |
|---|---|
| a whole number above 0 | that limit |
| unset, or 0 | 3 |
| below 0, or not a whole number | the command stops, naming the file and the field |
Above the board the page counts those stories against it. N is the blocked stories and the stories not yet defined together; nothing else counts.
| N | Every forge read | The line |
|---|---|---|
| below the limit | yes | Needs you: N of LIMIT |
| the limit | yes | Needs you: N of LIMIT, at the limit |
| above the limit | yes or no | Needs you: N of LIMIT, over the limit; in red. "at least N" when something was not read |
| the limit or below | no | Needs you: at least N of LIMIT |
Nothing is refused at the limit yet.
Which repositories
No list of repositories is kept, and no checkout is read.
| Repository | Outcome |
|---|---|
of a listed owner, maturity.code: 3 in task-plus.yml on its default branch |
its issues shown |
of a listed owner, a lower level or no task-plus.yml |
none shown, whatever their labels |
| level 3, with no open issue of the flow | not on the page |
| of another owner | not read |
The board
The page is a board: the flow's phases across the top, left to right,
and each open issue a card in the column of its phase, placed by the
labels tp wrote on it. "Pull request" is an
open one from story/<N>-… for issue N.
story |
defined |
Pull request | Other label | Column |
|---|---|---|---|---|
| no | — | — | idea |
Ideas |
| no | — | — | roadmap |
Roadmap |
| yes | no | any | — | Not yet defined |
| yes | yes | none | — | In development |
| yes | yes | open | — | In review, the pull request linked |
| no | — | — | none | no card |
Each heading has its count and links to its section below. A card is the repository, the issue number linked to the forge, and the title. A column fills from the top, by repository, then issue number; a repository's cards carry a colour of its own, the same in every column: its Peacock colour, the one that tints its VSCodium window, when it has committed one.
.vscode/settings.json on the repository's default branch |
peacock.color in it |
The cards' colour |
|---|---|---|
| absent, or the forge cannot give it | — | generated: one of the page's own, unlike the other generated ones |
| present | not set, or set only in a comment | generated |
| present, comments and trailing commas allowed | a hex colour ("#11ddaa", "#2cb") |
that colour |
| present | anything else ("red") |
generated |
A Peacock colour changed in an editor and not yet on the default branch is not seen. Two repositories with the same Peacock colour share it.
| One repository's cards in one column | Shown | Folded into "… N more" |
|---|---|---|
| 5 or fewer | all | none |
| more than 5 | the first 5 | the rest; the box opens in place |
A forge that cannot be reached, or whose token is missing, is named above the board with why, and the other forges' issues are still shown.
Ideas
Captured and not yet interviewed: tp idea add. An
interview ends in closing it, a roadmap item or a story.
Every card in the column has a button, "interview". It starts an agent
on this machine, claude --remote-control in the repository's checkout
(<dir>/R), under a terminal of tp's own, with a first message that
asks for the interview of that idea, and sends the browser to the
session on claude.ai/code. The agent, its commands and its tokens are
this machine's; the browser shows the conversation. The button writes
nothing to a forge: what the interview ends in, the agent runs as you
decide. It needs claude signed in, Remote Control allowed once on this
machine (claude remote-control, answering y), and the checkout
trusted by claude.
The forge's dir |
<dir>/R |
claude |
An interview of the idea from this tp overview |
"interview" |
|---|---|---|---|---|
| set | a directory | prints the session's address within a minute | none, or one that has ended | started, the session named R #N; the browser sent to it |
| set | a directory | the same | still running | none started; the browser sent to the one running |
| not set | — | — | — | nothing started; the page names the user config and the forge |
| set | absent, or not a directory | — | — | nothing started; the page names the path |
| set | a directory | not on the PATH | — | nothing started; the page says so |
| set | a directory | ends, or prints no address within a minute and is stopped | — | the page gives the last line it printed |
An interview lasts while tp overview runs and ends with it. Linux and
macOS.
Roadmap
Worth doing, not now: sharpened, bounded and placed in an epic of
ROADMAP.md by tp idea roadmap. Interviewed again when
its turn comes.
Not yet defined
A story being written: its acceptance is not yet agreed. It needs you,
and counts against the limit, until you accept it and
tp story accept says so.
A story that tp story offer has put on the forge can
be read and accepted from its card:
| The story's branch on the forge | Its story file there | Acceptance | The card has |
|---|---|---|---|
| none | — | — | nothing more |
| present | absent | — | nothing more |
| present | present | a blank cell, or no table | a link, "story", to the file as the forge shows it |
| present | present | filled | the link, and a button, "accept" |
"accept" does what tp story accept does, against the forge's copy.
Every card in the column has a button, "to idea", for a story that is
half formed or that the flow never interviewed: it moves the issue
back to Ideas, to be interviewed again, and off the count.
idea is added, then story and called are taken off; the story's
file, its branch, its worktree, its other labels and any roadmap line
stay as they are.
| Issue, read again | Open pull request from story/<N>-… |
"to idea" |
|---|---|---|
open, story, not defined |
none | relabelled; the board shown, the card in "Ideas" |
open, idea, not story |
— | nothing written; the board shown |
open, story and defined |
any | nothing written; the page names tp story call -undefined |
open, story, not defined |
open | nothing written; the page names the pull request |
closed, or neither story nor idea |
any | nothing written; the page says why |
open, story, the forge refusing a label |
none | the page gives the forge's words; with idea on and story not yet off the card stays, and a second press finishes it |
tp idea story N refuses a branch that exists already:
an idea moved back from a story with a branch needs the branch
removed, or another title, before it is a story again.
"accept", "to idea" and "answer" are all on
the page that writes to a forge,
with the token of token_env, and only to a level 3 repository of a
forge of the user config.
| Pressed, and the story read again | Issue | Outcome |
|---|---|---|
| filled | open, story, not defined |
defined added; the board, the card in "In development" |
| filled | defined already |
nothing written; the board |
| a blank cell now, or the file or branch gone | any | nothing written; the page says why, with a link back |
| filled | closed, or not story |
nothing written; the page says why |
| filled | the forge refusing the label | the page says why, in the forge's words |
A press
A press does not load the page again. It is sent in the background and the board stays in place:
| The press | The page |
|---|---|
| sent, not yet answered | the card says "accepting…" or "moving…"; none of its buttons can be pressed |
| taken: the forge is written | the board is refreshed at once, not at the next 30 seconds; the card stays as at the press until it arrives |
| refused | above the board, "Not accepted: why" or "Not moved to an idea: why"; the card's buttons can be pressed again; the board refreshed at once |
failed: tp overview stopped |
above the board, that the press failed and when; the card's buttons can be pressed again |
While a press is not yet answered no refresh is shown or asked for: the press ends with one, so the board shown is of the forge as written. What the page says of a refusal or a failure stays through that refresh, and is gone at the next one, 30 seconds on, or at the next press. A press of "interview" says "starting…" on its card, and the browser is then sent to the interview. Where the page's script does not run, a press loads the board again, or a page that says why not, with a link back.
The form carries a secret made when tp overview starts, so no other
page can press it: a request without it is refused. The page is served
only under this machine's own name (localhost, 127.0.0.1, ::1); a
request under any other is refused, so that a page elsewhere whose name
is made to resolve here can neither read the secret nor press.
In development
Defined, and being built by an agent against its acceptance table. Nothing is needed of you.
The agent's terminal (story 320)
The agent that builds a story runs in a tmux session of the story's
own, named R-N: the repository's name and the issue, a character
tmux does not take in a name replaced by -. The session is
tmux's, not tp overview's: it outlasts the page and tp overview,
a tp overview started later finds it, and tmux attach -t R-N
reaches it from a terminal. It ends when its agent does.
| Card in "In development", blocked or not | Has |
|---|---|
no session R-N, or tmux not on the PATH |
a button, "develop" |
session R-N exists |
a link, "terminal"; no button |
Whether there is a session is read when the forges are, on a load and on each refresh. A card in another column has neither.
"develop" reads the story again, and starts claude, without
--remote-control, in the story's worktree <dir>/R-<N>-<slug>, told
to build the story: run tp story query and do what it says. The
browser is sent to the terminal page. It writes nothing to a forge. It
needs tmux and claude on the PATH, and the worktree trusted by
claude.
The forge's dir |
The worktree | tmux, claude |
Session R-N |
"develop" |
|---|---|---|---|---|
| set | a directory | both on the PATH | none | the session started, claude in it; the browser sent to the terminal page |
| set | a directory | both on the PATH | exists | none started; the browser sent to the terminal page |
| not set | — | — | — | nothing started; the page names the user config and the forge |
| set | no branch on the forge, so none known | — | — | nothing started; the page says why |
| set | absent, or not a directory | — | — | nothing started; the page names the path |
| set | a directory | tmux not on the PATH |
— | nothing started; the page says so |
| set | a directory | claude not on the PATH |
— | nothing started; the page says so |
| set | a directory | both, tmux refusing the session |
none | nothing started; the page gives tmux's words |
| any | any | any | any; the story no longer open, story and defined |
nothing started; the page says why |
The terminal page has the repository and the issue, linked to the
forge, the command that attaches from a terminal, "back" to the board,
and the session's terminal. What draws it (xterm.js) is served by
tp overview itself: nothing is fetched from elsewhere.
Session R-N |
The terminal page |
|---|---|
| exists | its terminal as it now stands, then live; keys typed on the page reach the agent |
| exists, the page resized | the terminal takes the page's size |
| exists, open on two pages, or on a page and in a terminal | each shows it; keys from either reach the agent |
| exists, the page closed | the session and its agent carry on; opened again, the terminal as it then stands |
| ends while the page is open | the page says the session has ended; what it last showed stays |
detached from within (tmux's detach key) |
the page says so; the session carries on, and loading the page again attaches |
| none when the page is asked for | says no agent is running for the story; a link back |
tp overview stops while the page is open |
the page says the connection was lost; the session carries on |
The page and its connection are guarded as a press is: the
connection is taken only with the secret, only from a page
tp overview served, only under this machine's own name, and only for
a level 3 repository of a forge of the user config.
The terminal page shows a session for as long as there is one, whatever has become of its story: one since closed, or in review, still has its terminal at the page's address, though its card no longer links it.
tp overview sees only session R-N: an agent in the worktree in an
editor or another terminal is not seen, and "develop" starts a second
beside it. Two repositories of the same name on two forges share a
session name. A session is ended in its terminal, or by
tmux kill-session -t R-N. Linux and macOS.
In review
Its pull request is open: an agent that did not write the change
reviews it, and tp story land merges it once the review
passes and stands.
Blocked
A card flagged "blocked" is a story whose agent has stopped and waits
for you: the checks cannot be made green, a finding cannot be resolved,
or the story no longer holds. The reason is a comment on the issue.
Nothing more is done on it until it is answered. It stays in the
column of the phase it stopped in, comes first among its repository's
cards, and counts against the limit. The label and the command still
say called (tp story call); the word changes throughout with #281.
Answering (stories 311, 315)
A blocked card links "answer", a page of that story: the story as its
branch on the forge has it, why it was called (the Called: comments
since the last Answered: one, oldest first, each with its date and
time in this machine's zone, the zone named), a box for your answer,
"answer" and "back". Opening the page writes nothing. The page links
the issue and the story only from an http or https address; given
anything else by the forge, it has the same words and no link.
"answer" does what tp story answer TEXT
does, against the forge: the issue is read again, Answered: TEXT is
commented, then called taken off. It then starts an agent on this
machine in the story's worktree, <dir>/R-<N>-<slug> for the branch
story/<N>-<slug>, as "interview" starts one in the checkout: claude --remote-control, the session named R #N, told that the call is
answered and to run tp story query. The browser is sent to its
session. The answer is recorded before the agent is started, and stays
recorded when the start fails.
tp overview cannot see a session left open in the worktree by the
agent that called, nor tell it anything: close it first, or a second
agent is started beside it.
| The box | Issue, read again | The forge | The agent | The browser |
|---|---|---|---|---|
| text | open, story, called |
the comment; called off |
started | sent to its session |
| text | the same | the same | one started by an earlier "answer" for the story from this tp overview still runs: no second |
a page: the answer is recorded, the running agent not told; a link to its session |
| text | the same | the same | one such is still starting: no second; the press waits for it | as the row above when it starts; when it does not, the page of the press that started it |
| text | the same | the same | not started: dir not set, no branch on the forge, the worktree absent, claude not on the PATH, or claude ended or gave no address within a minute |
a page: the answer is recorded, and why no agent was started |
| empty | any | nothing written | none | the answer page again, saying an answer is needed |
| text | not called |
nothing written | none | a page: it is answered already |
| text | closed, or not story |
nothing written | none | a page saying why |
| text | the forge refusing the comment | nothing written | none | the answer page again, the forge's words above the box, the text still in it |
| text | the forge not reached, or failing, when the issue, its labels or its branches are read | nothing written | none | the answer page again, what went wrong above the box, the text still in it; when the page cannot be read either, a page saying what went wrong, with the text in a box and "answer" to press again |
| text | the forge refusing the label | the comment only | none | a page: called is still on; tp story answer with no text, in the worktree, takes it off |
An agent started by "answer" ends with tp overview, as an interview
does. Linux and macOS.
Not shown yet: stuck and stale stories, landings since the last human
review, dark features; and roadmap items are not in ROADMAP.md order.