mirror of https://github.com/mvschwarz/openrig.git synced 2026-10-02 00:27:21 +08:00

Files

T

History

Multi-host + Living Notes.

Multi-host foundation: shareable whole-topology staged spin-up brings
a rig topology up across multiple hosts in stages; VPS product-factory
multi-host hardening ships with rig host verbs (add / list / doctor,
capped at three; one built-in product-factory-vps posture, three-
valued per item); the transport posture is documented (ssh for pane
ops, http-bearer for daemon REST, no cross-transport fallback); the
For-You feed aggregates activity across every registered host; and
rig file moves files across the topology's registered hosts.

Living Notes: durable INTENT / PLAN / DELIVERED signal layer at
mission and slice altitude with agent authorship + timestamps; cheap
composer surfaces make it the first-class place agents record
decisions, plans, and delivered work; the one-structure review
contract reads left-to-right as a single vertical stack (INTENT above,
PLAN + mockup in the middle, DELIVERED with paired proof at the
bottom); a plan change deletes the old plan and writes a new one -
never demotes or stacks multiple competing plans.

Operationalize the SDLC control plane: conventions SSOT ships in
source at docs/reference/sdlc-conventions.md (Living Notes UI section
names, proof-contract format + plannedRef mockup pairing, staged-
approval locks, C1 proof header + closed sets, three role contracts,
curation rule, elastic-middle doctrine, advisory fail-open audit
posture); rig scope slice create scaffolds the convention sections +
proof + PROOF.md + an IMPLEMENTATION-PRD.md skeleton for every
template kind; rig scope audit + rig workspace doctor gain sdlc-
convention advisories (records-and-advises, gates on HIGH only); the
mission-slice-sop skill ships in canonical source with byte-parity
guard; rig proof / rig scope slice create / rig scope slice approve
help + cli-reference teach the SDLC flow.

