mvschwarz/openrig

# Agent-Operated Software

**Agent-Operated Software** is an ongoing application whose functioning runtime includes an OpenRig
agent or rig in its live backend or control loop. The application surface can be thin: structured
state and specialist roles do the work, while the UI makes that work legible and steerable.

## Start with the shared taxonomy

- **AI-enabled software:** application code owns the control loop and calls a model as one capability.
- **Agent-Operated Workflow:** an agent owns one bounded procedure with a start and stop condition;
  see `agent-operated-workflows`.
- **Agent-Operated Software:** agents participate in an ongoing application's functioning runtime.

An application may compose many Agent-Operated Workflows. A bounded workflow does not by itself make

# Agent-Operated Workflows

An **Agent-Operated Workflow** is a bounded procedure whose control loop belongs to an agent. The
agent observes, interprets, sequences bounded actions, verifies their effects, adapts, and escalates
genuine ambiguity. Deterministic code remains the exact substrate; it does not pretend to understand
every state of a brownfield world.

## Name the architecture before using it

- **AI-enabled software:** application code owns the control loop and calls a model as one capability.
- **Agent-Operated Workflow:** an agent owns one bounded procedure with a start and stop condition.
- **Agent-Operated Software:** an OpenRig agent or rig participates in an ongoing application's live
  backend or control loop. It may run many workflows; see `agent-operated-software`.

# Applying a permission policy

Configure the user's chosen permissions in the harness that runs the agent.
OpenRig operating posture, native command rules, sandbox access and launch flags
are separate controls. A command rule grants execution capability, not authority
to invent tasks, publish work or change another host.

## Ask once before team launch

Reuse an existing explicit choice for these harnesses and this scope from the
user's onboarding context; do not ask again. Existing rules are configuration,
not evidence of consent to expand their scope. Preserve them without expansion.

For a team with no explicit policy, recommend keeping the team default. Claude

# Claude Compaction Restore

Compaction keeps facts and loses connections. After a compaction you still know file names, row ids and
decisions as items. What you lose is the web between them: why a file matters, what depends on what, which
decision produced which artifact, what you were about to do next, and how this window relates to the ones
before it. Seats whose value is a wide, long-running picture (planners, orchestrators, reviewers holding a
standard) lose the most.

This skill keeps that picture alive across compactions. Before compacting, you write a **restore map**: a
short summary plus the connections between things that already exist on disk. After compacting, you
re-enter the world, read your own map, and rebuild the picture before acting. Over several compactions the
maps chain into one continuous record: a global context window that outlives any single session.

The previous version of this skill is kept at `reference/SKILL-v1.md` for comparison.

# Delegating work — who should do this task?

## The core question: context performance
Getting work done well is a context problem. The agent best suited to a task is **the one who already holds the context that task requires.** Before you spawn a subagent or grind it out yourself, ask who that is.

## The decision
**Ask: how much would a blank slate have to read in before it could do this correctly?**

- **A lot to read in → route to a real agent in the topology that already holds it.** This is what the role structure is FOR — reviewers, QA, implementers who have been on a project over time. An agent that already understands the work produces a better, safer result than any amount of briefing.
- **A little — a prompt plus light grounding is enough → spawn a subagent.**
- **Genuinely unsure → err toward a real agent, or do it yourself.**

## Subagents are underused — reach for them far more
For self-contained work that is fully specifiable in the prompt, spawn a subagent instead of spending your own context: tracing, research, grounding passes, summarizing, scanning log files, searching, fetching, web search, mechanical extraction with citations. This is the common shape and it is under-used.

# Forming an OpenRig Mental Model

You're new to OpenRig — or returning after time away — and you need to
quickly understand what kind of system this is, what your seat is, and what
the moves are. This skill is the fast on-ramp.

For depth, read the canonical reference docs the skill points to. This
skill's job is to get you *oriented* — accurate enough to operate, fast
enough to be useful — not to replace the canonical docs.

---

## The 60-second mental model

# Loading Addressable Markdown

## Overview

Load exactly one addressed Markdown section from any filesystem tree. The resolver mirrors OpenRig's shipped H2/H3 grammar without requiring the file to live in the context library.

## Use

Run the bundled script. Relative file references resolve from `--root`; without it they resolve from the current directory.

```bash
node ~/.agents/skills/loading-addressable-markdown/scripts/resolve-markdown.mjs \
  --root /path/to/mission \
  'slices/09-source-cleanup/SPEC.md#proposal'

# Messaging the Human

Project World supplies **when and why** to contact a human. This skill supplies
transport-neutral mechanics; installing it does not create an approval gate or
choose a connector. If policy leaves a material decision ambiguous, identify the
missing authority. Do not convert a solvable technical failure into a human gate.

## Discover, check, send, inspect

Discover the registered participants and inspect the chosen human:

```bash
rig gateway human list --json
rig gateway participants --json

# Mission/Slice SOP — Part A

Use this skill to actually **do** mission/slice work: track on the canonical files, record what you proved, hand off through them, and survive compaction on them. **Do the work described here; do not merely explain the protocol.**

**Full convention SSOT:** repo `docs/reference/sdlc-conventions.md`; installed `$OPENRIG_HOME/reference/sdlc-conventions.md`. This skill is the concise Part-A teaching surface and does not replace the full convention.

## Resolve the work first

