@markjaquith/agency 2.40.0 → 2.41.0

package/README.md

@@ -80,10 +80,10 @@ workbase/
 
 Agency keeps discovery and other observational commands read-only. Run
 `agency integration status` to inspect `.agency/AGENTS.md` and
-`.opencode/opencode.jsonc`, then `agency integration sync` to create missing
-files or refresh 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.
+`.opencode/opencode.jsonc`, and `.opencode/command/agency.md`, then `agency
+integration sync` to create missing files or refresh 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.
 
 When upgrading an existing workbase, synchronization moves a checksum-valid
 Agency-managed root `AGENTS.md` to `.agency/AGENTS.md` once the OpenCode config
@@ -96,6 +96,13 @@ reference. OpenCode discovers that config from task and epic launch directories.
 Agents receive whole-workbase visibility from that reference. Bash and Agency
 operations must still follow the write authority reported by `agency context`.
 
+OpenCode also discovers a managed `/agency` command. Use `/agency status` for a
+read-only current-work summary, `/agency start [target]` to begin or resume work
+in the active session, `/agency next` to inspect ready work, `/agency validate`
+to check the workbase, and `/agency finish [target]` for verified closeout. The
+command uses OpenCode positional arguments internally and defaults to the safe
+`status` workflow when no subcommand is supplied.
+
 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,
@@ -569,7 +576,7 @@ Targeted commands accept `--epic`, `--task`, and `--phase` where those entity
 kinds apply. A phase selector requires a task selector. Entity selectors cannot
 be mixed with positional target IDs, and an epic selector cannot be mixed with
 task or phase selectors. This makes commands such as
-`agency phase status done --task ship --phase release --workbase primary --no-input`
+`agency phase status working --task ship --phase release --workbase primary --no-input`
 fully independent of process cwd and prompts.
 
 Inspect tasks:
@@ -577,7 +584,7 @@ Inspect tasks:
 ```text
 agency task list [filters] [--json]
 agency task show <id> [--json]
-agency task status <id> <open|done|dropped> [--json]
+agency task status <id> <open|working|dropped> [--json]
 agency task update <id> [metadata options] [--json]
 agency task rename <id> <new-id> [--json]
 agency task move <id> (--epic <epic-id> | --no-epic) [--json]
@@ -616,7 +623,7 @@ agency phase create <task-id> <phase-id>
 
 agency phase list <task-id> [filters] [--json]
 agency phase show <task-id> <phase-id> [--json]
-agency phase status <task-id> <phase-id> <open|done|dropped> [--json]
+agency phase status <task-id> <phase-id> <open|working|dropped> [--json]
 agency phase update <task-id> <phase-id> [metadata options] [--json]
 agency phase rename <task-id> <phase-id> <new-id> [--json]
 agency phase dependency <add|remove> <task-id> <phase-id> <dependency-id>
@@ -639,6 +646,8 @@ writing anything.
 Single-phase tasks and phases store status in YAML. New execution units start
 `open`, and `agency work` marks the selected execution unit `working` immediately
 before launch. Running `agency work` again can relaunch unclaimed `working` work.
+The `done` status is reserved for an authoritative merged pull request and is
+applied by `agency sync --apply`, not by task or phase status commands.
 Use explicit claims only when an external orchestrator needs coordinated
 ownership. The interactive work selector displays status markers before
 execution units. Existing working and delegated work may be released to `open`
@@ -672,11 +681,12 @@ agency finish <task-id> [phase-id] --session-id <id>
   --revision <sha256> --outcome <done|dropped> [--json]
 ```
 
-An active claim sets status to `working`. Release returns it to `open`; finish
-sets the terminal outcome. Released and finished ownership metadata remains in
-frontmatter. Conflicts return the current revision and complete ownership record
-in the machine error envelope rather than overwriting it. Expired claims may be
-replaced with a revision-guarded claim.
+An active claim sets status to `working`. Release returns it to `open`. Finish
+records the claim outcome and ownership history; a `done` claim outcome leaves
+the execution unit `working` until its pull request is merged, while `dropped`
+remains terminal. Conflicts return the current revision and complete ownership
+record in the machine error envelope rather than overwriting it. Expired claims
+may be replaced with a revision-guarded claim.
 
 `agency work` does not claim execution units. It refuses active explicit claims,
 marks open execution work `working`, and launches the runner. External

package/package.json

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

package/skills/agency/SKILL.md

@@ -118,11 +118,12 @@ independently meaningful tasks need coordination.
 
 1. Re-run `agency validate` and repository checks.
 2. Create a PR only when requested: `agency pr create <task> [phase]`.
