AGENT SKILL

developing-openrig

Use when changing OpenRig's own source in a clone of the openrig repository: finding which package or file owns a behaviour, choosing which tests to run, testing a change without disturbing the OpenRig daemon your own session runs on, judging whether a diff touches a high-risk area, or preparing a pull request. Not for operating rigs (openrig-skills) or designing rig topologies.

License 许可
Apache-2.0
最近更新
2026-11-12
Stars
★ 16
Forks
4

01 前言 Front Matter

name
developing-openrig
description
Use when changing OpenRig's own source in a clone of the openrig repository: finding which package or file owns a behaviour, choosing which tests to run, testing a change without disturbing the OpenRig daemon your own session runs on, judging whether a diff touches a high-risk area, or preparing a pull request. Not for operating rigs (openrig-skills) or designing rig topologies.

03 SKILL.md 正文

Developing OpenRig

This skill is a map to the other maps. Each one is incomplete and may be stale: where a map and the code disagree, the code is right, and fixing the map is a welcome contribution.

First: which OpenRig are you in?

If you are an agent running inside OpenRig, two different OpenRigs are in play:

  • The installed one runs your session. rig --version and rig daemon status describe it.
  • The checkout is what you're changing. git rev-parse HEAD describes it.

Restarting the installed daemon does not run your checkout, and stopping it stops the agents running on it, including you. Test your change with the repo's own harnesses, which start a private daemon and tmux server (see "Test it" below), not by restarting the daemon you live in.

Find your way

You want to know Read How much to trust it
What OpenRig can already do, before you decide something is missing rig context get onboarding-width/public-what-you-can-do.md; in this checkout, packages/daemon/context-packs-src/onboarding-width/public-what-you-can-do.md (the installed copy can differ) The capability map; check it before proposing a new command or calling a gap a defect
Whether a rig command already exists rig --help: the full command list, before you decide a command is missing The running binary; read the whole list, not only the command you expected
Whether a problem is already known The "Known problems to compare against" section of docs/reference/help.md Lists known issues by symptom; check an issue's current status before relying on it
Whether a feature is already planned ROADMAP.md Check it before proposing a feature
How the packages fit, the request path, where to add a command, route, migration, adapter, skill, context pack or scenario ARCHITECTURE.md Checked against the commit it names; counts come with the command to refresh them
Whether your change touches a high-risk area, what depends on it, what broke there before docs/as-built/arteries.md Incomplete by design: absence from it doesn't make a change safe
What to run before you push, and what each layer can and can't prove docs/as-built/test-layers.md Checked against the commit it names
The exact behaviour of a rig command rig <command> --help on the running binary, then packages/cli/src/commands/ The binary and the code win over any document
A subsystem in depth docs/as-built/ Each module names the commit it was last checked against in last-verified-against-source; compare that marker with git log before relying on it
Rig spec, agent spec and other user-facing reference docs/reference/ Ships to every user; if you find drift, fix it there
Which shipped skill covers a task skills/_canonical/core/openrig-skills/SKILL.md The index of the skills that ship with OpenRig
How to open a good pull request, and what review looks like CONTRIBUTING.md Current

If none of these answers your question, search the code before inventing an answer. A missing map is worth an issue.

Before you change an artery

If your diff touches anything in arteries.md (message delivery, launch and resume, the queue, rig identity, skill projection, process observation, migrations, restore):

  1. Read the artery row: what depends on it, and the past regressions listed there.
  2. Describe the downstream effect in your pull request, not just the diff.
  3. Add or extend a stub-agent scenario, or say precisely why the stub can't exercise it and what you ran instead.

Test it

The short version is npm run build, npm run lint, npm test. test-layers.md has the full ladder, including the stub-agent scenarios, which run the real CLI, daemon, tmux and SQLite with scripted agents and no model cost.

  • The scenario runner starts its own daemon and tmux server and drops your session's TMUX and daemon variables, so it won't touch the daemon your session runs on.
  • A stub proves OpenRig's own plumbing, not how Claude Code or Codex behave. Say which you exercised.

How we judge changes

OpenRig is a coordination layer for a trusted environment: it should help agents and people keep work flowing.

  • A change that removes friction, or makes state more truthful, is usually welcome.
  • OpenRig runs on agents working in context with tools. Before adding code for a behaviour, ask whether an agent with the right instructions and today's commands could do it. A skill or a page of guidance is often the better change.
    • Where to look: the capability map above, and the agent-operated-workflows skill, which ships in the openrig-core plugin (packages/daemon/assets/plugins/openrig-core/skills/agent-operated-workflows/SKILL.md).
  • A change that adds a refusal, a prompt or a required step needs the concrete case in CONTRIBUTING.md: who is harmed, how, and what it costs everyone else.
  • One concern per pull request. Keep the diff reviewable in one sitting.

When the map is wrong

Fix it in the same pull request, or open an issue. Update a document's last-verified-against-source marker only when you have actually checked it against that commit.

04 同仓库更多 Skills

mvschwarz
mvschwarz/openrig-world

notes

Use when taking notes.

★ 16
mvschwarz
mvschwarz/openrig-world

software-for-agents

Use when older OpenRig instructions name software-for-agents or describe agent-in-the-middle or studio software under the former skill name.

★ 16
mvschwarz
mvschwarz/openrig-world

session-compaction-and-restore

Use when reasoning about what survives compaction/context-loss/restart/seat-refresh, designing a high-fidelity restore packet, or distinguishing native runtime resume vs fork vs artifact-backed mental-model rebuild. Covers the 4 failure modes that prevent honest restore (compacted seat drops hot potato; restore packet preserves details but loses product intent; runtime resume mistaken for handover or fork; rebuilt seat starts with stale instructions).

★ 16
mvschwarz
mvschwarz/openrig-world

seat-continuity-and-handover

Use when replacing a seat's occupant (rebuild/handover/swap), reasoning about stable-seat-identity vs fluid-occupant-identity, choosing an old-occupant disposition (retire/advise/shadow), or recording provenance for an occupant change. Two independent outcomes (continuityOutcome + seatBindingOutcome) and the 5 failure modes that prevent silent dishonesty.

★ 16
mvschwarz
mvschwarz/openrig-world

retiring-and-inheriting-a-seat

Use when you are a sitting agent near your context threshold (~85%) and a PLANNED seat transition is due — retire deliberately and hand your seat to a fresh successor primed from a packet, rather than let compaction degrade you. Covers the handover packet, the append-only lineage ledger (one row per tenure), physical-seat continuity, the do-not-over-inherit framing, the optional warm-handoff window, and wake-v0 (consulting a retired predecessor). NOT for unplanned compaction/crash recovery (session-compaction-and-restore / claude-compaction-restore) and NOT the seat-binding primitive mechanics (seat-continuity-and-handover).

★ 16
mvschwarz
mvschwarz/openrig-world

refocusing

Use when a long-running agent may have lost the product outcome, when context was compacted, when work has crossed a major boundary, or when a fresh path-based trace is needed before the next consequential action. Not for fresh-session orientation, waking an idle seat, or checkpoints.

★ 16