@markjaquith/agency 2.29.0 → 2.30.1

package/README.md

@@ -43,9 +43,9 @@ frontmatter; prose below it supplies human and agent context.
 workbase/
   AGENTS.md                # managed workbase instructions
   .opencode/
-    opencode.jsonc         # managed task and epic references
-  agency.json
-  repos/
+    opencode.jsonc         # managed whole-workbase reference
+  agency.json              # tracked config and portable repository declarations
+  repos/                   # ignored local materializations
     frontend/              # bare Git repository or symlink
     backend/
   epics/
@@ -76,14 +76,35 @@ Agency keeps discovery and other observational commands read-only. Run
 files or refresh checksum-safe managed files. Customized files are reported but
 never overwritten.
 
-The OpenCode config advertises only the task and epic directories as documented
-references. OpenCode automatically grants those references scoped
-external-directory access, so Agency does not add blanket permission rules that
-could hide missing tool permissions. References provide context and never expand
-the write authority reported by `agency context`.
+The OpenCode config advertises the complete workbase as one portable relative
+reference. `agency work` sets `OPENCODE_CONFIG` to the managed file and injects
+runtime-only absolute rules that allow external access across the workbase while
+denying edits outside the execution unit's writable checkout. This makes the
+config effective from nested task and phase Git checkouts without persisting a
+machine-specific path or granting access outside the workbase. Bash and Agency
+operations must still follow the write authority reported by `agency context`.
 
-Repository metadata comes directly from Git under `repos/{alias}`. Workbase
-configuration may provide a custom writable-worktree creation command.
+Repository aliases and canonical fetch remotes are declared in tracked
+`agency.json`; local bare clones and symlinks remain ignored under
+`repos/{alias}`. A declaration contains no local path, symlink target, checkout,
+or credential:
+
+```json
+{
+	"version": 2,
+	"repositories": {
+		"frontend": {
+			"remote": "git@example.com:team/frontend.git"
+		}
+	}
+}
+```
+
+Existing version 2 workbases without `repositories` remain valid. Run
+`agency repo setup` to preview deterministic adoption of legacy local aliases;
+`agency repo setup --apply` writes declarations only when a portable origin is
+unambiguous. Workbase configuration may also provide a custom writable-worktree
+creation command.
 
 ### Custom Worktree Command
 
@@ -182,6 +203,10 @@ Every runner receives the same `AGENCY_RUNNER`, `AGENCY_CLAIMANT`,
 `AGENCY_SESSION_ID`, `AGENCY_CLAIM_REVISION`, `AGENCY_WORKBASE`, `AGENCY_TARGET`,
 `AGENCY_TASK_ID`, `AGENCY_PHASE_ID`, and `AGENCY_PROMPT` environment. Configured
 environment is added without overriding these normalized values.
+The `opencode` runner additionally receives `OPENCODE_CONFIG` for the workbase's
+managed integration and `OPENCODE_CONFIG_CONTENT` with runtime-only,
+workbase-scoped access and edit rules. These values keep the Git-synced config
+portable while providing whole-workbase read access at every launch location.
 `--print-command` prints the exact cwd and argv plus non-secret environment keys
 without launching the runner.
 
