@openrig/cli 0.1.9 → 0.1.10

package/daemon/docs/reference/rig-bundle.md

@@ -0,0 +1,367 @@
+# RigBundle Reference
+
+Version: 2 (pod-aware)
+Last validated against code: 2026-04-11
+Source of truth: `packages/daemon/src/domain/bundle-types.ts`, `packages/daemon/src/domain/bundle-archive.ts`, `packages/daemon/src/domain/pod-bundle-assembler.ts`
+
+A `.rigbundle` is a self-contained distributable archive that packages a rig spec, all referenced agent specs, their resources (skills, guidance, startup files), culture file, documentation, and an integrity manifest into a single file. The recipient can install and launch the rig without needing the original source tree.
+
+---
+
+## Archive Format
+
+A `.rigbundle` file is a gzip-compressed tar archive (`.tar.gz`) with a fixed structure.
+
+### File extension
+
+The archive MUST have the `.rigbundle` extension. The packer rejects output paths that don't end with `.rigbundle`.
+
+### Sibling digest file
+
+Every `.rigbundle` has a sibling `.rigbundle.sha256` file containing the SHA-256 hex digest of the archive. This detects corruption during transfer. The unpacker verifies this digest before extraction.
+
+Example:
+```
+my-rig.rigbundle          — the archive
+my-rig.rigbundle.sha256   — "a1b2c3d4..." (64-char hex SHA-256)
+```
+
+### Determinism
+
+The packer produces deterministic output:
+- Files are sorted alphabetically
+- A fixed mtime is used (`2026-01-01T00:00:00Z`)
+- Portable mode normalizes uid/gid/mode
+- Maximum gzip compression (level 9)
+
+This means the same inputs always produce the same archive hash.
+
+---
+
+## Archive Layout
+
+```
+bundle.yaml                    — manifest (required)
+rig.yaml                       — the RigSpec (required, may be rewritten)
+CULTURE.md                     — culture file (if declared in rig spec)
+SETUP.md                       — documentation (if declared in rig spec docs field)
+agents/
+  agent-name/
+    agent.yaml                 — AgentSpec
+    guidance/
+      role.md                  — guidance files
+    skills/
+      skill-name/
+        SKILL.md               — skill files
+    startup/
+      context.md               — startup files
+```
+
+### Key rules
+
+- `bundle.yaml` is the manifest — always present, always at the root
+- `rig.yaml` is the rig spec — rewritten during assembly with vendored `agent_ref` paths
+- Agent directories are vendored copies of the original agent specs with all their resources
+- Import refs are rewritten from the original `local:` or `path:` paths to bundle-relative `local:` paths
+- All file paths within the archive are safe relative paths (no `..`, no absolute, no symlinks)
+
+---
+
+## Manifest (`bundle.yaml`)
+
+The manifest is a YAML file at the archive root that describes the bundle contents.
+
+### Schema Version 2 (pod-aware, current)
+
+```yaml
+schema_version: 2
+name: my-bundle
+version: "0.1.0"
+created_at: "2026-04-11T22:32:48.570Z"
+rig_spec: rig.yaml
+agents:
+  - name: pm-lead
+    version: "1.0"
+    path: agents/pm-lead
+    original_ref: "local:agents/pm-lead"
+    hash: "ed4cff20..."
+    import_entries: []
+  - name: researcher
+    version: "1.0"
+    path: agents/researcher
+    original_ref: "local:agents/researcher"
+    hash: "11f8a077..."
+    import_entries:
+      - name: shared
+        version: "1.0"
+        path: agents/shared
+        original_ref: "local:../../shared"
+        hash: "abc123..."
+culture_file: CULTURE.md
+integrity:
+  algorithm: sha256
+  files:
+    rig.yaml: "b80c0674..."
+    CULTURE.md: "9354361b..."
+    agents/pm-lead/agent.yaml: "ed4cff20..."
+    # ... every file in the archive
+```
+
+### Manifest Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `schema_version` | number | yes | Must be `2` for pod-aware bundles. |
+| `name` | string | yes | Bundle name. |
+| `version` | string | yes | Bundle version. |
+| `created_at` | string | yes | ISO-8601 timestamp of creation. |
+| `rig_spec` | string | yes | Relative path to the rig spec within the archive. Safe relative path. |
+| `agents` | AgentEntry[] | yes | Array of vendored agent entries. |
+| `culture_file` | string | no | Relative path to the culture file if present. |
+| `integrity` | Integrity | no | Per-file SHA-256 checksums for content verification. |
+
+### Agent Entry Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | yes | Agent name (from agent.yaml). |
+| `version` | string | no | Agent version. |
+| `path` | string | yes | Relative path to the vendored agent directory. Safe relative path. |
+| `original_ref` | string | yes | The original `agent_ref` before rewriting. |
+| `hash` | string | yes | SHA-256 hash of the agent.yaml content. |
+| `import_entries` | ImportEntry[] | yes | Vendored imports for this agent (may be empty). |
+
+### Import Entry Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | yes | Imported agent name. |
+| `version` | string | yes | Imported agent version. |
+| `path` | string | yes | Relative path to the vendored import within the archive. |
+| `original_ref` | string | yes | The original import ref before rewriting. |
+| `hash` | string | yes | SHA-256 hash of the imported agent.yaml. |
+
+### Integrity Section
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `algorithm` | string | yes | Must be `sha256`. |
+| `files` | map<string, string> | yes | Map of archive-relative file path → SHA-256 hex hash. Every file in the archive (except `bundle.yaml` itself) should be listed. |
+
+---
+
+## Security Model
+
+Bundle integrity provides **self-consistency verification, not authenticity**.
+
+- The sibling `.sha256` file detects corruption during transfer
+- The per-file integrity hashes detect tampering of individual files within the archive
+- Neither mechanism authenticates the bundle author
+
+An attacker who can rewrite the full bundle + digest can bypass verification. Users must trust the source they obtained the bundle from. This is the same trust model as unsigned npm packages and Docker images.
+
+Future enhancement: cryptographic signing (Ed25519) for author authentication.
+
+---
+
+## Safety Guarantees
+
+The unpacker enforces these safety rules before extraction:
+
+1. **No symlinks or hardlinks** — `SymbolicLink` and `Link` entries are rejected
+2. **No absolute paths** — entries starting with `/` are rejected
+3. **No path traversal** — entries containing `..` segments are rejected
+4. **Digest verification** — archive SHA-256 must match the sibling `.sha256` file
+5. **Content integrity** — after extraction, per-file hashes are verified against the manifest
+
+If any check fails, extraction is aborted and an error is thrown.
+
+---
+
+## CLI Surface
+
+### Create a bundle
+
+```bash
+rig bundle create <spec-path> -o <output.rigbundle> [--rig-root <dir>] [--name <name>] [--bundle-version <ver>]
+```
+
+| Flag | Required | Default | Description |
+|------|----------|---------|-------------|
+| `<spec-path>` | yes | — | Path to the rig spec YAML file. |
+| `-o, --output` | yes | — | Output path. Must end with `.rigbundle`. |
+| `--rig-root` | no | spec directory | Root directory for resolving `agent_ref` and other relative paths. |
+| `--name` | no | `my-bundle` | Bundle name in the manifest. |
+| `--bundle-version` | no | `0.1.0` | Bundle version in the manifest. |
+
+The create command:
+1. Validates the rig spec
+2. Resolves all `agent_ref` paths and their imports
+3. Vendors all agent specs, resources, and startup files into a staging directory
+4. Rewrites `agent_ref` paths to bundle-relative `local:` refs
+5. Collects culture file, docs files, and rig-level startup files
+6. Computes per-file integrity hashes
+7. Writes the manifest (`bundle.yaml`)
+8. Packs into a deterministic `.tar.gz`
+9. Writes the sibling `.sha256` digest
+
+### Inspect a bundle
+
+```bash
+rig bundle inspect <bundle-path> [--json]
+```
+
+Shows the manifest, digest validity, and integrity verification result. Inspect extracts the archive into a temporary directory for safe validation, then cleans that directory up. It does not install the bundle.
+
+### Install a bundle
+
+```bash
+rig bundle install <bundle-path> [--plan] [--yes] [--target <root>] [--json]
+```
+
+| Flag | Required | Default | Description |
+|------|----------|---------|-------------|
+| `<bundle-path>` | yes | — | Path to the `.rigbundle` file. |
+| `--plan` | no | `false` | Preview the bootstrap plan without installing or launching. |
+| `--yes` | no | `false` | Auto-approve trusted actions during apply mode. |
+| `--target <root>` | yes in apply mode | — | Target root directory for package installation. Required unless `--plan` is used. |
+| `--json` | no | `false` | Emit machine-readable JSON. |
+
+Extracts the bundle, validates integrity, and bootstraps the rig. In apply mode, the daemon requires `targetRoot`, so `rig bundle install` must be given `--target <root>` unless you are running with `--plan`.
+
+### Launch directly
+
+```bash
+rig up <bundle-path> [--target <root>] [--cwd <dir>]
+```
+
+`rig up` auto-detects `.rigbundle` files and routes them through the bundle bootstrap path.
+
+- `--target <root>` controls where packaged files are installed
+- if `--target` is omitted for a `.rigbundle`, the CLI defaults the install target to the current working directory
+- `--cwd <dir>` does **not** change the install target; it only overrides the launched members' working directory for that run
+
+---
+
+## Assembly Process
+
+When `rig bundle create` runs, the `PodBundleAssembler` performs these steps:
+
+1. **Parse and validate** the rig spec
+2. **Collect rig-level files:**
+   - Culture file (if `culture_file` is set)
+   - Docs files (if `docs` array is set) — **required: missing docs fail assembly**
+   - Rig-level startup files
+   - Pod-level and member-level startup files
+3. **For each member's `agent_ref`:**
+   - Resolve the ref to an agent spec directory
+   - Copy the agent spec and all its resources (skills, guidance, hooks, startup, runtime resources)
+   - Recursively resolve and copy imports
+   - Record the agent entry in the manifest with its hash
+   - Rewrite the ref to a bundle-relative `local:` path
+4. **Write the rewritten rig spec** to the staging directory
+5. **Compute integrity** — SHA-256 of every file in the staging directory
+6. **Write the manifest** (`bundle.yaml`) with all entries and integrity
+7. **Pack** the staging directory into a deterministic tar.gz
+
+### Terminal nodes
+
+Members with `agent_ref: "builtin:terminal"` are bundle-native sentinels. They are not vendored — the runtime handles them directly.
+
+### Deduplication
+
+If multiple members reference the same agent spec (same resolved path), the spec is vendored once and all members' refs are rewritten to the same bundle-relative path.
+
+### Import resolution
+
+When an agent spec has `imports`, each import is resolved, vendored into the bundle, and the import refs in the vendored agent.yaml are rewritten to bundle-relative `local:` paths. Import entries are recorded in the manifest's agent entry.
+
+---
+
+## Validation Rules Summary
+
+### Manifest validation (schema version 2)
+
+1. `schema_version` must be `2`
+2. `name` is required non-empty string
+3. `version` is required non-empty string
+4. `created_at` is required non-empty string
+5. `rig_spec` is required and must be a safe relative path
+6. `agents` must be an array
+7. Each agent must have `name`, `path` (safe relative), and `hash`
+8. Integrity `algorithm` must be `sha256`
+9. Integrity `files` must be a non-empty map of safe-relative-path → 64-char hex hash
+
+### Archive safety (enforced on unpack)
+
+1. No symlinks or hardlinks
+2. No absolute paths
+3. No `..` path traversal
+4. Archive digest must match sibling `.sha256`
+5. Per-file content hashes must match integrity section
+
+### Assembly validation
+
+1. Rig spec must validate
+2. All `agent_ref` paths must resolve to valid agent specs
+3. All declared `docs` files must exist on disk (missing docs fail assembly)
+4. Culture file and startup files are collected best-effort (missing = skipped)
+
+---
+
+## Legacy Bundles (Schema Version 1)
+
+Schema version 1 bundles are the pre-reboot format using flat-node rig specs and package-based bundling. They are still supported for backward compatibility but should not be created for new rigs.
+
+Key differences from v2:
+- `schema_version: 1` in the manifest
+- `packages` array instead of `agents` array
+- Package entries have `original_source` instead of `original_ref`
+- No `import_entries` in package entries
+- Legacy rig spec format (flat nodes, not pods)
+
+---
+
+## Example: Creating and Using a Bundle
+
+### Create
+
+```bash
+# From the rig directory
+rig bundle create rig.yaml -o my-team.rigbundle --rig-root . --name my-team --bundle-version 1.0.0
+```
+
+Output:
+```
+Bundle created: my-team.rigbundle
+  Name: my-team v1.0.0
+  Hash: a1b2c3d4e5f6...
+```
+
+### Inspect
+
+```bash
+rig bundle inspect my-team.rigbundle
+```
+
+Output:
+```
+Bundle: my-team v1.0.0
+Digest valid: true
+Integrity: PASS
+```
+
+### Install and launch
+
+```bash
+cd ~/projects/my-project
+rig up /path/to/my-team.rigbundle
+```
+
+Equivalent explicit form:
+
+```bash
+rig up /path/to/my-team.rigbundle --target ~/projects/my-project
+```
+
+The bundle is extracted to a temporary directory, integrity is verified, packaged files are installed into the target root, and the rig is bootstrapped with all agents and resources from the bundle. If you also want agents to launch with a different working directory for that run, pass `--cwd <dir>` separately.

