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.