From 8ce2ca85b1d41c5dcb01afcc841bd0eaf7d9cef8 Mon Sep 17 00:00:00 2001 From: sam Date: Tue, 10 Nov 2026 09:52:12 +1100 Subject: [PATCH] AGENTS.md: the operating instructions, including which key, where blockers really are, and the first thing to test --- AGENTS.md | 106 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 4 ++- 2 files changed, 109 insertions(+), 1 deletion(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..f94bbf4 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,106 @@ +# 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. + +## 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. The sandbox project `spike-2026-11-09` already has two tasks: `AUD-157` and `AUD-158`, + the second blocked by the first. Safe to use or delete. +2. Assign the first task to the Pi agent and see whether a heartbeat picks it up. **This + is unproven.** If assignment does not wake an agent, write down exactly what happened; + do not build a workaround yet. +3. Watch the status change, read the comment the agent writes, read the cost, and find the + worktree Paperclip created. +4. Report what you saw, with the commands and the responses. + +Do not start the Go program until that passes. + +## 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. diff --git a/README.md b/README.md index c62e42e..50cc0b2 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,9 @@ This is a new project. Nothing here runs yet. It exists so the third attempt starts from a clean place, with the history of the first two attempts attached. -Read these in order: +If you are an agent: read `AGENTS.md` first, then `HANDOVER.md`, then `docs/PLAN.md`. + +If you are the person: read these in order: 1. `HANDOVER.md` — what we tried before, what worked, what failed, and why this is different. 2. `docs/PLAN.md` — the plan: the four screens, the milestones, what is Paperclip's job and what is ours.