@openrig/cli 0.5.13 → 0.5.15

package/daemon/docs/reference/getting-started.md

@@ -5,6 +5,15 @@ Start with a repository and one bounded change you can exercise. The shipped
 an independent checker. It uses your installed Codex executable and login;
 terminal-provider support does not change the harness or account being used.
 
+**Choose permissions before starting the team.** The unchanged starter launches
+Codex with `-s workspace-write`; it leaves approval policy to your native Codex
+configuration. Network access is normally off in that sandbox, including access
+to the local OpenRig daemon. Its `profile: default` selects OpenRig resources,
+not a Codex permission profile. Ordinary permission prompts are therefore expected.
+You can keep those prompts, remember selected commands, or choose broader access.
+[Ask your agent to configure that choice](#have-your-agent-configure-permissions);
+OpenRig does not choose permissive operation for everyone.
+
 > Everything below reports **what is currently true**, never a guarantee that
 > downstream work will succeed. "Daemon up" does not mean every agent is healthy;
 > "kernel ready" does not mean every kernel agent is healthy; a workspace root
@@ -70,9 +79,20 @@ seat has an authentication, trust or permission prompt, resolve the named
 prompt before assigning it work. A model pin is configuration; the native
 harness must report the intended model before consequential work.
 
-The default Codex workspace sandbox may also ask before local `rig` calls.
-Approve only the intended operations in the selected instance. A waiting
-permission prompt is not task progress; inspect it before retrying delivery.
+When a seat pauses, open its existing terminal with **o** in the startup view.
+Read the proposed command, working directory and target instance. For an intended
+local `rig` call, choose the native prompt's one-time approval if that is the scope
+you want; a saved command-prefix allowance also affects future matching calls.
+Decline an unexpected operation and tell the same agent what to do instead.
+Approval controls whether an action may run; the sandbox controls its filesystem
+and network access. Turning approvals off does not grant network access.
+
+After answering, watch for the command's result and the agent continuing. Read
+the corresponding queue row and transition from your ordinary terminal. If an
+operation timed out, read its result before asking for another attempt: it may
+already have taken effect. A delivered message or disappearing prompt alone is
+not progress. If startup is still waiting for context delivery, use **c** for the
+same occupant, then **r** to refresh. Do not start another seat to clear a prompt.
 
 `first-project` is a deliberately small starting point, not a universal team.
 For a different installed runtime or team shape, inspect `rig specs ls --kind
@@ -94,10 +114,16 @@ independent check. You should not have to relay the review between terminals.
 `rig send` is the initial conversation; the queue and repository artifacts
 retain the work. An unbound shell does not need to impersonate a queue owner.
 
-Follow the work with `rig queue list --rig first-project --limit 1000`, then
-`rig queue show <id> --full` and `rig queue transitions <id>`. A delivered
-message is not a reviewed result. Read the final artifact, exercise the stated
-behavior, and check the candidate the review actually covered.
+From an actual `first-project` seat, follow the work with
+`rig queue list --limit 1000`: its default scope is the caller's current rig.
+`queue list` has no `--rig` option. From an observer shell or another rig, use
+`rig queue list --destination dev-owner@first-project --limit 1000` and the same
+command for `dev-check@first-project`, after verifying those live addresses.
+These show each destination's obligations, not a whole-rig view. An unbound shell
+must not pretend to be a seat to change scope; use `--all-rigs` only when that
+broader view is intended. Then read `rig queue show <id> --full` and
+`rig queue transitions <id>`. A delivered message is not a reviewed result.
+Read the artifact, exercise its behavior, and check the candidate reviewed.
 
 ## Share the dashboard and return to it
 
@@ -140,6 +166,18 @@ being built. When repeated coordination warrants a workflow, discover with
 selected name with `rig workflow instantiate --help`. A workflow is not needed
 merely to make the first local change.
 
+For a continuing team, [OpenRig Software Factory](../../packages/daemon/specs/agents/shared/skills/core/openrig-software-factory/SKILL.md)
+offers manual/team work, queue-supported orchestration without Workflow, and an
+optional explicit Workflow path, with wake defaults, token costs and permission
+choices visible. Give its short request to your existing agent. After
+installation, discover the compatible bundled recipe with `rig context show
+skills/core/openrig-software-factory --json`; retain a missing/version-mismatch
+result rather than silently using newer instructions. Its growth section keeps
+three choices clear: stay with the pair, add one or two seats to the running rig
+with `rig grow` and no YAML, or optionally author a custom rig. It covers
+new-seat context/work ownership, concurrency costs and saving the expanded spec.
+This guide remains the short first-use path.
+
 ## Incomplete setup and restart
 
 | Observation | Next action |
@@ -190,10 +228,169 @@ Two related primitives, often confused by new operators:
   an **entry qitem** that routes the first step to an owner. This is the live
   coordination of *who does the next step*.
 
-How they relate: a scope slice is the durable description of a unit of work; a
-workflow instance + its qitems are the live machinery that moves that work
-through owners (hot-potato handoffs). They are not auto-bridged - there is no
-auto-instantiate-from-scope - you instantiate a workflow by name when you want to
-run one, and you reference your scope artifacts as the work it coordinates. A
-typical loop: author/track the unit in `rig scope`, then
-`rig workflow instantiate <name>` to start the runtime that drives it.
+Scope files retain what the work is; workflow instances and their queue packets
+retain who acts next. Creating or editing a mission does not start work. You can
+instantiate a named workflow with `rig workflow instantiate <name>`, or explicitly
+inspect an authored lifecycle with `rig workflow compile` and create its runtime
+with `rig workflow instantiate-lifecycle`. Compilation alone does not start work.
+[OpenRig Software Factory](../../packages/daemon/specs/agents/shared/skills/core/openrig-software-factory/SKILL.md)
+shows a small reviewed example and how to retain custody through a genuine wait.
+
+## Have your agent configure permissions
+
+You choose the scope; the agent inspects the target harness and applies it.
+For example:
+
+> Configure persistent permission for OpenRig commands in this project. Explain
+> what the whole `rig` family allows and offer narrower verbs if appropriate.
+> Preserve existing deny/ask rules and unrelated settings, back up touched files,
+> apply my choice, then verify repeated ordinary reads without extra approvals.
+
+Allowing all `rig` commands includes lifecycle, topology and configuration
+operations, not only reads. Keeping prompts or selecting broader permissive
+operation are also valid choices. An existing explicit choice authorizes the
+routine setup; the agent need not ask you to approve each file edit again.
+
+Use the maintained **Applying a permission policy** procedure:
+
+```sh
+rig context get skills/applying-a-permission-policy/SKILL.md
+```
+
+In a source checkout, read [its source](../../packages/daemon/assets/plugins/openrig-core/skills/applying-a-permission-policy/SKILL.md).
+In an npm installation, the same file is under
+`@openrig/cli/daemon/assets/plugins/openrig-core/skills/applying-a-permission-policy/SKILL.md`
+below the matching `npm root -g` or local `npm root`. Use the version supplying
+your `rig` executable. It covers Codex/Claude command rules, actual config roots,
+preserving restrictions and verifying the target conversation. A missing guide or
+unsupported native version is a reported gap, not permission to silently bypass.
+
+The broader launch-mode recipes below are optional. Command-family rules do not
+require changing the starter's sandbox or everyone else's defaults.
+
+## Opt-in permissive operation
+
+Permissive operation lets agents act with your account's filesystem and network
+access with fewer permission stops. They can damage files or send data without
+another confirmation. Use it only for work and an environment you deliberately
+trust; it does not supply missing credentials or override organization policy.
+
+Make changes in a **user-owned spec before its first launch**. To customize the
+starter, run `rig specs show first-project --kind rig` and find its `Path`, ending
+in `specs/rigs/launch/first-project/rig.yaml`. Copy that whole `specs` directory to
+`./openrig-specs` in your repository, keeping its layout: copying only `rig.yaml`
+breaks its relative agent and culture references. Leave the installed copy alone.
+The examples below use `./openrig-specs/rigs/launch/first-project/rig.yaml`. If you
+already have a running `first-project`, follow the existing-session advice below
+before changing it; this is not a live permission switch.
+
+### Codex: select sandbox and approvals together
+
+For Codex versions supporting named `.config.toml` profiles, create
+`~/.codex/first-project-permissive.config.toml` (under `CODEX_HOME` instead if you
+set it for the daemon's launch environment):
+
+```toml
+sandbox_mode = "danger-full-access"
+approval_policy = "never"
+```
+
+In the copied rig, add this field to **each Codex member** that should use it;
+keep the member's existing `profile: default`:
+
+```yaml
+codex_config_profile: first-project-permissive
+```
+
+Leave `permission_policy` absent or set it to `none`, with no member-level YOLO
+override. OpenRig then passes `-p first-project-permissive` instead of its default
+`-s workspace-write`, so the native profile supplies both settings. Higher-priority
+native project configuration or managed requirements can still change/refuse the
+result. Inspect native `/status` before assigning work.
+
+```sh
+rig policy current --spec ./openrig-specs/rigs/launch/first-project/rig.yaml
+rig up ./openrig-specs/rigs/launch/first-project/rig.yaml --cwd . --plan
+rig up ./openrig-specs/rigs/launch/first-project/rig.yaml --cwd .
+```
+
+OpenRig's separate `permission_policy: builtin:yolo` setting passes only
+`-s danger-full-access` to Codex, **without an approval flag**, and replaces the
+named-profile argument. It does not mean `approval_policy = "never"`. A standalone
+`codex --yolo` command is not an OpenRig launch setting. Use the profile recipe
+above when you want to choose both controls explicitly.
+
+To return to a restricted next launch, change the selected profile to:
+
+```toml
+sandbox_mode = "workspace-write"
+approval_policy = "on-request"
+
+[sandbox_workspace_write]
+network_access = false
+```
+
+### Claude Code: a different launch flag
+
+The shipped `first-project` uses Codex. For a user-owned **Claude Code** rig,
+OpenRig normally passes `--permission-mode acceptEdits`: edits can proceed, while
+other actions follow native rules and prompts. It does not add a global
+`Bash(rig:*)` allowance. To explicitly select the bypass launch flag for that rig:
+
+```sh
+rig policy apply yolo --spec ./my-claude-rig/rig.yaml
+rig policy current --spec ./my-claude-rig/rig.yaml
+```
+
+This records `permission_policy: builtin:yolo`; the next managed launch passes
+`--dangerously-skip-permissions`. Member-level policies take precedence. To return
+future launches to OpenRig's `acceptEdits` mode, use `rig policy apply none --spec
+./my-claude-rig/rig.yaml` and remove any member-level bypass override. Native rules
+and managed restrictions still matter; this flag is not a promise about sandbox
+or account access. See [Claude permissions](https://code.claude.com/docs/en/permissions).
+
+**Already running:** changing a file or running `rig policy apply` does not revoke
+a live agent's permissions, nor rewrite a stored rig's policy on restore. Pause
+work and use the native permission controls for that conversation (current
+Codex and Claude CLIs expose `/permissions`); inspect the effective mode again.
+Keep the launch spec/profile consistent for subsequent launches. If the native
+version cannot apply the change in place, preserve the work and use the supported
+same-seat stop/resume path after checking its retained policy; do not erase the
+rig or start a duplicate to reset permissions. A resume can reapply the stored
+launch mode, so verify the native mode again before continuing work.
+
+## Custom settings and precedence
+
+- **OpenRig:** member `permission_policy` overrides rig `permission_policy`.
+  Normal managed launches bind the default mode explicitly when neither is set;
+  exporting `OPENRIG_YOLO=1` in a client shell is not a reliable per-team recipe.
+  A custom policy file is relative to the declaring rig spec, with no absolute
+  path or `..`. `surface: flag` selects a launch mode. Config-surface policies
+  (`locked`, `standard`, `open`, or custom) describe intent: recording one does
+  not translate and enforce its rules. Apply and inspect the actual native
+  settings separately. See [RigSpec policy references](rig-spec.md#attaching-a-permission-policy).
+- **Codex:** personal settings live in `~/.codex/config.toml` or `CODEX_HOME`;
+  trusted project settings live in `.codex/config.toml`. Current precedence is
+  CLI overrides, trusted project settings, selected profile, user settings,
+  cloud defaults when supplied, `/etc/codex/config.toml` on Unix, then built-in
+  defaults, subject to managed requirements. OpenRig's explicit sandbox flag
+  wins over a file's `sandbox_mode`; use `codex_config_profile` for a custom
+  sandbox instead. For workspace edits with network access while retaining
+  approvals, use a named profile with `sandbox_mode = "workspace-write"`,
+  `approval_policy = "on-request"` and `[sandbox_workspace_write]`
+  `network_access = true`. That grants network access generally, not just to
+  the local daemon. See [Codex configuration](https://learn.chatgpt.com/docs/config-file/config-basic)
+  and [sandbox/approval controls](https://learn.chatgpt.com/docs/agent-approvals-security).
+- **Claude Code:** use `~/.claude/settings.json`, shared project
+  `.claude/settings.json`, or personal project `.claude/settings.local.json`.
+  Managed settings precede launch flags, then project-local, project-shared and
+  user settings. Permission-rule lists combine; a higher-level allow is not a
+  way to defeat a deny. OpenRig's `acceptEdits` launch flag overrides a file's
+  `permissions.defaultMode`; selected runtime resources may also merge into
+  project-local settings. See [Claude settings and precedence](https://code.claude.com/docs/en/settings)
+  and [OpenRig's runtime config disclosure](agent-startup-guide.md#runtime-config-disclosure).
+
+These recipes do not establish every provider/version/config combination.
+Check the installed version and effective settings. Newer permission-profile or
+automatic review features are provider choices, not implicit OpenRig capabilities.
+Selecting rules or a broader mode does not change the shipped defaults.

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

@@ -199,6 +199,12 @@ referenced by a safe relative path (no `..`, no absolute). A shipped example of
 custom shape is `packages/daemon/policies/examples/my-cautious-dev.policy.md` — copy it
 into your project and edit it to taste.
 
+This records a selection, not a live permission change. Flag-surface policies
+select launch flags; config-surface policies still need native configuration
+application and inspection. In particular, `builtin:yolo` selects Codex's
+`danger-full-access` sandbox without forcing its approval policy, and replaces
+any `codex_config_profile` argument. See [practical permission choices](getting-started.md#opt-in-permissive-operation).
+
 ---
 
 ## Pod
@@ -229,6 +235,7 @@ into your project and edit it to taste.
 | `id` | string | yes | — | Member identifier. Must not contain dots. Must be unique within the pod. |
 | `agent_ref` | string | yes | — | Reference to an AgentSpec. Must start with `local:` (relative) or `path:` (absolute). Exception: `builtin:terminal` for infrastructure nodes. |
 | `profile` | string | yes | — | Profile name from the referenced AgentSpec. Use `default` for the default profile. Exception: `none` for terminal nodes. |
+| `codex_config_profile` | string | no | — | Codex-only native profile passed as `-p <name>`; letters, numbers, `_`, `.`, `-`. Separate from the AgentSpec `profile`. With the normal launch mode, this replaces OpenRig's explicit workspace-write sandbox flag. A full-bypass policy instead emits danger-full-access and omits this profile argument. |
 | `runtime` | string | yes | — | Agent runtime. Current supported values: `claude-code`, `codex`, `terminal`. |
 | `cwd` | string | yes | — | Working directory for the agent. Resolved relative to the rig root (the directory containing the rig spec). Use `"."` for the rig root itself. Can be overridden at launch time with `rig up --cwd`. |
 | `label` | string | no | — | Human-readable member name. Shown in UI when present. |

package/daemon/policies/builtin/yolo.policy.md

@@ -4,12 +4,16 @@ name: yolo
 surface: flag
 launch_posture: full_bypass
 policy_schema_version: 1
-description: Full-bypass posture — the flag-surface YOLO opt-in. Everything runs, nothing prompts. Guardrailed by skills and starter markdown, not by permission-blocking.
+description: Permissive launch opt-in. Claude skips permission prompts; Codex selects danger-full-access but retains native approval policy. Pi enables resource trust.
 ---
 
 # YOLO (built-in policy — flag surface)
 
-The maximum-permissive built-in. The seat runs the harness with its full-bypass launch flag: Claude `--dangerously-skip-permissions`, Codex full-bypass, Pi `--approve`. Nothing prompts; nothing is denied. Use only for fully-trusted autonomous work where any pause is unacceptable.
+This built-in selects Claude `--dangerously-skip-permissions`, Codex
+`-s danger-full-access`, or Pi `--approve` (resource trust). Codex receives no
+approval flag and no named-profile argument on this path: its native approval
+settings still apply. This is not a universal promise that nothing prompts or
+is denied. Use only for work and an environment you deliberately trust.
 
 **APPLICATION is deterministic, NOT skill-translated.** YOLO is a `surface: flag`
 policy: it resolves to a stable launch flag and is applied directly by the runtime
@@ -17,9 +21,15 @@ flag-surface opt-in. The `applying-a-permission-policy` skill does **NOT** trans
 this policy; it points at that setting. The flag surface is stable enough for
 deterministic code, so it does not pay the skill-indirection tax.
 
-**Config policies are MOOT when YOLO is on.** The full-bypass launch flag overrides any Claude prefix rules / Codex posture, so an attached config-surface policy (Locked/Standard/Open) has no effect while YOLO is active. Pick YOLO OR a config policy, not both.
+**Selection and native enforcement are separate.** A member policy overrides the
+rig policy. A resolved config-surface selection chooses OpenRig's normal launch
+mode and takes precedence over ambient YOLO. Native configuration and managed
+restrictions still matter; recording a policy does not translate config rules.
 
-**Guardrails come from skills + starter markdown, not permission-blocking** — a YOLO seat is bounded by what its skills and operating context tell it to do, since the permission layer imposes nothing.
+Skills and starter guidance describe intended behavior; they do not replace
+filesystem/network boundaries. For explicit Codex sandbox-plus-approval choices
+and returning to a restricted setting, see the getting-started permission guide
+at `docs/reference/getting-started.md#opt-in-permissive-operation`.
 
 **Naming:** YOLO names the full-bypass posture plainly; the picker presents all four
 named postures (Locked / Standard / Open / YOLO) uniformly.

package/daemon/specs/agents/shared/skills/core/messaging-the-human/SKILL.md

@@ -42,16 +42,44 @@ Check readiness: configured, enabled, active, ready, reason, and next action.
 `indeterminate` is not ready. Follow the reported next inspection; do not enable
 or reconfigure a connector merely to make the check pass.
 
-Write the decision, evidence, and continuation in a body file. The sole outbound
-human-message primitive is:
+Author for the person reading on a phone: a short subject in `--summary`, then
+one complete brief in `--body-file`. State why it matters, your recommendation
+and material tradeoff, the bounded action if approved, and the choice requested.
+For an update, state the user-visible outcome and “No action needed.” Aim for
+roughly 100–150 words; this is guidance, not a semantic validator. Keep technical
+continuation, exact candidate/revision and evidence on the owning agent row and
+in the durable artifact behind `--evidence-ref`. A local path is not a phone link
+and Markdown evidence files are not automatically attached.
+
+For example, a synthetic brief could say:
+
+> The repaired status view is ready. I recommend updating this instance; live
+> status will briefly pause. Sessions will be preserved. Approve this instance
+> update, or hold? Supporting test detail follows in this thread.
+
+This example grants no authority. Choose `--human-intent decision` for a request
+or `--human-intent update` for a quiet FYI. Omission retains legacy decision
+behavior; words such as “FYI” and tags do not change intent.
+
+The sole outbound human-message primitive is:
 
 ```bash
 rig queue create --destination <entityId>@external \
-  --summary "<decision or update>" --body-file <packet-file> \
+  --human-intent decision --summary "<short subject>" --body-file <brief-file> \
   --evidence-ref <durable-evidence> --verify --json
 ```
 
-If an existing agent-owned row must wait, block it on the **new live qitem ID**
+An optional `--human-detail-file <path>` supplies one coherent supplemental
+reply in the same thread. Announce its purpose in the brief; the product also
+marks that a detail reply follows. The primary must already contain the complete
+scope, options and action. Do not split an agent dump blindly or move the essential
+choice into overflow. Rendering checks every part and its accessibility fallback
+before posting; an oversized request is refused with a field-specific correction,
+never silently clipped. Shorten the brief or related detail as directed. Inspect
+the failed row, then deliberately cancel/replace the authored request if its
+content needs correction; a timeout alone is never a reason to replace it.
+
+If an existing agent-owned row must wait for a **decision**, block it on the **new live qitem ID**
 (`rig queue block <work-id> --on <human-qitem-id> ...`), not on the human address.
 Completion of the human qitem resumes its dependants. Blocking on the human as
 well would issue another notification for the same decision.
@@ -66,7 +94,14 @@ or blindly resend because verification timed out.
 rig queue transitions <qitem-id>
 ```
 
-A correlated reply binds to that exact human and qitem and records the resolution
+For `update`, confirmed complete delivery may close the delivery obligation.
+It creates no approval obligation and cannot be used as a decision blocker.
+Delivered updates remain queryable for Feed; a failure or ambiguous send stays
+separate. A root message alone does not prove supplemental delivery. Retries
+reconcile stable part identities and send only missing parts. An FYI reply is
+not a human decision.
+
+For a decision, a correlated reply binds to that exact human and qitem and records the resolution
 that resumes the owner. Check the recorded result before claiming the decision
 arrived; a delivery receipt alone is not acceptance.
 

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

@@ -71,6 +71,7 @@ These are auto-delivered to every rig; their name+description are already in you
 ### Load when your role or task calls for it (repo-shipped, profile-selected)
 These ship in the OpenRig repo and reach a seat when its profile selects them. To use one, select it in your profile's `uses.skills`, or open it directly at `packages/daemon/specs/agents/shared/skills/core/<skill>/SKILL.md`.
 
+- **openrig-software-factory** — a user wants continuing reviewed work: manual/team, queue-only orchestration or an explicit Workflow; add one or two seats to the running starter when useful, with context, ownership, concurrency, spend and permission limits. Load `rig context get skills/core/openrig-software-factory/SKILL.md`.
 - **openrig-architect** — authoring a rig or topology (NOT for changing OpenRig itself — that's `openrig-builder`).
 - **openrig-cmux** — driving the `cmux` terminal provider.
 - **openrig-herdr** — opening/managing seat terminals via the default proof-gated provider.

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

@@ -0,0 +1,138 @@
+---
+name: openrig-software-factory
+description: >-
+  Use when a user wants a continuing software team for a real repository, or has a
+  first OpenRig team and needs a repeatable path for reviewed work and later tasks.
+metadata:
+  cli_surfaces_referenced:
+    - context get
+    - context list
+    - context show
+    - grow
+    - queue create
+    - queue handoff
+    - workflow compile
+    - workflow instantiate-lifecycle
+  openrig:
+    stage: WIP
+    transfer_test: pending
+---
+
+# 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. |
+
+For the concrete queue loop, wake behavior and optional two-slice Workflow,
+read [references/worked-example.md](references/worked-example.md). Installed copy:
+`rig context get skills/core/openrig-software-factory/references/worked-example.md`.
+A roadmap, YAML file or wake does not execute work or authorize a new outcome.
+
+## Establish the working agreement
+
+Read the repository instructions, current work and desired user-visible result.
+Verify the intended instance, code/work roots, real seat addresses and native
+readiness. Reuse a suitable small team; an existing agent can bootstrap it.
+A kernel operator is optional and is not automatically the project owner.
+
+Agree the work boundary, time/spend limit, who answers unresolved choices, and
+when to stop: checked result, no authorized next work, exhausted budget, or a real
+user/permission/provider blocker. Background daemon checks are not themselves
+model turns, but delivered wakes and resumed work **can spend tokens**. Prefer
+an event-driven wait to frequent empty reminders. Wakes cannot answer a user
+question, clear a permission prompt or guarantee progress.
+
+**Choose permissions before launching or assigning work.** Offer ordinary prompts,
+persistent rules for selected commands, or deliberately broader access. Follow
+[Applying a permission policy](#find-the-compatible-permission-guide) to perform
+the user's choice and verify it in the target conversation. Preserve restrictions
+and unrelated settings. A whole `rig` allowance covers every verb, not just reads;
+it does not grant new product authority or change everyone else's defaults.
+
+Keep purpose, acceptance, decisions and evidence in existing project files.
+Deliver selected context and obtain each seat's scope reaction; retrieval alone
+is not peer delivery. The owner carries the candidate through the chosen check
+and bounded repairs, reports how to try it, and retains the next authorized task
+or explicitly reports none. Preserve work and custody before a supported stop.
+
+## Grow your factory
+
+Choose the team size separately from the coordination method above:
+
+1. **Use the two-agent starter.** Keep the existing owner and independent checker
+   while that pair meets the workload. The owner can implement and coordinate.
+2. **Add one or two seats to the running rig.** This is the usual next step.
+   Follow [Grow the running team](references/worked-example.md#grow-the-running-team)
+   for `rig grow` commands, readiness/context/work
+   assignment, and saving the expanded topology. Existing sessions need no
+   rebuild or down/up cycle solely to add capacity.
+3. **Author a custom rig when you want a different structure.** Read
+   [OpenRig Architect](../openrig-architect/SKILL.md), available through
+   `rig context get skills/core/openrig-architect/SKILL.md`. Request:
+   “Design a user-owned rig for [outcome] using the compatible RigSpec/AgentSpec
+   guidance. Reuse suitable agents, define responsibilities and context, and
+   validate the files. Preserve the existing rig and agree any new launch.”
+
+As independent work grows, the original owner can concentrate on orchestration,
+multiple builders can implement separate outcomes, and the checker can retain
+independent review capacity. Record that division explicitly; adding seats does
+not assign work, change permissions or create parallelism. Agree file/worktree
+boundaries and integration ownership, follow the project's existing review policy,
+and keep active concurrency within the user's time/spend budget. Two seats are
+an entry point, not a finished factory or a maximum.
+
+## Read compatible guidance
+
+Before installation, use this file and companion at the same published tag or
+commit as the selected package. After installation:
+
+```sh
+rig --version
+rig context list --json
+rig context show skills/core/openrig-software-factory --json
+rig context get skills/core/openrig-software-factory/SKILL.md
+```
+
+Compare build identity as well as version. Preserve missing, unreadable or older
+recipe results; do not silently substitute newer main or skip a missing companion.
+
+### Find the compatible permission guide
+
+Retrieve the maintained procedure with
+`rig context get skills/applying-a-permission-policy/SKILL.md`.
+For source or archive readers, locate it below; the companion getting-started
+guide contains optional broader launch-mode recipes under **Opt-in permissive
+operation**. These paths are relative to the named root, not this skill:
+
+| Reading from | Procedure and guide, at the same version as this recipe |
+| --- | --- |
+| Source checkout, including `skills/_canonical` | Below the repository root: `packages/daemon/assets/plugins/openrig-core/skills/applying-a-permission-policy/SKILL.md` and `docs/reference/getting-started.md`. |
+| npm installation | Below the matching `npm root -g` or local `npm root`: `@openrig/cli/daemon/assets/plugins/openrig-core/skills/applying-a-permission-policy/SKILL.md` and `@openrig/cli/daemon/docs/reference/getting-started.md`. |
+| Unpacked npm archive | Below the extraction directory: `package/daemon/assets/plugins/openrig-core/skills/applying-a-permission-policy/SKILL.md` and `package/daemon/docs/reference/getting-started.md`. |
+
+For installed guidance, use the npm installation that supplies the selected
+`rig` executable; another prefix or local project can contain a different version.
+If the matching guide or section is missing, report the gap before proceeding;
+do not substitute current main or guidance from another installation.
+
+## Request to give your agent
+
+> Help me achieve [observable change] in this repository. Read the compatible
+> Software Factory recipe, choose the lightest useful team/queue/Workflow path,
+> and keep the next owner visible. Preserve existing files and permissions.
+> Agree time/spend limits, perform the authorized work and chosen independent
+> check, and ask only about unresolved decisions or effects outside that scope.
+> Keep publication and destructive changes out of this task.
+
+When commands, defaults or permission semantics change, check this source and
+companion together and regenerate their existing projections. Website guidance
+should link to the same versioned recipe, not maintain another procedure.