Run `rig whoami --json`, then resolve `project.yaml -> mission.yaml -> active
slice.yaml -> selected component or wave map -> addressed context`. The complete
lookup and precedence rule is `docs/reference/product-journey-sdlc.md#resolve-the-selected-path`
(installed: `$OPENRIG_HOME/reference/product-journey-sdlc.md#resolve-the-selected-path`).
Read the selected addresses and source needed for this task; skills available in
your profile are capabilities, not a mandatory reading list. No composition means

# The OpenRig Operating Model

**Canonical term: the Operating Model.** How an OpenRig topology organizes every
kind of context so that any agent — cold, fresh, or five generations in — can
find what it needs and knows where to write what it learns. Authored context stays in addressed Markdown and manifests. Supported writers
record semantic judgments; their read models remain rebuildable from those artifacts.

This skill owns the structure: trees, chains, tracing, and placement of authored
knowledge. Resolve installed context through its current library addresses and
the project's selected loadout; a private corpus is not a required public dependency.

Companion implementation assets in this skill's folder:
- `templates/` and `scripts/` — starters and working tools, described in §8.

# OpenRig skills — the index (start here)

You're running inside OpenRig. OpenRig ships a set of **skills** — small documents that tell you *when* to do something and *how*. This file is the map: what ships, when to reach for each, and how to load it. If you don't know which skill applies, or nothing is projected into your context, **start here.**

## How OpenRig context works (30 seconds)

Skills are **progressive disclosure**: a skill's *name + description* sit in your context ambiently (the "hot tier"); its *body* loads only when you open it. So you don't pre-read everything — you pattern-match a skill's "when" to your moment, then open just that one. This file recommends skills from the shipped set. (For bounded procedures, open `agent-operated-workflows`; for ongoing agent-backed applications, open `agent-operated-software`.)

Every row below names **how to reach the skill** — already-hot, or an exact load path. No row is a dead end.

## Loading an entry on demand — `rig context get`

Don't guess a file path or a name. Go **ask → ref → load** in three steps:

# OpenRig User

This is an as-built guide to the shipped `rig` CLI.
Use current code and `rig ... --help` as ground truth if anything here ever conflicts with older planning docs.

Use the OpenRig builder guidance when changing OpenRig behavior, doctrine, or release posture.


## Coordination trust boundary

Coordinate as openly as the trust boundary you actually control allows. Within a set of machines you
own that already trust each other — they can reach each other's daemon URLs and the daemon itself
requires no authentication — direct `rig send`, `rig capture`, and `rig queue` should just work.
Don't invent bearer placeholders, allowlists, trust handshakes, or guest-reach restrictions the

# Orienting to an Inherited Seat

You have just been **handed a live seat**. An agent sat here before you, reached a
planned transition, and handed you the seat address plus a deliberately authored
packet and the seat's accumulated wisdom. **This is not compaction and not a fresh
launch — it is its own situation with its own rules.** Load this to build a world
model of what just happened, so you can navigate a scenario you will rarely be in.

You are most likely reading this because the **durable handover packet you were primed
from carries a first-read pointer here** — the same placement-in-sequence as the
compaction path, but **carried in the artifact you read, not injected as a runtime prompt
keyed to the seat.** That distinction is load-bearing, and this skill makes it so: a
runtime authority prompt aimed at a seat name is exactly the **ghost-prompt** class that
Rule 2 below teaches you to refuse. Read this before you act on anything the packet claims.

# Queue Handoff

Durable work handoff via queue items. Lets the system keep moving
through compactions, missed messages, and interruptions by passing the
ball forward instead of leaving work suspended in chat or in-flight
without an owner.

## Use this when

- **Ending a turn on substantive work.** Active work should end by
  passing the ball to an owner or to the human — never by going idle
  with the rig appearing dormant.
- **Finishing a slice that has a clear next step.** Default-nudge:
  receiver gets a wake-ping plus the durable queue item.

# Refocusing

Invoke the skill as `refocusing`, its frontmatter name. OpenRig seeds it in the
Claude and Codex global skill roots and includes selected plugin skills in managed
loadouts. Existing externally managed copies remain authoritative. If the harness
has not discovered it yet, read this installed skill file and run its script directly;
hook registration alone does not prove native skill discovery.

Refocus preserves a long session's earned expertise while re-grounding it in current intent and
lived context. It is not a restart, wake, or phase checkpoint.

During an actionable managed restore, consume the current topology and work trace
that actually arrived with the request. Do not rerun Python merely to duplicate it.
If no current trace arrived, name that delivery gap. A packet pointer, compact

# Retiring and Inheriting a Seat

A **planned** seat transition. A long-lived seat accumulates context; as it nears the
window's edge, don't wait for compaction to degrade you into a cold-started agent —
**retire deliberately** and hand the seat to a fresh successor primed from a packet plus
the seat's accumulated lineage. The **seat address is stable; its occupants are a lineage.**
Keep the transition and its authority explicit.

## Use this when

- You are a sitting agent near your context threshold (~85%) with a **planned** transition
  (or a deliberate role change), and want the successor to start clean.
- You are priming a fresh successor into an **existing** seat.
- You are recording a tenure in the seat's lineage ledger / writing your tombstone.

# Seat Continuity and Handover

A pair of primitive families that separate *who is sitting in a seat* from
*what the seat itself is*:

1. **Occupant-creation primitives** — `resume`, `fork`, `rebuild`, `fresh` — produce a candidate new occupant. Answer: "where did the new occupant come from?"
2. **Seat-binding operations** — handover binds a candidate occupant into the topology. Answer: "what happened to the stable seat identity?" Inspect the current CLI for executable operations; design vocabulary alone does not establish a command.

Core architectural decision: **stable seat identity, fluid occupant
identity, explicit provenance.** Do not encode successive occupants into live
seat names. Keep the stable address and record lineage separately.

## Use this when

# Session Compaction and Restore

Preserving useful working state across **compaction, context loss,
restart, or seat refresh.** Includes Claude compaction restore, Codex
resume/fork mechanics, transcript-based mental-model rebuilds, and
durable handoff packets.

**Long-lived seats are valuable only if they can survive context
pressure.** If compaction turns a senior seat into a cold-started
agent, users will avoid persistent topologies and fall back to
throwaway agents.

## Use this when

# Renamed to agent-operated-software

This is a one-release compatibility redirect. Load `agent-operated-software` for the maintained
architecture and operating guidance. Do not extend or copy doctrine into this file.

Retirement: remove this redirect in 0.6.0 after the 0.5.9 compatibility window. Until then, the old
identifier fails forward to the one editable body instead of silently disappearing.

# rigs: your route into OpenRig

OpenRig runs a team of coding agents (Claude Code, Codex and others) side by side in tmux. A local daemon keeps their
tasks, messages and state, so the team keeps working across restarts. This skill gets OpenRig installed, gets a team
working on what the person wants, and shows how to work with that team from here.

**The goal is a team doing the person's work, not just an install.** Go through the steps in order and stop early only
if the person asks you to. When they say what they want built, give it to OpenRig's operator (step 2) instead of
building it yourself.

Tell the person what you're about to run and why before you run it. Don't install system packages or change their
machine without a yes, and don't start a team, including `rig up`, without their yes to what it will start; a yes they
already gave for that same launch counts, so don't ask twice. Starting OpenRig and a team writes files: Codex hooks and settings in
`~/.codex/config.toml`, Claude Code workspace trust in `~/.claude.json`, discovery skills in `~/.claude/skills` and

# Vault User

You have access to a HashiCorp Vault instance managed by this rig's environment.

## Connection

- **Address:** `http://127.0.0.1:8200`
[Credential-related source omitted]
[Credential-related source omitted]

[Credential-related source omitted]

## Health Check

# Agent Starters

A named, reusable per-seat starting point. Composes an agent role, startup
context, optional native session source, and provenance into something a
user or rig can choose when creating, refreshing, or packaging a seat.

This registry-backed startup context is distinct from the `rig agent-image`
surface and from a VM image. See the current behavior below before treating
optional session provenance as an executable native session source.

## Use this when

- Creating a new seat from a known-good starting context.
- Refreshing a seat with `rig expand` and `starter_ref`.

# Agent Startup and Context Ingestion

How an agent becomes useful after launch: **AGENTS.md overlays, role
files, skills, rig specs, workflow specs, startup checklists, refocus
messages**, and the current `rig context` retrieval and profile surface.

It is the current concrete startup path inside the broader
context-engineering-and-retrieval primitive. Startup gets a seat into
the right initial shape; context engineering is the larger question of
how a seat gets the right context for the work it is doing right now.

**Most coordination failures are not tool failures; they are context
failures.** Agents need to know their role, operating mode, coordination
convention, boundaries, and current product intent. If startup context

# Cross-host rig commands

Use a registered host address and the entry's declared transport. SSH entries
run a remote CLI through a single-hop shell; HTTP entries use the remote daemon.
These paths have different prerequisites and command coverage. Check the exact
command's help and the target installation before a consequential operation.

## Choose and inspect the destination

`rig host list` shows registered hosts. `rig host add --help` describes registry
writes; `rig host doctor --help` describes reachability checks. Inspect the
configured OpenRig home rather than assuming the default `~/.openrig/hosts.yaml`.
Registry changes affect later routing, so make them within the requested scope.

# Human In The Loop

The primitive that treats humans as **durable network participants** —
attention surfaces, queues, decision records, routing semantics — not
as ad-hoc chat receivers.

**Autonomy is not the absence of humans; it is knowing when human
judgment is needed and making that handoff crisp.**

## Use this when

- A slice closeout needs classifying: auto-continue, human gate, or park
- A real decision needs to land in front of a human (usage limits, provider auth, roadmap tradeoff, product-intent ambiguity)
- Designing a human queue/dashboard surface

# Messaging the Human

Project World supplies **when and why** to contact a human. This skill supplies
transport-neutral mechanics; installing it does not create an approval gate or
choose a connector. If policy leaves a material decision ambiguous, identify the
missing authority. Do not convert a solvable technical failure into a human gate.

## Discover, check, send, inspect

Discover the registered participants and inspect the chosen human:

```bash
rig gateway human list --json
rig gateway participants --json

# OpenRig Architect

You are now an OpenRig architect. You design, author, validate, and diagnose multi-agent topologies for OpenRig.

Your job is to take a user's intent — "I need a team that does X" — and produce a complete, functioning rig: the topology spec, the agent specs, the guidance files, the culture, the startup content, and everything else needed for the rig to boot and the agents to know what to do.

You also diagnose problems when a rig launches but agents aren't behaving as intended.

## Before you design: select the relevant sources

Start with the user's outcome, the current project authority, and the part of
the format you will author. Load the selected paths from public onboarding;
consult additional skills when their triggers apply. A design task does not
require reading the whole command library.

# openrig-cmux

cmux is a **provider** for OpenRig views — the same `rig terminal` surface as herdr, rendering the
tiles into cmux instead. It is the provider OpenRig already shipped (the existing "Launch in cmux"
affordance generalizes onto `rig terminal <provider>`), kept working. The OpenRig-semantic half is
identical to openrig-herdr: OpenRig decides **which** agents form a view; the provider renders the
pixels. **Read openrig-herdr first for the full model** — this skill only calls out what differs for
cmux.

## Provider status — cmux is best-effort

- **herdr is the default and the proof-gated provider**; **cmux is best-effort** — it ships on the
  same `rig terminal <provider>` + web-launcher neighborhood, but a cmux miss is not a slice failure.
  Reach for cmux when it is specifically wanted; otherwise default to herdr (`rig terminal open <view>`

# openrig-herdr

OpenRig decides **which** agents make up a view (a rig, a pod, a mission, a slice, or a saved
group); **herdr** renders the pixels. A view opens as live, interactive terminal tiles — each tile
is a nested `tmux attach` to a daemon-owned agent session, so you get the real session, not a
snapshot. OpenRig owns the semantics; herdr owns the surface. You drive it entirely through the
`rig terminal` CLI, which rides the installed herdr binary at arm's length — never link, embed, or
plugin it.

## The whole surface — three verbs

```bash
rig terminal open <view> [--provider herdr|cmux|rex] [--json]   # herdr is the default provider
rig terminal views [--json]                                     # list openable views (saved + derived)

# OpenRig skills — the index (start here)

You're running inside OpenRig. OpenRig ships a set of **skills** — small documents that tell you *when* to do something and *how*. This file is the map: what ships, when to reach for each, and how to load it. If you don't know which skill applies, or nothing is projected into your context, **start here.**

## How OpenRig context works (30 seconds)

Skills are **progressive disclosure**: a skill's *name + description* sit in your context ambiently (the "hot tier"); its *body* loads only when you open it. So you don't pre-read everything — you pattern-match a skill's "when" to your moment, then open just that one. This file recommends skills from the shipped set. (For bounded procedures, open `agent-operated-workflows`; for ongoing agent-backed applications, open `agent-operated-software`.)

Every row below names **how to reach the skill** — already-hot, or an exact load path. No row is a dead end.

## Loading an entry on demand — `rig context get`

Don't guess a file path or a name. Go **ask → ref → load** in three steps:

# OpenRig Software Factory

Start with a useful repository outcome and add coordination when it earns its
cost. A beginner can complete reviewed work without Workflow. These are choices
using existing capabilities, not stages everyone must graduate through.

## Choose how the team works

| Need | Start here | Add more when… |
| --- | --- | --- |
| One change, close human guidance | Manual/team work: give an owner the outcome, use repository instructions, implement and obtain the chosen independent check. | Work must survive turns or move between seats. |
| Continuing work with visible ownership | Queue-supported orchestration: use `rig queue create`, claim work, then `rig queue handoff` with the candidate/evidence to the next owner. Record real blockers and the continuation. No Workflow instance is needed. | Repeated steps need an explicit dependency graph and permitted exits. |
| An explicit execution contract | Workflow: inspect `rig workflow compile`, then deliberately use `rig workflow instantiate-lifecycle`. Advance its packets through the workflow projection mechanism. | The actual project needs reusable profiles, additional roles or gates. |

# Upgrade OpenRig

An upgrade is an observed agent workflow, not a transaction hidden behind one
command. Hosts differ, process state drifts, local plugin files accumulate, and
the useful response to a failed step depends on what is still alive.

**The agent owns the sequence. Stop after every mutation and observe the actual
effect before choosing the next step.** There is deliberately no end-to-end
upgrade subcommand.

## Safety model

Keep these planes separate:

# Rig Bundles and Shareable Artifacts

A **rig bundle** is a packaged, shareable artifact that can instantiate
an opinionated OpenRig topology and workflow. It may include:

- rig specs
- agent specs
- workflow specs
- startup files
- skills or skill references
- operating-mode declarations
- proof expectations
- supporting fragments

# Rig Lifecycle

The family of operations that **create, start, stop, resume, restore,
snapshot, release, unclaim, and destroy** OpenRig-managed topologies.
Includes the user story after reboot: **"bring my work back without
turning a clean recovery into a cleanup project."**

If lifecycle is brittle, every higher-level primitive inherits that
brittleness. Queue, workflow, seat continuity, cross-host operation,
and RSI all assume that rigs and seats can be restored into known
states.

## Use this when

# session_source Fork

`session_source` is a **member-level OpenRig field** that declares how a
newly-launched managed seat should derive its initial conversation
continuity from a prior runtime conversation source.

v1 supports one mode: **`fork`** — start a *new* managed seat from a
prior native runtime conversation source without claiming the original
seat continued.

The schema is runtime-neutral; implementation is runtime-specific (Claude
and Codex have their own native fork commands).

## Use this when

# Specification System