-3. Record terminal state only when the requested outcome is true. A created PR
-   alone does not make work `done` if completion requires merge.
-4. If the session has a claim, use revision-guarded `agency finish`; otherwise
-   use the task or phase status command. Use `dropped` only for intentionally
-   abandoned work.
+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

package/skills/agency/references/commands.md

@@ -89,7 +89,7 @@ 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|done|dropped> [--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)
@@ -102,7 +102,7 @@ agency phase create <task-id> <phase-id> --repo <alias> --branch <name>
   [--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|done|dropped> [--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>

package/skills/agency/references/contracts.md

@@ -137,6 +137,8 @@ readable legacy state but cannot be newly assigned.
 - 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.

package/skills/agency/references/recipes.md

@@ -184,15 +184,17 @@ agency release checkout ui --session-id session-123 \
 
 ## Finish Verified Work
 
-Only after the assigned completion condition is true:
+After the claimed run completes successfully:
 
 ```bash
 agency finish checkout ui --session-id session-123 \
   --revision <current-sha256> --outcome done --json
 ```
 
-Do not substitute `phase status done` for `finish` when an active claim exists;
-`finish` preserves ownership history and revision safety.
+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
 

package/src/cli.test.ts

@@ -244,6 +244,10 @@ describe("CLI", () => {
 			),
 		)
 		expect(finished.claim).toMatchObject({ state: "finished", outcome: "done" })
+		expect(
+			parseJson(await runCli(["task", "show", "claimed", "--json"], root)).data
+				.status,
+		).toBe("working")
 	})
 
 	test("routes graph mutations through structured output", async () => {
@@ -476,7 +480,7 @@ describe("CLI", () => {
 			)
 		}
 		parseJson(
-			await runCli(["task", "status", "finished", "done", "--json"], root),
+			await runCli(["task", "status", "finished", "dropped", "--json"], root),
 		)
 
 		const human = await runCli(["next"], root)
@@ -490,9 +494,9 @@ describe("CLI", () => {
 		expect(result.excluded).toMatchObject([
 			{
 				key: "task/finished",
-				status: "done",
+				status: "dropped",
 				terminal: true,
-				blockers: [{ kind: "status", reason: "Task status is done" }],
+				blockers: [{ kind: "status", reason: "Task status is dropped" }],
 			},
 		])
 
@@ -504,8 +508,8 @@ describe("CLI", () => {
 			error: {
 				code: "EXECUTION_BLOCKED",
 				fields: {
-					status: "done",
-					blockers: [{ kind: "status", reason: "Task status is done" }],
+					status: "dropped",
+					blockers: [{ kind: "status", reason: "Task status is dropped" }],
 				},
 			},
 		})
@@ -522,6 +526,7 @@ describe("CLI", () => {
 		expect(before.files).toMatchObject([
 			{ name: "agents", state: "managed" },
 			{ name: "opencode", state: "managed" },
+			{ name: "opencode-command", state: "managed" },
 		])
 
 		const synced = parseJson(
@@ -530,6 +535,7 @@ describe("CLI", () => {
 		expect(synced.files).toMatchObject([
 			{ name: "agents", state: "managed", changed: false },
 			{ name: "opencode", state: "managed", changed: false },
+			{ name: "opencode-command", state: "managed", changed: false },
 		])
 	})
 
@@ -1131,18 +1137,18 @@ status: open
 			}
 
 			parseJson(
-				await runCli(["task", "status", "example", "done", "--json"], root),
+				await runCli(["task", "status", "example", "dropped", "--json"], root),
 			)
 			const blocked = await runCli(
 				["work", "--task", "example", "--runner", "noop"],
 				root,
 			)
 			expect(blocked.exitCode).toBe(1)
-			expect(blocked.stderr).toContain("Task status is done")
+			expect(blocked.stderr).toContain("Task status is dropped")
 			expect(
 				parseJson(await runCli(["task", "show", "example", "--json"], root))
 					.data.status,
-			).toBe("done")
+			).toBe("dropped")
 
 			const resumedTask = await runCli(
 				["work", "--task", "example", "--runner", "noop", "--force"],
@@ -1150,7 +1156,7 @@ status: open
 			)
 			expect(resumedTask).toMatchObject({ exitCode: 0, stderr: "" })
 			expect(resumedTask.stdout).toContain(
-				"Reopened task/example from done as working",
+				"Reopened task/example from dropped as working",
 			)
 			expect(
 				parseJson(await runCli(["task", "show", "example", "--json"], root))

package/src/commands/claim.ts

@@ -93,5 +93,6 @@ Release an execution unit owned by the session.
 export const finishHelp = `
 Usage: agency finish <task-id> [phase-id] --session-id <id> --revision <sha256> --outcome <done|dropped>
 
-Finish an execution unit owned by the session.
+Finish a claim owned by the session. A done claim outcome leaves unmerged work
+working; agency sync --apply marks the execution unit done after merge.
 `

package/src/commands/init.test.ts

@@ -44,6 +44,11 @@ describe("init command", () => {
 			workbase: expect.objectContaining({ path: ".." }),
 		})
 		expect(config.permission).toBeUndefined()
+		const command = await Bun.file(
+			join(root, ".opencode/command/agency.md"),
+		).text()
+		expect(command).toContain("Workflow: `$1`")
+		expect(command).toContain("Optional target: `$2`")
 	})
 
 	test("preserves existing gitignore entries", async () => {

package/src/commands/integration.test.ts

@@ -36,6 +36,11 @@ describe("integration command", () => {
 					diagnostic: expect.stringContaining("cannot load"),
 					remediation: expect.stringContaining("integration sync"),
 				},
+				{
+					name: "opencode-command",
+					state: "missing",
+					remediation: expect.stringContaining("integration sync"),
+				},
 			],
 		})
 	})
@@ -62,11 +67,15 @@ describe("integration command", () => {
 		expect(JSON.parse(logs[0]!).files).toMatchObject([
 			{ name: "agents", state: "managed", changed: true },
 			{ name: "opencode", state: "managed", changed: true },
+			{ name: "opencode-command", state: "managed", changed: true },
 		])
 		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(false)
 		expect(await Bun.file(join(root, ".agency/AGENTS.md")).exists()).toBe(true)
 		expect(
 			await Bun.file(join(root, ".opencode/opencode.jsonc")).exists(),
 		).toBe(true)
+		expect(
+			await Bun.file(join(root, ".opencode/command/agency.md")).exists(),
+		).toBe(true)
 	})
 })

