@markjaquith/agency 2.47.3 → 2.48.0

package/README.md

@@ -90,6 +90,12 @@ checksum-safe managed files. Customized files are reported but never
 overwritten. The root
 `AGENTS.md` is user-owned and is not inspected or modified by Agency.
 
+The managed `.agency/AGENTS.md` is the complete in-workbase operating contract
+for agents. It is created by `agency init`, updated by checksum-safe integration
+sync, and requires no separately installed Agency skill. CLI help remains the
+source of truth for exact command syntax; this README provides the detailed
+product and protocol reference.
+
 When upgrading an existing workbase, synchronization moves a checksum-valid
 Agency-managed root `AGENTS.md` to `.agency/AGENTS.md` once the OpenCode config
 can load the hidden file. A customized root file, including a symlink, is
@@ -882,14 +888,10 @@ payloads are exported as `@markjaquith/agency/fixtures/protocol/success.json` an
 Success, help, and version output exit `0`; usage and command failures exit `1`.
 There are no error-specific exit statuses. `graph --jsonl` streams versioned
 records on success instead of wrapping them in an envelope; JSONL failures still
-use one error envelope. See `skills/agency/references/contracts.md` for revision,
-selector, projection, retry, and capability details.
-
-## Agent Skill
-
-`skills/agency/SKILL.md` contains an agent-oriented operating guide for Agency.
-Install or link that directory into your agent's skill location when you want
-Agency workflows to be discovered automatically.
+use one error envelope. Revision and concurrency behavior is documented under
+Tasks, Phases, and Claims; selector behavior under Noninteractive Use; projection
+behavior under Target Context and Workbase Graph; and retry behavior in the
+machine error contract above.
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "2.47.3",
+  "version": "2.48.0",
   "description": "Manage agentic work across repositories with durable workbases",
   "keywords": [
     "agents",
@@ -23,7 +23,6 @@
     "src",
     "schemas",
     "fixtures/protocol",
-    "skills",
     "README.md",
     "LICENSE"
   ],

package/src/cli-parser.test.ts