package/daemon/docs/reference/rig-spec.md

@@ -37,6 +37,10 @@ summary: A full product squad with orchestration, development, and review pods.
 
 culture_file: culture/CULTURE.md
 
+docs:
+  - path: SETUP.md
+  - path: README.md
+
 startup:
   files:
     - path: guidance/team-norms.md
@@ -170,6 +174,7 @@ edges:
 | `name` | string | yes | — | Rig name. Used in session naming (`{pod}-{member}@{name}`), snapshot identification, and spec library lookup. |
 | `summary` | string | no | — | Human-readable description. Shown in spec library, review surfaces, and `rig specs show`. |
 | `culture_file` | string | no | — | Relative path to a rig-wide culture/constitution file. Must be a safe relative path (no `..`, no absolute). |
+| `docs` | Doc[] | no | — | Documentation files that should travel with the rig. Included in rig bundles. Each entry has a `path` field (safe relative path). The engine does not consume these — they are for humans and agents setting up the environment before launch. |
 | `startup` | StartupBlock | no | — | Rig-level startup files and actions. Applied to all members via the startup layering model. |
 | `services` | ServicesBlock | no | — | Optional managed services (Docker Compose). When present, services boot before any agent launches. |
 | `pods` | Pod[] | yes | — | At least one pod required. Each pod is a bounded context containing members and pod-local edges. |

