paperclip-harness/docs/WHAT-WE-ARE-BUILDING.md

What we are building

Behaviour first. No commands, no file names, no workspace numbers — those are in the build documents. This page is what the thing is and what it feels like to use, so that someone picking up the work understands the product, not just the plumbing.

One sentence

An autonomous coding factory you can walk around: a CEO that plans and assigns, workers that do the work in their own folders, and an interface where you can see everything, direct anyone, and are interrupted only for decisions.

Paperclip is the reference. Same idea — a goal becomes work, roles carry it out, there are approvals, budgets and a record — but as a terminal interface rather than a web dashboard.

Budgets are not strict at this stage and are more a record than a hard line.

A better understanding can be found through these headline docs.

Paperclip overview. https://github.com/paperclipai/paperclip

Working https://docs.paperclip.ing/guides/day-to-day/dashboard/

Org and agents https://docs.paperclip.ing/guides/org/agents/

Projects https://docs.paperclip.ing/guides/projects-workflow/projects/

My Desire.

A place where I can quickly keyboard navigate and when needed mouse that is functional, terminal based system which looks good. I can launch it from folders on my main machines .13, 51, 27 - or via web on those machiens as TUIOS allows this. I can take over pre-existing work, or initiate entirely new project, which may be simple research and document creation on a research project, or a full software system integrated with version control and Gitea.
The system, tuios coding harness, will take a plan or directive and divide it into phases and then specific tasks which it will disseminate and coordinate in a systematic manner to deliver that plan. Those tasks are handed to agents via oma with pi-durable for resumption and using pi as the agent. I can interact with the main controller or other agents as needed to redirect, answer questions etc. I might answer questions in the pi in terminal such as "pi ask user question" after an alert is raised in the main admin area, or the main admin area might raise an alert and there is box I can simply type into or select options. The project is delivered in a systematic documented manner. We can see the audit log, phases and tasks completed, costs, with notes on issues. I should be able to resume the project when ever needed. The system when using Gitea should use worktrees, spaces, sessions so there are no conflicts - see technical notes, and ensure things are working with something like ALibaba code review. Keys, Passwords, Secrets should be redacted and not exposed, The one mechanism known to work is redaction at the outbound provider request — a proxy on the wire.

The roles

• CEO. Takes the goal. Writes the plan, splits it into phases and tasks, assigns each to a worker, tracks progress, reports back, raises problems. This is OMA and Pi-durable.
• Workers. Do one task each, in their own folder on their own branch, with their own conversation. Visible while they work.
• The person. Approves or rejects a plan, changes how a role behaves, talks to anyone, and decides the things a machine should not decide.

Each role has settings that belong to it, not to a run: which model, what budget, what it may do (merge? touch tests? run commands?). Changing a setting changes that role from then on.

The four ways work starts

1. You type a goal. One line. The CEO plans it and shows you the plan before it spends anything.
2. You write the plan. Paste or type phases and tasks directly; it turns them into assigned work without inventing its own.
3. Something else calls it. n8n, a script, a webhook. A run starts with no person present, and the outcome comes back as data: what ran, what passed, what merged, what it cost.
4. You open it in a folder. Point it at any project, any directory, and it works on that. It is not tied to one repository or one machine.

The three things you do while it runs

• Watch a worker. See what it is doing right now, what it has spent, what it is about to change.
• Talk to anyone. Send a worker a correction mid-task and it continues in the same conversation. Ask the CEO what it is waiting for. Same for a task that has already finished.
• Approve or reject. A plan before it starts; a change before it merges when it is not obvious.

The four main things it tells you

• Progress — what is planned, what is running, what has finished.
• Completed — merged, tested, with what it cost and what changed.
• Problems — failed, blocked, or a check that could not run. With the reason, and something you can do about it.
• Decisions needed — the short list of things waiting for you, and nothing else. If it is not waiting for you, it does not belong there.

A finished run

Everything merged is tested and was re-checked after it was rebased onto the latest work. Nothing merges that a check could not verify. The record of the run is a set of files: the plan, each task, its cost, its verdict, its change. You can read it a week later without asking anyone, and reopen any task's conversation.

Our own agent awareness — do not hand this to TUIOS

TUIOS is transport — panes, navigation, focus, opening files. The model of the run — roles, plans, costs, verdicts, decisions — is ours.

We are building our own system for fast terminal navigation on top of TUIOS: who is running, where, on what, what they cost, what needs you. It may look like what TUIOS already offers — alerts, "what is running where", a list of agents, an inbox of things wanting attention. That is fine and expected. Overlap is not a problem.

Both can exist. TUIOS keeps everything it has, nothing is blocked or removed, and it remains excellent at windows, panes and opening files.

The rule is only about where the factory's own awareness lives: it lives in our interface. If the answer to "what is happening and what needs me" is "use TUIOS's agent list", the factory has no view of its own and the product is a pile of scripts. Our interface must know the roles, the plan, the budgets, the verdicts and the outstanding decisions — because TUIOS cannot: it sees terminals, not phases.

We can also leverage TUIOS CLI for navigation, control, refresh, rebuild - including preset terminal layouts.