package/src/commands/integration.ts

@@ -54,8 +54,8 @@ export const help = `
 Usage: agency integration <subcommand>
 
 Inspect or explicitly synchronize managed agent integration files. OpenCode
-launches load the managed file at runtime to provide whole-workbase read
-access without changing Agency write authority.
+launches load the managed instructions and project config at runtime, and expose
+the managed /agency command, without changing Agency write authority.
 
 Subcommands:
   status  Report file state, access diagnostics, and safe remediation

package/src/commands/phase.ts

@@ -275,7 +275,7 @@ Subcommands:
   list <task>           List task phases
   show <task> <phase>   Show a phase
   status <task> <phase> <status>
-                        Set open, working, done, or dropped
+                        Set open, working, or dropped
   update <task> <phase> Update phase metadata
   rename <task> <phase> <new-id>
                         Rename a phase and update dependencies

package/src/commands/read-only.test.ts

@@ -154,5 +154,8 @@ status: open
 		expect(
 			await Bun.file(join(root, ".opencode/opencode.jsonc")).exists(),
 		).toBe(false)
+		expect(
+			await Bun.file(join(root, ".opencode/command/agency.md")).exists(),
+		).toBe(false)
 	})
 })

package/src/commands/status.test.ts

@@ -74,7 +74,7 @@ describe("status command", () => {
 		await runTestEffect(
 			task({
 				subcommand: "status",
-				args: ["finished", "done"],
+				args: ["finished", "dropped"],
 				cwd: root,
 				silent: true,
 			}),

package/src/commands/task-phase.test.ts

@@ -239,13 +239,13 @@ describe("task and phase command JSON output", () => {
 			runTestEffect(
 				phase({
 					subcommand: "status",
-					args: ["multi", "first", "done"],
+					args: ["multi", "first", "working"],
 					cwd: root,
 					json: true,
 				}),
 			),
 		)
-		expect(JSON.parse(phaseLogs[0]!).data.status).toBe("done")
+		expect(JSON.parse(phaseLogs[0]!).data.status).toBe("working")
 
 		await runTestEffect(
 			task({
@@ -263,13 +263,13 @@ describe("task and phase command JSON output", () => {
 			runTestEffect(
 				task({
 					subcommand: "status",
-					args: ["single-status", "done"],
+					args: ["single-status", "working"],
 					cwd: root,
 					json: true,
 				}),
 			),
 		)
-		expect(JSON.parse(taskLogs[0]!).data.status).toBe("done")
+		expect(JSON.parse(taskLogs[0]!).data.status).toBe("working")
 	})
 
 	test("converts a single-phase task with an explicit first phase ID", async () => {

package/src/commands/task.ts

@@ -423,7 +423,7 @@ Subcommands:
   create <id>           Create a task without prompting
   list                  List tasks
   show <id>             Show a task
-  status <id> <status>  Set open, working, done, or dropped
+  status <id> <status>  Set open, working, or dropped
   update <id>           Update task metadata
   rename <id> <new-id>  Rename a task and update graph references
   move <id>             Move a task with --epic or --no-epic

package/src/readiness.ts

@@ -5,9 +5,9 @@ export interface ReadinessBlocker {
 }
 
 export const WORK_STATUS_TRANSITIONS = {
-	open: ["open", "working", "delegated", "done", "dropped"],
-	working: ["open", "working", "delegated", "done", "dropped"],
-	delegated: ["open", "working", "delegated", "done", "dropped"],
+	open: ["open", "working", "delegated", "dropped"],
+	working: ["open", "working", "delegated", "dropped"],
+	delegated: ["open", "working", "delegated", "dropped"],
 	done: ["open", "done"],
 	dropped: ["open", "dropped"],
 } as const satisfies Record<WorkStatus, readonly WorkStatus[]>

package/src/services/ClaimService.test.ts

@@ -139,7 +139,7 @@ describe("claim service", () => {
 				),
 			),
 		)
-		expect(finished.data.status).toBe("done")
+		expect(finished.data.status).toBe("working")
 		expect(finished.claim).toMatchObject({
 			state: "finished",
 			finishedAt: "2026-07-17T12:45:00.000Z",

package/src/services/ClaimService.ts

@@ -538,7 +538,11 @@ export class ClaimService extends Effect.Service<ClaimService>()(
 									outcome: input.outcome,
 								}
 								return {
-									data: { ...data, status: input.outcome, claim },
+									data: {
+										...data,
+										status: input.outcome === "done" ? "working" : "dropped",
+										claim,
+									},
 									claim,
 								}
 							},

package/src/services/IntegrationService.test.ts

@@ -5,6 +5,10 @@ import { mkdir, stat, symlink, unlink, utimes } from "node:fs/promises"
 import { dirname, join } from "node:path"
 import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
 import { managedWorkbaseAgents } from "../workbase/agents-file"
+import {
+	canUpdateManagedWorkbaseOpencodeCommand,
+	managedWorkbaseOpencodeCommand,
+} from "../workbase/opencode-command-file"
 import { managedWorkbaseOpencode } from "../workbase/opencode-file"
 import { IntegrationService } from "./IntegrationService"
 
@@ -46,14 +50,21 @@ describe("IntegrationService", () => {
 		expect((await status(root)).files.map(({ state }) => state)).toEqual([
 			"missing",
 			"missing",
+			"missing",
 		])
 		expect(await Bun.file(join(root, ".agency/AGENTS.md")).exists()).toBe(false)
 
 		await write(root, ".agency/AGENTS.md", managedWorkbaseAgents)
 		await write(root, ".opencode/opencode.jsonc", managedWorkbaseOpencode)
+		await write(
+			root,
+			".opencode/command/agency.md",
+			managedWorkbaseOpencodeCommand,
+		)
 		expect((await status(root)).files.map(({ state }) => state)).toEqual([
 			"managed",
 			"managed",
+			"managed",
 		])
 	})
 
@@ -68,9 +79,40 @@ describe("IntegrationService", () => {
 		expect((await status(root)).files.map(({ state }) => state)).toEqual([
 			"customized",
 			"drifted",
+			"missing",
 		])
 	})
 
+	test("generates a positional OpenCode command for Agency workflows", () => {
+		expect(managedWorkbaseOpencodeCommand).toContain(
+			"description: Operate Agency work",
+		)
+		expect(managedWorkbaseOpencodeCommand).toContain("Workflow: `$1`")
+		expect(managedWorkbaseOpencodeCommand).toContain("Optional target: `$2`")
+		expect(managedWorkbaseOpencodeCommand).toContain(
+			"Complete request: `$ARGUMENTS`",
+		)
+		for (const workflow of [
+			"start",
+			"status",
+			"next",
+			"validate",
+			"finish",
+			"help",
+		]) {
+			expect(managedWorkbaseOpencodeCommand).toContain(`- \`${workflow}\`:`)
+		}
+		expect(managedWorkbaseOpencodeCommand).toContain("Never run `agency work`")
+		expect(
+			canUpdateManagedWorkbaseOpencodeCommand(managedWorkbaseOpencodeCommand),
+		).toBe(true)
+		expect(
+			canUpdateManagedWorkbaseOpencodeCommand(
+				managedWorkbaseOpencodeCommand.replace("Workflow: `$1`", "Workflow"),
+			),
+		).toBe(false)
+	})
+
 	test("generates context-first safety and execution closeout guidance", () => {
 		const body = managedBody(managedWorkbaseAgents)
 
@@ -80,18 +122,20 @@ describe("IntegrationService", () => {
 		expect(body).toContain("External orchestrators claim before launching")
 		expect(body).toContain("Run `agency validate`")
 		expect(body).toContain("only with explicit user intent")
-		expect(body).toContain("An execution unit is `working`")
+		expect(body).toContain("An execution unit remains `working`")
 		expect(body).toContain("It becomes `done`")
-		expect(body).toContain("solely because its PR")
+		expect(body).toContain("Do not mark committed")
 		expect(body).toContain("creating or updating a PR")
 		expect(body).toContain("marking it ready")
 		expect(body).toMatch(/completing\s+a refinement loop/)
 		expect(body).toContain("pausing or handing off")
-		expect(body).toContain("`agency task status` or `agency phase status`")
+		expect(body).toContain("`agency finish`")
+		expect(body).toContain("`agency sync --apply`")
 		expect(body).toContain("`TASK.md` or `PHASE.md`")
 		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).toContain(".opencode/command/agency.md")
 	})
 
 	test("grants OpenCode access to the complete workbase", () => {
@@ -166,6 +210,7 @@ describe("IntegrationService", () => {
 		expect(first.files).toMatchObject([
 			{ name: "agents", state: "customized", changed: false },
 			{ name: "opencode", state: "managed", changed: true },
+			{ name: "opencode-command", state: "managed", changed: true },
 		])
 		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(
 			customRootAgents,
@@ -176,6 +221,9 @@ describe("IntegrationService", () => {
 		expect(await Bun.file(join(root, ".opencode/opencode.jsonc")).text()).toBe(
 			managedWorkbaseOpencode,
 		)
+		expect(
+			await Bun.file(join(root, ".opencode/command/agency.md")).text(),
+		).toBe(managedWorkbaseOpencodeCommand)
 
 		await unlink(join(root, ".agency/AGENTS.md"))
 		const second = await sync(root)
@@ -188,6 +236,34 @@ describe("IntegrationService", () => {
 		)
 	})
 
+	test("preserves user-owned OpenCode commands at either supported path", async () => {
+		const custom = "---\ndescription: Custom Agency command\n---\n\nCustom.\n"
+		await write(root, ".opencode/commands/agency.md", custom)
+
+		let result = await sync(root)
+		expect(result.files[2]).toMatchObject({
+			name: "opencode-command",
+			path: join(root, ".opencode/commands/agency.md"),
+			state: "customized",
+			changed: false,
+		})
+		expect(
+			await Bun.file(join(root, ".opencode/command/agency.md")).exists(),
+		).toBe(false)
+
+		await unlink(join(root, ".opencode/commands/agency.md"))
+		await write(root, ".opencode/command/agency.md", custom)
+		result = await sync(root)
+		expect(result.files[2]).toMatchObject({
+			path: join(root, ".opencode/command/agency.md"),
+			state: "customized",
+			changed: false,
+		})
+		expect(
+			await Bun.file(join(root, ".opencode/command/agency.md")).text(),
+		).toBe(custom)
+	})
+
 	test("migrates checksum-valid root instructions", async () => {
 		await write(root, "AGENTS.md", managedWorkbaseAgents)
 

package/src/services/IntegrationService.ts

@@ -10,11 +10,15 @@ import {
 	canUpdateManagedWorkbaseOpencode,
 	managedWorkbaseOpencode,
 } from "../workbase/opencode-file"
+import {
+	canUpdateManagedWorkbaseOpencodeCommand,
+	managedWorkbaseOpencodeCommand,
+} from "../workbase/opencode-command-file"
 
 type IntegrationFileState = "managed" | "customized" | "missing" | "drifted"
 
 interface IntegrationFileStatus {
-	readonly name: "agents" | "opencode"
+	readonly name: "agents" | "opencode" | "opencode-command"
 	readonly path: string
 	readonly state: IntegrationFileState
 	readonly diagnostic: string
@@ -52,6 +56,25 @@ const describe = (
 				"Run 'agency integration sync' to install Agency instructions and whole-workbase OpenCode access.",
 		}
 	}
+	if (name === "opencode-command") {
+		return state === "managed"
+			? {
+					diagnostic: "Agency's managed OpenCode /agency command is current.",
+					remediation: null,
+				}
+			: state === "customized"
+				? {
+						diagnostic:
+							"A user-owned OpenCode /agency command is present and was preserved.",
+						remediation: null,
+					}
+				: {
+						diagnostic:
+							"The managed OpenCode /agency command needs synchronization.",
+						remediation:
+							"Run 'agency integration sync' to install the managed /agency command.",
+					}
+	}
 
 	return state === "missing" || state === "drifted"
 		? {
@@ -98,6 +121,8 @@ const inspect = (root: string) =>
 		const opencodeDirectory = join(root, ".opencode")
 		const opencodePath = join(opencodeDirectory, "opencode.jsonc")
 		const opencodeJsonPath = join(opencodeDirectory, "opencode.json")
+		const commandPath = join(opencodeDirectory, "command", "agency.md")
+		const pluralCommandPath = join(opencodeDirectory, "commands", "agency.md")
 		const files: IntegrationFileStatus[] = []
 
 		files.push(
@@ -135,6 +160,29 @@ const inspect = (root: string) =>
 			files.push(fileStatus("opencode", opencodePath, "missing"))
 		}
 
+		if ((yield* fs.readSymlinkTarget(commandPath)) !== null) {
+			files.push(fileStatus("opencode-command", commandPath, "customized"))
+		} else if (
+			(yield* fs.readSymlinkTarget(pluralCommandPath)) !== null ||
+			(yield* fs.exists(pluralCommandPath))
+		) {
+			files.push(
+				fileStatus("opencode-command", pluralCommandPath, "customized"),
+			)
+		} else if (yield* fs.exists(commandPath)) {
+			files.push(
+				classify(
+					"opencode-command",
+					commandPath,
+					yield* fs.readFile(commandPath),
+					managedWorkbaseOpencodeCommand,
+					canUpdateManagedWorkbaseOpencodeCommand,
+				),
+			)
+		} else {
+			files.push(fileStatus("opencode-command", commandPath, "missing"))
+		}
+
 		return files
 	})
 
@@ -181,9 +229,12 @@ export class IntegrationService extends Effect.Service<IntegrationService>()(
 							if (status.name === "agents") {
 								yield* fs.createDirectory(join(root, ".agency"))
 								yield* fs.writeFile(status.path, managedWorkbaseAgents)
-							} else {
+							} else if (status.name === "opencode") {
 								yield* fs.createDirectory(join(root, ".opencode"))
 								yield* fs.writeFile(status.path, managedWorkbaseOpencode)
+							} else {
+								yield* fs.createDirectory(join(root, ".opencode", "command"))
+								yield* fs.writeFile(status.path, managedWorkbaseOpencodeCommand)
 							}
 						}
 						files.push({

package/src/services/PhaseService.ts

@@ -487,6 +487,12 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 						})
 					}
 					if (!canTransitionStatus(record.data.status, validStatus)) {
+						if (validStatus === "done") {
+							return yield* new PhaseError({
+								message:
+									"Work becomes done after its authoritative pull request is merged; run 'agency sync --apply'",
+							})
+						}
 						return yield* new PhaseError({
 							message: `Cannot transition phase '${id}' from ${record.data.status} to ${validStatus}; reopen it first`,
 						})

package/src/services/PullRequestService.test.ts

@@ -263,11 +263,13 @@ process.exit(${exitCode})
 		await createTask()
 		await runTestEffect(
 			TaskService.pipe(
-				Effect.flatMap((service) => service.setStatus("example", "done", root)),
+				Effect.flatMap((service) =>
+					service.setStatus("example", "dropped", root),
+				),
 			),
 		)
 
-		await expect(createPullRequest()).rejects.toThrow("Task status is done")
+		await expect(createPullRequest()).rejects.toThrow("Task status is dropped")
 		expect(
 			await Bun.file(join(root, "tasks/example/code/agency")).exists(),
 		).toBe(false)

package/src/services/SyncService.test.ts

@@ -390,6 +390,99 @@ process.stdout.write(${JSON.stringify(JSON.stringify(record))})
 		expect("pr" in task.data && task.data.pr).toEqual(record)
 	})
 
+	test("marks a successfully finished claim done only after merge", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "finished-claim",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "feat/example",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.materialize("finished-claim", undefined, root),
+				),
+			),
+		)
+		await git(
+			["remote", "set-url", "origin", "git@github.com:example/agency.git"],
+			join(root, "repos/agency"),
+		)
+		const initial = await runTestEffect(
+			ClaimService.pipe(
+				Effect.flatMap((service) =>
+					service.inspect("finished-claim", undefined, root),
+				),
+			),
+		)
+		const claimed = await runTestEffect(
+			ClaimService.pipe(
+				Effect.flatMap((service) =>
+					service.claim(
+						{
+							taskId: "finished-claim",
+							claimant: "orchestrator",
+							runner: "agent",
+							sessionId: "session-1",
+							revision: initial.revision,
+						},
+						root,
+					),
+				),
+			),
+		)
+		const finished = await runTestEffect(
+			ClaimService.pipe(
+				Effect.flatMap((service) =>
+					service.finish(
+						{
+							taskId: "finished-claim",
+							sessionId: "session-1",
+							revision: claimed.revision,
+							outcome: "done",
+						},
+						root,
+					),
+				),
+			),
+		)
+		expect(finished.data).toMatchObject({
+			status: "working",
+			claim: { state: "finished", outcome: "done" },
+		})
+
+		const synced = await runTestEffect(
+			SyncService.pipe(
+				Effect.flatMap((service) =>
+					service.reconcile({ cwd: root, apply: true }),
+				),
+			),
+		)
+		expect(synced.changes.map((change) => change.kind)).toContain("mark-done")
+		expect(
+			await runTestEffect(
+				TaskService.pipe(
+					Effect.flatMap((service) => service.show("finished-claim", root)),
+				),
+			),
+		).toMatchObject({
+			data: {
+				status: "done",
+				claim: { state: "finished", outcome: "done" },
+			},
+		})
+	})
+
 	test("materializes missing workspaces but leaves branch conflicts unresolved", async () => {
 		for (const [id, branch] of [
 			["missing", "feat/missing"],

package/src/services/TaskPhaseService.test.ts

@@ -318,22 +318,23 @@ describe("task and phase services", () => {
 				),
 			),
 		).rejects.toThrow("Delegation requires explicit ownership")
-		await runTestEffect(
-			TaskService.pipe(
-				Effect.flatMap((service) =>
-					service.setStatus("single-status", "done", root),
-				),
-			),
-		)
 		await expect(
 			runTestEffect(
 				TaskService.pipe(
 					Effect.flatMap((service) =>
-						service.setStatus("single-status", "dropped", root),
+						service.setStatus("single-status", "done", root),
 					),
 				),
 			),
-		).rejects.toThrow("reopen it first")
+		).rejects.toThrow("authoritative pull request is merged")
+		const droppedTask = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.setStatus("single-status", "dropped", root),
+				),
+			),
+		)
+		expect(droppedTask.data.status).toBe("dropped")
 
 		await runTestEffect(
 			TaskService.pipe(
@@ -389,7 +390,7 @@ describe("task and phase services", () => {
 					),
 				),
 			),
-		).rejects.toThrow("reopen it first")
+		).rejects.toThrow("authoritative pull request is merged")
 		await runTestEffect(
 			PhaseService.pipe(
 				Effect.flatMap((service) =>
@@ -397,17 +398,15 @@ describe("task and phase services", () => {
 				),
 			),
 		)
-		expect(
-			(
-				await runTestEffect(
-					PhaseService.pipe(
-						Effect.flatMap((service) =>
-							service.setStatus("multi-status", "implementation", "done", root),
-						),
+		await expect(
+			runTestEffect(
+				PhaseService.pipe(
+					Effect.flatMap((service) =>
+						service.setStatus("multi-status", "implementation", "done", root),
 					),
-				)
-			).data.status,
-		).toBe("done")
+				),
+			),
+		).rejects.toThrow("authoritative pull request is merged")
 		await expect(
 			runTestEffect(
 				TaskService.pipe(

package/src/services/TaskService.ts

@@ -270,6 +270,12 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 					})
 				}
 				if (!canTransitionStatus(record.data.status, validStatus)) {
+					if (validStatus === "done") {
+						return yield* new TaskError({
+							message:
+								"Work becomes done after its authoritative pull request is merged; run 'agency sync --apply'",
+						})
+					}
 					return yield* new TaskError({
 						message: `Cannot transition task '${id}' from ${record.data.status} to ${validStatus}; reopen it first`,
 					})

package/src/workbase/AGENCY_COMMAND.md

@@ -0,0 +1,48 @@
+---
+description: Operate Agency work with safe start, status, next, validate, and finish workflows
+---
+
+Operate the current Agency workbase using the managed Agency instructions.
+
+Invocation inputs:
+
+- Workflow: `$1`
+- Optional target: `$2`
+- Complete request: `$ARGUMENTS`
+
+Use `status` when the workflow is empty. Treat words after the optional target as
+additional user instructions. If the workflow is unknown, make no changes and
+list the supported workflows.
+
+Always follow these rules:
+
+- Run `agency context . --json` first when no target is provided. With a target,
+  pass that target to `agency context` instead.
+- Use the returned document paths, readiness, authority, checkout state, claim,
+  and validation result. Do not infer them from directory names.
+- Stop on validation errors, dependency blockers, an unexpected writable
+  repository, or a conflicting active claim.
+- Write code only in `authority.writable.checkoutPath`; references are read-only.
+- Never run `agency work` to start the current agent again.
+- Create a pull request only when the complete request explicitly asks for one.
+
+Dispatch the workflow as follows:
+
+- `start`: Read the returned task and phase documents, inspect the writable
+  checkout, then begin or resume the requested work in this session. Keep durable
+  decisions current and carry the work through focused verification.
+- `status`: Make no changes. Summarize the target, readiness, authority, durable
+  status, claim and PR state, checkout state, current Git changes, blockers, and
+  the most useful next action.
+- `next`: Run `agency next --json`, summarize ready and blocked execution units,
+  and recommend the highest-priority ready unit. Do not launch another agent.
+- `validate`: Run Agency validation for the discovered workbase. Explain every
+  issue and, when safe and within authority, repair requested non-structural
+  problems before validating again.
+- `finish`: Complete any remaining requested implementation first. Run focused
+  repository checks, refresh the task or phase delivery context, and run
+  `agency validate`. Finish an active claim with its current revision; otherwise
+  update unclaimed status only when the requested outcome and delivery work are
+  actually complete. Do not create a PR unless explicitly requested.
+- `help`: Make no changes. Briefly explain these workflows and the positional
+  form `/agency <workflow> [target] [additional instructions]`.

package/src/workbase/AGENTS.md

@@ -48,17 +48,19 @@ reason to edit `agency.json` or `repos/` by hand.
 
 ## Closeout
 
-An execution unit is `working` while implementation or requested delivery work
-remains. It becomes `done` when both are complete, even if its PR remains open
-for review or merge. Do not leave a task or phase `working` solely because its PR
-is open; if merge was requested, merge remains delivery work.
+An execution unit remains `working` after implementation is committed and while
+its pull request is open. It becomes `done` only after its authoritative pull
+request is merged and Agency reconciles that state. Do not mark committed or
+review-ready work `done` manually.
 
 At each closeout trigger (creating or updating a PR, marking it ready, completing
 a refinement loop, or pausing or handing off completed implementation work):
 
-- Finish an active claim with the current revision via `agency finish`.
-  Otherwise use `agency task status` or `agency phase status` to set the
-  execution unit's current status.
+- Finish an active claim with the current revision via `agency finish`; a
+  successful claim outcome leaves unmerged work `working`. For unclaimed work,
+  keep the execution unit `working` through review and merge.
+- After merge, run `agency sync --apply` to reconcile the execution unit to
+  `done`.
 - Refresh durable delivery context in `TASK.md` or `PHASE.md`, including recorded
   PR state, current head, diff summary, and verification results after later
   pushes when those details are maintained there.
@@ -69,6 +71,8 @@ a refinement loop, or pausing or handing off completed implementation work):
 `agency integration status` reports `managed`, `drifted`, `customized`, or
 `missing` generated files. Agency keeps these instructions in
 `.agency/AGENTS.md`, and its managed OpenCode config loads them automatically.
+It also installs `.opencode/command/agency.md`, which provides safe `/agency`
+workflows for active OpenCode sessions.
 The workbase-root `AGENTS.md`, when present, belongs entirely to the workbase
 owner and composes with these instructions through OpenCode's normal discovery.
 `agency integration sync` updates only missing or checksum-safe drifted managed

package/src/workbase/opencode-command-file.ts

@@ -0,0 +1,30 @@
+import { createHash } from "node:crypto"
+import commandTemplate from "./AGENCY_COMMAND.md" with { type: "text" }
+
+const managedHeaderPattern =
+	/^---\r?\n# agency-managed: sha256=([a-f0-9]{64})\r?\n/
+
+const checksum = (content: string) =>
+	createHash("sha256").update(content).digest("hex")
+
+const canonicalBody = commandTemplate.endsWith("\n")
+	? commandTemplate
+	: `${commandTemplate}\n`
+
+const renderManagedWorkbaseOpencodeCommand = (
+	content: string = canonicalBody,
+) =>
+	content.replace(
+		/^---\n/,
+		`---\n# agency-managed: sha256=${checksum(content)}\n`,
+	)
+
+export const managedWorkbaseOpencodeCommand =
+	renderManagedWorkbaseOpencodeCommand()
+
+export const canUpdateManagedWorkbaseOpencodeCommand = (content: string) => {
+	const match = content.match(managedHeaderPattern)
+	if (!match?.[1]) return false
+
+	return checksum(content.replace(managedHeaderPattern, "---\n")) === match[1]
+}