package/daemon/specs/agents/product-management/pm/agent.yaml

@@ -0,0 +1,37 @@
+name: pm
+version: "1.0"
+description: >
+  Product Manager agent — owns the "what" and "why" for features.
+  Runs the 8-step feature flow from idea capture through dev handoff.
+  Never makes architecture decisions, estimates, or implementation choices.
+
+defaults:
+  runtime: claude-code
+
+imports:
+  - ref: "local:../../shared"
+
+profiles:
+  default:
+    uses:
+      skills:
+        - openrig-user
+        - office-hours
+        - context-builder
+        - requirements-writer
+        - ui-mockup
+        - plan-review
+        - exec-summary
+        - backlog-capture
+
+resources:
+  guidance:
+    - id: role
+      path: guidance/role.md
+
+startup:
+  files:
+    - path: guidance/role.md
+      delivery_hint: send_text
+      required: true
+  actions: []

package/daemon/specs/agents/product-management/pm/guidance/role.md

@@ -0,0 +1,43 @@
+# Product Manager Agent
+
+## Role
+Senior Product Manager. Own the "what" and "why" — never architecture, estimates, or implementation details.
+
+## 8-Step Feature Flow
+
+1. **Capture** — run `backlog-capture` and record the idea in `idea_backlog.md`.
+2. **Validate** — run `office-hours` and produce `validation.md` with a `GO`, `REFINE`, or `PAUSE` verdict.
+3. **Context** — run `context-builder` and produce `background.md` using `validation.md` as the starting point.
+4. **Require** — run `requirements-writer` and produce `requirements.md` using `validation.md` and `background.md`.
+5. **Mockup** — run `ui-mockup` and produce `supporting/mockup-ascii.md` plus one or more `mockup-*.html` artifacts.
+6. **Review** — run `plan-review` and record issues or revisions before handoff.
+7. **Summarize** — run `exec-summary` and produce `executive-summary.md` from the full artifact set.
+8. **Handoff** — prepare the branch/ticket handoff only after the earlier artifacts are coherent.
+
+Each step's output feeds the next. `validation.md` is the foundation for the rest of the feature packet.
+
+## Working Norms
+
+1. **Research before you build** — every feature needs context (competitive, regulatory, customer) before requirements are finalized.
+2. **Requirements are literal** — AI agents treat requirements.md as instructions. Be precise. No aspirational content.
+3. **Stay in your lane** — PM writes requirements, researcher gathers context, coder builds prototypes. Escalate when you hit a boundary.
+4. **Write things down** — every step should leave artifacts in the feature folder. Nothing important lives only in conversation.
+
+## Feature Folder Structure
+
+```text
+{feature}/
+├── validation.md
+├── background.md
+├── requirements.md
+├── executive-summary.md
+└── supporting/
+    ├── mockup-ascii.md
+    └── mockup-*.html
+```
+
+## Key Outputs
+- validation.md — GO/REFINE/PAUSE verdict on feature ideas
+- background.md — synthesized context for a feature
+- requirements.md — structured acceptance criteria and business rules
+- executive-summary.md — single document orienting sales, leadership, and engineering

