320 — tp overview: a story's agent in a terminal on the page (#320)
Roadmap: #317
Why
tp overview shows a story as "In development" and does nothing more
for it: the agent that builds it is started by hand, in a terminal or
an editor window found some other way, and the board cannot say whether
one is running at all. The agents the board does start, for an
interview and for an answer, are shown on claude.ai/code, die with
tp overview, and cannot be reached from a terminal.
#317 wants the board to be the control point for the agents working on stories. This is its first step: an accepted story's agent started from its card, and its terminal seen and typed into on a page of the board.
What changes
tp overview, a card in "In development": a button, "develop", when the story has no agent session, and a link, "terminal", when it has.- "develop": starts
claudein the story's worktree, in atmuxsession of the story's own, and sends the browser to its terminal page. tp overview, the terminal page: the session's terminal, live; keys typed on the page go to it. It names thetmuxcommand that attaches to the same session from a terminal, and links back to the board.- The session is
tmux's, nottp overview's: it outlasts the page andtp overview, and atp overviewstarted later finds it. ROADMAP.md: a new epic, "Development cycle harness":tp overviewas the harness of the development cycle, the agents that interview, build and review stories started, seen and steered from the board. #317 is placed in it bytp idea roadmaponce this story has landed the heading.docs/overview.md: "In development" describes the button, the page and the session;diris needed to develop as well;tmuxis named as what "develop" needs.
Acceptance
R is the repository's name, N the issue, story/<N>-<slug> the story's
branch on the forge, the worktree <dir>/R-<N>-<slug>, where
tp idea story makes it, and the session the tmux
session named R-N, a character tmux does not take in a name
replaced by -.
The card
| Card | Session R-N |
Has |
|---|---|---|
| in "In development", blocked or not | none | a button, "develop" |
| in "In development", blocked or not | exists | a link, "terminal", to the terminal page; no button |
| in any other column | either | neither |
any, tmux not on the PATH |
— | the button, as with no session |
Whether a session exists is read when the forges are, on a load and on each refresh.
The press
The agent is claude, without --remote-control, in the worktree, its
first message: build story #N; run tp story query and do what it
says. The press writes nothing to a forge.
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 |
The story is read again at the press: one no longer open, story and
defined starts nothing, and the page says why.
The terminal page
Session R-N |
The page |
|---|---|
| exists | its terminal as it now stands, then live: what the agent prints appears as it is printed; 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 agent has ended) | the page says the session has ended; what it last showed stays; a link back |
| none when the page is asked for | says no agent is running for the story; a link back |
The page also has the repository and the issue, linked to the forge,
the command tmux attach -t R-N, and "back" to the board. What draws
the terminal is served by tp overview itself: nothing is fetched from
elsewhere.
The session
| Event | The session |
|---|---|
tp overview stops |
carries on, its agent with it |
a tp overview started later |
finds it: the card links "terminal", and the page shows it |
tmux attach -t R-N in a terminal |
the same session as the page shows |
| the agent ends | ends; the card has "develop" again |
The guard
| Request | Outcome |
|---|---|
the press without the secret tp overview made when it started |
refused; nothing started |
the terminal's connection without the secret, or opened by a page that tp overview did not serve |
refused; nothing shown, no key taken |
| the page, the press or the connection under a name other than this machine's own | refused |
| the press or the page for a repository below level 3, or of a forge not in the user config | refused |
Linux and macOS.
Out of scope
- "interview" and "answer": they start their agents as they do now,
under
--remote-controland ending withtp overview. Moving them to a session and a terminal page of this kind is a later story. - An agent in the worktree that is not in session
R-N: one in an editor or another terminal is not seen, and "develop" starts a second beside it. - Ending a session from the board. The agent is ended in its terminal,
or
tmux kill-session -t R-N. - A reviewer's agent for a card in "In review", and any agent for a story not yet defined.
- Telling an agent anything from the board other than by typing in its terminal; one session that talks to the board (#317).
- Two repositories of the same name on two forges: they share the session name.
- Showing on the card what the agent is doing, or that it waits for input.
- A page reached from another machine.
Decisions
The session is tmux's rather than a terminal tp overview holds, as
it holds an interview's: a story is built over a longer time than
tp overview is left running, and the same session can then be reached
from a terminal. It costs a dependency, tmux, that the press names
when it is missing. An ADR if the fork is thought worth one.
Done when
- tests express the acceptance table and pass
- spec updated
- the epic's heading in
ROADMAP.md; #317 stays open, this being its first step - changelog entry
- issue closed with a link to the release