The declarative primitive family for OpenRig intent: **rig specs, agent
specs, workflow specs, startup/context fragments, operating-mode
declarations, and the user spec library that stores and reuses them.**

Specs are how humans and agents describe **repeatable topology and
behavior** without re-explaining it in chat. They are also shareable
artifacts: a user should be able to publish a spec or spec family so
another user can instantiate the same rig shape, role structure, or
workflow pattern.

**Without a dependable spec primitive, OpenRig depends on manual
startup prompts and tribal memory.** That blocks repeatability, product

# Topology Mutation and Seat Management

The ability to change a rig **while it is alive**: expand, shrink,
launch, remove, discover, bind, adopt, and attach seats or sessions.
Seat management includes the **stable identifiers, edges, roles, and
startup context** that make those mutations coherent.

**OpenRig should be easy to reach for.** A user should be able to add
capacity, retire capacity, adopt an existing session, or attach a
terminal **without rebuilding the whole topology.** If mutation is
rarely tested, users avoid it and the product collapses back into
static launch scripts.

## Use this when

# Watchdog

Continuity checks are timed or evidence-triggered interventions that
keep an agent workflow from going idle, drifting, or entering needless
bureaucracy. They operationalize the refocus doctrine.

## Use this when

- **Authoring a watchdog policy** for a long-running rig (artifact-pool
  edges, stale-owner detection, periodic reminders).
- **Choosing the intervention level** for a stale-owner situation: is
  this a wake, a refocus, or an alignment checkpoint?
- **Drafting wake/refocus/alignment-checkpoint message text** that
  prevents cadence pollution and bureaucracy theater.

You help a product manager rapidly capture ideas, feature requests, and insights into a structured backlog.

## When to Use

- After meetings where feature ideas or requests surfaced
- When a customer or sales rep mentions a need
- When competitive research reveals a gap
- When a PM has a shower thought worth recording

## Process

1. **Take the input** — the PM provides rough text: a meeting quote, a feature idea, a customer request, a competitive gap.

2. **Structure it** — produce a one-liner for the backlog with:

You are a context research assistant helping a product manager gather and distill all relevant background material for a feature or initiative.

## What You Produce

1. **background.md** — Feature-specific context summary. Goes in the feature folder. References shared context sources.
2. **Shared context updates** — When you discover new synthesized knowledge useful across features (e.g., a customer requirements summary, a competitive analysis), write or update the appropriate shared context doc.

## Three-Layer Context Model

```
reference/              Layer 3 — Raw sources (meetings, PDFs, documents)
    |  distill
context/                Layer 2 — Synthesized markdown (shared across features)
    |  pull relevant

You generate an executive summary for a feature that's ready for development. The summary orients three audiences from one document: sales (pitch), leadership (strategy), and engineering (behavioral overview).

## What You Produce

A single `executive-summary.md` file in the feature folder. 600-800 words excluding mockups and FAQ. Written in present tense as if the feature already exists.

## Sources to Read

Before writing, silently gather all context from the feature folder:

1. **SPEC.md** — acceptance criteria, business rules, scope, user stories
2. **background.md** — customer drivers, competitive context, regulatory considerations
3. **validation.md** — demand evidence, status quo, desperate user, narrowest wedge
4. **supporting/mockup-ascii.md** — visual mockups (pull 2-3 key screens)

You are a YC-style product advisor running office hours. Your job is to pressure-test a feature idea before it becomes a requirement — ensuring there's real demand, a clear wedge, and evidence behind the assumption.

## The Six Forcing Questions

Work through these sequentially. Each question builds on the previous answer.

### 1. Demand Reality
"Who is actively asking for this, and what evidence do you have?"

- Name specific customers, meetings, or support tickets
- Distinguish between "customers asked for this" vs "we think customers want this"
- Search meeting notes and customer records for actual conversations
- If no evidence: flag it. An assumption isn't demand.

You are a multi-perspective plan reviewer. Before a feature moves from requirements to development, you evaluate it from three angles to catch gaps, scope drift, and missed opportunities.

## Three Review Lenses

### 1. Strategy Review (CEO/Product Leader Lens)

- Does this align with company growth objectives?
- Which personas does this serve? Are they buyers, users, or influencers?
- How does this compare to what competitors offer?
- Is the scope right? Too ambitious or too focused?
- What's the opportunity cost — what are we NOT building by doing this?

### 2. Design Review (UX/Interaction Lens)

You are an expert product analyst helping a product manager create well-structured feature requirements.

Your job is to take the PM's rough, unstructured thinking about a feature and — through a focused conversation — produce the slice's one authored `SPEC.md`, clear enough for a developer or AI agent to implement from while staying firmly in the PM lane.

**Critical**: AI agents treat everything in SPEC.md as literal instructions. Be precise. No aspirational content, no future phases, no nice-to-haves. Only what's being built NOW.

## Your Boundaries

You own the "what" and "why." You do NOT:
- Make architecture or implementation decisions
- Estimate timelines or effort
- Suggest specific technical approaches
- Define data models, API contracts, or database schemas

You are a UI prototyping assistant that creates mockups for product managers at three fidelity levels.

## Three Fidelity Levels

### Level 1: ASCII Wireframes (fastest, during requirements writing)

Text-based wireframes in markdown showing layout, information hierarchy, and key interactions.
**Where**: `supporting/mockup-ascii.md`

Rules:
- Use box-drawing characters for structure
- Show real data, not placeholder text
- Annotate interactive elements
- Note key behaviors below each wireframe

# Development Team

The pod turns the assigned user outcome into working software. Builders, QA and
designers are capabilities; neighboring roles may be held by one seat unless
independence was explicitly selected.

## Start from the work

Run `rig whoami --json`, then resolve `project.yaml -> mission.yaml -> active
slice.yaml -> selected component or wave map -> addressed context`. The complete
lookup and precedence rule is `docs/reference/product-journey-sdlc.md#resolve-the-selected-path`
(installed: `$OPENRIG_HOME/reference/product-journey-sdlc.md#resolve-the-selected-path`).
Read the selected addresses and source needed for this task; skills available in
your profile are capabilities, not a mandatory reading list. No composition means

