87 lines
4.1 KiB
Markdown
87 lines
4.1 KiB
Markdown
# Handover
|
|
|
|
Written 2026-11-09, at the end of the OMA-based attempt, before any code exists here.
|
|
|
|
## What we set out to make
|
|
|
|
A coding factory inside TUIOS. A person writes a goal; it becomes tasks; each task runs on
|
|
its own copy of the code; tests and a review decide whether it is finished; finished work
|
|
is merged one at a time; the person is interrupted only to decide. Terminal only. One
|
|
project at a time, not the whole machine.
|
|
|
|
## Attempt one: OMA with our own cockpit
|
|
|
|
`@open-multi-agent` is a good library. It plans a goal into a task graph, orders it,
|
|
verifies output with judges, and records approvals durably. We built a coordinator around
|
|
it and then spent two weeks building what it does not have: an approval path, a viewer, a
|
|
task starter, a card board, a task tree.
|
|
|
|
**What that cost us.** Each of those was built twice, because two implementations of the
|
|
same job disagree. Faults arrived in threes. The same question had two answers, and both
|
|
were plausible.
|
|
|
|
**The other mistakes, plainly.**
|
|
|
|
- Nothing ran end to end on a small plan. Every failure had several possible causes, so
|
|
every fix was a guess and several were wrong.
|
|
- The interface came first: nine pages, panes, notes, filters — before one task had passed
|
|
one test.
|
|
- A plan that was re-run was re-planned, which silently discarded the dependencies that
|
|
made it safe. Layout ran before content existed.
|
|
- Task state was guessed from folder names, so old work coloured new cards. One panel said
|
|
"refuse" about a task that had never run.
|
|
- The pane layout was lost twice. TUIOS deletes a workspace whose last pane closes, and a
|
|
repair command did not carry the project name with it.
|
|
- I reported "fixed and verified" far too often for something I had only dry-run.
|
|
|
|
## What we achieved and keep
|
|
|
|
- A page layout and page notes written in plain language.
|
|
- A project convention: `.harness/settings.toml`, role files, page notes, a to-do list per
|
|
project, a verify command.
|
|
- `office` to open a project; `project-reset` to start one again cleanly.
|
|
- A real understanding of what an approval must be (content-bound, stale-proof) and what a
|
|
per-task check must be (a command, agreed before the work, run by something other than
|
|
the agent).
|
|
- The knowledge that OMA is a viable fallback: see `docs/FALLBACK-OMA.md`.
|
|
|
|
## Attempt two: understanding instead of building
|
|
|
|
We read OMA's documentation, then read Paperclip's API and probed it. That ended the
|
|
guessing. The measurements are in `docs/PAPERCLIP-API-NOTES.md`.
|
|
|
|
## Why Paperclip, in one paragraph
|
|
|
|
The four screens you want are already its data model: tasks with todo / in progress /
|
|
blocked / done, blockers as links between tasks, comment threads on each task, approvals
|
|
as records, cost per task, and run history. It also creates the git worktree for a task
|
|
itself — the piece we were going to build next and the piece most likely to break. So the
|
|
work that remains is small and specific: one Go terminal program, and a thin executor
|
|
where Paperclip's own worker does not cover our review step.
|
|
|
|
## What is ours because Paperclip does not do it
|
|
|
|
- One project in one folder, on one machine, and remembering which machine.
|
|
- The page layout, and repairing it after a crash or on a new host.
|
|
- Creating, adopting, resetting and deleting a project.
|
|
- `ocr` code review over a diff, and the merge order (one at a time, re-checked).
|
|
- The test that decides a task is finished, kept with the project.
|
|
- The notes: what each screen is for.
|
|
|
|
## The pitfalls that would sink a third attempt
|
|
|
|
1. Building a second copy of anything Paperclip owns.
|
|
2. Styling a screen before a real task has run.
|
|
3. Testing with a six-task plan instead of a two-task one.
|
|
4. Judging a task by a folder name.
|
|
5. Letting a page have no permanent pane — it will vanish when TUIOS renumbers.
|
|
6. Using an agent key where a person's key is required.
|
|
7. Re-planning a stored plan.
|
|
8. Reporting work as done without a command that shows it.
|
|
|
|
## Where the old project is
|
|
|
|
`~/paseo/projects/tuios_coding_harness` (plans, history) and `~/paseo/harness` (the code).
|
|
Both are untouched by this handover and remain as reference. `docs/OPEN-ISSUES.md` lists
|
|
what is broken or unfinished there, in case you go back.
|