@openrig/cli 0.1.3 → 0.1.5

package/daemon/specs/agents/shared/skills/core/openrig-user/SKILL.md

@@ -0,0 +1,468 @@
+---
+name: openrig-user
+description: Use when operating OpenRig with the `rig` CLI and you need the shipped command surface for identity, inventory, communication, lifecycle, specs, recovery, or agent-facing JSON output.
+---
+
+# 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.
+
+## Core Loop
+
+Most work in OpenRig reduces to this loop:
+- recover identity: `rig whoami --json`
+- inspect inventory: `rig ps --nodes --json`
+- read context: `rig transcript ...`, `rig ask ...`, `rig chatroom history ...`
+- act: `rig send`, `rig capture`, `rig broadcast`, lifecycle commands
+
+## Identity and Recovery
+
+Start here after launch, compaction, or confusion:
+
+```bash
+rig whoami --json
+```
+
+What it gives you today:
+- identity: rig, logical ID, pod/member, session name, runtime
+- peers and directional edges
+- transcript info
+- `contextUsage` when available
+
+Flags:
+```bash
+rig whoami --session <name>
+rig whoami --node-id <id>
+```
+
+If the daemon is unreachable but identity can still be inferred, `--json` may return a partial result instead of crashing.
+
+## Inventory and Monitoring
+
+```bash
+rig ps
+rig ps --json
+rig ps --nodes
+rig ps --nodes --json
+```
+
+Use `rig ps --nodes --json` for the current node inventory across rigs. It is the best machine-readable operator surface for:
+- session name
+- runtime
+- session/startup status
+- restore outcome
+- attach/resume commands
+- latest error
+
+Other health surfaces:
+
+```bash
+rig status
+rig daemon status
+rig config
+rig preflight
+rig doctor
+```
+
+## Transcript and Communication
+
+### Transcript access
+
+```bash
+rig transcript <session> --tail 100
+rig transcript <session> --grep "pattern"
+rig transcript <session> --json
+```
+
+### Send to one session
+
+```bash
+rig send <session> "message"
+rig send <session> "message" --verify
+rig send <session> "message" --force
+rig send <session> "message" --json
+```
+
+Use `--verify` when you want delivery evidence. Use `--force` only when you intentionally want to bypass activity-risk checks.
+
+### Capture terminal output
+
+```bash
+rig capture <session>
+rig capture <session> --lines 50
+rig capture --rig <name>
+rig capture --pod <name> --rig <name>
+rig capture --rig <name> --json
+```
+
+### Broadcast
+
+```bash
+rig broadcast --rig <name> "message"
+rig broadcast --pod <name> "message"
+rig broadcast "message"
+rig broadcast --rig <name> "message" --json
+```
+
+Without `--rig` or `--pod`, broadcast targets all running sessions.
+
+### Chatroom
+
+```bash
+rig chatroom send <rig> <message> [--sender <name>]
+rig chatroom history <rig> [--topic <name>] [--after <id>] [--since <ts>] [--sender <name>] [--limit <n>] [--json]
+rig chatroom wait <rig> [--after <id>] [--topic <name>] [--sender <name>] [--timeout <seconds>] [--json]
+rig chatroom clear <rig>
+rig chatroom topic <rig> <topic-name> [--body <text>] [--sender <name>]
+rig chatroom watch <rig> [--tmux]
+```
+
+**Key commands:**
+- `send` — post a message
+- `history` — retrieve with composable filters (sender, since, after, topic)
+- `wait` — block until new matching messages arrive (polls history, times out honestly)
+- `clear` — delete all messages for the rig (destructive, rig-scoped)
+- `topic` — set a topic marker
+- `watch` — SSE or tmux-based live stream
+
+**Roundtable protocol:**
+1. Inspect old room: `rig chatroom history my-rig --limit 5`
+2. Save if needed: `rig chatroom history my-rig --json > /tmp/old-room.json`
+3. Clear if needed: `rig chatroom clear my-rig`
+4. Set topic: `rig chatroom topic my-rig "ROUND START"`
+5. Post: `rig chatroom send my-rig "position..." --sender <session>`
+6. Monitor: `rig chatroom wait my-rig --timeout 120`
+7. Close: `rig chatroom topic my-rig "ROUND CLOSED"`
+
+See `docs/planning/roadmaps/chatroom-roundtable-protocol.md` for the full protocol.
+
+### `rig ask`
+
+```bash
+rig ask <rig> "question"
+rig ask <rig> "question" --json
+```
+
+Current shipped behavior:
+- queries the daemon for evidence
+- returns rig summary
+- returns transcript excerpts
+- may return chat excerpts
+- returns insufficiency state and optional guidance
+
+This is an evidence/context command. It is not a hidden second-LLM call.
+
+## Lifecycle
+
+### Bring a rig up
+
+```bash
+rig up <source>
+rig up <source> --plan
+rig up <source> --yes
+rig up <source> --json
+```
+
+`<source>` can be:
+- a rig spec path
+- a `.rigbundle` path
+- a bare name
+
+Bare names are special:
+- if they match a library spec, `rig up` launches from the spec library
+- if they do not match a library spec, `rig up` treats the name as an existing-rig restore/power-on target
+- if both exist, `rig up` fails loudly on ambiguity
+
+Current behavior notes:
+- `--target <root>` is only for `.rigbundle` / package installation. It does not change agent cwd.
+- `local:` `agent_ref` values resolve relative to the rig spec directory, not your shell cwd.
+- if you copy a built-in spec elsewhere, keep its `agents/` tree beside the YAML or rewrite those refs to `path:/absolute/path`
+- there is no shipped `rig up --cwd` override yet
+
+Legacy/spec-specific surfaces still ship too:
+
+```bash
+rig bootstrap <spec> [--plan] [--yes] [--json]
+rig requirements <spec> [--json]
+```
+
+### Tear a rig down
+
+```bash
+rig down <rigId>
+rig down <rigId> --snapshot
+rig down <rigId> --delete
+rig down <rigId> --force
+rig down <rigId> --json
+```
+
+If `--snapshot` succeeds, human output includes the restore hint.
+
+### Release management without killing live claimed sessions
+
+```bash
+rig release <rigId>
+rig release <rigId> --delete
+rig release <rigId> --json
+```
+
+Use `rig release` for adopted/claimed-session rigs when you want OpenRig to stop managing the rig but leave the tmux sessions alive.
+This is the safe recovery/reset surface for the "sessions still exist, management is broken or stale" case.
+If the rig contains OpenRig-launched nodes, `rig release` refuses loudly instead of pretending the mixed rig is safe to detach.
+
+### Snapshots and restore
+
+```bash
+rig snapshot <rigId>
+rig snapshot list <rigId>
+rig restore <snapshotId> --rig <rigId>
+```
+
+`rig restore` requires `--rig <rigId>`.
+
+Claude Code autonomy note:
+- unattended `rig whoami` on boot may require the local permission allow list to include `Bash(rig:*)`
+
+### Import/export and bundles
+
+```bash
+rig export <rigId> -o rig.yaml
+rig import <path> [--instantiate] [--materialize-only] [--preflight] [--target-rig <rigId>] [--rig-root <root>]
+rig bundle create <spec> -o out.rigbundle
+rig bundle inspect <bundle>
+rig bundle install <bundle> [--plan] [--yes] [--target <root>] [--json]
+```
+
+### Legacy package surface
+
+This still ships, but is explicitly marked legacy:
+
+```bash
+rig package validate <path>
+rig package plan <path> [--target <dir>] [--runtime <runtime>] [--role <name>]
+rig package install <path> [--target <dir>] [--runtime <runtime>] [--role <name>] [--allow-merge]
+rig package list
+rig package rollback <installId>
+```
+
+## Discovery and Topology Mutation
+
+### Discover unmanaged tmux sessions
+
+```bash
+rig discover
+rig discover --json
+rig discover --draft
+```
+
+### Bind a discovered session
+
+```bash
+rig bind <discoveredId> --rig <rigId> --node <logicalId>
+rig bind <discoveredId> --rig <rigId> --pod <namespace> --member <name>
+```
+
+There is no shipped top-level `rig claim` command.
+The current adoption surface is `discover`, `bind`, `adopt`, and `unclaim`.
+
+### Self-attach the current shell or agent
+
+```bash
+rig attach --self --rig <rigId> --node <logicalId>
+rig attach --self --rig <rigId> --node <logicalId> --print-env
+rig attach --self --rig <rigId> --pod <namespace> --member <name> --runtime <runtime>
+```
+
+Use `rig attach --self` when the current agent should attach itself directly instead of going through `discover` + `bind`.
+
+Current proven behavior:
+- inside `tmux`: attaches as a normal tmux-backed node, preserving inbound `rig send` / `rig capture`
+- outside `tmux`: attaches as `external_cli`
+- `--print-env` prints the `OPENRIG_NODE_ID` and `OPENRIG_SESSION_NAME` exports for the current shell
+
+Recommended flow:
+
+```bash
+rig attach --self --rig <rigId> --node <logicalId> --print-env > /tmp/openrig-self-attach.env
+. /tmp/openrig-self-attach.env
+rig whoami --json
+```
+
+Notes:
+- for tmux-backed self-attach, `rig whoami --json` is the right verification
+- for raw/external self-attach, `rig ps --nodes --json` is currently the more reliable verification surface
+- if the current shell is outside tmux, pass `--display-name <name>` when you want a stable human session label recorded
+
+### Adopt a topology and bind live sessions
+
+```bash
+rig adopt <path> --bind <logicalId=tmuxSessionOrDiscoveryId>
+rig adopt <path> --bind <logicalId=...> --bind <logicalId=...> --json
+rig adopt <path> --bindings-file <bindings.yaml>
+rig adopt <path> --bind <logicalId=...> --target-rig <rigId> --rig-root <root>
+```
+
+Use `rig adopt` when the sessions already exist and you want OpenRig to start managing them.
+
+A bindings file is the durable map from authored logical IDs to live sessions. Shape:
+
+```yaml
+bindings:
+  dev1.impl2: dev1.impl2@rigged-buildout
+  dev1.qa: dev1.qa@rigged-buildout
+```
+
+Spec + bindings is the proven recovery pair for adopted rigs.
+Spec gives OpenRig the intended topology. Bindings tells OpenRig which discovered live session belongs in each logical node.
+
+### Proven adopted-rig recovery workflow
+
+This workflow is proven for the case where the external tmux sessions are still alive:
+
+```bash
+rig release <rigId> --delete
+rig discover --json
+rig adopt <spec.yaml> --bindings-file <bindings.yaml>
+```
+
+What this does:
+- removes OpenRig management without killing the sessions
+- re-discovers those same sessions as unmanaged
+- re-attaches them to the topology defined by the spec + bindings
+
+Important limits:
+- this is for `sessions still alive`
+- spec alone is not enough for adopted rigs; you also need bindings
+- this does not yet mean OpenRig can recreate dead external sessions from nothing
+
+### Add unmanaged pods into an existing rig
+
+This is the proven workflow when a rig is already managed, but a new pod was created outside OpenRig and you want to add it later:
+
+```bash
+rig adopt <pod-fragment.yaml> --bindings-file <pod.bindings.yaml> --target-rig <rigId>
+```
+
+Use this when:
+- the target rig already exists
+- the new sessions are live and visible in `rig discover --json`
+- you want additive topology growth, not a full rebuild
+
+What to prepare:
+- a pod fragment spec with only the new pod
+- a bindings file mapping the new logical IDs to the live session names
+
+Verification loop:
+
+```bash
+rig discover --json
+rig adopt <fragment.yaml> --bindings-file <bindings.yaml> --target-rig <rigId>
+rig ps --nodes --json
+rig export <rigId> -o rig.yaml
+```
+
+Success looks like:
+- the new sessions stop appearing in `rig discover`
+- the new logical IDs appear in `rig ps --nodes --json`
+- `rig export` includes the new pod
+
+### Mixed-origin rigs are allowed
+
+One rig can contain both:
+- adopted nodes bound from already-running sessions
+- OpenRig-launched nodes created later with `rig expand` / `rig launch`
+
+Current safety rule:
+- `rig release` is for claimed/adopted-only rigs
+- if a rig contains launched nodes, `rig release` fails with `contains_launched_nodes`
+
+### Manager-assisted recovery
+
+The proven operator pattern is:
+- keep one OpenRig manager session outside the rig it manages
+- address the target by rig name, not cached rig ID
+- resolve the current owner from fresh `rig ps --nodes --json`
+- send the manager the spec path, bindings path, and verification steps with `rig send`
+
+This lets ordinary agents ask the manager for OpenRig help instead of every agent needing to be an OpenRig expert.
+
+### Add/remove running topology parts
+
+```bash
+rig expand <rig-id> <pod-fragment-path> [--rig-root <path>] [--json]
+rig launch <rigId> <nodeRef> [--json]
+rig remove <rigId> <nodeRef> [--json]
+rig shrink <rigId> <podRef> [--json]
+rig unclaim <sessionRef> [--json]
+```
+
+## Specs and Validation
+
+### Validate specs
+
+```bash
+rig spec validate <path> [--json]
+rig spec preflight <path> [--rig-root <root>] [--json]
+rig agent validate <path> [--json]
+```
+
+### Spec library
+
+```bash
+rig specs ls [--kind <kind>] [--json]
+rig specs show <name-or-id> [--json]
+rig specs preview <name-or-id> [--json]
+rig specs add <path> [--json]
+rig specs sync [--json]
+rig specs remove <name-or-id> [--json]
+rig specs rename <name-or-id> <new-name> [--json]
+```
+
+## MCP
+
+```bash
+rig mcp serve [--port <port>]
+```
+
+Current shipped MCP tools:
+- `rig_up`
+- `rig_down`
+- `rig_ps`
+- `rig_status`
+- `rig_snapshot_create`
+- `rig_snapshot_list`
+- `rig_restore`
+- `rig_discover`
+- `rig_bind`
+- `rig_bundle_inspect`
+- `rig_agent_validate`
+- `rig_rig_validate`
+- `rig_rig_nodes`
+- `rig_send`
+- `rig_capture`
+- `rig_chatroom_send`
+- `rig_chatroom_watch`
+
+## JSON and Error Posture
+
+Design assumptions that hold in the shipped CLI:
+- many operator commands support `--json`
+- error messages are intended to say what happened, why it matters, and what to do next
+- daemon-backed commands fail loudly when the daemon is stopped or unhealthy
+- restore failure is not something you should silently reinterpret as success
+
+## After-Compaction Recovery Checklist
+
+1. `rig whoami --json`
+2. `rig transcript <your-session> --tail 100`
+3. `rig ps --nodes --json`
+4. `rig chatroom history <rig> --limit 50`
+
+## Commands That Do Not Exist
+
+Do not assume these exist unless the shipped help starts listing them:
+- `rig claim`
+- `rig env`
+- `rig blame`
+- `rig replay`