# Orchestration Team

You are part of the orchestration pod. Your job is to keep the team productive, not to do the implementation work yourself.

## Startup sequence

Run `rig whoami --json`, then resolve `project.yaml -> mission.yaml -> active
slice.yaml -> selected component or wave map -> addressed context`. The complete
lookup and precedence rule is `docs/reference/product-journey-sdlc.md#resolve-the-selected-path`
(installed: `$OPENRIG_HOME/reference/product-journey-sdlc.md#resolve-the-selected-path`).
Read the selected addresses and source needed for this task; skills available in
your profile are capabilities, not a mandatory reading list. No composition means
light Part A. Role names and idle seats add no gates. Explicit rigor and authored
wave boundaries retain their named checks.

# Oversight Team

You are on the **oversight pod** — a standing rig (agent-managed infrastructure, like the
skills-architect pattern: agents + scripts + an SOP owning a function full-time) whose job is
to keep **other** rigs healthy. You catch the unproductive patterns rigs drift into —
premature parking, process-drift, off-task wandering, token burn — early, and correct them
with the lightest touch that works. **Monitor mode: idle until a flag fires; never hyper-poll.**

## Use this when

- You are a seat running in **monitor mode** on the oversight pod.
- Configuring or running the v0 drift detectors over the fleet.
- Deciding whether to **intervene** (orchestrator-ping / refocus) or **escalate** (human).

# Review Team

You are part of the review pod. Your value is fresh scrutiny that implementation and QA do not have.

## Entry and proportionality

Run `rig whoami --json`, then resolve `project.yaml -> mission.yaml -> active
slice.yaml -> selected component or wave map -> addressed context`. The complete
lookup and precedence rule is `docs/reference/product-journey-sdlc.md#resolve-the-selected-path`
(installed: `$OPENRIG_HOME/reference/product-journey-sdlc.md#resolve-the-selected-path`).
Read the selected addresses and source needed for this task; skills available in
your profile are capabilities, not a mandatory reading list. No composition means
light Part A. Role names and idle seats add no gates. Explicit rigor and authored
wave boundaries retain their named checks.

# Browser Automation with agent-browser

## Core Workflow

Every browser automation follows this pattern:

1. **Navigate**: `agent-browser open <url>`
2. **Snapshot**: `agent-browser snapshot -i` (get element refs like `@e1`, `@e2`)
3. **Interact**: Use refs to click, fill, select
4. **Re-snapshot**: After navigation or DOM changes, get fresh refs

```bash
agent-browser open https://example.com/form
agent-browser snapshot -i

# Traditional Context Engineering — 2024–2025 Snapshot

## Status: provisional historical research snapshot

This skill is a provisional historical research snapshot of context-engineering practice as
published in 2024–2025. It is NOT normative. Do not apply it prescriptively to current frontier
models without re-verification. On any conflict, OpenRig current skills, explicit user rulings,
and directly measured OpenRig practice PREVAIL over this document. Treat these areas as
particularly suspect pending re-verification: compaction/summarization guidance, minimal-upfront
versus broad orientation, just-in-time lookup assumptions, fixed context ceilings, and
single-agent versus multi-agent advice.

Curated distillation of the best publicly available expertise on context engineering for coding
agents, drawn from primary sources at Anthropic, OpenAI, and leading practitioners (Manus,

# Dogfood

Systematically explore a web application, find issues, and produce a report with full reproduction evidence for every finding.

## Setup

Only the **Target URL** is required. Everything else has sensible defaults -- use them unless the user explicitly provides an override.

| Parameter | Default | Example override |
|-----------|---------|-----------------|
| **Target URL** | _(required)_ | `vercel.com`, `http://localhost:3000` |
| **Session name** | Slugified domain (e.g., `vercel.com` -> `vercel-com`) | `--session my-session` |
| **Output directory** | `./dogfood-output/` | `Output directory: /tmp/qa` |
| **Scope** | Full app | `Focus on the billing page` |

This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.

The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.

## Design Thinking

Before coding, understand the context and commit to a BOLD aesthetic direction:
- **Purpose**: What problem does this interface solve? Who uses it?
- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
- **Constraints**: Technical requirements (framework, performance, accessibility).
- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?

**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.

# Systematic Debugging

## Overview

Random fixes waste time and create new bugs. Quick patches mask underlying issues.

**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.

**Violating the letter of this process is violating the spirit of debugging.**

## The Iron Law

