sam/paperclip-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Showcase README; Outline collection for agents; repository created on Gitea

Browse Source
This commit is contained in:
Sam
2026-11-11 21:12:35 +11:00
parent 28993d029d
commit f07e7b5d98
9 changed files with 608 additions and 112 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
docs/outline/00-index.md Normal file
View File

@@ -0,0 +1,26 @@
# Index
What is in this collection, and what each document is for. Written in Simplified Technical
English: short sentences, one idea each, no metaphor.
| Document | Read it when |
|---|---|
| `01-system-overview.md` | you need to know what the system is and how the parts fit |
| `02-config-and-env.md` | you need to run it, or find a setting, a path or a key |
| `03-code-map.md` | you need to change the code and want to know which file does what |
| `04-agent-runbook.md` | an agent is picking up this project and needs the rules and the traps |
Outside this collection:
| File | What it is |
|---|---|
| `AGENTS.md` | the first file an agent reads |
| `HANDOVER.md` | where the project is now, and why it is shaped this way |
| `docs/PLAN-INTERFACE.md` | the plan, and the measurements behind each decision |
| `docs/WORKSPACES.md` | every workspace and pane, with its status |
| `docs/RUNS-AND-MERGE.md` | what a task, a run and a merge are |
| `docs/TEST-PLAN.md` | every step of a manual test, with the keys |
| `docs/SESSIONS.md` | TUIOS sessions, Pi conversations, cleanup |
| `docs/PAPERCLIP-API-NOTES.md` | what the API actually returned |
| `docs/ENVIRONMENT-FACTS.md` | ids, machines, toolchain, fonts |
| `docs/NEXT.md` | what is left to build, and what is unproven |

45
docs/outline/01-system-overview.md Normal file
View File

@@ -0,0 +1,45 @@
# System overview
## What it is
Paperclip Harness is a terminal interface over Paperclip. Paperclip is a control plane. It keeps
tasks, blockers, comments, approvals, runs, cost and a git worktree for each task. This project
shows that work in a terminal, inside TUIOS, and adds the few actions a person needs.
## The parts
- **Paperclip** on `http://127.0.0.1:3100`. It owns every fact. It runs Pi agents.
- **TUIOS**. It owns sessions, workspaces, panes and part of the keyboard.
- **The Go program** in `tui/`. One binary. Each pane runs one screen.
- **Commands** in `bin/`. They do the work that should not be a keystroke: adopt a folder, build
panes, merge one task, review one task, ask Mouse-1 one question.
## The eight workspaces
| Workspace | Purpose |
|---|---|
| Shell | a prompt in the project folder, with the paths printed above it |
| Board | the state of the work, and what needs a person |
| Work | runs, diff, facts, review, run log, merge |
| Agents | who is working, on what, for how much; and their settings, skills, extensions |
| Reply | the task thread and a reply box |
| New task | the form that creates a task |
| Project | dashboard, costs, settings, adopted projects |
| Repair | health checks, live layout, rebuild log, session cleanup |
## The data flow
1. A person creates a task in `New task`, or one already exists in Paperclip.
2. The person assigns it on `Board`. Paperclip wakes the agent.
3. The agent works in its own git worktree, on its own branch.
4. The agent comments and sets the status.
5. The person reads the run log, the diff and the review.
6. The person merges. `bin/merge` rebases, checks, reviews, merges, and checks again.
## What the project stores
One file per project: `<folder>/.harness/harness.toml`. It holds the session name, the machine,
the Paperclip project id, and the task being watched. It holds no task data.
A registry at `~/.config/paperclip-harness/projects.toml` lists adopted projects, so a person can
see which folder lives where.

58
docs/outline/02-config-and-env.md Normal file
View File

@@ -0,0 +1,58 @@
# Configuration and environment
## Required
| Name | Where | What it is |
|---|---|---|
| `PAPERCLIP_BOARD_KEY` | `~/.config/environment.d/10-secrets.conf` | the person's key. All writes use it. |
| `PAPERCLIP_API_KEY` | the same file | the agent key. Use it for reads only. Writes are refused outside a run. |
| `MOUSE_API_KEY` | the same file | the Mouse-1 API key |
| `GITEA_TOKEN` | the same file | used once, to create and push the repository |
Never print a key. Never commit a key. Never put a key in a prompt.
## The project file
`<folder>/.harness/harness.toml`:
```toml
session = "paperclip-harness"
watching = "AUD-171"
[paperclip]
company = "d4921013-…"
project = "17adbb47-…"
[machine]
host = "nixos-desktop"
folder = "/tmp/pc-sandbox-2026-11-10"
```
`bin/office <folder>` writes it and also writes `.harness/check.sh` and `.harness/NOTES.md` when
they are missing. It never overwrites an existing file.
## Paths that matter
| What | Where |
|---|---|
| task worktrees | `<folder>/.paperclip/worktrees/<branch>` |
| Pi conversations | `~/.pi/paperclips/<timestamp>-<agentId>.jsonl` |
| Pi skills (installed by Paperclip) | `~/.pi/agent/skills/` |
| the person's skills | `~/.agents/skills/` |
| Paperclip data | `~/.paperclip/instances/default/` |
| merge log | `/tmp/paperclip-harness-merge.log` |
| rebuild log | `/tmp/paperclip-harness-rebuild.log` |
## Instance settings that change behaviour
- `enableIsolatedWorkspaces` and `enableWorktreeRunExecution` must be true, or no task gets a
worktree. `GET /api/instance/settings/experimental` shows them.
- `enableIsolatedWorkspacesByDefault` is left off. Only projects that ask for a worktree get one.
## Machines, measured 2026-11-11
| | `.13` | `.27` | `.51` |
|---|---|---|---|
| Go | 1.26.5 | 1.26.2 | installed in config, needs a rebuild |
| Pi | 0.82.1 | 0.82.1 | 0.87.1 |
| TUIOS | 0.12.1 | 0.12.1 | 0.12.1 |

