harness-multitool

Agent workflow specification

How an agent works through this harness. It binds every agent on every adapter (CON-97). A situation brings the same action every time, and each row says what the session's log must show, so it can be checked by a program.

Read this file before acting, and again after a compaction or a resume: the harness gives you its path then. Tools and modes are described in their own definitions.

Where a tool is named mode__x, on a program running as an agent backend it is mcp__mode__x; journal_x, mindmap_x, flowchart_x, map_x and agent_x are mcp__harness__x there, such as mcp__harness__journal_agenda. These tools are this project's only journal and maps: a command-line journal or other instructions that name one reach a different store, and do not count.

1. What the user says

#SituationDoDo notThe log shows
W-1The user asks to plan: "let's plan", "давай спланируем".mode__plan_enter, first thing.Answer with a plan in words; start building.mode__plan_enter before any write.
W-2The user asks to build an app, a feature or a fix, or any change that is not trivial, even without saying plan, even "just try".mode__plan_enter, first thing.Write anything first.mode__plan_enter before any write.
W-3The user, in plan mode, says to implement the plan: "now let's implement", "теперь давай реализуем".mode__plan_exit with the plan and user_said quoting their words exactly, then build.Ask again; build without leaving the mode.mode__plan_exit with user_said from their last message, plan mode off, then writes.
W-4The plan is ready and the user has not said to go.mode__plan_exit with the plan, no user_said: the user is asked with a card in their window and with buttons on their Telegram; the first answer decides (CON-163). End your turn and wait. An approval comes as ✅ План одобрен в терминале. Plan mode is off: ... or [telegram_message]: ✅ План одобрен в Telegram. ...: plan mode is already off, go ahead with the plan. A rejection asks you to find out what to change.Quote words they did not say; call mode__plan_exit again after a press.mode__plan_exit, then their answer.
W-5The user says to debug: "let's debug", "теперь давай отладим".mode__debug with on true. In plan mode, leave it first (W-3).Debug without the mode.mode__debug on before the first command of the debugging.
W-6The user asks a question, or to read or diagnose, with nothing to change.Answer, reading what you need. Journal what you find; a research or an analysis as W-18 says.Enter a mode; write code.No write and no mode.
W-7Something only the user can decide, and the work cannot go on without it. (When it can, W-17.)ask_user, one question, and wait.Guess; ask in plain text and go on.ask_user, then nothing until the answer.
W-8The user stops you.Stop, and say nothing was finished that was not. Take what they say next.Carry on with the stopped work unasked.No further call for the stopped work.

2. Every session

#SituationDoThe log shows
W-10A fresh context: start, resume, compaction.Read this file. Your prompt already holds the binding entries, the maps and the newest open work. Read what bears on the task with journal_search and journal_get, and journal_agenda for the rest.One of those before the first write.
W-11Before a decision that is not trivial.journal_search for an earlier one. Its linked names the neighbours of what it found: journal_get those that bear on the decision. An entry that another replaces is history; the other is the current word.journal_search before the entry that records it.
W-12You decide something, or the user does.journal_add, category decision: who, what, why, what was rejected. One entry each, when it happens.An entry per decision.
W-13You learn something not obvious, or an assumption falls.journal_add, finding or assumption-falsified, naming the file and line.An entry per finding.
W-14You change the project.journal_add, update: what, where, why, citing journal#N.An update after each change.
W-15A correction from the user, or your own mistake worth not repeating.journal_add, lesson.An entry.
W-16A task matches the description of one of the harness's skills (skill_list).skill_load it, and follow it.skill_load before the task's first write.
W-17Something only the user can decide, and the work can go on elsewhere meanwhile.journal_add flagged wait-for-decision, the options laid out; do not go on with what depends on it. When the user decides, journal_close it with the decision as its resolution.That entry, then its close with the decision.
W-18A research or an analysis: a cause hunted, options compared, a system or code read, something measured.Before it, journal_list with flags research and journal_search: what is found and still true is cited, not redone. After it, journal_add flagged research, standing alone: what was asked, how, its sources named exactly, the result, how sure it is and what it does not cover. A long one keeps a mind map too (W-48).The search before; the entry flagged research after.

Each entry stands alone: a later session reads it without this conversation. An entry you rely on is cited as journal#N. If the code says otherwise, the code wins, and that is a finding.

3. Spec first

#SituationDoThe log shows
W-20Before building a feature.Its specification first, one journal_add per rule, flagged specification, with constraint when it is a rule, under its feature.specification entries before the first write.
W-21Before changing a feature.Read its specification: journal_list by specification and feature.journal_list before the first write.
W-22A spec has to change.A new entry saying "Replaces journal#N" and why; journal_mark the old one deprecated.Both.
W-23Code and spec disagree.A finding; settle it before going on.An entry.
W-24A project with docs/ holds a binding entry: specification, constraint, invariant or principle.Give the rule an id in its docs, such as a new CON- row in docs/spec/constraints.md, an INV- row in docs/spec/invariants.md or a P- row in docs/spec/principles.md, and name that id in the entry. Read the docs for the next free id; never name one they do not define.The id in the entry, defined in docs/.

4. In plan mode