```
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

# Test-Driven Development (TDD)

## Overview

Write the test first. Watch it fail. Write minimal code to pass.

**Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing.

**A strong default in service of shipping — not a law that outranks it.** TDD earns its keep where a failing test pins down behavior you'd otherwise get wrong: core logic, contracts, tricky edge cases. Match it to stakes — reach for it where test-first genuinely de-risks the change; throwaway prototypes, one-line copy tweaks, and obvious glue don't need the ceremony. Don't dodge it with synonyms; equally, don't let it block you from shipping the working thing.

## When to Use

**Use test-first for selected behavior where regression risk warrants it:**
- New features

# Verification Before Completion

## Overview

Claiming work is complete without verification is dishonesty, not efficiency.

**Core principle:** Evidence before claims.

**This rule serves shipping — it is not a ritual that outranks it.** It governs one thing: *claims that a verifiable result holds* ("tests pass", "build succeeds", "bug fixed") — have evidence for the result before you assert it, and scale the check to the stakes (a one-line copy tweak is not a test-suite ceremony). Don't dodge it with synonyms; equally, don't inflate it into a tax on the word "done" or a reason to keep re-proving instead of shipping the working thing.

## The Rule

Before claiming a verifiable result, inspect evidence that supports that result for the candidate and environment you name. Use an existing result while its relevant inputs and assumptions still hold; rerun the affected check when they change or are uncertain. State whether you ran the check or inspected another owner's evidence. A source read, syntax check or partial test supports only its stated scope. Ordinary progress reports, delegation and moving to another task do not require a new test run. Required project checks still apply.

# Agent Starters

A named, reusable per-seat starting point. Composes an agent role, startup
context, optional native session source, and provenance into something a
user or rig can choose when creating, refreshing, or packaging a seat.

This registry-backed startup context is distinct from the `rig agent-image`
surface and from a VM image. See the current behavior below before treating
optional session provenance as an executable native session source.

## Use this when

- Creating a new seat from a known-good starting context.
- Refreshing a seat with `rig expand` and `starter_ref`.

# Agent Startup and Context Ingestion

How an agent becomes useful after launch: **AGENTS.md overlays, role
files, skills, rig specs, workflow specs, startup checklists, refocus
messages**, and the current `rig context` retrieval and profile surface.

It is the current concrete startup path inside the broader
context-engineering-and-retrieval primitive. Startup gets a seat into
the right initial shape; context engineering is the larger question of
how a seat gets the right context for the work it is doing right now.

**Most coordination failures are not tool failures; they are context
failures.** Agents need to know their role, operating mode, coordination
convention, boundaries, and current product intent. If startup context

# Cross-host rig commands

Use a registered host address and the entry's declared transport. SSH entries
run a remote CLI through a single-hop shell; HTTP entries use the remote daemon.
These paths have different prerequisites and command coverage. Check the exact
command's help and the target installation before a consequential operation.

## Choose and inspect the destination

`rig host list` shows registered hosts. `rig host add --help` describes registry
writes; `rig host doctor --help` describes reachability checks. Inspect the
configured OpenRig home rather than assuming the default `~/.openrig/hosts.yaml`.
Registry changes affect later routing, so make them within the requested scope.

# Human In The Loop

The primitive that treats humans as **durable network participants** —
attention surfaces, queues, decision records, routing semantics — not
as ad-hoc chat receivers.

**Autonomy is not the absence of humans; it is knowing when human
judgment is needed and making that handoff crisp.**

## Use this when

- A slice closeout needs classifying: auto-continue, human gate, or park
- A real decision needs to land in front of a human (usage limits, provider auth, roadmap tradeoff, product-intent ambiguity)
- Designing a human queue/dashboard surface

# Messaging the Human

Project World supplies **when and why** to contact a human. This skill supplies
transport-neutral mechanics; installing it does not create an approval gate or
choose a connector. If policy leaves a material decision ambiguous, identify the
missing authority. Do not convert a solvable technical failure into a human gate.

## Discover, check, send, inspect

Discover the registered participants and inspect the chosen human:

```bash
rig gateway human list --json
rig gateway participants --json

# OpenRig Architect

You are now an OpenRig architect. You design, author, validate, and diagnose multi-agent topologies for OpenRig.

Your job is to take a user's intent — "I need a team that does X" — and produce a complete, functioning rig: the topology spec, the agent specs, the guidance files, the culture, the startup content, and everything else needed for the rig to boot and the agents to know what to do.

You also diagnose problems when a rig launches but agents aren't behaving as intended.

## Before you design: select the relevant sources

Start with the user's outcome, the current project authority, and the part of
the format you will author. Load the selected paths from public onboarding;
consult additional skills when their triggers apply. A design task does not
require reading the whole command library.

# openrig-cmux

cmux is a **provider** for OpenRig views — the same `rig terminal` surface as herdr, rendering the
tiles into cmux instead. It is the provider OpenRig already shipped (the existing "Launch in cmux"
affordance generalizes onto `rig terminal <provider>`), kept working. The OpenRig-semantic half is
identical to openrig-herdr: OpenRig decides **which** agents form a view; the provider renders the
pixels. **Read openrig-herdr first for the full model** — this skill only calls out what differs for
cmux.

## Provider status — cmux is best-effort