@@ -298,6 +323,15 @@ agency work tasks/refresh-copy
 agency pr create refresh-copy
 ```
 
+After cloning an existing workbase on another machine, restore its declared
+repositories before preparing work:
+
+```bash
+agency repo setup --dry-run
+agency repo setup --apply
+agency validate
+```
+
 ## Commands
 
 ### Target Context
@@ -361,22 +395,27 @@ materializing or pushing. Blocked, done, and dropped targets are rejected unless
 
 ### Reconciliation
 
-`agency sync` compares every execution declaration with local branch and worktree
-registration, writable and reference checkout dirtiness, resolved reference
-commits, claim expiry, and GitHub pull request and merge state. It reports
+`agency sync` first compares portable repository declarations with local
+materializations, then compares every execution declaration with local branch
+and worktree registration, checkout dirtiness, resolved reference commits, claim
+expiry, and pull request and merge state. It reports
 structured `changes`, `warnings`, `unresolved`, and per-execution evidence. The
 default and `--dry-run` modes are observational.
 
 `agency sync --apply` performs only these safe transitions:
 
+- materialize declared but missing repositories from their canonical remotes;
+- adopt legacy materializations only when they have an unambiguous portable origin;
 - materialize missing checkouts when no registration, branch, or path conflicts;
 - release an active claim only after its declared expiry has passed;
 - record a single PR whose head and base match the declaration; and
 - mark work done after its authoritative PR is merged and no active claim remains.
 
-Apply never modifies dirty checkouts, moves worktrees, switches branches, resets
-reference commits, chooses among multiple PRs, or bypasses active claims. Those
-conditions remain visible in `warnings` or `unresolved` with a suggested action.
+Apply never overwrites linked or invalid repositories, repairs remote drift,
+modifies dirty checkouts, moves worktrees, switches branches, resets reference
+commits, chooses among conflicting remotes or PRs, or bypasses active claims.
+Those conditions remain visible in `warnings` or `unresolved` with a suggested
+action.
 
 ### Workbase and Repositories
 
@@ -393,6 +432,7 @@ agency workbase prune [--json]
 agency workbase default [<id|name|path> | --clear] [--json]
 agency integration status [--json]
 agency integration sync [--json]
+agency repo setup [--dry-run | --apply] [--json]
 agency repo add <alias> <remote> [--json]
 agency repo link <alias> <path> [--json]
 agency repo list [--json]
@@ -405,6 +445,22 @@ agency repo remote <alias> [remote] [--json]
 agency repo verify <alias> [--json]
 ```
 
+Repository JSON output exposes state facets rather than hiding partial setup:
+`declared`, `materialized`, `linked`, `missing`, `invalid`, and
+`remote-drifted`. A normal bare clone is declared and materialized; a local
+checkout is declared and linked; a fresh workbase clone is declared and missing
+until setup is applied.
+
+`repo add`, `link`, `remote`, `rename`, and `remove` update the portable
+declaration transactionally with local state. `repo remove` removes both the
+declaration and an unused local materialization. `repo unlink` removes only this
+machine's symlink and retains the declaration, leaving an actionable missing
+state. Linking a local checkout over an unused managed clone likewise retains the
+portable remote for other machines. `repo remote` updates managed clones but
+never mutates an external linked checkout; drift remains visible until that
+checkout is updated explicitly. Credential-bearing URLs, file URLs, and local
+paths are never accepted as declarations.
+
 Registered workbases are stored in
 `$XDG_CONFIG_HOME/agency/workbases.json` (or `~/.config/agency/workbases.json`).
 Each registration has a stable ID and may have a unique name. A default workbase

package/cli.ts

@@ -414,6 +414,8 @@ const commands: Record<string, Command> = {
 					silent: options.silent,
 					verbose: options.verbose,
 					json: options.json,
+					dryRun: options["dry-run"],
+					apply: options.apply,
 					cwd: options.cwd,
 				}),
 			)
@@ -514,6 +516,7 @@ const commands: Record<string, Command> = {
 					json: options.json,
 					silent: options.silent,
 					verbose: options.verbose,
+					cwd: options.cwd,
 				}),
 			)
 		},

package/fixtures/protocol/skill-setup-commands.json