package/daemon/specs/agents/shared/agent.yaml

@@ -38,5 +38,20 @@ resources:
       path: skills/pods/review-team
     - id: rig-architect
       path: skills/rig-architect
+    # PM skills
+    - id: office-hours
+      path: skills/pm/office-hours
+    - id: context-builder
+      path: skills/pm/context-builder
+    - id: requirements-writer
+      path: skills/pm/requirements-writer
+    - id: ui-mockup
+      path: skills/pm/ui-mockup
+    - id: plan-review
+      path: skills/pm/plan-review
+    - id: exec-summary
+      path: skills/pm/exec-summary
+    - id: backlog-capture
+      path: skills/pm/backlog-capture
 
 profiles: {}

package/daemon/specs/agents/shared/skills/pm/backlog-capture/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: backlog-capture
+description: "Quickly capture product ideas, feature requests, or insights from meetings and conversations. Rapid documentation with smart categorization and deduplication."
+---
+
+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:
+   - **Bold name** — short, descriptive feature name
+   - **Description** — 1-3 sentences covering: what it is, who it's for, why it matters, where it originated (meeting, customer, competitor)
+   - **Epic/area** — which product area it belongs to
+   - **Dependencies** — if it relates to existing features or backlog items
+
+3. **Check for duplicates** — search the existing backlog for similar items. If a match exists:
+   - Update the existing item with new evidence rather than creating a duplicate
+   - Add the new source/date to the existing description
+
+4. **Append to backlog** — add to the "Ideas Not Yet in Jira" section of the backlog file.
+
+## Output Format
+
+```markdown
+- **[Feature Name]** — [Description. Who needs it. Why. Origin (meeting/customer/competitor, date).] Belongs under [Epic] epic. [Dependencies if any.]
+```
+
+## Guidelines
+
+- **Capture fast, refine later.** The goal is not to lose the idea. Polish comes during prioritization.
+- **Include the source.** "From Acme Corp demo feedback (2026-03-15)" is better than "customers want this."
+- **Convert relative dates to absolute.** "Next Thursday" becomes "2026-04-10."
+- **One idea per entry.** If a meeting produced 5 ideas, create 5 entries.
+- **Don't validate here.** That's what `/office-hours` is for. Just capture.

