harness-multitool

Mind maps and flowcharts

Mind maps hold where a long task stands; flowcharts draw how something flows. Both are kept by the daemon beside the project's journal, and their nodes point at its entries.

What it is

They are two separate tools, because they answer different questions (ADR 0011):

Mind mapFlowchart
Answerswhat is known about a topichow something flows from a start to an end
Shapea tree around one topic, with cross linksa directed graph, loops allowed
Edgesparent to child; labelled cross links ("contradicts")arrows with conditions ("yes", "no")
Typical usethe working memory of a task, a research, a hunt for a cause, the project's architecturea request path, an algorithm, a release procedure, the logic of a check, a pipeline

A mind map is a document: the map of a project's decisions, questions, constraints and specifications, which answers why the system is made this way. A flowchart is both a document of a flow and the live view of a running pipeline (below).

How it works

Mind map nodes

A mind map is a tree from its root, the topic. Its node kinds, as the terminal UI draws them:

KindSymbol
topic (the root)◆
goal◎
decision◈
fact●
hypothesis◐
question?
task☐ / ☑
idea✦
dead end (dead-end)✕
note✎

A node is open, done (drawn muted) or dropped (struck through). A dropped node stays visible, so what was ruled out is not tried twice.

A node, a branch or a cross link can point at flowcharts, shown as ▸ flow #3: the map says what, the chart says how that part works.

Flowchart symbols

A flowchart is a block diagram by ISO 5807. Its kinds in flowchart_add:

A chart runs right (left to right) or down (top to bottom), chosen at flowchart_new. Each symbol is added with an arrow from the node after, and label is that arrow's condition.

Refs to the journal

Any node can point at journal entries with refs (on mindmap_add, flowchart_add, map_link) or later with map_ref. The map holds where the work is; the journal holds the detail.

These refs join maps and journal entries into one graph of the project's knowledge. A mind map node shows its refs as #137; a flowchart node lists them on its last line, an arrow on its pill.

Using it

ToolFor
mindmap_new, flowchart_newstart a map or a chart (title; a chart's direction)
mindmap_addadd a node under parent (the root by default), with its kind and refs
flowchart_addadd a symbol with an arrow from after, its label and refs
mindmap_show, flowchart_showread one back as an outline, and draw it for the user
map_editchange a node's text, kind, or both
map_node_statemark a node open, done or dropped
map_linkan arrow between two nodes, with a label and refs
map_refpoint a node at journal entries
map_closeclose a map whose task is done; it stays readable

Each tool is described in Tools and modes. On an agent backend they are mcp__harness__mindmap_new and so on.

In the terminal UI

Each result is a MINDMAP or FLOWCHART card in the transcript (the TUI). One layout draws both: filled cards and box-drawing lines in text mode, SVG in graphics terminals. Every map reads in text mode, which is the primary target.

A map wider than its room pans: press and drag on it. ◀ ▶ mark the hidden parts. There is no zoom.

Tickets

A click on a ref unfolds the entries as a ticket on the right of the map card:

In a ticket of several entries, a click on an entry's header shows it and folds the others. A second click, or a click on the ticket, folds it. Only one ticket is open in a transcript, and tickets do not come back after a /reload.

Live flowcharts

A flowchart can be bound to a real process of the project: a CI job, a deploy, a data pipeline, a request path (ADR 0012). The process sends flowstate_update callbacks naming the chart, the node and its state, and the chart is drawn with that node active.

The chart the agent draws is the reference. Each pass of the process is an instance of it, keyed by the client's own instance or correlation_id. A flowstate_update changes only its instance, never the reference, and starts no agent turn (CON-23).

How instances draw (the TUI):

The node a run is at is outlined in the accent; the node an event changed is tinted with it.

A flowstate payload is data: it cannot change the chart. A step that is not on the chart is recorded as off-chart, never added (INV-12).

In plan mode

A plan holds both forms (agent workflow, W-33 and W-34):

mode__plan_exit refuses a plan whose map or chart is empty (CON-117). A slave's mind map also points at its task (CON-111). See Modes.

A long task or a hunt for a cause keeps a mind map too (W-48): where it is, what it suspects, what is ruled out.

Settings

Settings > Memory sets map_max_nodes: the most nodes a mind map or flowchart holds (CON-114). It is 200 by default, and 0 means no limit.

A session already running keeps the limit it started with until it restarts.

Limits and status

Specs and decisions

This page's source