paperclip-harness/AGENTS.md

Instructions for the agent working in this project

You are picking up a project that is starting fresh, after two earlier attempts are closed. Read this file first, then HANDOVER.md, then docs/PLAN.md. Do not read the old project unless this file tells you to.

Read this before anything else: the environment is TUIOS, not tmux

This system runs inside TUIOS, a terminal multiplexer with workspaces and panes. There is no tmux here. docs/TUIOS-RUNBOOK.md explains it, including how to start a session from .27, .13 or .51, and the four rules that have already cost us two days: workspaces disappear when empty and renumber, TUIOS keeps h j k l in window mode, a resize arrives as a normal terminal resize, and a page must keep one pane that never exits.

Do not write a design that assumes tmux, a single fullscreen app, or a fixed window size.

What we are building

One small Go terminal program with four screens, sitting on top of Paperclip, inside TUIOS. Paperclip already keeps tasks, blockers, comments, approvals, run history, cost and the git worktree for each task. We do not build any of that again.

The four screens:

1. Task tree — todo, in progress, blocked, done, for one project.
2. New task — a form: title, description, what must finish first, and the command that proves it is finished.
3. Live log and diff — what the selected task is doing, and what it changed.
4. Unblock and reply — the task's conversation, with a box to reply.

The one rule that matters most

Each fact has exactly one owner, and for tasks, blockers, comments, approvals, runs and cost that owner is Paperclip. Our code never stores its own copy. If a screen and Paperclip disagree, the screen is wrong and gets fixed.

Which key to use

Two credentials exist and they are not interchangeable.

• Use the user key — environment variable PAPERCLIP_BOARD_KEY — for everything this program does on the person's behalf: creating tasks, adding blockers, posting comments. It records the action as the person's.
• Do not use the agent key (PAPERCLIP_API_KEY) for writes. Outside a heartbeat run Paperclip refuses it with 403 "cross-issue writes need a run to attribute them to". That refusal is correct. Use the agent key only for read-only checks.

Example read, safe with either key:

curl -s -H "Authorization: Bearer $PAPERCLIP_BOARD_KEY" \
  http://127.0.0.1:3100/api/health

Never print either key, never commit it, never paste it into a prompt.

Blockers are not in the task list

This is the trap that would look fine and be wrong. The list endpoint returns tasks with blockedByIssueIds empty even when a blocker exists. To know what blocks a task, ask about that task:

GET /api/issues/{id}/diagnostics/blockers

It returns readiness.unresolvedBlockerCount and the blocking tasks. The task tree reads this per task. docs/PAPERCLIP-API-NOTES.md has the measured response.

What the first session must do

Only the first item of CHECKLIST.md. One task, really run, with no interface.

1. Read docs/ENVIRONMENT-FACTS.md first. It has the company id, the agent ids, the fact that Go is not installed, and the sandbox project's state.
2. Make a fresh sandbox project with the payload in docs/PAPERCLIP-API-NOTES.md, or reuse the archived one. Assign one task to Builder (403de1f7-…).
3. Trigger the wake with POST /api/agents/{id}/heartbeat/invoke, then read GET /api/issues/{id}/runs and .../activity. Whether a heartbeat wakes Pi is unproven. If no run starts, write down what the API said and stop; do not build a workaround.
4. Watch the status change, read the comment the agent writes, read the cost, and find the worktree Paperclip created.
5. Report what you saw, with the commands and the responses.

Do not start the Go program until that passes.

Operating rules

docs/OPERATING-RULES.md is not optional reading. It has nine rules: the project folder convention, how a task is judged finished (a command agreed beforehand), approvals being content-bound, untrusted text being data, how secrets are handled, ocr review and serialised merges, one project per machine, cost limits, and the four commands that already work (office, office --host, project-reset, board).

Things that are ours, because Paperclip does not do them

• One project = one folder on one machine, and remembering which machine it is on.
• The page layout in TUIOS, and repairing it.
• Creating, adopting, resetting and deleting a project.
• ocr code review over the diff, and merging one task at a time.
• The command that decides a task is finished, kept with the project.
• The notes that explain each screen.

Interface rules, from the person, not negotiable

• Handle the terminal resize message. Never hardcode sizes. Show a short "too small" screen instead of a broken one. Run in the alternate screen.
• Inside TUIOS window mode, h j k l, z and n belong to TUIOS and never reach the program. Use Tab, Shift-Tab, arrows, Space and Enter inside the app, and keep a bare Esc free to close a box.
• Create the mouse-click zone manager once and wrap the whole view; per-part wrapping drifts when panes resize.
• No network calls and no git work inside the update or view functions. Use commands that return messages, or the pane freezes.
• Go with Bubble Tea, Lipgloss, Bubbles, Huh and BubbleZone.

How to report

Say what you ran and what came back. If something is unproven, say it is unproven. "It should work" is not a result. A dry run is not a test.

The old project

~/paseo/projects/tuios_coding_harness (plans and history) and ~/paseo/harness (the code). Read docs/OPEN-ISSUES.md first if you need to know what broke there. Do not copy code from it; copy nothing but understanding.