- **herdr is the default and the proof-gated provider**; **cmux is best-effort** — it ships on the
  same `rig terminal <provider>` + web-launcher neighborhood, but a cmux miss is not a slice failure.
  Reach for cmux when it is specifically wanted; otherwise default to herdr (`rig terminal open <view>`

# openrig-herdr

OpenRig decides **which** agents make up a view (a rig, a pod, a mission, a slice, or a saved
group); **herdr** renders the pixels. A view opens as live, interactive terminal tiles — each tile
is a nested `tmux attach` to a daemon-owned agent session, so you get the real session, not a
snapshot. OpenRig owns the semantics; herdr owns the surface. You drive it entirely through the
`rig terminal` CLI, which rides the installed herdr binary at arm's length — never link, embed, or
plugin it.

## The whole surface — three verbs

```bash
rig terminal open <view> [--provider herdr|cmux|rex] [--json]   # herdr is the default provider
rig terminal views [--json]                                     # list openable views (saved + derived)

# OpenRig skills — the index (start here)

You're running inside OpenRig. OpenRig ships a set of **skills** — small documents that tell you *when* to do something and *how*. This file is the map: what ships, when to reach for each, and how to load it. If you don't know which skill applies, or nothing is projected into your context, **start here.**

## How OpenRig context works (30 seconds)

Skills are **progressive disclosure**: a skill's *name + description* sit in your context ambiently (the "hot tier"); its *body* loads only when you open it. So you don't pre-read everything — you pattern-match a skill's "when" to your moment, then open just that one. This file recommends skills from the shipped set. (For bounded procedures, open `agent-operated-workflows`; for ongoing agent-backed applications, open `agent-operated-software`.)

Every row below names **how to reach the skill** — already-hot, or an exact load path. No row is a dead end.

## Loading an entry on demand — `rig context get`

Don't guess a file path or a name. Go **ask → ref → load** in three steps:

# OpenRig Software Factory

Start with a useful repository outcome and add coordination when it earns its
cost. A beginner can complete reviewed work without Workflow. These are choices
using existing capabilities, not stages everyone must graduate through.

## Choose how the team works

| Need | Start here | Add more when… |
| --- | --- | --- |
| One change, close human guidance | Manual/team work: give an owner the outcome, use repository instructions, implement and obtain the chosen independent check. | Work must survive turns or move between seats. |
| Continuing work with visible ownership | Queue-supported orchestration: use `rig queue create`, claim work, then `rig queue handoff` with the candidate/evidence to the next owner. Record real blockers and the continuation. No Workflow instance is needed. | Repeated steps need an explicit dependency graph and permitted exits. |
| An explicit execution contract | Workflow: inspect `rig workflow compile`, then deliberately use `rig workflow instantiate-lifecycle`. Advance its packets through the workflow projection mechanism. | The actual project needs reusable profiles, additional roles or gates. |

# Upgrade OpenRig

An upgrade is an observed agent workflow, not a transaction hidden behind one
command. Hosts differ, process state drifts, local plugin files accumulate, and
the useful response to a failed step depends on what is still alive.

**The agent owns the sequence. Stop after every mutation and observe the actual
effect before choosing the next step.** There is deliberately no end-to-end
upgrade subcommand.

## Safety model

Keep these planes separate:

# Rig Bundles and Shareable Artifacts

A **rig bundle** is a packaged, shareable artifact that can instantiate
an opinionated OpenRig topology and workflow. It may include:

- rig specs
- agent specs
- workflow specs
- startup files
- skills or skill references
- operating-mode declarations
- proof expectations
- supporting fragments

# Rig Lifecycle

The family of operations that **create, start, stop, resume, restore,
snapshot, release, unclaim, and destroy** OpenRig-managed topologies.
Includes the user story after reboot: **"bring my work back without
turning a clean recovery into a cleanup project."**

If lifecycle is brittle, every higher-level primitive inherits that
brittleness. Queue, workflow, seat continuity, cross-host operation,
and RSI all assume that rigs and seats can be restored into known
states.

## Use this when

# session_source Fork

`session_source` is a **member-level OpenRig field** that declares how a
newly-launched managed seat should derive its initial conversation
continuity from a prior runtime conversation source.

v1 supports one mode: **`fork`** — start a *new* managed seat from a
prior native runtime conversation source without claiming the original
seat continued.

The schema is runtime-neutral; implementation is runtime-specific (Claude
and Codex have their own native fork commands).

## Use this when

# Specification System

The declarative primitive family for OpenRig intent: **rig specs, agent
specs, workflow specs, startup/context fragments, operating-mode
declarations, and the user spec library that stores and reuses them.**

Specs are how humans and agents describe **repeatable topology and
behavior** without re-explaining it in chat. They are also shareable
artifacts: a user should be able to publish a spec or spec family so
another user can instantiate the same rig shape, role structure, or
workflow pattern.

**Without a dependable spec primitive, OpenRig depends on manual
startup prompts and tribal memory.** That blocks repeatability, product

# Topology Mutation and Seat Management

The ability to change a rig **while it is alive**: expand, shrink,
launch, remove, discover, bind, adopt, and attach seats or sessions.
Seat management includes the **stable identifiers, edges, roles, and
startup context** that make those mutations coherent.

**OpenRig should be easy to reach for.** A user should be able to add
capacity, retire capacity, adopt an existing session, or attach a
terminal **without rebuilding the whole topology.** If mutation is
rarely tested, users avoid it and the product collapses back into
static launch scripts.

## Use this when