@@ -1,6 +1,5 @@
 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) => {
@@ -14,12 +13,6 @@ 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(

package/src/commands/init.test.ts

@@ -34,7 +34,11 @@ describe("init command", () => {
 			"/repos/\n/tasks/*/code/\n/tasks/*/phases/*/code/\n",
 		)
 		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(false)
-		expect(await Bun.file(join(root, ".agency/AGENTS.md")).exists()).toBe(true)
+		const agents = await Bun.file(join(root, ".agency/AGENTS.md")).text()
+		expect(agents).toContain("agency context . --json")
+		expect(agents).toContain("## Consent Boundaries")
+		expect(agents).toContain("## Execution")
+		expect(agents).not.toContain("SKILL.md")
 		const opencode = await Bun.file(
 			join(root, ".opencode/opencode.jsonc"),
 		).text()

package/src/services/IntegrationService.test.ts

@@ -291,9 +291,21 @@ describe("IntegrationService", () => {
 		const body = managedBody(managedWorkbaseAgents)
 
 		expect(body).toContain("agency context . --json")
+		expect(body).toContain("agency next --json")
+		expect(body).toContain("agency <command> --help")
 		expect(body).toContain("authority.writable.checkoutPath")
-		expect(body).toContain("`agency work` is the local launch flow")
-		expect(body).toContain("External orchestrators claim before launching")
+		expect(body).toContain("Only `done` satisfies a dependency")
+		expect(body).toContain("Require explicit user intent")
+		expect(body).toContain("changing repository")
+		expect(body).toMatch(/archiving, restoring,\s+dropping, or/)
+		expect(body).toContain("Never invent entity IDs")
+		expect(body).toContain("Preserve parent backlinks")
+		expect(body).toContain("dirty-worktree, active-claim, revision")
+		expect(body).toContain("`agency work` is the human launch flow")
+		expect(body).toContain("marks execution work")
+		expect(body).toContain("without creating a claim")
+		expect(body).toContain("formatting, type checks, build, dead-code checks")
+		expect(body).toContain("Review and commit the diff")
 		expect(body).toContain("Run `agency validate`")
 		expect(body).toContain("only with explicit user intent")
 		expect(body).toContain("An execution unit remains `working`")
@@ -309,6 +321,8 @@ describe("IntegrationService", () => {
 		expect(body).toContain("PR state, current head, diff summary")
 		expect(body).toContain("Run `agency validate` before reporting completion")
 		expect(body).toContain("agency integration status")
+		expect(body).not.toContain("SKILL.md")
+		expect(body).not.toContain("~/.agents")
 		expect(body).toContain(".opencode/command/agency.md")
 	})
 
@@ -480,6 +494,31 @@ describe("IntegrationService", () => {
 		)
 	})
 
+	test("upgrades prior managed instructions without changing owner instructions", async () => {
+		const ownerInstructions = "# User-owned workbase instructions\n"
+		const priorInstructions = managed(
+			"<!-- agency-managed: sha256=",
+			"# Previous Agency instructions\n",
+			" -->",
+		)
+		await write(root, "AGENTS.md", ownerInstructions)
+		await write(root, ".agency/AGENTS.md", priorInstructions)
+
+		const result = await sync(root)
+
+		expect(result.files[0]).toMatchObject({
+			name: "agents",
+			state: "managed",
+			changed: true,
+		})
+		expect(await Bun.file(join(root, ".agency/AGENTS.md")).text()).toBe(
+			managedWorkbaseAgents,
+		)
+		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(
+			ownerInstructions,
+		)
+	})
+
 	test("preserves user-owned checkout-skill plugins at either supported path", async () => {
 		const custom = "export default async () => ({})\n"
 		await write(root, ".opencode/plugins/agency-repository-skills.ts", custom)

package/src/workbase/AGENTS.md

@@ -16,6 +16,10 @@ Use the returned target, document paths and revisions, dependency readiness,
 authority, checkout state, PR state, and validation result. Do not infer these
 from directory names or stale prose.
 
+At the workbase root, use `agency next --json` or `agency graph --json` to choose
+work, then inspect the returned document path or explicit entity selectors. Use
+`agency --help` and `agency <command> --help` for exact command syntax.
+
 If context or doctor reports a declared but missing repository, run
 `agency repo setup --dry-run` and obtain explicit approval before
 `agency repo setup --apply`. Missing declared aliases are setup state, not a
@@ -25,27 +29,52 @@ reason to edit `agency.json` or `repos/` by hand.
 
 - An epic or multi-phase task is orchestration context and has no implementation
   write authority.
+- A single-phase task or phase is an execution unit with one writable `repo` and
+  optional read-only `repos`. Only `done` satisfies a dependency; `dropped` is
+  terminal but leaves dependents blocked.
 - For an execution unit, write code only at
   `authority.writable.checkoutPath`. Every `authority.references` checkout is
   read-only, even if filesystem permissions allow writes.
 - Keep task-wide decisions in `TASK.md` and phase-specific delivery context in
   `PHASE.md`. Use Agency commands for structural frontmatter mutations.
 
+## Consent Boundaries
+
+Require explicit user intent before initializing a workbase; changing repository
+aliases or applying repository setup or workbase sync changes; launching another
+agent from an active agent session; creating a pull request; archiving, restoring,
+dropping, or reopening work; or using `--force` to override readiness.
+
 ## Safety
 
 - Stop on validation errors, dependency blockers, an unexpected writable
   repository, or a conflicting active claim.
-- `agency work` is the local launch flow and marks execution units `working`
-  without claiming them. External orchestrators claim before launching runners.
 - Do not manually create, move, or remove worktrees under `code/`.
 - Use `agency archive`, rather than moving work item folders manually.
 - Do not edit bare repositories or repository symlinks under `repos/`.
+- Never invent entity IDs, revisions, PR state, dependency completion, or
+  checkout state. Preserve parent backlinks and dependency declarations.
+- Do not bypass dirty-worktree, active-claim, revision, or readiness protections.
 - Do not run `agency work` from an active agent session unless the user
   explicitly asks to launch another agent.
 - Run `agency validate` before worktree or pull-request operations.
 - Create a pull request only with explicit user intent, using
   `agency pr create <task> [phase]` so the URL is recorded durably.
 
+## Execution
+
+For implementation work, read the task and phase prose returned by context,
+change only the writable checkout, keep durable decisions current, and run the
+repository's formatting, type checks, build, dead-code checks, and focused tests.
+Review and commit the diff according to the repository's instructions.
+
+`agency work` is the human launch flow: it reconciles managed integration,
+selects work, checks readiness, prepares checkouts, marks execution work
+`working` without creating a claim, and starts the runner. Epic and multi-phase
+task launches remain orchestration-only. External orchestrators instead claim
+an execution unit, launch and monitor their runner separately, and finish or
+release the claim with the current document revision.
+
 ## Closeout
 
 An execution unit remains `working` after implementation is committed and while

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

@@ -1,18 +0,0 @@
-[
-  ["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/skills/agency/SKILL.md

@@ -1,151 +0,0 @@
----
-name: agency
-description: >
-  Operate Agency workbases, epics, tasks, phases, execution worktrees, claims,
-  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 OpenCode, Claude, or a configured runner; default GitHub delivery requires gh.
----
-
-# Agency
-
-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
-
-For an entity target, the first inspection command is:
-
-```bash
-agency context . --json
-```
-
-It identifies the target and ancestors, document revisions, dependency
-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 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:
-
-```bash
-agency graph --json
-agency doctor --json
-agency --help
-agency <command> --help
-```
-
-Use `agency next --json` when choosing ready execution work. Read
-[`references/contracts.md`](references/contracts.md) when consuming machine
-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 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
-read-only, even if filesystem permissions permit writes.
-
-## Decide Before Acting
-
-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
-- using `--force` to override readiness.
-
-Use a single-phase task for one outcome delivered by one PR. Use phases when an
-outcome needs multiple PRs or ordered execution units. Use an epic when several
-independently meaningful tasks need coordination.
-
-## Safety Invariants
-
-- 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, or readiness protections.
-
-## Operating Protocol
-
-### Start
-
-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, dependency blockers, an unexpected writable
-   repository, or a conflicting active owner. A local `agency work` launch has
-   no claim; an externally assigned agent must own the active claim.
-
-### Work
-
-1. Change files only in the declared writable checkout.
-2. Keep durable status and decisions current as the work changes.
-3. Validate structure after Agency document mutations.
-4. Run repository-specific formatting, type checks, builds, dead-code checks,
-   and focused tests before committing.
-5. Review the diff and commit according to the repository's instructions.
-
-### Finish
-
-1. Re-run `agency validate` and repository checks.
-2. Create a PR only when requested: `agency pr create <task> [phase]`.
-3. Keep committed work `working` while its pull request is open. After the
-   authoritative pull request merges, use `agency sync --apply` to reconcile it
-   to `done`.
-4. If the session has a claim, use revision-guarded `agency finish`; a successful
-   claim outcome closes ownership without marking unmerged work `done`. Use
-   `dropped` only for intentionally abandoned work.
-5. Report the durable status and PR URL. Do not manually remove the worktree.
-
-## Human Launch vs Active Agent
-
-`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, marks it working without a claim, and starts
-the selected built-in or configured runner. Epic and multi-phase task launches
-start in orchestration context without materializing execution work. The runner
-opens without a prompt unless the human explicitly selects `--auto`.
-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
-finish its claim or update unclaimed status directly. Launch a nested or
-replacement agent only when the user explicitly asks.
-
-Use [`references/recipes.md`](references/recipes.md) for human setup, agent
-execution, claim, PR, conversion, and recovery workflows. Use
-[`references/commands.md`](references/commands.md) only when exact command syntax
-is needed.

package/skills/agency/references/commands.md

@@ -1,188 +0,0 @@
-# Agency Command Reference
-
-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
-
-```text
-agency context [target] [--json] [--compact | --full]
-agency graph [--json | --jsonl] [--ready | --blocked]
-  [--status <status>...] [--repository <alias>...] [--kind <kind>...]
-  [--include <bodies|workspace|git|pr>...]
-agency next [--select] [--json]
-agency status [filters] [--json]
-agency validate [path] [--json]
-agency doctor [--json]
-agency sync [--dry-run | --apply] [--json]
-agency integration status [--json]
-agency integration sync [--json]
-```
-
-`context` defaults to cwd and accepts the workbase root, entity directories,
-document paths, checkout descendants, or a task ID. Root context catalogs all
-epics, tasks, and phases in compact form and hints that `--full` includes prose.
-Entity context is complete by default; `--compact` intentionally omits prose and
-low-level Git details. `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. Integration status includes safe
-remediation when customized OpenCode config prevents Agency from guaranteeing
-whole-workbase access.
-
-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
-
-```text
-agency workbase init [path] [--json]
-agency init [path] [--json] # Alias
-agency workbase add <path> [--name <name>] [--json]
-agency workbase list [--json]
-agency workbase show <id|name|path> [--json]
-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]
-agency repo show <alias> [--json]
-agency repo fetch <alias> [--json]
-agency repo remote <alias> [remote] [--json]
-agency repo verify <alias> [--json]
-agency repo rename <alias> <new-alias> [--json]
-agency repo remove <alias> [--json]
-agency repo unlink <alias> [--json]
-```
-
-`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
-
-```text
-agency epic create <id> --ticket-url <url> [--description <text>]
-  --repo <alias>:<ref>... [--json]
-agency epic list [filters] [--json]
-agency epic show <id> [--json]
-agency epic update <id> [metadata options] [--if-revision <hash>] [--json]
-agency epic rename <id> <new-id> [--if-revision <hash>] [--json]
-
-agency task new [id]
-agency task create <id> --repo <alias> [--ticket-url <url>]
-  [--description <text>] [--epic <id>] [--reference <alias>:<ref>...]
-  [--branch <name>] [--base <name>] [--json]
-agency task create <id> --multi-phase [--ticket-url <url>]
-  [--description <text>] [--epic <id>] [--json]
-agency task list [filters] [--json]
-agency task show <id> [--json]
-agency task status <id> <open|working|dropped> [--json]
-agency task update <id> [metadata options] [--if-revision <hash>] [--json]
-agency task rename <id> <new-id> [--if-revision <hash>] [--json]
-agency task move <id> (--epic <epic-id> | --no-epic)
-  [--if-revision <hash>] [--json]
-agency task dependency <add|remove> <task-id> <dependency-id>
-  [--if-revision <hash>] [--json]
-
-agency phase create <task-id> <phase-id> --repo <alias> --branch <name>
-  --base <name> [--description <text>] [--reference <alias>:<ref>...]
-  [--depends-on <phase-id>...] [--first-phase <phase-id>] [--json]
-agency phase list <task-id> [filters] [--json]
-agency phase show <task-id> <phase-id> [--json]
-agency phase status <task-id> <phase-id> <open|working|dropped> [--json]
-agency phase update <task-id> <phase-id> [metadata options]
-  [--if-revision <hash>] [--json]
-agency phase rename <task-id> <phase-id> <new-id>
-  [--if-revision <hash>] [--json]
-agency phase dependency <add|remove> <task-id> <phase-id> <dependency-id>
-  [--if-revision <hash>] [--json]
-```
-
-`task new` uses the OpenTUI Solid footer and requires a TTY. A sole repository is
-selected automatically. Agents and scripts use noninteractive `task create`.
-Mutation commands that accept `--if-revision`
-return a revision conflict instead of overwriting changed documents.
-
-## Ownership And Lifecycle
-
-```text
-agency claim <task-id> [phase-id] --claimant <id> --runner <id>
-  --session-id <id> --revision <sha256> [--expires-at <timestamp>] [--json]
-agency release <task-id> [phase-id] --session-id <id>
-  --revision <sha256> [--json]
-agency finish <task-id> [phase-id] --session-id <id>
-  --revision <sha256> --outcome <done|dropped> [--json]
-
-agency archive list [--kind <kind>] [--status <status>]
-  [--repository <alias>]
-agency archive show <epic|task> <id>
-agency archive show phase <task-id> <phase-id>
-agency archive epic <epic-id> [--dry-run] [--json]
-agency archive task <task-id> [--dry-run] [--json]
-agency archive phase <task-id> <phase-id> [--dry-run] [--json]
-agency restore epic <epic-id> [--dry-run] [--json]
-agency restore task <task-id> [--dry-run] [--json]
-agency restore phase <task-id> <phase-id> [--dry-run] [--json]
-```
-
-Claim mutations require the current execution-document revision. Archive and
-restore preflight graph and destination safety, remove registered clean
-worktrees when needed, preserve branches, and retain lifecycle provenance.
-
-## Worktrees, Launch, And Pull Requests
-
-```text
-agency work [<directory-or-task-id> | --epic <id> | --task <id> [--phase <id>]]
-  [--runner <name> | --opencode | --claude] [--auto] [--print-command] [--force]
-agency work prepare [target] [--dry-run] [--json]
-agency worktree list [--json]
-agency worktree inspect <task-id> [phase-id] [--json]
-agency worktree prepare <task-id> [phase-id] [--dry-run] [--json]
-agency worktree remove <task-id> [phase-id] [--dry-run] [--json]
-agency worktree rebuild <task-id> [phase-id] [--dry-run] [--json]
-agency worktree repair <task-id> [phase-id] [--dry-run] [--json]
-agency pr create <task-id> [phase-id] [--draft] [--force] [--json]
-```
-
-`work` is a local launch flow, not an active-agent step. It synchronizes managed
-integration files before launch. Execution targets are materialized and marked
-working without a claim; epics and multi-phase tasks launch in orchestration
-context without those steps. Unclaimed working targets can be launched again.
-The runner opens without a generated prompt unless `--auto` is set.
-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` materializes execution targets but does not launch or change
-status. `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. 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.
-
-Selectors are only a resolution mechanism. There is no `assign` command. Use
-`work` for a local human launch, or use `claim` and manage an external runner
-separately.

package/skills/agency/references/contracts.md

@@ -1,322 +0,0 @@
-# Agency Data Contracts
-
-Use Agency JSON output instead of scraping human tables. Entity IDs are directory
-names; they are not duplicated in frontmatter.
-
-## Context Contract
-
-`agency context . --json` returns a versioned success envelope whose result
-contains:
-
-- `projection`: `compact` for root discovery by default, otherwise `complete`
-  unless compact entity context was explicitly requested;
-- `workbase`: root, config path, and config version;
-- `target`: resolved workbase, epic, task, or phase identity;
-- `discovery`: at the workbase root, all valid epic, task, and phase documents;
-- `documents`: ancestor frontmatter, paths, SHA-256 revisions, and prose;
-- `graph`: parent, dependencies, dependents, readiness blockers, and progress;
-- `authority`: `orchestration` or `execution`, one writable checkout or none,
-  and read-only references;
-- `workspace`: code path, materialization and registration state, commits, and
-  inspection warnings;
-- `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
-
-```yaml
----
-ticketUrl: https://example.com/tickets/checkout
-description: Coordinate checkout delivery.
-repos:
-  - repo: frontend
-    ref: main
-tasks:
-  - id: api
-  - id: ui
-    dependsOn:
-      - api
----
-```
-
-Epics have read-only `repos`, never a writable `repo`. Their `tasks` list owns
-task ordering and task dependencies.
-
-### Single-Phase Task
-
-```yaml
----
-ticketUrl: null
-description: Refresh checkout copy.
-epic: checkout
-repo: frontend
-repos:
-  - repo: backend
-    ref: main
-branch: task/refresh-copy
-base: main
-pr: null
-status: open
----
-```
-
-### Multi-Phase Task
-
-```yaml
----
-ticketUrl: null
-description: Deliver checkout.
-epic: checkout
-phases:
-  - id: api
-  - id: ui
-    dependsOn:
-      - api
----
-```
-
-The task's `phases` list owns phase ordering and dependencies. Execution fields
-belong in each phase document.
-
-### Phase
-
-```yaml
----
-description: Build the checkout UI.
-repo: frontend
-repos:
-  - repo: backend
-    ref: main
-branch: task/checkout-ui
-base: task/checkout-api
-pr: null
-status: open
----
-```
-
-`ticketUrl` belongs to tasks and epics, not phases. `description` is optional but
-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`, `merged`, and optional `mergeable`. Mergeability is `true`,
-`false`, or `null` when the provider cannot determine it. 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
-
-- An execution unit has one writable `repo`; plural `repos` are read-only
-  `{ repo, ref }` entries and cannot repeat the writable alias.
-- A writable `(repo, branch)` pair belongs to exactly one active execution unit.
-- `done` represents an authoritative merged pull request and is reconciled by
-  `agency sync --apply`; committed or review-ready work remains `working`.
-- Only `done` satisfies dependencies. `dropped` is terminal but blocks dependents.
-- Epic task dependencies live in `EPIC.md`; phase dependencies live in `TASK.md`.
-- IDs remain stable; use `dependsOn`, not numeric directory prefixes, for order.
-- YAML duplicate keys, anchors, aliases, and custom tags are invalid.
-- Use a commit SHA as a reference `ref` when reproducibility is required.
-
-## Graph Contract
-
-`agency graph --json` emits graph contract version 1. Stable node IDs are
-`epic:<id>`, `task:<id>`, `phase:<task>/<phase>`,
-`repository:<alias>`, and `execution-unit:<kind>/<id>`. Edge types are `owns`,
-`depends_on`, `writes`, and `references`.
-
-Every work node includes status, readiness, `blockedBy`, detailed blockers,
-terminal state, reverse dependents, and aggregate progress. Filters run after
-state computation. `--jsonl` emits a versioned `meta` record, node and edge
-records, then an `end` record; together they reconstruct the JSON result.
-
-## Machine Envelope
-
-The published success fixture is normalized from
-`agency init /work/agency --json`:
-
-```json
-{
-	"version": 1,
-	"ok": true,
-	"result": {
-		"root": "/work/agency"
-	}
-}
-```
-
-The published error fixture is the output of `agency unknown --json`:
-
-```json
-{
-	"version": 1,
-	"ok": false,
-	"error": {
-		"code": "CLI_USAGE",
-		"message": "Unknown command 'unknown'.\n\nUsage: agency <command> [options]",
-		"fields": {
-			"detail": "Unknown command 'unknown'.",
-			"usage": "agency <command> [options]"
-		},
-		"retryable": false,
-		"remediation": "Correct the arguments using the usage value in error.fields."
-	}
-}
-```
-
-These examples are exported from `fixtures/protocol/` and tested against real
-CLI subprocess output. The Effect schemas are exported by the package and by
-`@markjaquith/agency/protocol`. The distributable JSON Schemas are exported as
-`@markjaquith/agency/schemas/agency-envelope-v1.json` and
-`@markjaquith/agency/schemas/agency-graph-v1.json`.
-
-Only the envelope and graph result have published JSON Schemas. The envelope's
-`result` is intentionally unconstrained. Context, next, claim, prepare, sync,
-repository setup, and PR result shapes are exercised by CLI tests but do not have independent
-published schemas.
-
-### Output And Exit Guarantees
-
-- `--json` writes exactly one newline-terminated envelope to stdout on success
-  or failure. It disables interactive selection and takes precedence over
-  `--silent`; explicit entity selectors remain valid.
-- Human output is not a machine contract. Do not parse tables, progress text, or
-  diagnostic wording.
-- Progress and verbose diagnostics use stderr. Structured command warnings stay
-  inside the stdout result. Successful JSON mode does not promise empty stderr
-  when `--verbose` is requested.
-- Success, help, and version output exit `0`. Usage errors and every command
-  failure exit `1`. Version 1 has no error-specific exit statuses; branch on
-  `error.code`.
-- `graph --jsonl` is the one streaming exception. On success it writes a `meta`
-  record, node and edge records, and an `end` record rather than an envelope. A
-  JSONL failure still writes one error envelope and exits `1`.
-- A command that emits zero machine results succeeds with `result: null`.
-  Multiple results are a `PROTOCOL_OUTPUT_ERROR`.
-
-### Error Codes
-
-| Code                      | Meaning                                                        |
-| ------------------------- | -------------------------------------------------------------- |
-| `CLI_USAGE`               | Invalid command, option, argument, or combination              |
-| `WORKBASE_NOT_FOUND`      | No workbase could be resolved                                  |
-| `WORKBASE_CONFIG_INVALID` | Invalid workbase configuration                                 |
-| `WORKBASE_REGISTRY_ERROR` | Invalid or inaccessible workbase registry                      |
-| `FILE_NOT_FOUND`          | A required path does not exist                                 |
-| `FILESYSTEM_ERROR`        | A filesystem operation failed                                  |
-| `FRONTMATTER_INVALID`     | Durable document frontmatter is invalid                        |
-| `VALIDATION_FAILED`       | Workbase validation reported issues                            |
-| `REPOSITORY_ERROR`        | Repository operation failed                                    |
-| `EPIC_ERROR`              | Epic operation failed                                          |
-| `TASK_ERROR`              | Task operation failed                                          |
-| `PHASE_ERROR`             | Phase operation failed                                         |
-| `CLAIM_ERROR`             | Claim input or lifecycle state is invalid                      |
-| `CLAIM_CONFLICT`          | Active or legacy ownership conflicts with an operation         |
-| `REVISION_CONFLICT`       | A durable document changed since inspection                    |
-| `CLAIM_OWNERSHIP`         | The session does not own the active claim                      |
-| `ARCHIVE_ERROR`           | Archive or restore operation failed                            |
-| `WORKTREE_ERROR`          | Worktree operation failed                                      |
-| `PULL_REQUEST_ERROR`      | Pull request operation failed                                  |
-| `CONTEXT_ERROR`           | A context target or required document is invalid               |
-| `GRAPH_ERROR`             | Graph construction or filtering failed                         |
-| `EXECUTION_BLOCKED`       | Readiness or lifecycle blockers prevent execution              |
-| `SYNC_ERROR`              | Reconciliation validation, inspection, or provider data failed |
-| `PROCESS_ERROR`           | A child process failed                                         |
-| `PROTOCOL_OUTPUT_ERROR`   | A command violated the one-result machine contract             |
-| `COMMAND_FAILED`          | An otherwise unclassified failure                              |
-
-`CLAIM_CONFLICT`, `REVISION_CONFLICT`, and `PROCESS_ERROR` are retryable in the
-v1 metadata. Retryable means new evidence may change the result, not that blind
-or non-idempotent retries are safe. Inspect `fields` and apply `remediation`
-before retrying.
-
-## Revisions And Concurrency
-
-A document revision is the lowercase SHA-256 hash of the complete Markdown file,
-including frontmatter and prose. It is per document, not a workbase-wide graph
-revision. Context, graph, and entity reads expose revisions.
-
-`claim`, `release`, and `finish` require `--revision <sha256>`. They lock and
-recheck the execution document before an atomic replacement, then return
-`previousRevision` and the new `revision`. Use the returned revision or inspect
-again before the next mutation. Claim conflicts include the current revision and
-ownership evidence in `error.fields`; revision conflicts include ownership only
-when claim evidence applies.
-
-Structural update, rename, move, and dependency commands accept optional
-`--if-revision <sha256>`. Machine orchestrators should provide it. Multi-document
-mutations recheck every affected file while holding the graph mutation lock.
-
-## Selectors And Projections
-
-`--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. Global
-`--cwd` and `--workbase` selectors apply to `next` as they do to other discovery
-commands.
-
-At a workbase root, context defaults to a compact discovery catalog of epics,
-tasks, and phases, includes no writable authority, and provides a hint for
-requesting `--full`. Entity context defaults to the `complete` projection.
-`--compact` omits prose and low-level Git details but retains identity, document
-hashes, authority, paths, graph state, materialization, and validation warnings.
-
-Graph projections are opt-in with repeatable
-`--include <bodies|workspace|git|pr>`. Filters such as `--ready`, `--blocked`,
-`--status`, `--repository`, and `--kind` are applied after readiness and graph
-state are computed; returned edges always have both endpoints in the filtered
-node set.
-
-## Capability Boundaries
-
-- There is no atomic find-ready-and-claim operation. `next` is observational,
-  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` launches one local built-in or
-  configured runner without a claim; 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.
-- Reconciliation never discards changes, switches branches, resets reference
-  commits, moves conflicting worktrees, chooses among multiple PRs, or bypasses
-  active claims. Such conditions remain unresolved for a human or orchestrator.
-- `delegated` is readable legacy state but cannot be newly assigned. `--force`
-  only overrides readiness for `work` and `pr create`; it is not general
-  reconciliation authority.

package/skills/agency/references/recipes.md

@@ -1,264 +0,0 @@
-# Agency Recipes
-
-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 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
-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
-agency context --task <task-id> --phase <phase-id> --json
-agency worktree inspect <task-id> <phase-id> --json
-```
-
-Confirm the target, current document revision, readiness, authority, checkout,
-claim, PR, and validation state. Use `--compact` only when prose and detailed Git
-evidence are not needed.
-
-## Find Ready Work
-
-Run this from the intended workbase:
-
-```bash
-agency next --json
-agency graph --ready --json
-```
-
-`next` ranks ready execution units and explains every excluded unit. It does not
-reserve work. Another orchestrator may claim the same candidate before you do,
-so always handle `CLAIM_CONFLICT` or `REVISION_CONFLICT`.
-
-## Human: Create And Launch Work
-
-```bash
-agency task create refresh-copy --repo frontend --branch task/refresh-copy --base main
-agency validate
-agency work tasks/refresh-copy
-```
-
-For a multi-PR outcome:
-
-```bash
-agency task create checkout --multi-phase
-agency phase create checkout api --repo backend --branch task/checkout-api --base main
-agency phase create checkout ui --repo frontend --branch task/checkout-ui \
-  --base main --reference backend:main --depends-on api
-agency validate
-agency work tasks/checkout/phases/api
-```
-
-`agency work` is intentionally last: it synchronizes managed integration files,
-checks readiness, materializes worktrees, marks this execution unit working
-without a claim, and launches the runner. Run it again to relaunch unclaimed
-working work. The runner opens without a prompt by default; add `--auto` only
-when the generated context prompt should start autonomous execution.
-OpenCode receives whole-workbase visibility through the managed project plugin;
-this does not expand the writable checkout reported by `agency context`.
-
-## Active Agent: Execute Assigned Work
-
-```bash
-agency context . --json
-```
-
-1. Verify context reports the expected execution target, valid structure, and
-   the current checkout as `authority.writable.checkoutPath`. Reject dependency
-   or validation blockers and conflicting active claims.
-2. Read `TASK.md`, and `PHASE.md` for phase work.
-3. Implement only in the writable checkout; treat all reference checkouts as
-   read-only.
-4. Run repository formatting, checks, build, and focused tests.
-5. Review and commit the diff.
-6. If requested, run `agency validate`, then
-   `agency pr create <task-id> [phase-id]`.
-7. Finish an active claim after its completion condition is true; otherwise set
-   the task or phase status directly.
-
-Never invoke `agency work` merely because an execution checkout already exists;
-that would start another agent rather than continue the current assignment.
-
-## Claim Ready Work
-
-Get the current document revision from context. Use stable claimant, runner, and
-session IDs:
-
-```bash
-agency claim checkout ui \
-  --claimant orchestrator-1 --runner opencode --session-id session-123 \
-  --revision <sha256> --json
-```
-
-Claim records ownership and sets status to `working`; it does not launch a runner
-or recheck dependency readiness. A machine orchestrator must launch and monitor
-its runner separately. There is no atomic find-and-claim or `assign` command.
-
-## Prepare Checkouts
-
-Preview and then materialize without claiming, launching, or changing status:
-
-```bash
-agency work prepare --task checkout --phase ui --dry-run --json
-agency work prepare --task checkout --phase ui --json
-```
-
-Use the returned checkout paths and resolved commits. Do not create or move
-worktrees manually.
-
-## Assign A Runner
-
-For a human-operated local launch, Agency combines readiness checks, prepare,
-status mutation, and runner launch without creating a claim:
-
-```bash
-agency work tasks/checkout/phases/ui --runner opencode
-```
-
-This is not a JSON assignment API. An external orchestrator instead claims with
-its own `claimant`, `runner`, and `session-id`, starts the runner outside Agency,
-and passes it the target and claim result. Agency has no queue, heartbeat,
-monitoring, cancellation, or automatic claim-renewal service.
-
-## Reconcile Durable And Local State
-
-```bash
-agency sync --dry-run --json
-agency sync --apply --json
-```
-
-The first command is observational. Apply may materialize an unconflicted missing
-checkout, release an expired claim, record one unambiguous matching PR, or mark
-unclaimed work done after its authoritative PR merges. Review `warnings` and
-`unresolved`; apply never discards or resets work and never chooses among
-ambiguous PRs.
-
-## Release Interrupted Work
-
-After every claim mutation, use the returned revision or inspect again. Release
-interrupted work back to open:
-
-```bash
-agency release checkout ui --session-id session-123 \
-  --revision <current-sha256> --json
-```
-
-## Finish Verified Work
-
-After the claimed run completes successfully:
-
-```bash
-agency finish checkout ui --session-id session-123 \
-  --revision <current-sha256> --outcome done --json
-```
-
-Do not substitute a phase status mutation for `finish`; `finish` preserves
-ownership history and revision safety. A `done` claim outcome leaves unmerged
-execution work `working`. After the authoritative pull request merges, use
-`agency sync --apply` to reconcile the execution unit to `done`.
-
-## Create A Pull Request
-
-```bash
-agency validate
-agency pr create checkout ui --json
-```
-
-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.
-
-## Convert A Task To Phases
-
-Name the phase that inherits the existing task's execution metadata:
-
-```bash
-agency phase create refresh-copy verification \
-  --first-phase implementation \
-  --repo frontend --branch task/refresh-copy-verification --base main \
-  --depends-on implementation
-agency validate
-```
-
-Agency converts the task shape, creates both phase documents, and relocates
-materialized worktrees. Do not perform those moves manually.
-
-## Recover From Interrupted State
-
-Inspect before applying changes:
-
-```bash
-agency doctor --json
-agency sync --dry-run --json
-agency worktree inspect <task-id> [phase-id] --json
-agency worktree repair <task-id> [phase-id] --dry-run --json
-```
-
-Use `agency sync --apply` only with explicit user intent. It may safely
-materialize an unconflicted missing checkout, release an expired claim, record a
-single matching PR, refresh recorded PR state and mergeability, or mark work done
-after its authoritative PR merged and no claim remains. It never modifies dirty
-checkouts, switches branches, resets
-references, chooses among PRs, or bypasses active claims.
-
-For a worktree-specific issue, use `worktree repair --dry-run` before repair.
-Repair is conservative and never discards work. Use remove or rebuild only after
-reviewing the dry run and confirming every checkout is clean.
-
-## Archive Or Restore
-
-```bash
-agency archive phase checkout ui --dry-run --json
-agency archive phase checkout ui
-agency restore phase checkout ui --dry-run --json
-agency restore phase checkout ui
-```
-
-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.