46
docs/outline/03-code-map.md Normal file
View File

@@ -0,0 +1,46 @@
# Code map
## The binary
`tui/` builds one binary. `main.go` reads the flags and starts one screen.
| File | Does |
|---|---|
| `main.go` | flags, palette, which screen to start |
| `model.go` | the task tree screen and the shared row loader |
| `board.go` | `Board`: tasks, chosen task, needs you |
| `work.go` | `Work`: runs, change, facts, review, log, merge |
| `agents.go` | `Agents`: roster, runs, log, settings, skills, extensions |
| `reply.go` | `Reply`: thread and reply box |
| `newtask.go` | `New task`: the form, guidance, preview |
| `project.go` | `Project`: overview, facts, costs, settings, projects |
| `repair.go` | `Repair`: health, layout, log, cleanup |
| `frame.go` | the panel frame, tabs, hints, overlays, wrapping |
| `theme.go` | the palette and the icon set |
| `toolpane.go` | opening a tool as a pane, and finding the current workspace |
| `picker.go` | skills and extensions for one agent |
| `rebuild.go` | detached rebuild, merge and review, and their logs |
`tui/paperclip/client.go` is the whole API client. It holds no state.
## The commands
| File | Does |
|---|---|
| `bin/office` | adopt a folder, create its session, build its panes |
| `bin/board` | build or repair the panes, by name, in order |
| `bin/merge` | rebase, check, review, merge, re-check, roll back on failure |
| `bin/review` | the review alone |
| `bin/triage` | ask Mouse-1 one four-option question |
| `bin/project-reset` | close panes, remove worktrees and branches, keep the folder |
| `bin/shell-banner` | the box printed at the top of `Shell` |
| `bin/lib/tuios.py` | sessions, workspaces, panes: claim by name, never by number |
| `bin/lib/harness.py` | API, git, ocr, and the tool-path fix |
| `bin/lib/project.py` | the project file and the registry |
## The rules the code keeps
- No network or git call inside an update or view function. They run in commands.
- No hardcoded sizes. The size comes from the terminal on every refresh.
- One click-zone manager, created once, wrapping the whole view.
- Every panel line is exactly the width asked for. `tui/frame_test.go` fails if it is not.

45
docs/outline/04-agent-runbook.md Normal file
View File

@@ -0,0 +1,45 @@
# Agent runbook
Read this before you change anything.
## First
1. Read `AGENTS.md`.
2. Read `HANDOVER.md`.
3. Run `tuios ls` and find the session called `paperclip-harness`.
4. In a pane, run `Repair>repair`. Every check must pass. If it does not, fix that first.
## Build and restart
```sh
cd tui && go build -o ../bin/harness .
```
Then press `R` in `Repair>repair`. Do not start a second copy of a panel: `bin/board` adopts the
pane that is already there.
## Rules that are not preferences
- Writes use `PAPERCLIP_BOARD_KEY`. The agent key is refused outside a run, and that refusal is
correct.
- Read blockers from `/api/issues/{id}/diagnostics/blockers`. The task list does not carry them.
- Read a worktree path from a single-task read. The task list does not carry it either.
- Never store a fact Paperclip owns.
- A comment on an assigned task wakes its agent. Tool verdicts hand the task back to the person
first.
- TUIOS keeps `h j k l z n` and also `[ ] Tab , . = ;` and the digits. Use arrows, `jk`, `(` `)`,
`Space`, `Enter`. Keep `Esc` free.
## Traps, measured
- A pane started by TUIOS has a smaller `PATH`. `bin/lib/harness.py` and `toolpane.go` add the
usual directories for that reason.
- TUIOS can re-tile a pane without the program hearing about it. Re-ask for the size.
- Closing the last pane deletes a workspace and renumbers the rest. Resolve workspaces by name.
- `switch-session` is refused when the call comes from a pane. A program cannot move the person's
client.
## Reporting
Say what you ran and what came back. If something is unproven, say it is unproven. A dry run is
not a test.