Mike Schwarz
1bbe81f428
Community-maintained harnesses use one naming family throughout OpenRig: `rig community-harness list`, `/api/community-harnesses`, presets under `$OPENRIG_HOME/community-harnesses/`, and `communityHarness` selection and status fields. Rig specs keep `runtime`, existing preset runtime names and the built-in runtimes. - The old command, route, directory discovery and JSON names have no public alias. Existing preset files are left untouched and aren't moved or discovered from the old directory. - The database column and migration 114 are unchanged and map to the new domain field. Launch-only handling, unconfirmed identity, screen-only activity and the resume/fork refusal are preserved. - Saved snapshots get a narrow read-only decoder: a nonempty legacy `agentApp` string supplies `communityHarness` only when the new key is absent, and a present new key wins, including an explicit null or a malformed value. Reads preserve the stored bytes, the old key is removed from returned objects, and new capture never writes it. This is storage compatibility, not an old public alias. Tests cover 11 snapshot-boundary cases (readers, precedence, malformed legacy values, unchanged stored bytes, new-key-only serialization) and five naming and storage cases (API and preset-directory isolation, untouched old preset files, migration 114 fresh and already applied, partial-schema reads). Native harness behaviour isn't exercised; synthetic fixtures stand in for it.
4.5 KiB
Naming rigs, pods and seats
Names tell people and agents what a team does and who does each part. Use the team's purpose for the rig, a domain for each pod, and a role for each seat. These are authoring conventions, not additional parser restrictions.
What each name means
| Level | Meaning | Example |
|---|---|---|
| Fleet | A group of OpenRig instances | Your development fleet |
| Instance | One daemon and its rigs; several instances can share a machine | The instance selected by a registered host route |
| Rig | A team or project purpose | starter, workshop, factory, or your project's name |
| Pod | A domain or shared context | orch, dev, review, research, sre |
| Seat (member) | A role within that pod | lead, advisor, build, qa, design, review |
The logical seat ID is pod.member: dev.build. Its session address is
pod-member@rig: dev-build@workshop. A cross-instance command also selects the
registered host route; a display label is not a route. Discover actual addresses
with rig ps --nodes and host routes with rig host list before sending work.
Runtime, model and account belong in configuration. Changing a provider does not change the role's name. Keep machine and instance identifiers stable rather than renaming them whenever their workload changes.
What a seat runs has its own words:
| Term | Meaning | Example |
|---|---|---|
| Runtime | What a seat runs: a harness, a terminal, or the stub (a scripted stand-in used in tests). It's the rig spec's runtime field and the TUI's runtime column |
claude-code, codex, terminal |
| Harness | The agent software around a model | Claude Code, Codex, Pi |
| Community harness | A harness an outside contributor maintains. It's installed as a preset under $OPENRIG_HOME/community-harnesses/, listed by rig community-harness list, and OpenRig doesn't test it |
A preset's name in a member's runtime |
| Terminal | A seat with no agent: a shell for infrastructure processes | runtime: terminal |
How the software teams grow
| Team | Logical seats |
|---|---|
| Starter | dev.build, dev.review |
| Workshop | orch.lead, dev.build, dev.qa, dev.review |
| Factory | orch.lead, orch.advisor, dev.build, dev.qa, dev.design, review.r1, review.r2 |
Starter and Factory are built-in teams. Workshop is a
bundle.
The built-in specs live under packages/daemon/specs/rigs/launch/ in the product
source. Runtime presets keep these logical names.
Workshop's one code reviewer is dev.review; Factory has an independent review
pod with review.r1 and review.r2. Both are intentional. A small team does not
need every pod or role from a larger one.
Name a new team
Start with the outcome, then group its work by domain. For a team studying a
dataset, research.analyst and research.synthesizer describe useful roles.
For operating a service, sre.admin describes the domain and responsibility.
Use a project-specific rig name when that helps distinguish two teams.
Avoid a generic operation such as check as the pod name: it does not say whether
the team owns software quality, research validation or service health. Put the
role in its domain, such as dev.qa. This is a rule for choosing new names, not a
word blacklist or a demand that all teams share one roster.
Use the same IDs in the rig spec, edges, workflow targets, configuration presets, startup instructions and terminal views. Validate those references together. See RigSpec and publishing a bundle.
Existing identities and retained references
An existing team's address remains its actual address until it is deliberately migrated. Changing a label does not rename a seat or move its conversation, queue or work. Preserve those records and verify the new routes when doing a migration; do not edit a database or restart a team just to make a display match an example.
first-project is the compatibility name for Starter; it is not a second team
template. Existing-name safeguards still apply. See
getting started before using the alias.
The factory-rsi bundle is a retained reference with original workflow-bound
addresses, including build.implementer and check.qa. It is distinct from the
current built-in Factory and is not the naming template for a new team. Old
release notes, pinned bundles, run records and compatibility tests keep the
identities they describe.