Additional Notes

• Page generally refers to workspace. Confirm if unsure.
• Rebuilding and starting the layout should be consistent with a set layout. A full reset. Define left, right, top-left, top-right, bottom-left, bottom-right etc.
• Refresh refreshes the panels and workspaces as they were.
• Workspaces should open in the same order.
• We should be able to jump to workers or other workspaces using TUIOS cli - eg exec(`tuios workspace switch ${workspaceNum}
• WE should have an area where we can start a new project, where we can see the projects plan and objectives, where we can write a plan, where we can write a prompt to the OMA to direct a variation or new task.
• If the project is started in an existing folder of work which is not from the tuios coding harness we are making then it can look at the AGENTS.md or other docs and formulate a plan.
• We should have a workers page where agents are running.
• We shold have a page where we can edit the workers directives, LLM etc
• We should have a Documents or Files page which might show us the output of documents, code etc. These might be diffs - Hunk or images, pdfs, documents that might need to be opened externally or viewed internall.
• We need a page where we can interact with the Gitea and similar. Hunk, LazyGit etc.
• Some panels may need custom interfaces while many can simply be terminal tools.
• Tasks and todo can and should also be shown via Tuxedo
• We can use a terminal tool to show CPU if needed there are several installed.
• I want to include Mouse-1 (probability LLM) and possibly switch which simply builds Mouse-1 JSON (I think, needs research), where feasible for massive speed and cost savings. Ensure these are understood.
• https://mouse.dev/blog/compare/mouse-vs-openai-decisions/
• API https://mouse.dev/api
• Docs https://mouse.dev/docs
• And we use Switch which can turn the "state of a task" into typed questions for Mouse-1 or Jev
• Understand it here https://github.com/osolmaz/switch
• We can use Apprise to send alerts to me.
• We can use the TUIOS CLI to achieve things like navigation.
• We can interact with other Docker or local tools installed to improve functionality.
• Pi-durable is a candidate for durable run records, not something in the loop.
• Some tools named in here may already be installed, others may not. Confirm do not assume.
• a workspace holds panes; a page is what you see on a workspace; a panel is one pane's content.

CRITICAL

• We work together to have a very well defined interface, workspaces, panels that we write down in a document to follow. We will work towards a system similar to other autonomous coding software factories with paperclip as our inspiration. We have decided upon Open Multi Agent as our main coordinator with pi-durable for resumable operations, pi as our in pane interactive agents which CAN use "ask user question".

Additional Notes from previous session

Where settings live. One file per project, in the project's own hidden folder, holding one block per role: the role's prompt, its model and provider, its budget for a run, and its permissions — may it merge, may it change tests, may it run commands. The worker-settings page reads and writes that file; it owns it, nothing else writes it. A change applies to that role's next task, never to one already running: the page shows "active now" versus "next task", and no agent is ever repointed mid-conversation. Runs copy the settings they started with into the run record, so a later change never rewrites history.

Concurrency. Three workers at a time by default, set per project. Three because that is what merges cleanly without babysitting; more is a setting, not a rewrite. Two tasks wanting the same file is not prevented, it is contained: each works in its own folder on its own branch, so they cannot overwrite each other; the collision shows up at merge, where merges are one at a time, each rebased onto the latest and re-checked. If the rebase conflicts or the re-check fails, that task is held with a reason and appears as a decision for you. If you know two tasks touch the same file, the CEO should give them an order (one depends on the other) so they never collide at all.

Failure policy. Three answers, three behaviours. Pass → merges. Fail → returned to the same worker, once, in the same conversation, with the check's reasons included; if it fails a second time it stops and becomes a decision for you — the machine never retries a third time. Refuse (the check could not run) → never retried automatically, because retrying will fail identically; it becomes a decision immediately, and the reason is the checker, not the agent. Blocked is different from failed: a task is blocked when it cannot start — its dependency is not merged, or its folder or permissions are unavailable. Blocked tasks are not failures and must not be counted as such; they are waiting, and the reason is always shown.

Resume, twice over. Resuming a task means reopening its own conversation in its own folder, continuing with the context it already had. Resuming a run means reading the plan again and continuing the plan: tasks already merged are skipped because their branch is already in the main line, tasks pending are dispatched, tasks failed or blocked come back as they were. Resuming a run never redoes merged work and never re-plans unless you ask. Opening the project is the third and simplest: the plan, the tasks, the costs and the record are on disk, so it looks the same a week later. For all three to be true, these must persist: the plan, each task's own record, and the branch-and-merge state of each task.

Exposure. Only .13 is reachable over the web; .27 and .51 are local only. What the web surface gives is a full terminal on that machine, so it must be treated as equivalent to root on .13: bind it to the LAN only, never expose it to the internet, and assume anyone who can reach it can do anything the account can do. I have not verified whether tuios-web requires its own login — that must be checked before it is relied on, and until it is, treat it as open to the local network. The standing decision stays: no production use until X1 passes (reference/acceptance-tests.md), and secrets are stripped on the outbound provider request — a prompt instruction is not a control.