Files
paperclip-harness/docs/WORKSPACES.md

107 lines
4.8 KiB
Markdown

# Every workspace and pane, at the end
The finished shape, so a gap is visible at a glance. One pane per workspace unless stated;
panels are what the pane's program draws, switched with Tab or the tab keys.
Status: **built** means running in the project session now. **missing** means planned, not
written yet.
## 1. Shell — a plain prompt in the project folder
It is not a screen of the factory. It is there because some things are quicker to type than
to click, and because every workspace needs one pane that never exits: TUIOS deletes a
workspace whose last pane closes and renumbers the rest. It is also the fallback for a
command no panel covers, and the place a tool pane is opened *from* when you know what you
want.
There is deliberately nothing in it beyond your own shell, in the project folder, so that
what it shows is never a second copy of anything.
| Pane | Shows | Status |
|---|---|---|
| `Shell>shell` | a prompt in the project folder | built |
## 2. Board
| Pane | Shows | Status |
|---|---|---|
| `Board>tasks` | tasks grouped todo, running, blocked, review, done; each row: identifier, state, assignee, title, what it waits on | built |
| `Board>detail` | the chosen task: state, assignee, blockers, verify command, last run, cost | built |
| `Board>needs` | decisions waiting on a person; second tab: the chosen task's activity | built |
## 3. Work
| Pane | Shows | Status |
|---|---|---|
| `Work>runs` | run timeline and activity, with cost per run | built |
| `Work>change` | worktree, branch, base, commits, changed files, the diff | built |
| `Work>facts` | task, state, worktree path, branch, base, cost | built |
| `Work>review` | the verdicts recorded on this task: review findings, refused merges, merged results, blocking ones in red | built |
## 4. Reply
| Pane | Shows | Status |
|---|---|---|
| `Reply>task` | the task above the conversation: identifier, state, assignee, verify command | built |
| `Reply>thread` | every message, with author and time | built |
| `Reply>replybox` | the reply box, and the state that will be sent with it | built |
## 5. New task
| Pane | Shows | Status |
|---|---|---|
| `New task>form` | title, what it must do, what must finish first, the command that proves it is done, whether to assign | built |
| `New task>guidance` | what a task needs: one thing, a command, a boundary, a blocker | built |
| `New task>preview` | exactly the description the agent will receive | built |
## 6. Agents — the missing workspace
| Pane | Shows | Status |
|---|---|---|
| `Agents>roster` | every agent: name, state, spend this month, budget | built |
| `Agents>runs` | the company's runs, newest first: agent, task, state, what woke it, duration | built |
| `Agents>log` | the chosen run's output, deltas gathered back into paragraphs — this is watching Pi work | built |
| `Agents>settings` | role, job title, model, monthly budget, heartbeat — each one editable, with pause and resume | built |
## 7. Project
| Pane | Shows | Status |
|---|---|---|
| `Project>project` | overview: agents, tasks, money, run activity sparkline — then facts, costs, settings | built |
| `Project>costs` | spend per task and the total | built |
| `Project>settings` | the project's own file, and the limits Paperclip holds | built |
## 8. Repair
| Pane | Shows | Status |
|---|---|---|
| `Repair>repair` | health: three-state checks and an icon test row | built |
| `Repair>layout` | what TUIOS actually has, read live | built |
| `Repair>rebuild-log` | the last rebuild's output | built |
## Tool panes — any of these, in any workspace, on demand
A tool pane is not part of a layout. `t` opens a chooser in the workspace you are in, the
tool appears beside what you were reading, `esc` closes it and focus returns. This is how
Yazi, fzf, Neovim, Lazygit, Hunk and anything else fits without being rebuilt by us.
| Tool | What it is for | Status |
|---|---|---|
| Lazygit | branches, commits, staging, history | wired: `t` in Board>board or Work>work |
| Hunk | reading a change as a review | wired the same way |
| Yazi | files | wired the same way |
| Neovim | editing a file the task touched | wired the same way |
| fzf | picking anything | wired the same way |
| shell | any command the interface does not cover | built (`Shell>shell`) |
| ocr | the review of the current change | installed, behind `bin/review` |
## Count
- **23 panels built**, across 8 workspaces. Nothing is missing from the list above.
- **tool panes wired** in Board>board and Work>work: `t` opens the chooser, `enter` opens
the tool beside the pane, `esc` closes it, and the tool's own quit key closes its pane.
The other workspaces can get the same key whenever it is wanted.
Nothing in the missing list changes the layout: each is one more panel inside a pane that
already exists, or one pane-opener for a tool.