@markjaquith/agency 2.72.0 → 2.73.1

package/README.md

@@ -441,7 +441,7 @@ variables. A worker must verify either signal against `agency context . --json`
 before acting; a matching worker performs the task directly and must not invoke
 `agency work` for the same target. Managed guidance also fails safe for older
 generated prompts when their document paths, current directory, and active valid
-context all agree. Herdr is not part of this identity contract.
+context all agree. External session state is not part of this identity contract.
 The managed OpenCode plugin validates the marker against Agency context, binds it
 to the receiving OpenCode session, injects an explicit active-worker system
 instruction, and restores Agency identity for that session's shell environment.
@@ -860,13 +860,13 @@ includes `selector`, absolute `documentPath`, the document `revision`, full
 `validation`, normalized `recalledContext`, and `evidence`. Evidence version 1 is
 an auditable local payload containing the canonical workbase root, target and
 document identities, aggregate workbase revision, configuration revision,
-repository-mapping revision, kickoff-contract version, validity result, recalled
+repository-mapping revision, execution-contract version, validity result, recalled
 context, and a digest over those fields. It is not a signature or an authority
 grant. A different workbase, target, document revision, document set,
 configuration, repository mapping, contract version, or payload digest
 invalidates reuse. Older creation output without evidence remains compatible;
 preflight simply validates again. The published machine schema is
-`schemas/agency-kickoff-v1.schema.json`.
+`schemas/agency-execution-v1.schema.json`.
 
 Create investigation-only work with the existing task architecture:
 
@@ -1128,12 +1128,18 @@ promptless by default; use `--auto` to send Agency's generated context prompt.
 `agency work prepare` resolves an execution unit and creates or reuses its
 writable and reference worktrees, or its single pinned review checkout, without
 launching an agent or changing status.
+Managed workbase guidance provides exact fast paths for 15 common intents:
+single-phase creation; create-and-start; materialization; remote PR sync; phase
+conversion; archive; review creation and start; status inspection; drop;
+continuation; publication and PR creation; non-PR completion; initial multi-phase
+setup; investigation handoff; and review refresh.
 Its JSON result includes the workspace, validation result, whether supplied
 evidence was `reused` or `refreshed` with stable reason strings, refreshed
-evidence, and a versioned `agency-kickoff-v1` orchestration plan. The plan has a
-deterministic idempotency key and ordered, retry-safe actions for worktree
-preflight/preparation, a background tab, side-by-side task document,
-`agency work . --auto`, and exactly one final `agency context <document> --json`.
+evidence, and a versioned `agency-execution-v1` contract. The contract reports
+whether preparation was previewed or applied, a stable target identity, prepared
+workspace and document paths, and canonical Agency-native commands for starting
+work and reading context. It does not prescribe how callers present or execute
+prepared work.
 The evidence argument may be an evidence object, task-creation JSON, or a path to
 either. Use `--dry-run` to report planned fetch, branch, and worktree changes
 without applying them. Validation reuse never skips readiness, active-claim,
@@ -1142,7 +1148,7 @@ checks.
 
 The authoritative implementation locations for this contract are
 `src/commands/task.ts` (creation output),
-`src/workbase/kickoff-contract.ts` (evidence and orchestration schemas),
+`src/workbase/execution-contract.ts` (evidence and execution schemas),
 `src/commands/work.ts` (launch preflight),
 `src/services/WorktreeService.ts` (workspace safety), and
 `src/workbase/AGENTS.md` (generated OpenCode guidance). These paths are the

package/index.ts

@@ -2,4 +2,4 @@ export * from "./src/workbase/schemas"
 export * from "./src/protocol"
 export * from "./src/graph-schema"
 export * from "./src/readiness"