BREAKING: rig ps default flips to consolidated all-active-rigs
compact projection (the v0.4.0 current-rig-only default is retired -
it hid running rigs from the operator's field of view). --json is
scope-not-shape (still a bare array with existing per-entry keys;
scope widens to all non-archived rigs including stopped ones; one-line
migration for the old fleet firehose: rig ps --nodes -A --full).
-A / --all-rigs keeps exactly ONE meaning (the --nodes fleet widener;
bare -A is a structured teaching error). --nodes names its scope
everywhere (session default local-only; --host <id> --nodes requires
--rig or -A; multi-host fan-out is rollup-only by default; the
explicit ladder --all-hosts --nodes -A --full fans out per-node with
hostId-stamped projected rows). --all-hosts / --hosts --json emits the
shared AggregatedPayload (items + hosts with closed-enum statuses:
ok | unreachable | unsupported-transport | auth-failed).

Operator UX: agent altitude coordination panel scopes multi-agent
state to the right altitude (workspace / mission / slice) so the
coordination surface reads without per-seat drowning; composes with
the workspace observability tabs from 0.4.1. Docs closeout catches
docs/as-built/architecture.md, docs/as-built/cli-reference.md, and
the codemaps up to shipped state.

Migrations: additive only. Existing v0.4.3 databases upgrade by
running rig daemon start.

Behavior change (rig ps default view): the compact all-active-rigs
projection replaces the current-rig-only default. If your call sites
relied on the v0.4.3 default shape, add --full for the rich per-node
projection or --rig <name> for the prior scope.

Public-safety scrub applied inline to packages/ui/twin/corrective/
fixtures-corrective.ts (one demo-fixture role identifier neutralized
to the demo-namespace baseline established at 0.4.1).

See CHANGELOG.md and docs/releases/v0.4.4.md.

2026-07-06 01:20:09 -07:00

agents

NS-T15: North Star demo — fixture, proof package, and validation

2026-03-31 09:40:40 -07:00

scripts

demo: switch proof scripts to rig commands

2026-04-19 01:25:56 -07:00

culture.md

NS-T15: North Star demo — fixture, proof package, and validation

2026-03-31 09:40:40 -07:00

README.md

Release 0.4.4

2026-07-06 01:20:09 -07:00

rig.yaml

demo: switch proof scripts to rig commands

2026-04-19 01:25:56 -07:00

run-proof.sh

Release 0.4.4

2026-07-06 01:20:09 -07:00

run.sh

Release 0.4.4

2026-07-06 01:20:09 -07:00

README.md

North Star Demo

A complete multi-agent topology demonstrating OpenRig's core capabilities.

This directory is the canonical authoring example for OpenRig. It is meant to be read by both humans and coding agents as the reference layout for a real rig:

rig.yaml — the topology source of truth
culture.md — rig-wide culture/guidance
agents/*/agent.yaml — per-agent package manifests
scripts/ — baseline seeding, verification, and proof helpers

The same tree is also the golden source for same-checkout bundle tests:

rig bundle create demo/rig.yaml --rig-root demo -o /tmp/demo.rigbundle
rig bundle inspect /tmp/demo.rigbundle
rig bundle install /tmp/demo.rigbundle --yes --target /tmp/demo-install
rig up /tmp/demo.rigbundle

Topology

orch pod: lead (claude-code) — orchestrator
dev pod: impl (claude-code), qa (codex), design (claude-code)
rev pod: r1 (claude-code), r2 (codex)
infra pod: daemon (terminal, monitoring), ui (terminal, cwd: packages/ui)
Edges: orch.lead delegates to dev.impl, dev.qa observes dev.impl, rev.r1 collaborates with rev.r2

8 nodes across 4 pods. 6 agent harnesses + 2 terminal infrastructure nodes.

Prerequisites

Node.js 22+
tmux 3+
OpenRig built: npm run build from repo root
Claude Code and/or Codex CLI installed

Quick Start

./demo/run.sh

run.sh boots the topology and then establishes a restore-safe baseline for the demo rig. If fresh runtime sessions are not yet resumable, it seeds one warmup turn per agent and re-verifies native resume before handing control back.

Resume Baseline

Before treating restore as trustworthy, establish and verify the runtime resume baseline on a fresh boot:

npx tsx demo/scripts/check-demo-health.ts --rig demo-rig
npx tsx demo/scripts/verify-native-resume.ts --rig demo-rig
npx tsx demo/scripts/seed-resume-baseline.ts --rig demo-rig
npx tsx demo/scripts/verify-native-resume.ts --rig demo-rig

The baseline matters because Claude and Codex have different native resume semantics. See docs/planning/post-northstar-round/runtime-resume-semantics.md for the currently observed runtime caveats.

Current known-good rule on macOS:

fresh Codex sessions in this demo are resumable immediately
fresh Claude sessions are not snapshot-safe immediately after rig up
one completed warmup turn is enough to make the current stored Claude IDs resumable on this fixture

Full Proof Package

./demo/run-proof.sh

This produces automated proof artifacts in demo/proof/:

Artifact	Source	Type
`up-transcript.txt`	`rig up demo/rig.yaml` output	Automatic
`ps-nodes.txt`	`rig ps --nodes --rig <rig>` after boot	Automatic
`health-after-boot.json`	`check-demo-health.ts` after boot	Automatic
`native-resume-after-boot.txt`	immediate native probe after boot	Automatic
`native-resume-after-boot.json`	immediate native probe machine output	Automatic
`seed-resume-baseline.txt`	baseline seeding summary	Automatic, only if seeding was needed
`seed-resume-baseline.json`	baseline seeding machine output	Automatic, only if seeding was needed
`native-resume-before-down.txt`	native Claude/Codex probe before down	Automatic
`native-resume-before-down.json`	native probe machine output	Automatic
`down-transcript.txt`	`rig down` output	Automatic
`tmux-check.txt`	`tmux ls` after teardown	Automatic
`restore-transcript.txt`	`rig restore <snapshotId> --rig <rigId>` output	Automatic
`ps-restored.txt`	`rig ps --nodes --rig <rig>` after restore	Automatic
`browser-screenshot.png`	Explorer + Graph + Detail Panel	Manual
`resume-test.txt`	Post-restore agent context check	Manual

Manual Steps

After run-proof.sh completes:

Browser screenshot: Open http://localhost:5173 → screenshot showing Explorer with all pods, Graph with pod grouping, Node Detail Panel open. Save to demo/proof/browser-screenshot.png.
Resume test: Run tmux attach -t orch-lead@demo-rig → ask "What were you working on?" → copy response to demo/proof/resume-test.txt.

Expected Session Names

After boot, tmux list-sessions should show:

orch-lead@demo-rig
dev-impl@demo-rig
dev-qa@demo-rig
dev-design@demo-rig
rev-r1@demo-rig
rev-r2@demo-rig
infra-daemon@demo-rig
infra-ui@demo-rig

Expected Boot Time

6 harness launches + 2 terminal launches. Sequential (topological order). Expected total: 2-5 minutes depending on hardware.

Restore Notes

For exact proof and repeated local testing, prefer explicit restore: rig restore <snapshotId> --rig <rigId>
rig up demo-rig is only safe as a restore shortcut while there is a single stopped historical rig with that name. Once multiple historical demo-rig instances exist, OpenRig correctly returns an ambiguity error.