package/daemon/specs/agents/shared/skills/pm/context-builder/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: context-builder
+description: "Gather and distill context from meetings, competitors, regulatory sources, and internal discussions. Produces background.md for a feature and updates shared context docs when new knowledge is discovered."
+---
+
+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
+background.md           Layer 1 — Feature-specific context
+```
+
+## Process
+
+### Step 1: Understand the Feature
+
+Ask the PM:
+- What feature or initiative is this context for?
+- What aspects are most important? (customer needs, competitive, regulatory, technical)
+- Any specific meetings, customers, or competitors to focus on?
+
+### Step 2: Search and Gather
+
+Search across all layers. Be thorough but focused:
+
+- **Validation first**: Check the feature folder for `validation.md` (office hours output). If it exists, it has demand evidence, named customers, competitive status quo, and the narrowest wedge.
+- **Shared context first**: Check if synthesized context already exists.
+- **Meetings**: Search by topic keywords, customer names. Check last 3-6 months.
+- **Competitors**: Check competitor research for existing analysis.
+- **Regulatory**: Find applicable regulations.
+- **Customers**: Look for customer requests and pain points.
+- **Existing specs**: Check for related work and shipped features.
+
+### Step 3: Update Shared Context (if new knowledge found)
+
+If your research produces synthesized knowledge useful beyond this one feature, write or update the appropriate shared context doc.
+
+### Step 4: Write background.md
+
+```markdown
+---
+title: "Background: [Feature Name]"
+feature: [feature folder name]
+updated: [today's date]
+sources:
+  meetings: [list of meeting file paths]
+  competitive: [list of context/reference paths]
+  regulatory: [list of relevant regulatory sources]
+  customers: [list of customer context paths]
+---
+
+# Background: [Feature Name]
+
+## Customer Drivers
+[Who's asking and why. Key quotes and pain points.]
+
+## Competitive Landscape
+[How competitors handle this. Where we differentiate.]
+
+## Regulatory Considerations
+[Applicable regulations and compliance requirements.]
+
+## Persona Context
+[Which personas use this. Day-in-the-life context.]
+
+## Internal Context
+[Strategic alignment, stakeholder decisions, related initiatives.]
+```
+
+## Guidelines
+
+- **Reference, don't duplicate.** Point to source files rather than copying content.
+- **Distill, don't dump.** background.md should be under 500 lines.
+- **Include sources for everything.** Every claim traces back to a meeting, report, or decision.
+- **Highlight what's surprising or non-obvious.**
+- **Flag contradictions.** If customers want different things, or data conflicts, call it out.
+- **Date your sources.** Context decays.