The plan from here: Paperclip underneath, a Go terminal app on top

Written 2026-11-09. Read with WHAT-WE-ARE-BUILDING.md. This is the third attempt, and it says where we have been as well as where we are going, because the first two were lost by plans that only said "next".

1. What we set out to make

A coding factory that runs inside TUIOS. A person writes a goal; it is split into tasks; each task runs on its own copy of the code; tests and a review decide whether the work is finished; finished work is merged one at a time; the person is interrupted only to make a decision. Terminal only. Per project, not per machine.

2. Where we have been

Attempt one (OMA, our own cockpit). We built a coordinator around the @open-multi-agent library, which is genuinely good at planning a task graph and verifying output. Then we spent two weeks building the things it does not have: an approval path, a viewer, a task starter, a card board. Those were built twice, because faults appeared in threes — two implementations of the same job disagreeing.

What went wrong, specifically.

Nothing was ever run end to end on a small plan. Every failure had several causes, so every fix was a guess.
The interface came before the engine: nine pages, panes, notes and filters before one task had passed one test.
A plan that was re-run was re-planned, which silently threw away its dependencies.
A task's state was guessed from folder names, so old work coloured new cards.
The layout was lost twice: TUIOS deletes a workspace when its last pane closes, and a repair command did not carry the project with it.

What we achieved and keep. A working page layout and page notes in plain language; a project convention (.harness/settings.toml, role files, notes, a to-do list per project); office for opening a project; project-reset; and a real understanding of what an approval and a per-task check must be (plan/90).

Attempt two (understanding, not building). We read OMA properly and found it has approvals, checks and worktrees of its own kind. We then studied Paperclip instead of assuming.

3. What Paperclip actually is, from our own probes

Not marketing — measured on this machine (spike/api-notes.md).

A server with a database, already running here: http://127.0.0.1:3100, 685 API endpoints, browser UI at https://paperclip.lab.audasmedia.com.au.
Your work is already in it: 10 projects, 145 tasks, with statuses todo, backlog, in_progress, blocked, done.
Pi is the worker already installed on the agent identity (adapterType: pi_local).
Blockers are real: setting one returned "1 unresolved blocker" and named the task that blocks it. But the blocker is not on the task list, only on the single task and its blocker diagnosis. A tree must ask per task.
Comments land on a blocked task's thread.
Cost per task is readable — cents, input and output tokens, run count.
Writes from an agent key are refused unless it is inside a heartbeat run. A person's tool must use the user key. This is Paperclip protecting its own audit trail.
Paperclip creates git worktrees itself. The installed code runs git worktree and enforces a workspace strategy of git_worktree with a branch template, a worktree parent folder, and setup and teardown commands. The worktree was on our list; it is not ours to build.

4. Pitfalls, so the third attempt does not repeat the first two

One owner per fact. The task queue, blockers, approvals, comments, runs and cost belong to Paperclip. Our code never keeps a second copy. If a screen disagrees with Paperclip, the screen is wrong.
No interface before a working run. The first milestone ends with a task that a person watched finish. Nothing is styled before that.
Small plans only, until small plans work. Two tasks, then three, then a real job.
Never judge a task by a folder name. State comes from the task's record.
The layout is ours to protect. A workspace dies when its last pane closes, so every page keeps a pane that does not close. Repair must carry the project name.
Agent keys are not person keys. Anything the TUI does on your behalf uses the user credential, so the audit trail names you.
Do not re-plan a plan. A stored plan is read, never regenerated.
Every claim comes with the command that showed it.

5. What Paperclip does not do, and is ours

Per project, not per company. Paperclip has companies, projects and tasks. Our unit of work is one project in one folder on one machine. Mapping and scoping are ours.
Which host. Moving between .13, .27 and .51, remembering where a project lives and building its layout there. Ours.
The layout and its repair. Pages, panes, and rebuilding them after a crash or on a new machine. Ours.
Project lifecycle. Create, adopt, reset, delete. Ours.
The code review gate. ocr over the diff, and the merge order. Paperclip has approvals; it does not know our review tool.
Serial merging. One task at a time, re-checked after each rebase. Ours.
The wording of a task's test. Paperclip records a task; the command that decides it is finished is our convention, kept with the project.
The notes. What each screen is for, in plain language. Ours.

6. The shape: four screens, one Go program

Go, with Bubble Tea, Lipgloss, Bubbles, Huh and BubbleZone. One program, four screens, each in a TUIOS pane. All data comes from Paperclip's API; nothing is stored twice.

Screen 1 — Task tree. Todo, in progress, blocked, done, for the current project. Each row shows the task, who has it, and what blocks it (read per task, not from the list). Enter opens the task. This replaces the old HOME, BOARD and DONE pages.

Screen 2 — New task. A form: title, description, what must finish first, and the test that decides it is done. On submit it calls Paperclip, and the task appears in the tree.

Screen 3 — Live log and diff. For the selected task: what the agent is doing, the files it touched, and the change as a diff. Reads Paperclip's run and activity records; the diff comes from the task's own worktree, which Paperclip made.

Screen 4 — Unblock and reply. The task's thread, with a box to reply. Sending posts a comment, and optionally changes status — which is what wakes the agent.

Around those four, the things we already know we need, kept as thin pages rather than a second application: project open/reset, the notes page, and a repairs page that rebuilds the layout.

7. Plan of attack

Milestone 0 — done. Read-only probe of the API, plus sandbox writes. Results in spike/api-notes.md.

Milestone 1 — one task, really run. In the sandbox project, give the task to Pi, let Paperclip make the worktree and run it, and see the comment and the status change come back. Pass when: the task goes todo → in progress → done, a comment written by Pi holds the change, and the cost appears. No interface.

Milestone 2 — screen 1 and screen 4. Read the tree from the API, and reply from a box. Pass when: you move a blocked task forward entirely from the terminal, without a browser and without a shell command.

Milestone 3 — screen 2 and screen 3. Create a task with a blocker and a test; watch a running task's log and diff. Pass when: a two-task plan is created, ordered and finished from the terminal alone.

Milestone 4 — the project layer. Adopt a folder, remember its host, build the layout, repair it, reset it. Pass when: a new project on another machine can be opened and used from here.

Milestone 5 — the review gate and merging. ocr over the diff, and serial merge. Pass when: a task that fails review is refused, and the next task cannot merge until the first is settled.

8. On the Bubble Tea analysis

It is correct, and it names the two things that would otherwise cost a week:

Resize. Handle the window-size message, never hardcode sizes, subtract border sizes, and show a short "too small" screen rather than a broken one. Also run in the alternate screen so TUIOS scrollback does not fight the redraws.
Keys. In TUIOS window mode, h j k l, z and n belong to TUIOS and never reach the app. So inner navigation uses Tab, Shift-Tab, arrows, Space and Enter, and a bare Esc must be free to close a box. This is a design constraint, not a detail.

Two additions from our own experience:

Wrap the whole top-level view in one BubbleZone scan, and create the zone manager once. Per-component scanning drifts when panes resize.
Never do network or git work inside the update or view functions; do it in commands that return messages. A freeze is visible to the person as a stuck pane.

9. Decisions this plan needs from the person

Confirm Paperclip as the owner of tasks, blockers, comments, approvals, runs and cost.
Confirm the four screens and the thin pages around them.
Confirm that the first milestone runs a task with no interface at all, even though the interface is the part you most want to see.

9.0 KiB Raw Blame History