package/daemon/specs/agents/shared/skills/pods/development-team/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: development-team
+description: How the development pod coordinates implementation, QA, and design without skipping gates.
+---
+
+# Development Team
+
+You are part of the development pod. Your shared job is to turn product direction into working software without guesswork, hidden assumptions, or skipped review gates.
+
+## Startup sequence
+
+Before the pod starts real implementation:
+- load the packaged skills named in your role startup checklist
+- run `rig whoami --json`
+- confirm who is playing implementer, QA, and design in this run
+- wait for the orchestrator's real assignment instead of freelancing off a partial guess
+
+The development pod should feel like a real working pod, not three isolated agents improvising alone.
+
+## Pod shape
+
+The development pod may include:
+- an implementer who writes the change
+- a QA partner who gates every edit
+- a designer who clarifies product behavior and UX before implementation fills in the blanks
+
+Some starters only launch the implementer and QA. Others also launch a designer. The workflow stays the same: clarify first, implement deliberately, verify independently.
+
+## Shared loop
+
+This is the default loop for product work:
+
+```
+1. Clarify the work and the acceptance criteria
+2. Implementer sends a pre-edit proposal to QA
+3. QA approves or rejects with specifics
+4. Implementer changes code with TDD
+5. Implementer sends the diff and verification output back to QA
+6. QA approves or rejects with specifics
+7. If commit authority is enabled, the implementer may commit
+8. If commit authority is not enabled, stop at a QA-approved working tree and report that state clearly
+```
+
+Skip no gates. If the task is ambiguous, resolve the ambiguity before editing.
+
+## What the implementer must hand QA
+
+Pre-edit proposal should include:
+- the files expected to change
+- the behavior or acceptance criteria being targeted
+- the first failing test or verification step
+- any likely edge cases or invariants
+
+Post-edit review bundle should include:
+- what changed
+- the actual verification commands run
+- the result of those commands
+- any remaining uncertainty or follow-up risk
+
+QA should not have to reverse-engineer what the implementer thought they were doing.
+
+## Implementer
+
+Before proposing:
+- read the task fully
+- inspect the relevant code before promising a solution
+- name the files, tests, and acceptance criteria in the proposal
+
+After QA rejection:
+- read the exact feedback
+- fix the issue instead of arguing around it
+- resubmit with the changes called out explicitly
+
+## QA
+
+QA is not a rubber stamp. QA is a product voice — not just a test gate.
+
+When reviewing a proposal:
+- reject if the scope is wrong
+- check whether the planned tests actually prove the contract
+- flag hidden risks and missing failure cases
+
+When reviewing a diff:
+- read the actual code, not just the summary
+- verify independently when possible
+- if you cannot verify independently, require real output in the review bundle and inspect it critically
+
+If the implementer stalls on a permission or approval prompt, call that out immediately. Do not treat a blocked pane as finished implementation.
+
+### QA dogfood mode
+
+When QA is dogfooding (testing existing features rather than gating new code), QA works solo with full autonomy:
+- find issues AND fix them in a loop
+- test the fix, then move to the next issue
+- only escalate architecture-level concerns to the orchestrator
+- do not wait for approval to fix obvious bugs during dogfood
+- report findings to the chatroom so the rig has visibility
+
+### QA as a product voice
+
+QA sees the product from the user's perspective. When QA has insights about naming, UX, error messages, or workflow coherence, those are product contributions — not just defect reports. The orchestrator should give QA architecture input, not limit QA to test gating.
+
+## Designer
+
+When present, the designer should work ahead of implementation:
+- turn vague goals into concrete flows, states, copy, and interaction choices
+- surface edge cases before engineering has to guess
+- review built results for coherence, not just visual polish
+
+The designer is part of the development pod, not a decorative sidecar.
+
+## Browser testing and dogfood tools
+
+The development pod has access to browser automation and structured dogfood testing tools:
+
+- **`agent-browser`** — browser automation CLI. Navigate to the daemon UI, snapshot interactive elements, take annotated screenshots, record repro videos. Use `agent-browser open <url>`, `agent-browser snapshot -i`, `agent-browser screenshot --annotate`.
+- **`dogfood`** — structured exploratory testing workflow. Produces a report with screenshots, repro videos, and step-by-step evidence for every finding.
+- **`containerized-e2e`** — Docker-based clean-install testing. Simulates a fresh user environment.
+
+QA typically drives browser and dogfood testing, but both impl and QA should know these tools exist and can use them. When dogfooding UI:
+1. Load `/agent-browser` and `/dogfood`
+2. Open the daemon UI: `agent-browser open http://127.0.0.1:7433`
+3. Systematically explore surfaces, take screenshots as proof
+4. Report findings using the PASS/FAIL/GAP format to the chatroom
+
+## When the pod is blocked
+
+If the blocker is:
+- ambiguity: pull in design or ask the orchestrator for clarification
+- failing tests / unexpected behavior: use `systematic-debugging`
+- code changes: use `test-driven-development`
+- completion claims: use `verification-before-completion`
+
+Do not hand-wave around blockers. Name them and route them.
+
+## Communication
+
+- Pre-edit proposal: `rig send <qa-session> "PRE-EDIT: ..." --verify`
+- Review bundle: `rig send <qa-session> "REVIEW BUNDLE: ..." --verify`
+- Design clarification: `rig send <design-session> "Need product/design input on ..." --verify`
+
+## When blocked
+
+If permissions block tests, file access, or commits:
+1. identify the exact blocked command
+2. tell the human what that prevents
+3. continue with the work you can still do
+
+Do not silently stall. Do not pretend blocked verification is complete.