@@ -0,0 +1,18 @@
+[
+  ["init", "/work/agency", "--json"],
+  ["workbase", "init", "/work/agency", "--json"],
+  ["repo", "add", "agency", "git@example.com:owner/agency.git", "--json"],
+  ["repo", "setup", "--dry-run", "--json"],
+  ["repo", "setup", "--apply", "--json"],
+  ["repo", "link", "agency", "/work/agency-repository", "--json"],
+  [
+    "--workbase",
+    "/work/agency",
+    "repo",
+    "link",
+    "agency",
+    "/work/agency-repository"
+  ],
+  ["validate", "/work/agency"],
+  ["--workbase", "/work/agency", "repo", "verify", "agency"]
+]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "2.29.0",
+  "version": "2.30.1",
   "description": "Manage agentic work across repositories with durable workbases",
   "keywords": [
     "agents",

package/skills/agency/SKILL.md

@@ -5,14 +5,15 @@ description: >
   and pull requests. Use when inspecting or changing Agency-managed work,
   coordinating dependencies, launching agents, or finishing an execution unit.
 license: MIT
-compatibility: Requires the agency CLI and Git. Agent launch requires a configured runner; GitHub pull requests require gh.
+compatibility: Requires the agency CLI and Git. Agent launch requires OpenCode, Claude, or a configured runner; default GitHub delivery requires gh.
 ---
 
 # Agency
 
-Agency keeps plans and lifecycle state in durable Markdown documents. Git
-checkouts under `code/` are materialized local state. Treat the documents as the
-source of truth and Agency commands as the safe way to mutate their structure.
+Agency keeps plans and lifecycle state in durable Markdown documents and keeps
+portable repository aliases in `agency.json`. Bare repositories under `repos/`
+and Git checkouts under `code/` are ignored local materializations. Treat tracked
+workbase state as authoritative and Agency commands as the safe mutation path.
 
 ## Start With Context
 
@@ -27,8 +28,9 @@ readiness, write authority, checkout state, PR state, and validation warnings.
 Use its paths and IDs instead of inferring them from the process cwd.
 
 At the workbase root, context cannot infer one entity from `.`. Use
-`agency next --json` or `agency graph --json` to choose a target, then pass that
-target to `agency context <target> --json`.
+`agency next --json` or `agency graph --json` to choose a target, then inspect it
+with explicit `--epic`, `--task`, and `--phase` selectors or its returned document
+path. Do not pass a graph node key as a positional context target.
 
 For broader orchestration, load the graph and discover available capabilities:
 
@@ -46,14 +48,17 @@ output or editing documents.
 ## Mental Model
 
 - A **workbase** contains durable epics, tasks, phases, and repository aliases.
+- A repository declaration stores an alias and credential-free canonical fetch
+  remote; local bare clones and linked checkouts are replaceable machine state.
 - An **epic** coordinates tasks. It may inspect repositories but never writes code.
 - A **task** is one durable outcome. It is either an execution unit itself or a
   container for phases.
 - A **phase** is one execution unit within a multi-phase task, normally one PR.
 - An **execution unit** has exactly one writable `repo`, optional read-only
   `repos`, one branch, one base, and one recorded PR value.
-- `open` is available, `working` is actively owned, and `done` or `dropped` is
-  terminal. Only `done` satisfies a dependency.
+- `open` is eligible for readiness evaluation, `working` is actively owned, and
+  `done` or `dropped` is terminal. An open unit may still be blocked; only `done`
+  satisfies a dependency.
 
 The `authority` returned by context is decisive. Write only through
 `authority.writable.checkoutPath`. Every entry in `authority.references` is
@@ -65,6 +70,7 @@ Require explicit user intent before:
 
 - initializing a workbase;
 - adding, linking, renaming, or removing a repository alias;
+- applying repository setup or sync changes;
 - launching another agent with `agency work` from an active agent session;
 - creating a pull request;
 - archiving, restoring, dropping, or reopening work; or
@@ -79,13 +85,14 @@ independently meaningful tasks need coordination.
 - Keep task-wide decisions in `TASK.md` and phase delivery details in `PHASE.md`.
 - Never write through plural `repos` references.
 - Never edit bare repositories or repository symlinks under `repos/`.
+- Never persist local paths, symlink targets, worktrees, or credentials as
+  repository remotes.
 - Never manually create, move, or remove generated `code/` worktrees.
 - Never invent IDs, revisions, PR URLs, dependency completion, or checkout state.
 - Preserve parent backlinks and dependency declarations; use Agency mutations
   instead of hand-editing structural frontmatter.
 - Run `agency validate` before worktree or PR operations and after structural edits.
-- Do not bypass dirty-worktree, active-claim, revision, readiness, or failed-check
-  protections.
+- Do not bypass dirty-worktree, active-claim, revision, or readiness protections.
 
 ## Operating Protocol
 
@@ -94,8 +101,9 @@ independently meaningful tasks need coordination.
 1. Run `agency context . --json`.
 2. Confirm `target`, `graph.readiness`, `authority`, `workspace`, and `validation`.
 3. Read the returned task and phase document paths for prose requirements.
-4. Stop on validation errors, blockers, an unexpected writable repository, or a
-   conflicting active owner.
+4. Stop on validation errors, dependency blockers, an unexpected writable
+   repository, or a conflicting active owner. For an active agent, a `working`
+   status blocker is expected only when the current session owns the claim.
 
 ### Work
 
@@ -119,9 +127,16 @@ independently meaningful tasks need coordination.
 
 ## Human Launch vs Active Agent
 
-`agency work` is a human/orchestrator launch flow. It selects work, checks
-readiness, materializes managed checkouts, claims the execution unit, marks it
-working, and starts the configured runner.
+`agency work` is a human/orchestrator launch flow. It first reconciles managed
+integration files, then selects work and checks readiness. For an execution unit,
+it materializes managed checkouts, claims the unit, marks it working, and starts
+the selected built-in or configured runner. Epic and multi-phase task launches
+start in orchestration context without materializing or claiming execution work.
+OpenCode launches expose the managed config file and inject runtime-only access
+rules scoped to the workbase. These grant visibility from orchestration
+directories and nested execution checkouts while denying direct edits outside
+the writable checkout. They do not make the Git-synced config machine-specific
+or replace write authority from `agency context`.
 
 An agent already running in an Agency checkout must not call `agency work` to
 start itself again. It should inspect context, perform the assigned work, and

package/skills/agency/references/commands.md

@@ -1,7 +1,8 @@
 # Agency Command Reference
 
-Use this reference after `agency context . --json` identifies the target. Run
-`agency <command> --help` for the exact options supported by the installed CLI.
+Use this reference after `agency context . --json` identifies the target. The
+forms below are exact for this Agency release. Run `agency <command> --help` when
+using an option not shown here or when the installed CLI version differs.
 Commands that return Agency-owned data accept `--json` unless noted otherwise.
 
 ## Discovery And Health
@@ -25,10 +26,13 @@ checkout descendants, or a task ID. Complete output includes prose and Git
 details; `--compact` intentionally omits them. `graph` computes readiness before
 applying filters. `doctor` discovers required tools, integrations, repositories,
 refs, worktrees, permissions, drift, and optional runner capabilities. `sync` is
-observational unless `--apply` is explicit.
+observational unless `--apply` is explicit. Integration status includes safe
+remediation when customized OpenCode config prevents Agency from guaranteeing
+whole-workbase access.
 
-`next` currently resolves only the process cwd. Although global `--cwd` and
-`--workbase` are accepted by the parser, run `next` from the intended workbase.
+Where `[filters]` appears, use repeatable `--status <status>` and `--repository
+<alias>`, plus `--ready` or `--blocked` and `--pr` or `--no-pr`. Each pair is
+mutually exclusive.
 
 ## Workbase And Repositories
 
@@ -42,6 +46,7 @@ agency workbase name <id|name|path> (<name> | --clear) [--json]
 agency workbase default [<id|name|path> | --clear] [--json]
 agency workbase remove <id|name|path> [--json]
 agency workbase prune [--json]
+agency repo setup [--dry-run | --apply] [--json]
 agency repo add <alias> <remote> [--json]
 agency repo link <alias> <path> [--json]
 agency repo list [--json]
@@ -54,9 +59,15 @@ agency repo remove <alias> [--json]
 agency repo unlink <alias> [--json]
 ```
 
-`repo add` creates a bare clone; `repo link` creates a symlink to an existing
-repository. Removal, unlink, and rename refuse active references or linked
-worktree conflicts.
+`repo setup` defaults to an observational dry-run. Apply clones declared missing
+repositories and adopts legacy materializations only when their portable origin
+is unambiguous. Invalid paths and remote drift remain unresolved.
+
+`repo add` creates a declaration and bare clone. `repo link` creates a local
+symlink while retaining or inferring a credential-free portable remote.
+`repo remove` removes both the declaration and unused local materialization;
+`repo unlink` removes only this machine's symlink and retains the declaration.
+Removal and rename refuse active references or linked worktree conflicts.
 
 ## Epics, Tasks, And Phases
 
@@ -131,7 +142,8 @@ worktrees when needed, preserve branches, and retain lifecycle provenance.
 ## Worktrees, Launch, And Pull Requests
 
 ```text
-agency work [<directory> | --epic <id>] [--runner <name>] [--print-command]
+agency work [<directory-or-task-id> | --epic <id> | --task <id> [--phase <id>]]
+  [--runner <name> | --opencode | --claude] [--print-command] [--force]
 agency work prepare [target] [--dry-run] [--json]
 agency worktree list [--json]
 agency worktree inspect <task-id> [phase-id] [--json]
@@ -142,17 +154,26 @@ agency worktree repair <task-id> [phase-id] [--dry-run] [--json]
 agency pr create <task-id> [phase-id] [--draft] [--force] [--json]
 ```
 
-`work` is a launch flow, not an active-agent step. `work prepare` materializes
-without launching or changing status. Destructive remove and rebuild operations
-refuse dirty or conflicting state. Conservative repair may correct registration
-while preserving dirty files, but never discards changes. `pr create` requires a
-clean writable checkout, pushes the declared branch, invokes the configured
-delivery provider or falls back to `gh pr create --fill`, and records the
-returned URL.
+`work` is a launch flow, not an active-agent step. It synchronizes managed
+integration files before launch. Execution targets are materialized and claimed;
+epics and multi-phase tasks launch in orchestration context without those steps.
+The OpenCode runner receives a runtime managed-config path plus absolute access
+and edit rules scoped to the workbase; none are persisted, and `context` still
+defines write authority.
+`--print-command` suppresses only the final launch, so execution targets are still
+materialized and claimed before the command is printed. `work prepare`
+materializes without launching or changing status. Destructive remove and
+rebuild operations refuse dirty or conflicting state. Conservative repair may
+correct registration while preserving dirty files, but never discards changes.
+`pr create` materializes a missing workspace, requires the resulting writable
+checkout to be clean, pushes the declared branch, invokes the configured delivery
+provider or falls back to `gh pr create --fill`, and records the returned pull
+request record.
 
 ## Noninteractive Selection
 
-Use global `--workbase <id|name|path>` outside a workbase, or `--cwd <path>` to
+Use global `--workbase <id|name|path>` outside a workbase. A path may identify a
+registered workbase or an existing workbase directly. Use `--cwd <path>` to
 perform cwd inference elsewhere. Targeted commands accept `--epic`, `--task`,
 and, with a task, `--phase`. `--json`, `--no-input`, or non-TTY execution disables
 prompts; provide all selectors and required inputs explicitly.

package/skills/agency/references/contracts.md

@@ -17,12 +17,36 @@ contains:
   and read-only references;
 - `workspace`: code path, materialization and registration state, commits, and
   inspection warnings;
-- `pr`: recorded URL and state; and
+- `pr`: recorded provider-neutral pull request identity and state; and
 - `validation`: validity and issues.
 
 Compact context retains identity, revisions, authority, paths, graph state,
 materialization, and warnings while omitting prose and low-level Git details.
 
+## Repository Declarations
+
+Tracked `agency.json` may contain portable repository declarations:
+
+```json
+{
+	"version": 2,
+	"repositories": {
+		"frontend": { "remote": "git@example.com:team/frontend.git" }
+	}
+}
+```
+
+Remotes are provider-neutral network Git remotes. Local paths, file URLs, and
+credential-bearing HTTP URLs are invalid. `repos/`, task and phase `code/`, and
+symlink targets are local-only and never part of this contract.
+
+Repository inspection returns `declaredRemote`, the actual local `remote`, and
+orthogonal `states`: `declared`, `materialized`, `linked`, `missing`, `invalid`,
+and `remote-drifted`. Setup JSON contains `mode`, `actions`, `unresolved`, and the
+post-operation `repositories`. Actions are `materialize` or `adopt`, with
+`planned` or `applied` status. Dry-run never mutates. Apply never overwrites a
+link or path and never repairs drift without an explicit remote choice.
+
 ## Frontmatter Shapes
 
 ### Epic
@@ -98,9 +122,11 @@ status: open
 ```
 
 `ticketUrl` belongs to tasks and epics, not phases. `description` is optional but
-must be non-empty when present. `pr` is a GitHub PR URL or `null`. Status is
-`open`, `working`, `delegated`, `done`, or `dropped`; `delegated` is readable
-legacy state but cannot be newly assigned.
+must be non-empty when present. `pr` is `null`, a legacy GitHub PR URL, or a
+provider-neutral record containing `provider`, `repository`, `identifier`, `url`,
+`state`, `draft`, and `merged`. New PR creation writes the structured record.
+Status is `open`, `working`, `delegated`, `done`, or `dropped`; `delegated` is
+readable legacy state but cannot be newly assigned.
 
 ## Structural Invariants
 
@@ -167,7 +193,7 @@ CLI subprocess output. The Effect schemas are exported by the package and by
 
 Only the envelope and graph result have published JSON Schemas. The envelope's
 `result` is intentionally unconstrained. Context, next, claim, prepare, sync,
-and PR result shapes are exercised by CLI tests but do not have independent
+repository setup, and PR result shapes are exercised by CLI tests but do not have independent
 published schemas.
 
 ### Output And Exit Guarantees
@@ -244,18 +270,18 @@ mutations recheck every affected file while holding the graph mutation lock.
 
 ## Selectors And Projections
 
-`--workbase <id|name|path>` selects a registered workbase. `--cwd <path>` asks
-Agency to perform target inference as if invoked there. They are mutually
-exclusive. Targeted commands accept `--epic`, `--task`, and `--phase` where
-applicable; phase requires task, and entity selectors cannot be combined with a
-positional target ID. Non-target positional values, such as a status outcome,
-remain valid where the command syntax requires them.
+`--workbase <id|name|path>` selects a registered workbase by ID, name, or path;
+an existing path may also resolve an unregistered workbase directly. `--cwd
+<path>` asks Agency to perform target inference as if invoked there. They are
+mutually exclusive. Targeted commands accept `--epic`, `--task`, and `--phase`
+where applicable; phase requires task, and entity selectors cannot be combined
+with a positional target ID. Non-target positional values, such as a status
+outcome, remain valid where the command syntax requires them.
 
 `--json`, `--no-input`, and non-TTY execution disable interactive prompts and
-selection. Supply every required value or explicit entity selector. The current
-`next` implementation uses the process cwd even when global `--cwd` or
-`--workbase` parses successfully; run `next --json` from the intended workbase
-until that routing gap is fixed.
+selection. Supply every required value or explicit entity selector. Global
+`--cwd` and `--workbase` selectors apply to `next` as they do to other discovery
+commands.
 
 Context defaults to the `complete` projection. `--compact` omits prose and
 low-level Git details but retains identity, document hashes, authority, paths,
@@ -273,10 +299,11 @@ node set.
   and `claim` does not enforce dependency readiness. Inspect readiness, then
   claim with the observed revision and handle conflicts.
 - There is no `assign` command, remote queue, scheduler, heartbeat, claim renewal,
-  runner monitor, or cancellation API. `work` can claim and launch one local
-  configured runner, but it is a process-launching, non-JSON flow rather than a
-  machine assignment API. External orchestrators claim with claimant and runner
-  IDs, then manage their runner themselves.
+  runner monitor, or cancellation API. For an execution unit, `work` can claim
+  and launch one local built-in or configured runner, but it is a
+  process-launching, non-JSON flow rather than a machine assignment API. External
+  orchestrators claim with claimant and runner IDs, then manage their runner
+  themselves.
 - Agency does not edit code, create commits, run repository checks, wait for PR
   checks, merge PRs, or verify that a requested completion condition is true.
   `finish` records the caller's asserted outcome after ownership checks.

package/skills/agency/references/recipes.md

@@ -2,7 +2,9 @@
 
 For an entity target, run `agency context . --json` before selecting a recipe.
 At the workbase root, use `agency next --json` or `agency graph --json` to choose
-a target, then inspect that explicit target with `agency context <target> --json`.
+a target, then inspect it with explicit `--epic`, `--task`, and `--phase`
+selectors or its returned document path. Graph node keys such as `task/<id>` and
+`phase/<task>/<phase>` are not positional context targets.
 
 The machine-orchestration forms in the inspect-through-recover recipes are
 captured in `fixtures/protocol/orchestration-recipes.json` and tested against the
@@ -10,6 +12,38 @@ real CLI parser. Their lifecycle behavior is covered by CLI and service fixtures
 Replace angle-bracket placeholders with values from context or a prior machine
 result; never scrape them from human output.
 
+## Initialize A Workbase
+
+For an existing local checkout, initialize the workbase and link the repository:
+
+```bash
+agency init <workbase-path>
+agency --workbase <workbase-path> repo link <alias> <repository-path>
+agency validate <workbase-path>
+agency --workbase <workbase-path> repo verify <alias>
+```
+
+Use `repo add <alias> <remote>` instead when Agency should create and manage a
+bare clone from a remote. Initialization and repository registration require
+explicit user intent.
+
+## Restore A Workbase On A New Machine
+
+After cloning the tracked workbase, inspect repository setup before applying it:
+
+```bash
+agency repo setup --dry-run --json
+agency repo setup --apply --json
+agency validate
+agency doctor --json
+```
+
+Apply clones only declared missing repositories. It does not overwrite linked
+checkouts, repair invalid paths, or choose between drifted remotes. Resolve those
+states explicitly, then rerun setup. A machine may replace an unused managed
+clone with `repo link`; the portable declaration remains available to every
+other machine.
+
 ## Inspect A Target
 
 ```bash
@@ -53,9 +87,11 @@ agency validate
 agency work tasks/checkout/phases/api
 ```
 
-`agency work` is intentionally last: it checks readiness, materializes
-worktrees, creates a claim, marks the execution unit working, and launches the
-runner.
+`agency work` is intentionally last: it synchronizes managed integration files,
+checks readiness, materializes worktrees, creates a claim, marks this execution
+unit working, and launches the runner. OpenCode receives whole-workbase read
+visibility through runtime-only config and permission values; this does not
+expand the writable checkout reported by `agency context`.
 
 ## Active Agent: Execute Assigned Work
 
@@ -63,8 +99,10 @@ runner.
 agency context . --json
 ```
 
-1. Verify context reports the expected execution target, no blockers, valid
-   structure, and the current checkout as `authority.writable.checkoutPath`.
+1. Verify context reports the expected execution target, valid structure, the
+   current checkout as `authority.writable.checkoutPath`, and a claim owned by
+   the current session. Reject dependency or validation blockers and conflicting
+   claims; the owned unit's `working` status blocker is expected.
 2. Read `TASK.md`, and `PHASE.md` for phase work.
 3. Implement only in the writable checkout; treat all reference checkouts as
    read-only.
@@ -160,11 +198,12 @@ agency validate
 agency pr create checkout ui --json
 ```
 
-The writable worktree must be clean. Agency pushes the declared branch, invokes
-the configured delivery provider's create command or falls back to
-`gh pr create --fill`, and records the returned URL. Do not manually write a URL
-if creation fails. A PR being open is not equivalent to completion when the
-assigned outcome requires merge.
+Agency materializes a missing workspace, then requires the writable worktree to
+be clean. It pushes the declared branch, invokes the configured delivery
+provider's create command or falls back to `gh pr create --fill`, and records the
+returned pull request record. Do not manually write a URL or record if creation
+fails. A PR being open is not equivalent to completion when the assigned outcome
+requires merge.
 
 Agency does not create commits, run tests, wait for checks, merge the PR, or
 verify completion. Those remain orchestrator responsibilities.
@@ -214,6 +253,7 @@ agency restore phase checkout ui --dry-run --json
 agency restore phase checkout ui
 ```
 
-Archive only terminal work and only with explicit intent. Agency preserves the
+As an operating policy, archive only terminal work and only with explicit intent;
+the CLI also permits safe archival of nonterminal work. Agency preserves the
 branch and lifecycle provenance while enforcing graph, worktree, and destination
 safety. Never move archived directories by hand.

package/src/cli-parser.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test"
 import orchestrationRecipes from "../fixtures/protocol/orchestration-recipes.json"
+import skillSetupCommands from "../fixtures/protocol/skill-setup-commands.json"
 import { parseCli } from "./cli-parser"
 
 const expectUsageError = (args: string[], usage: string) => {
@@ -13,6 +14,12 @@ describe("strict CLI parsing", () => {
 		}
 	})
 
+	test("accepts every documented skill setup command", () => {
+		for (const args of skillSetupCommands) {
+			expect(() => parseCli(args)).not.toThrow()
+		}
+	})
+
 	test("rejects misspelled and command-inapplicable options", () => {
 		expectUsageError(["task", "list", "--josn"], "agency task")
 		expectUsageError(