choosing-graph · diff
git:20260828.82b6b6c to git:20260828.26f7340
19 added, 87 removed. Audit A to A.
---
name: choosing-graph
description: Pick the coordination graph and the reality anchor before work starts — how the agents on this task are wired, and what contact with reality will prove the result. Use at the start of any straw-boss work, whether a main agent is about to dispatch or a dispatched worker is about to begin its own task, and again when the shape of the work changes under you.
---
## Overview
- Two choices, made before the first turn of real work and stated out loud: the
- **coordination graph** — how the agents on this task are wired — and the
- **reality anchor** — the contact with reality that proves the result. Both are
- coordination, so a main agent fixes both when it dispatches and the anchor
- travels with the brief. A dispatched worker states its own graph for its own
- task and works inside the anchor it was handed.
+ Two choices, made before the first turn of real work and stated out loud: the **coordination graph** — how the agents on this task are wired — and the **reality anchor** — the contact with reality that proves the result. Both are coordination, so a main agent fixes both when it dispatches and the anchor travels with the brief. A dispatched worker states its own graph for its own task and works inside the anchor it was handed.
- **Naming the anchor is not naming the tests.** The anchor fixes the category and
- its checkpoint; inside it the worker and the user choose the method — which
- seam, which cases, which tool. That split is `docs/roles.md`'s, and it is what
- keeps the brief clear of the worker's own work definition.
+ **Naming the anchor is not naming the tests.** The anchor fixes the category and its checkpoint; inside it the worker and the user choose the method — which seam, which cases, which tool. That split is `docs/roles.md`'s, and it keeps the brief clear of the worker's own work definition.
- Both are stated, not asked. The single exception is the human anchor's question
- below.
+ Both are stated, not asked. The human anchor carries the one user question described below.
## Coordination graphs
- Which one applies is observable: how many app-rooted workers run under one
- coordination loop, and by what mechanism.
+ Which graph applies follows from how the work actually runs.
- - **single-loop** — one agent carries the work end to end. A coordinator
- driving a single dispatch's lifecycle events is still this shape, and so is a
- worker that brought one coworker. Reach for it when the work is uncomplicated
- and its length is visible from here.
- - **sub-agent fan-out/fan-in** — the working agent spawns subagents through its
- own `Agent` tool and integrates what comes back. A main agent and a dispatched
- worker both use this one. Reach for it when the goal is already clear and the
- scope has converged, so every branch can be stated in full before any of them
- starts.
- - **orchestrator-worker** — the coordinator dispatches more than one app-rooted
- worker and runs the loop over their status events. A confirmed dependency
- graph and a capped batch are both this shape, whether or not the workflow is
- still settling. It is the only graph that writes
- `~/.straw-boss/plans/<slug>/plan.json`; the other two carry no dispatch plan.
+ - **single-loop** — one agent carries uncomplicated work whose length is visible end to end. A coordinator driving one dispatch's lifecycle, or a worker using one coworker as a check, remains a single loop.
+ - **sub-agent fan-out/fan-in** — a main agent or dispatched worker sends clear, converged branches to subagents and integrates their results.
+ - **orchestrator-worker** — the coordinator runs multiple app-rooted workers through status events. A dependency graph and a capped batch use this shape. It is the only graph that writes `~/.straw-boss/plans/<slug>/plan.json`; the other two carry no dispatch plan.
- `orchestrator-worker` is settled ahead of the other two: more than one
- app-rooted worker under one coordination loop is that shape whatever else runs
- beside it, because it alone writes the dispatch plan. Subagents the coordinator
- runs alongside those workers do not move it.
+ `orchestrator-worker` is settled ahead of the other two: more than one app-rooted worker under one coordination loop keeps that shape whatever else runs beside it.
- `single-loop` and `sub-agent fan-out/fan-in` route this work exactly as far as
- it needs to go: no `plan.json`, and no repo-internal Straw Boss planning or
- spec document either — that plan is `orchestrator-worker`'s alone to write.
- Every app-rooted dispatch still writes its own
- `~/.straw-boss/dispatch/<app>--<slug>.json` instruction and `.contract.md`,
- whichever graph carries it — the dispatch's lifecycle record, archived once
- the dispatch wraps up. That record is the routing mechanism's own bookkeeping,
- not the dispatch plan or spec document this section is about.
+ `single-loop` and `sub-agent fan-out/fan-in` create no `plan.json` and no repo-internal Straw Boss planning or spec document. An app-rooted dispatch still writes its own `~/.straw-boss/dispatch/<app>--<slug>.json` instruction and `.contract.md`; these are the dispatch's lifecycle record, archived once the dispatch wraps up.
- Between **single-loop** and **sub-agent fan-out/fan-in**, the deciding question
- is whether a branch of the work itself runs in a subagent: if one does, the
- shape is fan-out. The anchor's own check — including an independent review
- agent — is not a branch of the work and never changes the graph.
+ Between **single-loop** and **sub-agent fan-out/fan-in**, the deciding question is whether a branch of the work itself runs in a subagent: if one does, the shape is fan-out. The anchor's own check — including an independent review agent — is not a branch of the work and never changes the graph.
## Reality anchors
- - **testing** — the default. Unit tests at the smallest credible seam that can
- go red before the change; the worker escalates to integration or E2E when the
- target project's own conventions call for it.
- - **pseudo-human** — a computer or browser drives the real interface and
- verifies a simple element by screenshot and measurement.
- - **human** — the user operates the real artifact and judges it: a new UI
- element, a UX behaviour. When this is the anchor, ask the user whether their
- own risk judgment prefers pseudo-human instead. Reading code or a document is
- review, not this anchor — with nothing to operate, use the one below.
- - **adversarial-review** — an independent agent attacks the finished result and
- reports what it breaks. Independent means fresh context: hand it the result
- and the requirement, never your own reasoning about them. Every ordinary
- programming change carries adversarial-review beside whichever anchor above
- applies, and it can serve as the anchor itself when the other three have no
- checkpoint to offer. Two routes discharge it: the worker reaches for it
- through its own `Agent` tool or `bringing-coworker`, or the main agent
- dispatches it against the committed result. The generated contract carries
- that obligation to every worker, and whichever skill confirms the change
- landed confirms the review happened too — `shipping-task` Task 6 for a task
- it drives to completion, `boss-say` Task 7 for a batch item, and
- `dispatching-work`'s own Wrap-up branch for a dispatch closed out directly by
- neither. A plan or batch task's own terminal event may instead reach
- `plan-mechanics.md`'s auto-detach procedure directly; its own guard carries
- the identical check, so whichever of the two reaches a given task first is
- what discharges it.
+ - **testing** — the default. Unit tests cover the smallest credible seam that can go red before the change; the worker escalates to integration or E2E when the target project's own conventions call for it.
+ - **pseudo-human** — a computer or browser drives the real interface and verifies a simple element by screenshot and measurement.
+ - **human** — the user operates the real artifact and judges a new UI element, UX behaviour, or finished article. Ask whether their risk judgment prefers pseudo-human instead. Reading code or a document is review, not a human anchor.
+ - **adversarial-review** — a fresh-context agent attacks the finished result against the requirement and evidence. It is the anchor when the other three offer no credible checkpoint, and accompanies an ordinary programming change as an independent check.
- Read-only work — an audit, research, a separate diagnosis — has no artifact to
- operate and no change to go red, so adversarial-review is its anchor. What that
- independent agent attacks is the report's claims against the evidence references
- `inspecting-app`, `investigating-app`, and `troubleshooting-app`'s integration
- preflight already require. Those references make the attack possible; they are
- not the anchor. `troubleshooting-app`'s other branch lands a fix, so it takes
- the testing anchor like any other change.
+ Review one coherent change-set with one adversarial review after implementation and primary verification. The reviewer examines the finished change-set directly. Correctness and contract findings return to the working loop; nits close with an explicit disposition. The lifecycle owner records the review once against the confirmed completion reference.
+ For read-only work with no operable artifact or red test, adversarial-review is its anchor. The reviewer attacks the report's claims against its evidence references. A troubleshooting branch that lands a fix uses testing like any other change.
+
## The port a frontend anchor needs
- A human or pseudo-human check on a frontend needs something running at a known
- address before there is anything to look at, so the main agent claims the port
- at dispatch and the worker binds it. Mechanics, the reason the worker does not
- re-claim, and the release step:
- `${CLAUDE_PLUGIN_ROOT}/skills/dispatching-work/references/shared-resource-coordination.md`.
+ A frontend human or pseudo-human anchor needs a running address, so the main agent assigns the port at dispatch and the worker binds it. Claim and release mechanics live in `${CLAUDE_PLUGIN_ROOT}/skills/dispatching-work/references/shared-resource-coordination.md`.
- **Verification:** the graph and the anchor are both named before work starts;
- `plan.json` exists only under orchestrator-worker; a frontend human or
- pseudo-human anchor carries an assigned port in the dispatch instruction; the
- brief names the anchor and leaves the method inside it to the worker; an
- ordinary programming change has an adversarial review beside its anchor, run by
- the worker or dispatched by the main agent.
+ **Verification:** the graph and anchor are named before work starts; `plan.json` exists only under orchestrator-worker; a frontend human or pseudo-human anchor carries an assigned port; the brief leaves the method to the worker; one coherent programming change-set receives one independently dispositioned review.