#DoThe log shows
W-30Study; what only the user can decide, ask_user, or, when the plan can go on without it, journal it flagged wait-for-decision (W-17).Reads, ask_user, wait-for-decision entries.
W-31Journal every decision, finding, assumption, open question and choice left to the user (wait-for-decision).Entries.
W-32Each work item a todo carrying its test protocol: what to test, regressions named; how; under which conditions; what evidence proves it.todo entries with a protocol.
W-33mindmap_new, then mindmap_add your strategy: the decisions, the work and the proofs you will produce, with refs holding a journal entry; in an orchestra, your task.A mind map; mode__plan_exit refuses without it.
W-34flowchart_new, then flowchart_add the logic branches of the planned behaviour, with its outcomes.A flowchart; mode__plan_exit refuses without it.
W-35If the project has docs/, describe the feature there.Writes under docs/.
W-36Only then mode__plan_exit. Nothing is built before it is approved.Entries and maps before mode__plan_exit; no other write.

5. Building and proving

#SituationDoThe log shows
W-40Implemented.journal_add, update, flag unverified: "Implements journal#T", with the verification protocol.That entry.
W-41After a planned fix or a built feature.mode__debug on. A fix: reproduce before changing, a failing test for a small bug. Verify after, then off.mode__debug on, the failing run, the change, the passing run, off.
W-42Checked.journal_add, verification, flag verified: "Verifies journal#I", what was run and what it showed, with proof saying what shows it: a test's name, a command and its result, a commit, a URL. If the evidence is kept in a file, a log or a screenshot, save it in the project's .harness/proofs/ and give proof_file with its path; a file named from elsewhere is copied in there, to .harness/proofs/journal/, and its copy is what the entry links to. The todo's journal_get and journal_branch then list every proof file of its branch. Where no file is needed, leave proof_file out. Never without having run it. A close refuses a verification with no proof.That entry, with a proof, after the runs.
W-49Saying a thing works.Check it as the user will meet it, in the program they run, not only in a build of your own or a preview; if that is not possible here, say so, and do not say "done". If what you changed is the harness you run under, it needs plugins_reload before anyone can see it: ask whoever may, an orchestrator if you have one.A proof from the running program, or the limit said in words.
W-43Then close.journal_close the todo. A close refused means it lacks evidence or waits for something: settle that, do not work round it.journal_close after the evidence.
W-44A bug found.journal_add, bug, flag todo, at once. The fix: "Fixes journal#B" unverified, proved the same way.Entries in that order.
W-45Work dropped.journal_abandon, saying why.That call.
W-46Put off.A todo entry, tag deferred, at once.That entry.
W-47One thing cannot be solved until another in the journal is.blocked_by that entry; work on the blocker first. If released or blocker_dropped names something, re-read it.blocked_by, then work on the blocker.
W-48A long task or a hunt for a cause.Keep a mind map: where you are, what you suspect, what is ruled out.A mind map and its updates.
W-63A product needs a callback type of its own (an app should wake you, or do something first).Write it as docs/callbacks.md says: multitool callback new <name>, its logic in Rust in src/main.rs (other languages only called from it), multitool callback build <name>; callback_handlers shows its state. Ask the user to turn it on for this conversation in Settings > Callbacks (Enter on its row approves and subscribes); never a script as its handler, never turning it on yourself.The folder under .harness/callbacks, the build, callback_handlers, the ask.

6. In an orchestra

#SituationDoThe log shows
W-50You have just been started as an agent of an orchestrator, on a journal entry.Read this file and the entry, and work on it now. Everything above holds.journal_get of that entry, then its work.
W-57Your task's work is done and proved, in an orchestra.agent_send your orchestrator asking to close the entry, naming the proofs. Do not close it: only it can.That call; no journal_close of the entry.
W-58Your orchestrator approved.agent_send it asking to close your session, and stop.That call last of all.
W-51A user message in that tab.Treat it as the user's: it stands for the user there. Everything above holds.As above.
W-52You are done, or need something.agent_send your orchestrator. It is your only contact.That call at the end of the work.
W-55You have a question, in an orchestra.ask_user, as anywhere: it goes to your orchestrator, whose answer is your next message.ask_user, then nothing until the answer.
W-56Your plan is ready, in an orchestra.agent_send your orchestrator the plan, and wait. When it says to go, W-3: mode__plan_exit with its words in user_said.agent_send before mode__plan_exit.
W-53You are the orchestrator, and there is work for an agent.Write the entry, mode__agent_spawn with it as task; end your turn while it works.The entry, the spawn, then no polling.
W-59You are the orchestrator, and an agent asks to close its entry.Check it (W-54, W-62). Good: journal_close, and tell it. Not good: W-62. When it then asks to close its session: mode__agent_close.mode__agent_read, journal_close, mode__agent_close.
W-62You are the orchestrator, checking an agent's change. Matching the specs is your duty: it may not keep track of them.journal_search or journal_list what binds it and read the diff against that, not only its report. It broke a spec: do not close, do not fix it yourself; agent_send it back, naming the rule and what breaks it. A spec that has to change takes the user's word (W-22).Those reads before journal_close; a message naming the rule when something was wrong.
W-60You are the orchestrator, and the harness reminds you to check on an agent.mode__agent_read. If it has stopped with no word, agent_send it to move on, or mode__agent_close if its work is over.mode__agent_read after the reminder.
W-54An orchestrator checking an agent's work.mode__agent_read, against the rows of this file.That call before a verdict.

7. Always

This page's source