The earlier dispatchers
Make the handoffs visible.
The stage-dispatcher design gave work an explicit route. That made the inputs and outputs of each handoff easier to inspect.
FROM THE ORCHESTRA WORKBENCH / PORTFOLIO PREVIEW
An engineer’s view of the harness
Orchestra
Study
A resource for engineers and anyone who codes. Explore how Orchestra fits together through diagrams, walkthroughs, and selected source from the working harness.
Walk through a decisionA note from the creator
Why I’m sharing it
this way.
I’d love to share the whole project as open source. But after all the work I’ve put into Orchestra, I’m not comfortable handing over the complete system without knowing how it might be reused or commercialized.
I still want other engineers and people who code to understand how it fits together. This study shares selected source, diagrams, and walkthroughs so you can follow the architecture and the decisions behind it. The complete harness stays private; what’s here is shared for reading and study.
THREE WAYS INTO THE WORK
03 walkthroughs · 06 selected excerpts · A dated view of the system
The question behind the machinery
Follow the work past “done.”
A small interface change makes the journey concrete. The interesting part is the handoff between doing the work and knowing enough to move it forward.
THE SHAPE OF THE WORKSELECT A STEP
PM supervision · Human decisions
STEP 1 OF 4 / Plan
Agree on the work before starting it.
The unit starts with a written change and an agreed scope. A later session needs to be able to find that agreement, including decisions the owner has changed.
What to look for
The intended change, its boundaries, and the current owner decisions.
01 / 04
Try a different situationILLUSTRATIVE EXAMPLE
What happens after a model says “done”?
The worker reports the change complete.
Ready for the next checked transition
In this example, the required evidence is present and there is no unresolved hold. The next transition follows its contract.
- Work
- Change ready to inspect
- Evidence
- Required records present
- Human decision
- No open hold in this example
Small pieces, with a reason to read them
The lines behind the notes.
Six selected fragments from the actual source. Each one supports a specific point in the walkthroughs; the commentary around it is written for this page.
01Completion has to be earned.Bash fragment · 8 lines
The default outcome is an error. This small fragment shows the principle behind that choice: an interrupted process must not look like a successful unit.
Bash fragment8 lines
RAN_TO_END=0
FINAL_STATUS="error"
finalize(){
local rc=$?
if [ "$RAN_TO_END" -ne 1 ]; then
FINAL_STATUS="error"
[ $rc -eq 0 ] && rc=1 # parent-kill mid-poll must not read as success (guide §9)
fi
harness/engine/spindle-orchestrate.sh
Lines 44–51 · snapshot b85e3b1b
02A fresh session reads the authority again.Prompt excerpt · 3 lines
The previous conversation is not the source of authority. A new window has to check the current record.
Prompt excerpt3 lines
- **Re-read it at EVERY phase start AND after every context rotation.** A fresh window must never
inherit a stale seat roster from its predecessor's memory: the FILE is the authority, not what a
previous window believed. The owner can change it mid-run, and mid-run is exactly when it matters.
harness/engine/spindle-prompts/_flag_contract.md
Lines 10–12 · snapshot b85e3b1b
03An event starts an investigation.Source comment · 3 lines
The monitor calls for attention. The PM still has to inspect what the worker is doing before deciding what the signal means.
Source comment3 lines
# EVENTS ARE TRIGGERS, NOT TRUTH (owner standing rule 2026-07-21): every event line ends in
# "[verify: pane]" — the PM must capture-pane before acting or reporting, both to get the WHY
# (the agent's own words) and to debug THIS monitor (claimed vs pane vs commit).
harness/pm/monitor.sh
Lines 20–22 · snapshot b85e3b1b
04Keep the failure as a test.Source comment · 3 lines
A monitoring defect becomes a repeatable case. That is how a lesson survives beyond the session in which it was learned.
Source comment3 lines
# SPINDLE PM — monitor regression harness. THE debug loop for the monitoring system:
# every monitor defect ever found gets a fixture here reproducing it; a monitor change must go
# green across ALL fixtures before it is re-armed. (Owner ruling: the PM debugs the monitor.)
harness/pm/harness.sh
Lines 8–10 · snapshot b85e3b1b
05Carry the oversight across.Doctrine excerpt · 4 lines
The build can outlive the person or model watching it. A handoff carries the unfinished responsibilities into the next session.
Doctrine excerpt4 lines
Read on `/<pm-leaf> handoff`, or when ending a session after real PM work. Same idea as
`/hultra handoff` but catches up the next **PM**: the pipeline keeps running when your session
ends, but your oversight (Monitor, heartbeat, owner-proxy decision log, surfaced-unanswered
items, quirks) dies with you. The handoff carries it across.
harness/doctrine/handoff.md
Lines 3–6 · snapshot b85e3b1b
06Observation must not break execution.Source comment · 2 lines
Recording an event is useful, but an observability failure should not be allowed to kill the work it is describing.
Source comment2 lines
# CONTRACT [A8]: this script must NEVER be able to kill the pipeline.
# - every failure path logs to stderr and exits 0
harness/engine/spindle-emit.sh
Lines 25–26 · snapshot b85e3b1b
How the approach evolved
From a sequence of steps
to work you can inspect.
Three themes connect the earlier dispatcher records to the later engine and PM architecture. These are editorial summaries of that development.
The per-unit engine
Give progress a durable record.
The SPINDLE design organized work around a unit, its phase, and its recorded evidence. A session could stop without being the only place the state existed.
Independent supervision
Watch the conditions around the work.
The PM and its governor separate doing the task, assessing its progress, and preserving supervision across sessions.
Keep the questions going
The studies take a closer look at the model assignments.