-export * from "./src/workbase/kickoff-contract"
+export * from "./src/workbase/execution-contract"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "2.72.0",
+  "version": "2.73.1",
   "description": "Manage agentic work across repositories with durable workbases",
   "keywords": [
     "agents",
@@ -46,8 +46,8 @@
     "./schemas/agency-graph-v1.json": {
       "default": "./schemas/agency-graph-v1.schema.json"
     },
-    "./schemas/agency-kickoff-v1.json": {
-      "default": "./schemas/agency-kickoff-v1.schema.json"
+    "./schemas/agency-execution-v1.json": {
+      "default": "./schemas/agency-execution-v1.schema.json"
     },
     "./fixtures/protocol/success.json": {
       "default": "./fixtures/protocol/success.json"

package/schemas/{agency-kickoff-v1.schema.json → agency-execution-v1.schema.json}

@@ -1,10 +1,10 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/markjaquith/agency/schemas/agency-kickoff-v1.schema.json",
-  "title": "Agency kickoff contract v1",
+  "$id": "https://github.com/markjaquith/agency/schemas/agency-execution-v1.schema.json",
+  "title": "Agency execution contract v1",
   "oneOf": [
     { "$ref": "#/$defs/validationEvidence" },
-    { "$ref": "#/$defs/kickoffPlan" }
+    { "$ref": "#/$defs/executionContract" }
   ],
   "$defs": {
     "recalledContext": {
@@ -54,69 +54,93 @@
       },
       "additionalProperties": false
     },
-    "kickoffPlan": {
+    "command": {
+      "type": "object",
+      "required": ["cwd", "argv"],
+      "properties": {
+        "cwd": { "type": "string" },
+        "argv": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": false
+    },
+    "executionContract": {
       "type": "object",
       "required": [
         "version",
-        "idempotencyKey",
+        "capability",
+        "mode",
+        "executionIdentity",
         "workbaseRoot",
-        "target",
-        "documentRevision",
         "sourceLocations",
-        "taskDirectory",
-        "taskDocument",
-        "phaseDocument",
-        "preparedCheckout",
-        "orchestrator",
-        "steps",
-        "successFields"
+        "workspace",
+        "commands"
       ],
       "properties": {
         "version": { "const": 1 },
-        "idempotencyKey": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "capability": { "const": "agency-execution-v1" },
+        "mode": { "enum": ["preview", "applied"] },
+        "executionIdentity": {
+          "type": "object",
+          "required": ["key", "target", "documentRevision"],
+          "properties": {
+            "key": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+            "target": { "type": "string" },
+            "documentRevision": {
+              "type": "string",
+              "pattern": "^[a-f0-9]{64}$"
+            }
+          },
+          "additionalProperties": false
+        },
         "workbaseRoot": { "type": "string" },
-        "target": { "type": "string" },
-        "documentRevision": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
-        "sourceLocations": { "type": "array", "items": { "type": "string" } },
-        "taskDirectory": { "type": "string" },
-        "taskDocument": { "type": "string" },
-        "phaseDocument": { "type": ["string", "null"] },
-        "preparedCheckout": { "type": ["string", "null"] },
-        "orchestrator": {
+        "sourceLocations": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "workspace": {
           "type": "object",
           "required": [
-            "capability",
-            "knownCurrentCommandsBypassDiscovery",
-            "fallback"
+            "state",
+            "executionDirectory",
+            "taskDocument",
+            "phaseDocument",
+            "checkoutPath"
           ],
           "properties": {
-            "capability": { "const": "agency-kickoff-v1" },
-            "knownCurrentCommandsBypassDiscovery": { "const": true },
-            "fallback": { "type": "string" }
+            "state": { "enum": ["planned", "materialized"] },
+            "executionDirectory": { "type": "string" },
+            "taskDocument": { "type": "string" },
+            "phaseDocument": { "type": ["string", "null"] },
+            "checkoutPath": { "type": ["string", "null"] }
           },
           "additionalProperties": false
         },
-        "steps": {
+        "plannedActions": {
           "type": "array",
-          "minItems": 6,
           "items": {
             "type": "object",
-            "required": ["id"],
+            "required": ["kind", "target", "checkoutPath"],
             "properties": {
-              "id": { "type": "string" },
-              "argv": { "type": "array", "items": { "type": "string" } },
-              "cwd": { "type": "string" },
-              "action": { "type": "string" },
-              "path": { "type": "string" },
-              "retry": { "type": "string" },
-              "recovery": { "type": "string" },
-              "idempotencyKey": { "type": "string" },
-              "exactlyOnce": { "type": "boolean" }
+              "kind": { "const": "workspace-materialization" },
+              "target": { "type": "string" },
+              "checkoutPath": { "type": ["string", "null"] }
             },
             "additionalProperties": false
           }
         },
-        "successFields": { "type": "array", "items": { "type": "string" } }
+        "commands": {
+          "type": "object",
+          "required": ["work", "context"],
+          "properties": {
+            "work": { "$ref": "#/$defs/command" },
+            "context": { "$ref": "#/$defs/command" }
+          },
+          "additionalProperties": false
+        }
       },
       "additionalProperties": false
     }

package/src/cli-parser.test.ts

@@ -229,7 +229,9 @@ describe("strict CLI parsing", () => {
 	test("parses addressable resource maintenance commands", () => {
 		for (const args of [
 			["doctor", "--json"],
+			["repo", "materialize", "--help"],
 			["repo", "show", "agency", "--json"],
+			["repo", "materialize", "agency", "--json"],
 			["repo", "fetch", "agency"],
 			["repo", "remove", "agency"],
 			["repo", "unlink", "agency"],
@@ -270,6 +272,7 @@ describe("strict CLI parsing", () => {
 			[["integration", "sync", "extra"], "agency integration sync"],
 			[["repo", "add", "a", "b", "extra"], "agency repo add"],
 			[["repo", "link", "a", "b", "extra"], "agency repo link"],
+			[["repo", "materialize", "a", "extra"], "agency repo materialize"],
 			[["repo", "list", "extra"], "agency repo list"],
 			[
 				[

package/src/cli-parser.ts

@@ -259,7 +259,7 @@ const commands = {
 	},
 	repo: {
 		usage:
-			"agency repo <setup|add|link|list|show|fetch|remove|unlink|rename|remote|verify>",
+			"agency repo <setup|add|link|materialize|list|show|fetch|remove|unlink|rename|remote|verify>",
 		options: {
 			...outputOptions,
 			"dry-run": { type: "boolean" },
@@ -285,6 +285,12 @@ const commands = {
 				maxArgs: 2,
 				options: ["json"],
 			},
+			materialize: {
+				usage: "agency repo materialize <alias> [--json]",
+				minArgs: 1,
+				maxArgs: 1,
+				options: ["json"],
+			},
 			list: {
 				usage: "agency repo list [--json]",
 				minArgs: 0,

package/src/cli.test.ts

@@ -934,6 +934,48 @@ status: open
 		})
 	})
 
+	test("materializes a linked repository through the CLI", async () => {
+		const parent = await createTempDir()
+		tempDirs.push(parent)
+		const root = join(parent, "workbase")
+		const source = join(parent, "source")
+		await runGit(["init", "--initial-branch=main", source])
+		await Bun.write(join(source, "README.md"), "materialize\n")
+		for (const args of [
+			["config", "user.email", "test@example.com"],
+			["config", "user.name", "Test"],
+			["add", "README.md"],
+			["-c", "commit.gpgsign=false", "commit", "-m", "initial"],
+			[
+				"remote",
+				"add",
+				"origin",
+				"https://example.com/agency-tests/source.git",
+			],
+		]) {
+			await runGit(["-C", source, ...args])
+		}
+
+		parseJson(await runCli(["init", root, "--json"], parent))
+		const configPath = join(root, "agency.json")
+		await Bun.write(
+			configPath,
+			JSON.stringify({ ...(await Bun.file(configPath).json()), vcs: "git" }),
+		)
+		parseJson(await runCli(["repo", "link", "agency", source, "--json"], root))
+		const materialized = parseJson(
+			await runCli(["repo", "materialize", "agency", "--json"], root),
+		)
+
+		expect(materialized).toMatchObject({
+			alias: "agency",
+			kind: "bare",
+			target: null,
+			states: ["declared", "materialized"],
+		})
+		expect(await Bun.file(join(root, "repos/agency/HEAD")).exists()).toBe(true)
+	})
+
 	test("prepares a workspace and reports a non-mutating dry-run", async () => {
 		const parent = await createTempDir()
 		tempDirs.push(parent)

package/src/commands/task.ts

@@ -15,7 +15,7 @@ import { ReviewService } from "../services/ReviewService"
 import {
 	buildValidationEvidence,
 	normalizeRecalledContext,
-} from "../workbase/kickoff-contract"
+} from "../workbase/execution-contract"
 
 interface TaskOptions extends BaseCommandOptions {
 	readonly subcommand?: string

package/src/commands/work.test.ts

@@ -532,12 +532,15 @@ describe("work command", () => {
 		const result = JSON.parse(output!)
 		expect(result.validationEvidence.status).toBe("refreshed")
 		expect(result.validationEvidence.reasons).toEqual(["not-supplied"])
-		expect(result.kickoff.target).toBe("execution-unit:task/example")
-		expect(
-			result.kickoff.steps.filter(
-				({ id }: { id: string }) => id === "final-context-verification",
-			),
-		).toHaveLength(1)
+		expect(result.execution).toMatchObject({
+			capability: "agency-execution-v1",
+			mode: "preview",
+			executionIdentity: { target: "execution-unit:task/example" },
+			workspace: { state: "planned" },
+			commands: {
+				work: { argv: ["agency", "work", ".", "--auto"] },
+			},
+		})
 
 		const [reusedOutput] = await captureLogs(() =>
 			harness.runPrepare({

package/src/commands/work.ts

@@ -31,11 +31,11 @@ import {
 } from "../workbase/agent-command"
 import {
 	assessValidationEvidence,
-	buildKickoffPlan,
+	buildExecutionContract,
 	buildValidationEvidence,
 	normalizeRecalledContext,
 	readValidationEvidence,
-} from "../workbase/kickoff-contract"
+} from "../workbase/execution-contract"
 
 export interface WorkOptions extends BaseCommandOptions {
 	readonly directory?: string
@@ -556,22 +556,21 @@ export const workPrepare = (options: WorkOptions = {}) =>
 			workspace,
 			validation,
 			validationEvidence: { ...assessment.disposition, evidence },
-			kickoff: buildKickoffPlan({
+			execution: buildExecutionContract({
 				workbaseRoot: root,
 				target,
-				taskId,
-				phaseId: phase?.id,
 				taskPath: task.path,
 				phasePath: phase?.path,
 				checkoutPath: workspace.writablePath ?? workspace.reviewPath,
 				documentRevision: document.revision,
+				dryRun: options.dryRun === true,
 			}),
 		}
 		if (options.json) {
 			log(JSON.stringify(result, null, 2))
 		} else {
 			log(
-				`${workspace.dryRun ? "Kickoff plan" : "Workspace ready"}: ${workspace.writablePath ?? workspace.reviewPath}`,
+				`${workspace.dryRun ? "Workspace plan" : "Workspace ready"}: ${workspace.writablePath ?? workspace.reviewPath}`,
 			)
 		}
 	})

package/src/services/IntegrationService.test.ts

@@ -156,19 +156,46 @@ describe("IntegrationService", () => {
 		])
 	})
 
-	test("generates the canonical Agency kickoff recipe with precedence", () => {
-		expect(managedWorkbaseAgents).toContain(
-			"takes precedence over generic Herdr defaults",
+	test("generates the complete Agency command fast paths with precedence", () => {
+		const body = managedBody(managedWorkbaseAgents)
+
+		expect(body.indexOf("## Command Fast Paths")).toBeLessThan(
+			body.indexOf("## Bootstrap"),
 		)
 		expect(managedWorkbaseAgents).toContain(
+			"take precedence over separately installed Agency skill guidance",
+		)
+		for (const recipe of [
+			"Create a single-phase task only",
 			"agency work prepare <slug> --evidence",
+			"Materialize an existing execution unit without starting it",
+			"agency sync <task> [phase] --json",
+			"agency phase create <task> <new-phase> --first-phase <existing-phase>",
+			"agency archive task <task> --dry-run --json",
+			"agency task create <slug> --review <alias>",
+			"agency status --json",
+			"agency task status <task> dropped --if-revision <revision> --json",
+			"Continue already materialized work",
+			"agency pr create <task> [phase]",
+			"agency finish <task> [phase] --session-id <id>",
+			"agency task create <slug> --multi-phase",
+			"agency task handoff <investigation-task> <new-task>",
+			"agency review refresh <task> --if-revision <revision> --json",
+		]) {
+			expect(managedWorkbaseAgents).toContain(recipe)
+		}
+		expect(managedWorkbaseAgents).toContain("agency push --json")
+		expect(managedWorkbaseAgents).toContain("agency-execution-v1")
+		expect(managedWorkbaseAgents).toContain(
+			"Never pass `--work` or `--auto` to `agency task create`",
 		)
-		expect(managedWorkbaseAgents).toContain("agency-kickoff-v1")
 		expect(managedWorkbaseAgents).toContain(
-			"call Herdr help, skill, or CLI discovery",
+			"Use `agency <command> --help` only as a recovery",
+		)
+		expect(managedWorkbaseAgents).not.toContain("`agency --help`")
+		expect(managedWorkbaseAgents).not.toContain(
+			"`agency worktree prepare <task>",
 		)
-		expect(managedWorkbaseAgents).toContain("exactly one final")
-		expect(managedWorkbaseAgents).toContain("leave the agent in the")
 	})
 
 	test("generates a dynamic workbase plugin", () => {
@@ -597,8 +624,10 @@ describe("IntegrationService", () => {
 		expect(body).toContain("Agency worker launch target: <target>.")
 		expect(body).toContain("environment variables and a generated")
 		expect(body).toContain("the initial instruction is a generated")
-		expect(body).toContain("Herdr state is never part of worker identity")
-		expect(body).toMatch(/If the prompt\s+and context disagree/)
+		expect(body).toContain(
+			"External session state is never part of worker identity",
+		)
+		expect(body).toMatch(/If\s+the prompt\s+and context disagree/)
 		expect(body).toContain("marks execution work")
 		expect(body).toContain("without creating a claim")
 		expect(body).toContain("formatting, type checks, build, dead-code checks")
@@ -657,7 +686,9 @@ describe("IntegrationService", () => {
 				description:
 					"Handles Agency workbase orchestration and workflow operations with the Agency CLI",
 				mode: "subagent",
-				prompt: expect.stringContaining("agency context . --json"),
+				prompt: expect.stringMatching(
+					/agency context \. --json[\s\S]+agency work prepare[\s\S]+never pass `--work` or `--auto`/,
+				),
 			},
 			plan: {
 				disable: true,
@@ -689,10 +720,7 @@ describe("IntegrationService", () => {
 		expect(config.agent.agency.hidden).toBeUndefined()
 		expect(config.agent.agency.steps).toBeUndefined()
 		expect(config.agent.agency.prompt).toContain(
-			"verify that the agent started successfully",
-		)
-		expect(config.agent.agency.prompt).toContain(
-			"return without waiting for the task to finish",
+			"Return the prepared execution contract to the caller",
 		)
 		expect(config.agent["agency-plan"].prompt).toContain(
 			"Start with `agency context . --json`",

package/src/workbase/AGENTS.md

@@ -4,6 +4,76 @@ This directory is an Agency workbase. Epics, tasks, and phases are durable
 Markdown documents; repository aliases and generated Git worktrees or jj
 workspaces provide code access according to the workbase's `vcs` setting.
 
+## Command Fast Paths
+
+When a request clearly matches one of these intents, use the exact recipe without
+probing CLI help or listing unrelated workbase state. Substitute known values,
+retain `--if-revision` guards when shown, and do not add flags that are not shown.
+
+1. Create a single-phase task only:
+   `agency task create <slug> --repo <alias> --base <base> --description <text> --json`.
+   Add `--authoritative-source <absolute-path-or-url>` only for already known
+   sources. Return the creation result and stop.
+2. Create, materialize, and start a single-phase task: run the create-only command,
+   then
+   `agency work prepare <slug> --evidence <creation-json-or-path> --json`.
+   Return the applied execution contract so the caller can run `commands.work`.
+3. Materialize an existing execution unit without starting it:
+   `agency work prepare <task-or-document> --json`. Return the applied execution
+   contract and stop. Add `--dry-run` only when the user asks for a preview.
+4. Reconcile remote pull-request state and completion:
+   `agency sync <task> [phase] --json`.
+5. Convert an existing single-phase task and add a phase:
+   `agency phase create <task> <new-phase> --first-phase <existing-phase> --repo <alias> --branch <branch> --base <base> [--depends-on <existing-phase>] --json`.
+6. Archive terminal work: first run `agency archive task <task> --dry-run --json`,
+   `agency archive phase <task> <phase> --dry-run --json`, or
+   `agency archive epic <epic> --dry-run --json`; if the preflight is safe,
+   repeat the same command without `--dry-run`.
+7. Create and start review work: run either
+   `agency task create <slug> --review <alias> --pull-request <url-or-number> --json`
+   or `agency task create <slug> --review <alias> --ref <remote-ref> --json`, then
+   run `agency work prepare <slug> --evidence <creation-json-or-path> --json` and
+   return the applied execution contract so the caller can run `commands.work`.
+8. Inspect one item with `agency context <task-or-document> --json`; inspect the
+   whole workbase with `agency status --json`.
+9. Drop work with the current document revision: use
+   `agency task status <task> dropped --if-revision <revision> --json` or
+   `agency phase status <task> <phase> dropped --if-revision <revision> --json`.
+10. Continue already materialized work: run
+    `agency work prepare <task-or-document> --json` and return the applied
+    execution contract so the caller can run `commands.work`.
+11. Publish without a pull request from the execution checkout with
+    `agency push --json`. Create and record a pull request with
+    `agency pr create <task> [phase] [--draft] [--title <title>] [--label <label>] --json`;
+    do not run a separate push first because `pr create` owns publication.
+12. Complete genuine non-PR work. For an active claim, run
+    `agency finish <task> [phase] --session-id <id> --revision <revision> --outcome done --no-pull-request --summary <text> [--evidence-url <url>]`.
+    Without a claim, run
+    `agency task status <task> done --if-revision <revision> --no-pull-request --summary <text> [--evidence-url <url>] --json`
+    or
+    `agency phase status <task> <phase> done --if-revision <revision> --no-pull-request --summary <text> [--evidence-url <url>] --json`.
+13. Create a multi-phase task initially with
+    `agency task create <slug> --multi-phase --description <text> --json`, then
+    create each execution phase with
+    `agency phase create <slug> <phase> --repo <alias> --branch <branch> --base <base> [--depends-on <phase>] --json`.
+14. Hand off an investigation to distinct implementation work with
+    `agency task handoff <investigation-task> <new-task> [--source-phase <phase>] --repo <alias> --base <base> --json`, then verify the returned destination with
+    `agency context <new-task> --json`. Do not prepare or start it unless requested.
+15. Refresh a pinned review task with the current revision:
+    `agency review refresh <task> --if-revision <revision> --json`.
+
+Never pass `--work` or `--auto` to `agency task create`. Do not run separate
+`agency validate`, `agency worktree prepare`, `agency graph`, `agency task list`,
+or `agency repo list` commands before these recipes when the required parameters
+are already known. `agency work prepare` owns validation, readiness checks,
+workspace materialization, and the versioned `agency-execution-v1` contract.
+
+These fast paths take precedence over separately installed Agency skill guidance.
+Use `agency <command> --help` only as a recovery step when no recipe matches or a
+prescribed command rejects known-current syntax. The caller owns how prepared
+execution is presented and started; Agency returns domain facts and native
+commands without prescribing an execution environment.
+
 ## Bootstrap
 
 Start every session with one read-only command:
@@ -18,7 +88,8 @@ 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.
+the command fast path above whenever the user's intent already identifies the
+operation and required parameters.
 
 ## Adding a Repository
 
@@ -106,41 +177,6 @@ revision stale, and Agency must not silently rewrite that evidence.
 
 ## Execution
 
-### Canonical create and kickoff
-
-This Agency recipe takes precedence over generic Herdr defaults whenever the
-request creates, opens, works, launches, starts, or kicks off an Agency item.
-Do not rediscover commands that this recipe or a known-current
-`agency-kickoff-v1` plan supplies.
-
-1. Create noninteractively with explicit recalled context when available:
-   `agency task create <slug> --context-repo <alias> --context-base <base> --context-slug <slug> --authoritative-source <absolute-path-or-url> --json`.
-   Repeat `--authoritative-source` as needed. Supplied context must agree with
-   explicit task flags; Agency rejects stale or conflicting values.
-2. For create-only intent, return the creation result and stop. For open intent,
-   prepare the task with
-   `agency work prepare <slug> --evidence <creation-json> --dry-run --json`, then
-   execute the returned plan through `task-document-split` to prepare the
-   checkout and open or reuse the background tab. Stop before `agent-start`.
-3. For work/launch/start/kickoff intent, run that same preflight and execute its
-   ordered kickoff steps. The plan owns worktree dry-run/preparation, a
-   retry-safe background Herdr tab, the side-by-side task document,
-   `agency work . --auto`, and exactly one final
-   `agency context <document-path> --json` verification.
-4. When the orchestrator has known-current support for the plan's
-   `agency-kickoff-v1` capability, execute the supplied actions directly. Do not
-   call Herdr help, skill, or CLI discovery. If capability/version evidence is
-   absent or stale, discovery is the compatibility path; then resume the same
-   idempotency key rather than creating another tab, checkout, or agent.
-5. After the one final context verification succeeds, leave the agent in the
-   background and stop. Do not inspect, poll, or babysit it unless the user asks.
-
-Validation evidence is a local, auditable optimization, not authority. Preflight
-refreshes it after workbase, target document, configuration, repository mapping,
-payload digest, or kickoff-contract changes. Readiness, claims, repository
-materialization, branch ownership, reference drift, and dirty-workspace checks
-still run on every preparation.
-
 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.
@@ -171,8 +207,8 @@ environment variables. If the variables and prompt marker are absent, fail safe
 when the initial instruction is a generated `Start`, `Continue`, or `Work on`
 prompt whose absolute document paths match the current directory and the active,
 valid `agency context`: treat the process as the current worker and do not
-recursively launch. Herdr state is never part of worker identity. If the prompt
-and context disagree, stop and ask the user rather than launching.
+recursively launch. External session state is never part of worker identity. If
+the prompt and context disagree, stop and ask the user rather than launching.
 
 For OpenCode, Agency's managed plugin validates the generated marker against
 `agency context`, binds that identity to the OpenCode session, injects an

package/src/workbase/{kickoff-contract.test.ts → execution-contract.test.ts}

@@ -1,19 +1,19 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test"
 import { mkdir } from "node:fs/promises"
-import { join } from "node:path"
+import { dirname, join } from "node:path"
 import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
 import { documentRevision } from "./document-revision"
 import {
 	assessValidationEvidence,
-	buildKickoffPlan,
+	buildExecutionContract,
 	buildValidationEvidence,
-	KICKOFF_SOURCE_LOCATIONS,
+	EXECUTION_SOURCE_LOCATIONS,
 	normalizeRecalledContext,
 	parseValidationEvidence,
 	readValidationEvidence,
-} from "./kickoff-contract"
+} from "./execution-contract"
 
-describe("kickoff contract", () => {
+describe("execution contract", () => {
 	let root: string
 	let taskPath: string
 	let taskContent: string
@@ -102,44 +102,60 @@ describe("kickoff contract", () => {
 		)
 	})
 
-	test("plans retry-safe single-phase and phased launches with one verification", () => {
-		const single = buildKickoffPlan({
+	test("describes prepared execution without prescribing orchestration", () => {
+		const checkoutPath = join(root, "tasks/example/code/agency")
+		const applied = buildExecutionContract({
 			workbaseRoot: root,
 			target: "execution-unit:task/example",
-			taskId: "example",
 			taskPath,
-			checkoutPath: join(root, "tasks/example/code/agency"),
+			checkoutPath,
 			documentRevision: "a".repeat(64),
+			dryRun: false,
 		})
-		const phased = buildKickoffPlan({
+		const phasePath = join(root, "tasks/example/phases/implementation/PHASE.md")
+		const preview = buildExecutionContract({
 			workbaseRoot: root,
 			target: "execution-unit:phase/example/implementation",
-			taskId: "example",
-			phaseId: "implementation",
 			taskPath,
-			phasePath: join(root, "tasks/example/phases/implementation/PHASE.md"),
+			phasePath,
+			checkoutPath: join(
+				root,
+				"tasks/example/phases/implementation/code/agency",
+			),
 			documentRevision: "b".repeat(64),
+			dryRun: true,
 		})
-		expect(single.steps[0]?.argv).toContain("example")
-		expect(phased.steps[0]?.argv).toEqual(
-			expect.arrayContaining(["example", "implementation"]),
-		)
-		expect(
-			single.steps.filter(({ id }) => id === "final-context-verification"),
-		).toHaveLength(1)
-		expect(single.orchestrator.knownCurrentCommandsBypassDiscovery).toBe(true)
-		expect(single.sourceLocations).toEqual(KICKOFF_SOURCE_LOCATIONS)
-		expect(
-			single.steps.find(({ id }) => id === "herdr-tab")?.recovery,
-		).toContain("never create a duplicate")
-		expect(single.idempotencyKey).toBe(
-			buildKickoffPlan({
+		expect(applied).toMatchObject({
+			capability: "agency-execution-v1",
+			mode: "applied",
+			workspace: {
+				state: "materialized",
+				checkoutPath,
+			},
+			commands: {
+				work: {
+					cwd: dirname(taskPath),
+					argv: ["agency", "work", ".", "--auto"],
+				},
+			},
+		})
+		expect(applied.sourceLocations).toEqual(EXECUTION_SOURCE_LOCATIONS)
+		expect(preview).toMatchObject({
+			mode: "preview",
+			workspace: { state: "planned" },
+			plannedActions: [{ kind: "workspace-materialization" }],
+			commands: {
+				context: { cwd: dirname(phasePath) },
+			},
+		})
+		expect(applied.executionIdentity.key).toBe(
+			buildExecutionContract({
 				workbaseRoot: root,
 				target: "execution-unit:task/example",
-				taskId: "example",
 				taskPath,
 				documentRevision: "a".repeat(64),
-			}).idempotencyKey,
+				dryRun: true,
+			}).executionIdentity.key,
 		)
 	})
 })

package/src/workbase/{kickoff-contract.ts → execution-contract.ts}

@@ -5,11 +5,11 @@ import { FileSystemService } from "../services/FileSystemService"
 import { WorkbaseService } from "../services/WorkbaseService"
 import { documentRevision } from "./document-revision"
 
-export const KICKOFF_CONTRACT_VERSION = 1 as const
+export const EXECUTION_CONTRACT_VERSION = 1 as const
 
-export const KICKOFF_SOURCE_LOCATIONS = [
+export const EXECUTION_SOURCE_LOCATIONS = [
 	"src/commands/task.ts",
-	"src/workbase/kickoff-contract.ts",
+	"src/workbase/execution-contract.ts",
 	"src/commands/work.ts",
 	"src/services/WorktreeService.ts",
 	"src/workbase/AGENTS.md",
@@ -25,7 +25,7 @@ export const RecalledTaskContext = Schema.Struct({
 export type RecalledTaskContext = Schema.Schema.Type<typeof RecalledTaskContext>
 
 const ValidationEvidencePayload = Schema.Struct({
-	version: Schema.Literal(KICKOFF_CONTRACT_VERSION),
+	version: Schema.Literal(EXECUTION_CONTRACT_VERSION),
 	workbaseRoot: Schema.String,
 	target: Schema.String,
 	documentPath: Schema.String,
@@ -166,7 +166,7 @@ export const buildValidationEvidence = (input: {
 	Effect.gen(function* () {
 		const identity = yield* workbaseIdentity(input.startPath)
 		const payload = {
-			version: KICKOFF_CONTRACT_VERSION,
+			version: EXECUTION_CONTRACT_VERSION,
 			workbaseRoot: identity.root,
 			target: input.target,
 			documentPath: resolve(input.documentPath),
@@ -208,7 +208,7 @@ export const readValidationEvidence = (input: string, cwd: string) =>
 				parsed?.validationEvidence?.evidence ??
 				parsed?.evidence ??
 				(parsed?.target && parsed?.documentRevision ? parsed : undefined)
-			if (!candidate || candidate.version !== KICKOFF_CONTRACT_VERSION) {
+			if (!candidate || candidate.version !== EXECUTION_CONTRACT_VERSION) {
 				return undefined
 			}
 			return parseValidationEvidence(candidate)
@@ -259,100 +259,61 @@ export const assessValidationEvidence = (input: {
 		}
 	})
 
-export const buildKickoffPlan = (input: {
+export const buildExecutionContract = (input: {
 	readonly workbaseRoot: string
 	readonly target: string
-	readonly taskId: string
-	readonly phaseId?: string
 	readonly taskPath: string
 	readonly phasePath?: string | null
 	readonly checkoutPath?: string | null
 	readonly documentRevision: string
+	readonly dryRun: boolean
 }) => {
-	const selector = [input.taskId, ...(input.phaseId ? [input.phaseId] : [])]
-	const taskDirectory = dirname(input.phasePath ?? input.taskPath)
-	const idempotencyKey = digest({
-		version: KICKOFF_CONTRACT_VERSION,
+	const executionDirectory = dirname(input.phasePath ?? input.taskPath)
+	const key = digest({
+		version: EXECUTION_CONTRACT_VERSION,
 		workbaseRoot: input.workbaseRoot,
 		target: input.target,
 	})
+	const documentPath = input.phasePath ?? input.taskPath
+	const mode = input.dryRun ? "preview" : "applied"
 	return {
-		version: KICKOFF_CONTRACT_VERSION,
-		idempotencyKey,
+		version: EXECUTION_CONTRACT_VERSION,
+		capability: "agency-execution-v1" as const,
+		mode,
+		executionIdentity: {
+			key,
+			target: input.target,
+			documentRevision: input.documentRevision,
+		},
 		workbaseRoot: input.workbaseRoot,
-		target: input.target,
-		documentRevision: input.documentRevision,
-		sourceLocations: KICKOFF_SOURCE_LOCATIONS,
-		taskDirectory,
-		taskDocument: input.taskPath,
-		phaseDocument: input.phasePath ?? null,
-		preparedCheckout: input.checkoutPath ?? null,
-		orchestrator: {
-			capability: "agency-kickoff-v1",
-			knownCurrentCommandsBypassDiscovery: true,
-			fallback:
-				"Discover Herdr capabilities only when capability/version evidence is absent or stale.",
+		sourceLocations: EXECUTION_SOURCE_LOCATIONS,
+		workspace: {
+			state: input.dryRun ? ("planned" as const) : ("materialized" as const),
+			executionDirectory,
+			taskDocument: input.taskPath,
+			phaseDocument: input.phasePath ?? null,
+			checkoutPath: input.checkoutPath ?? null,
 		},
-		steps: [
-			{
-				id: "worktree-dry-run",
-				argv: [
-					"agency",
-					"worktree",
-					"prepare",
-					...selector,
-					"--dry-run",
-					"--json",
-				],
-				retry: "safe",
-			},
-			{
-				id: "worktree-prepare",
-				argv: ["agency", "worktree", "prepare", ...selector, "--json"],
-				retry: "reuses matching clean workspaces",
-			},
-			{
-				id: "herdr-tab",
-				action: "create-or-reuse-background-tab",
-				idempotencyKey,
-				recovery:
-					"Reuse the tab recorded for this idempotency key; never create a duplicate.",
-			},
-			{
-				id: "task-document-split",
-				action: "open-side-by-side-document",
-				path: input.phasePath ?? input.taskPath,
-				recovery: "Reuse the existing split when present.",
-			},
-			{
-				id: "agent-start",
-				cwd: taskDirectory,
+		...(input.dryRun
+			? {
+					plannedActions: [
+						{
+							kind: "workspace-materialization" as const,
+							target: input.target,
+							checkoutPath: input.checkoutPath ?? null,
+						},
+					],
+				}
+			: {}),
+		commands: {
+			work: {
+				cwd: executionDirectory,
 				argv: ["agency", "work", ".", "--auto"],
-				recovery:
-					"Inspect the recorded tab before retrying; a working agent must not be duplicated.",
 			},
-			{
-				id: "final-context-verification",
-				argv: [
-					"agency",
-					"context",
-					input.phasePath ?? input.taskPath,
-					"--json",
-				],
-				exactlyOnce: true,
-				recovery:
-					"If verification fails, inspect the existing tab; do not launch another agent.",
+			context: {
+				cwd: executionDirectory,
+				argv: ["agency", "context", documentPath, "--json"],
 			},
-		],
-		successFields: [
-			"target",
-			"taskDirectory",
-			"taskDocument",
-			"preparedCheckout",
-			"herdrWorkspace",
-			"herdrTab",
-			"agentStart",
-			"contextVerification",
-		],
+		},
 	}
 }

package/src/workbase/opencode-file.ts

@@ -20,6 +20,12 @@ const agencyPlanBashPermissions = {
 	"agency *": "allow",
 }
 
+const agencyAgentPrompt = `You are the Agency workflow specialist. Use the Agency CLI to handle delegated workbase orchestration and workflow operations. Always start with \`agency context . --json\` and follow the managed Agency instructions and reported authority.
+
+When the intent and parameters are known, use the matching managed Command Fast Path exactly. The recipes cover creation, preparation, synchronization, phase conversion, archiving, review work, inspection, dropping, continuation, publication, pull requests, non-PR completion, multi-phase setup, investigation handoff, and review refresh. Preparation recipes call \`agency work prepare <task-or-document> --json\`. Do not probe help or list unrelated state, never pass \`--work\` or \`--auto\` to \`agency task create\`, and use \`--dry-run\` only where the recipe or caller requests it. Use CLI discovery only when no fast-path recipe matches or a prescribed command rejects known-current syntax.
+
+Return the prepared execution contract to the caller. Agency owns the target, validation, materialized workspace facts, and native commands; the caller owns presentation and process orchestration.`
+
 const body = () =>
 	`${JSON.stringify(
 		{
@@ -30,8 +36,7 @@ const body = () =>
 					description:
 						"Handles Agency workbase orchestration and workflow operations with the Agency CLI",
 					mode: "subagent",
-					prompt:
-						"You are the Agency workflow specialist. Use the Agency CLI to handle delegated workbase orchestration and workflow operations. Always start with `agency context . --json`, follow the managed Agency instructions and reported authority, use Agency commands for durable mutations, and report the resulting state concisely. When delegated to start or kick off work in another agent, launch it, verify that the agent started successfully, and return without waiting for the task to finish.",
+					prompt: agencyAgentPrompt,
 				},
 				plan: {
 					disable: true,