@markjaquith/agency 2.44.0 → 2.46.0

package/README.md

@@ -52,6 +52,10 @@ workbase/
     AGENTS.md              # managed Agency instructions
   .opencode/
     opencode.jsonc         # managed @agency subagent, instructions, and reference
+    tui.jsonc              # managed TUI plugin registration
+    command/agency.md      # managed /agency workflow command
+    plugin/agency-repository-skills.ts # managed checkout skill discovery
+    tui/agency-debug.ts    # managed /agency-debug TUI diagnostic
   agency.json              # tracked config and portable repository declarations
   repos/                   # ignored local materializations
     frontend/              # bare Git repository or symlink
@@ -80,9 +84,10 @@ workbase/
 
 Agency keeps discovery and other observational commands read-only. Run
 `agency integration status` to inspect `.agency/AGENTS.md` and
-`.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
+`.opencode/opencode.jsonc`, `.opencode/tui.jsonc`, and their managed command and
+plugin files, 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
@@ -97,6 +102,11 @@ and replaces the built-in Plan agent with `agency-plan`. That planning agent can
 update `TASK.md`, `PHASE.md`, and `EPIC.md` while other edits remain disabled.
 When the subagent launches work in another agent, it verifies that the runner
 started and returns without waiting for the task to finish.
+The TUI-only `/agency-debug` command reports TUI companion initialization and
+whether the server plugin registered writable-checkout skills. It uses a native
+toast and does not submit a prompt to an LLM. When no writable checkout skill
+directory is available, server initialization is reported as indeterminate
+rather than inferred from plugin discovery.
 OpenCode discovers the 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`.
@@ -232,12 +242,18 @@ Every runner receives the same `AGENCY_RUNNER`, `AGENCY_CLAIMANT`,
 `AGENCY_SESSION_ID`, `AGENCY_CLAIM_REVISION`, `AGENCY_WORKBASE`, `AGENCY_TARGET`,
 `AGENCY_TASK_ID`, `AGENCY_PHASE_ID`, and `AGENCY_PROMPT` environment. Configured
 environment is added without overriding these normalized values.
+Execution-unit runners also receive `AGENCY_WRITABLE_CHECKOUT` with the
+authoritative writable checkout path.
 `AGENCY_CLAIM_REVISION` is empty for local `agency work` launches.
 `AGENCY_PROMPT` is empty unless `--auto` is set.
-The `opencode` runner discovers the managed project config from its task or epic
-working directory; Agency does not inject OpenCode-specific configuration.
-`AGENCY_CLAIM_REVISION` is empty for local `agency work` launches.
-`AGENCY_PROMPT` is empty unless `--auto` is set.
+The `opencode` runner remains rooted in its task or epic working directory so
+the workbase `AGENTS.md` and managed OpenCode config are discovered normally.
+Agency's managed OpenCode plugin adds existing checkout-local `.claude/skills`,
+`.agents/skills`, and `.opencode/{skill,skills}` directories to `skills.paths`.
+`agency work` supplies the checkout directly; plain OpenCode launches resolve a
+materialized execution-unit checkout through `agency context`. A multi-phase
+task root has no single checkout, so launch from its phase directory when using
+plain OpenCode. Other checkout-local configuration is not composed.
 `--print-command` prints the exact cwd and argv plus non-secret environment keys
 without launching the runner.
 

package/package.json

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

package/src/cli.test.ts

@@ -1,6 +1,6 @@
 import { afterAll, afterEach, describe, expect, test } from "bun:test"
-import { access, mkdir, realpath } from "node:fs/promises"
-import { join } from "node:path"
+import { access, mkdir, realpath, symlink } from "node:fs/promises"
+import { join, sep } from "node:path"
 import errorFixture from "../fixtures/protocol/error.json"
 import successFixture from "../fixtures/protocol/success.json"
 import { cleanupTempDir, createTempDir } from "./test-utils"
@@ -527,6 +527,9 @@ describe("CLI", () => {
 			{ name: "agents", state: "managed" },
 			{ name: "opencode", state: "managed" },
 			{ name: "opencode-command", state: "managed" },
+			{ name: "opencode-plugin", state: "managed" },
+			{ name: "opencode-tui", state: "managed" },
+			{ name: "opencode-tui-plugin", state: "managed" },
 		])
 
 		const synced = parseJson(
@@ -536,6 +539,9 @@ describe("CLI", () => {
 			{ name: "agents", state: "managed", changed: false },
 			{ name: "opencode", state: "managed", changed: false },
 			{ name: "opencode-command", state: "managed", changed: false },
+			{ name: "opencode-plugin", state: "managed", changed: false },
+			{ name: "opencode-tui", state: "managed", changed: false },
+			{ name: "opencode-tui-plugin", state: "managed", changed: false },
 		])
 	})
 
@@ -864,10 +870,17 @@ status: open
 					.exitCode,
 			).toBe(0)
 			await Bun.write(join(source, "README.md"), "example\n")
+			await mkdir(join(source, ".claude/skills/repository-skill"), {
+				recursive: true,
+			})
+			await Bun.write(
+				join(source, ".claude/skills/repository-skill/SKILL.md"),
+				"---\nname: repository-skill\ndescription: Repository discovery test.\n---\n\nRepository skill content.\n",
+			)
 			for (const args of [
 				["config", "user.email", "test@example.com"],
 				["config", "user.name", "Test"],
-				["add", "README.md"],
+				["add", "."],
 				["-c", "commit.gpgsign=false", "commit", "-m", "initial"],
 			]) {
 				expect(Bun.spawnSync(["git", "-C", source, ...args]).exitCode).toBe(0)
@@ -1001,18 +1014,35 @@ status: open
 				{
 					args: ["--task", "example"],
 					cwd: join(workbaseRoot, "tasks/example"),
+					checkoutPath: join(workbaseRoot, "tasks/example/code/agency"),
+					skillPath: join(
+						workbaseRoot,
+						"tasks/example/code/agency/.claude/skills",
+					),
 				},
 				{
 					args: ["--task", "pipeline", "--phase", "build"],
 					cwd: join(workbaseRoot, "tasks/pipeline"),
+					checkoutPath: join(
+						workbaseRoot,
+						"tasks/pipeline/phases/build/code/agency",
+					),
+					skillPath: join(
+						workbaseRoot,
+						"tasks/pipeline/phases/build/code/agency/.claude/skills",
+					),
 				},
 				{
 					args: ["--epic", "delivery"],
 					cwd: join(workbaseRoot, "epics/delivery"),
+					checkoutPath: undefined,
+					skillPath: undefined,
 				},
 				{
 					args: ["--task", "pipeline"],
 					cwd: join(workbaseRoot, "tasks/pipeline"),
+					checkoutPath: undefined,
+					skillPath: undefined,
 				},
 			]
 			for (const launch of launches) {
@@ -1024,7 +1054,11 @@ status: open
 				expect(printed.stderr).toBe("")
 				const contract = JSON.parse(printed.stdout)
 				expect(contract.cwd).toBe(launch.cwd)
+				expect(contract.argv).toEqual(["opencode"])
 				expect(contract.environment.OPENCODE_CONFIG).toBeUndefined()
+				expect(contract.environment.AGENCY_WRITABLE_CHECKOUT).toBe(
+					launch.checkoutPath,
+				)
 				expect(
 					JSON.parse(contract.environment.OPENCODE_CONFIG_CONTENT),
 				).toEqual({
@@ -1053,13 +1087,49 @@ status: open
 						}),
 					]),
 				)
+				const configProbe = Bun.spawnSync(["opencode", "debug", "config"], {
+					cwd: contract.cwd,
+					env: environment,
+				})
+				expect(configProbe.exitCode).toBe(0)
+				const effectiveConfig = JSON.parse(configProbe.stdout.toString())
+				expect(effectiveConfig.plugin_origins).toEqual(
+					expect.arrayContaining([
+						expect.objectContaining({
+							spec: expect.stringContaining("agency-repository-skills.ts"),
+						}),
+					]),
+				)
+				if (launch.skillPath) {
+					expect(effectiveConfig.skills.paths).toContain(
+						`${launch.skillPath}${sep}.`,
+					)
+					const skillProbe = Bun.spawnSync(
+						[
+							"opencode",
+							"debug",
+							"agent",
+							"build",
+							"--tool",
+							"skill",
+							"--params",
+							JSON.stringify({ name: "repository-skill" }),
+						],
+						{ cwd: contract.cwd, env: environment },
+					)
+					expect(skillProbe.exitCode).toBe(0)
+					expect(
+						JSON.parse(skillProbe.stdout.toString()).result.output,
+					).toContain("Repository skill content.")
+				} else {
+					expect(
+						(effectiveConfig.skills?.paths ?? []).filter((path: string) =>
+							path.endsWith(`${sep}.`),
+						),
+					).toEqual([])
+				}
 				if (launch === launches[0]) {
-					const configProbe = Bun.spawnSync(["opencode", "debug", "config"], {
-						cwd: contract.cwd,
-						env: environment,
-					})
-					expect(configProbe.exitCode).toBe(0)
-					const effectiveConfig = JSON.parse(configProbe.stdout.toString())
+					expect(effectiveConfig.instructions).toContain(".agency/AGENTS.md")
 					expect(effectiveConfig.agent.agency).toMatchObject({
 						description: expect.stringContaining(
 							"Agency workbase orchestration",
@@ -1106,19 +1176,28 @@ status: open
 				}
 			}
 
+			const agencyBin = join(parent, "bin")
+			await mkdir(agencyBin)
+			await symlink(cliPath, join(agencyBin, "agency"))
 			const directEnvironment: Record<string, string | undefined> = {
 				...process.env,
+				PATH: `${agencyBin}:${process.env.PATH ?? ""}`,
 				XDG_CONFIG_HOME: isolatedConfigHome,
 				OPENCODE_DISABLE_EXTERNAL_SKILLS: "1",
 			}
 			delete directEnvironment.OPENCODE_CONFIG
 			delete directEnvironment.OPENCODE_CONFIG_CONTENT
 			delete directEnvironment.AGENCY_WORKBASE
-			for (const cwd of [
+			delete directEnvironment.AGENCY_TASK_ID
+			delete directEnvironment.AGENCY_PHASE_ID
+			delete directEnvironment.AGENCY_WRITABLE_CHECKOUT
+			const directDirectories = [
 				join(workbaseRoot, "tasks/example"),
 				join(workbaseRoot, "tasks/pipeline"),
+				join(workbaseRoot, "tasks/pipeline/phases/build"),
 				join(workbaseRoot, "epics/delivery"),
-			]) {
+			]
+			for (const cwd of directDirectories) {
 				const probe = Bun.spawnSync(["opencode", "debug", "agent", "build"], {
 					cwd,
 					env: directEnvironment,
@@ -1134,6 +1213,20 @@ status: open
 						}),
 					]),
 				)
+				const configProbe = Bun.spawnSync(["opencode", "debug", "config"], {
+					cwd,
+					env: directEnvironment,
+				})
+				expect(configProbe.exitCode).toBe(0)
+				expect(
+					JSON.parse(configProbe.stdout.toString()).plugin_origins,
+				).toEqual(
+					expect.arrayContaining([
+						expect.objectContaining({
+							spec: expect.stringContaining("agency-repository-skills.ts"),
+						}),
+					]),
+				)
 				for (const document of documents) {
 					const read = Bun.spawnSync(
 						[
@@ -1154,6 +1247,28 @@ status: open
 					)
 				}
 			}
+			for (const cwd of [
+				join(workbaseRoot, "tasks/example"),
+				join(workbaseRoot, "tasks/pipeline/phases/build"),
+			]) {
+				const manualSkill = Bun.spawnSync(
+					[
+						"opencode",
+						"debug",
+						"agent",
+						"build",
+						"--tool",
+						"skill",
+						"--params",
+						JSON.stringify({ name: "repository-skill" }),
+					],
+					{ cwd, env: directEnvironment },
+				)
+				expect(manualSkill.exitCode, manualSkill.stderr.toString()).toBe(0)
+				expect(
+					JSON.parse(manualSkill.stdout.toString()).result.output,
+				).toContain("Repository skill content.")
+			}
 
 			parseJson(
 				await runCli(["task", "status", "example", "dropped", "--json"], root),

package/src/commands/init.test.ts

@@ -66,6 +66,22 @@ describe("init command", () => {
 		).text()
 		expect(command).toContain("Workflow: `$1`")
 		expect(command).toContain("Optional target: `$2`")
+		const plugin = await Bun.file(
+			join(root, ".opencode/plugin/agency-repository-skills.ts"),
+		).text()
+		expect(plugin).toContain("AGENCY_WRITABLE_CHECKOUT")
+		expect(plugin).toContain("config.skills.paths")
+		const tui = await Bun.file(join(root, ".opencode/tui.jsonc")).text()
+		expect(JSON.parse(tui.slice(tui.indexOf("\n\n") + 2))).toEqual({
+			$schema: "https://opencode.ai/tui.json",
+			plugin: ["./tui/agency-debug.ts"],
+		})
+		const tuiPlugin = await Bun.file(
+			join(root, ".opencode/tui/agency-debug.ts"),
+		).text()
+		expect(tuiPlugin).toContain('slashName: "agency-debug"')
+		expect(tuiPlugin).toContain("api.ui.toast")
+		expect(tuiPlugin).not.toContain("chat.message")
 	})
 
 	test("preserves existing gitignore entries", async () => {

package/src/commands/integration.test.ts

@@ -41,6 +41,21 @@ describe("integration command", () => {
 					state: "missing",
 					remediation: expect.stringContaining("integration sync"),
 				},
+				{
+					name: "opencode-plugin",
+					state: "missing",
+					remediation: expect.stringContaining("integration sync"),
+				},
+				{
+					name: "opencode-tui",
+					state: "missing",
+					remediation: expect.stringContaining("integration sync"),
+				},
+				{
+					name: "opencode-tui-plugin",
+					state: "missing",
+					remediation: expect.stringContaining("integration sync"),
+				},
 			],
 		})
 	})
@@ -79,7 +94,22 @@ OpenCode config: missing
 OpenCode /agency command: missing
   Path: .opencode/command/agency.md
   The managed OpenCode /agency command needs synchronization.
-  Action: Run 'agency integration sync' to install the managed /agency command.`)
+  Action: Run 'agency integration sync' to install the managed /agency command.
+
+OpenCode checkout skills: missing
+  Path: .opencode/plugin/agency-repository-skills.ts
+  The managed OpenCode checkout-skill plugin needs synchronization.
+  Action: Run 'agency integration sync' to expose writable-checkout skills in OpenCode.
+
+OpenCode TUI config: missing
+  Path: .opencode/tui.jsonc
+  The managed OpenCode TUI config needs synchronization.
+  Action: Run 'agency integration sync' to register /agency-debug.
+
+OpenCode /agency-debug: missing
+  Path: .opencode/tui/agency-debug.ts
+  The managed OpenCode TUI diagnostic companion needs synchronization.
+  Action: Run 'agency integration sync' to install /agency-debug.`)
 	})
 
 	test("explicitly synchronizes integration files", async () => {
@@ -91,6 +121,9 @@ OpenCode /agency command: missing
 			{ name: "agents", state: "managed", changed: true },
 			{ name: "opencode", state: "managed", changed: true },
 			{ name: "opencode-command", state: "managed", changed: true },
+			{ name: "opencode-plugin", state: "managed", changed: true },
+			{ name: "opencode-tui", state: "managed", changed: true },
+			{ name: "opencode-tui-plugin", 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)
@@ -100,6 +133,17 @@ OpenCode /agency command: missing
 		expect(
 			await Bun.file(join(root, ".opencode/command/agency.md")).exists(),
 		).toBe(true)
+		expect(
+			await Bun.file(
+				join(root, ".opencode/plugin/agency-repository-skills.ts"),
+			).exists(),
+		).toBe(true)
+		expect(await Bun.file(join(root, ".opencode/tui.jsonc")).exists()).toBe(
+			true,
+		)
+		expect(
+			await Bun.file(join(root, ".opencode/tui/agency-debug.ts")).exists(),
+		).toBe(true)
 	})
 
 	test("formats integration sync results for people", async () => {
@@ -119,6 +163,18 @@ OpenCode config: synced
 
 OpenCode /agency command: synced
   Path: .opencode/command/agency.md
-  Agency's managed OpenCode /agency command is current.`)
+  Agency's managed OpenCode /agency command is current.
+
+OpenCode checkout skills: synced
+  Path: .opencode/plugin/agency-repository-skills.ts
+  Agency's managed OpenCode plugin exposes writable-checkout skills to work-item sessions.
+
+OpenCode TUI config: synced
+  Path: .opencode/tui.jsonc
+  Agency's managed OpenCode TUI config explicitly loads /agency-debug.
+
+OpenCode /agency-debug: synced
+  Path: .opencode/tui/agency-debug.ts
+  Agency's managed OpenCode TUI diagnostic companion is current.`)
 	})
 })

package/src/commands/integration.ts

@@ -12,7 +12,13 @@ interface IntegrationOptions extends BaseCommandOptions {
 interface IntegrationResult {
 	readonly root: string
 	readonly files: readonly {
-		readonly name: "agents" | "opencode" | "opencode-command"
+		readonly name:
+			| "agents"
+			| "opencode"
+			| "opencode-command"
+			| "opencode-plugin"
+			| "opencode-tui"
+			| "opencode-tui-plugin"
 		readonly path: string
 		readonly state: string
 		readonly diagnostic: string
@@ -25,6 +31,9 @@ const integrationNames = {
 	agents: "Agent instructions",
 	opencode: "OpenCode config",
 	"opencode-command": "OpenCode /agency command",
+	"opencode-plugin": "OpenCode checkout skills",
+	"opencode-tui": "OpenCode TUI config",
+	"opencode-tui-plugin": "OpenCode /agency-debug",
 } as const
 
 const logHumanResult = (
@@ -83,7 +92,8 @@ Usage: agency integration <subcommand>
 
 Inspect or explicitly synchronize managed agent integration files. OpenCode
 launches load the managed instructions and project config at runtime, and expose
-the managed /agency command, without changing Agency write authority.
+the managed /agency command, writable-checkout skills, and /agency-debug TUI
+diagnostic, without changing Agency write authority.
 
 Subcommands:
   status  Report file state, access diagnostics, and safe remediation

package/src/commands/work.test.ts

@@ -929,6 +929,23 @@ describe("work command", () => {
 		expect(printed.environment.OPENCODE_CONFIG_CONTENT).toBe(workbasePermission)
 	})
 
+	test("provides the writable checkout to plugins without changing the project", async () => {
+		const harness = createHarness()
+		await harness.run({ taskId: "example", opencode: true })
+
+		expect(harness.launches[0]).toEqual({
+			cli: "opencode",
+			args: ["opencode"],
+			cwd: taskDirectory,
+		})
+		expect(harness.launchEnvironments[0]?.AGENCY_WRITABLE_CHECKOUT).toBe(
+			"/workbase/tasks/example/code/agency",
+		)
+		expect(harness.launchEnvironments[0]?.OPENCODE_CONFIG_CONTENT).toBe(
+			workbasePermission,
+		)
+	})
+
 	test("does not override customized OpenCode access policy", async () => {
 		const harness = createHarness({ opencodeIntegrationState: "customized" })
 		await harness.run({ taskId: "example", opencode: true })

package/src/commands/work.ts

@@ -239,6 +239,7 @@ export const work = (
 				(target.status !== undefined && target.status !== "open"))
 		let prompt: string
 		let launchPath: string
+		let writablePath: string | undefined
 		if (target.kind === "epic") {
 			prompt = `Work on the epic. Read ${target.path}.`
 			launchPath = dirname(target.path)
@@ -264,6 +265,7 @@ export const work = (
 				? `${action} the task. Read ${workspace.taskPath} and ${workspace.phasePath}.`
 				: `${action} the task. Read ${workspace.taskPath}.`
 			launchPath = dirname(workspace.taskPath)
+			writablePath = workspace.writablePath
 		}
 
 		const explicitlyRequested = Boolean(
@@ -334,6 +336,7 @@ export const work = (
 			...resolved.environment,
 			...runnerEnvironment(runner, variables),
 		}
+		if (writablePath) environment.AGENCY_WRITABLE_CHECKOUT = writablePath
 		if (runner === "opencode" && managedOpencode) {
 			environment.OPENCODE_CONFIG_CONTENT = JSON.stringify({
 				permission: {

package/src/services/IntegrationService.test.ts

@@ -3,6 +3,7 @@ import { Effect } from "effect"
 import { createHash } from "node:crypto"
 import { mkdir, stat, symlink, unlink, utimes } from "node:fs/promises"
 import { dirname, join } from "node:path"
+import { pathToFileURL } from "node:url"
 import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
 import { managedWorkbaseAgents } from "../workbase/agents-file"
 import {
@@ -10,6 +11,15 @@ import {
 	managedWorkbaseOpencodeCommand,
 } from "../workbase/opencode-command-file"
 import { managedWorkbaseOpencode } from "../workbase/opencode-file"
+import {
+	canUpdateManagedWorkbaseOpencodePlugin,
+	managedWorkbaseOpencodePlugin,
+} from "../workbase/opencode-plugin-file"
+import { managedWorkbaseOpencodeTui } from "../workbase/opencode-tui-file"
+import {
+	canUpdateManagedWorkbaseOpencodeTuiPlugin,
+	managedWorkbaseOpencodeTuiPlugin,
+} from "../workbase/opencode-tui-plugin-file"
 import { IntegrationService } from "./IntegrationService"
 
 const write = async (root: string, path: string, content: string) => {
@@ -51,6 +61,9 @@ describe("IntegrationService", () => {
 			"missing",
 			"missing",
 			"missing",
+			"missing",
+			"missing",
+			"missing",
 		])
 		expect(await Bun.file(join(root, ".agency/AGENTS.md")).exists()).toBe(false)
 
@@ -61,10 +74,24 @@ describe("IntegrationService", () => {
 			".opencode/command/agency.md",
 			managedWorkbaseOpencodeCommand,
 		)
+		await write(
+			root,
+			".opencode/plugin/agency-repository-skills.ts",
+			managedWorkbaseOpencodePlugin,
+		)
+		await write(root, ".opencode/tui.jsonc", managedWorkbaseOpencodeTui)
+		await write(
+			root,
+			".opencode/tui/agency-debug.ts",
+			managedWorkbaseOpencodeTuiPlugin,
+		)
 		expect((await status(root)).files.map(({ state }) => state)).toEqual([
 			"managed",
 			"managed",
 			"managed",
+			"managed",
+			"managed",
+			"managed",
 		])
 	})
 
@@ -80,9 +107,111 @@ describe("IntegrationService", () => {
 			"customized",
 			"drifted",
 			"missing",
+			"missing",
+			"missing",
+			"missing",
 		])
 	})
 
+	test("generates a dynamic repository skill plugin", () => {
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			"process.env.AGENCY_WRITABLE_CHECKOUT",
+		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			'["agency", "context", ".", "--compact", "--json"]',
+		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			'join(checkout, ".claude", "skills")',
+		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			'join(checkout, ".agents", "skills")',
+		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			'join(checkout, ".opencode", "skills")',
+		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			"config.skills.paths = [...new Set",
+		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			".map((path) => `${path}${sep}.`)",
+		)
+		expect(
+			canUpdateManagedWorkbaseOpencodePlugin(managedWorkbaseOpencodePlugin),
+		).toBe(true)
+		expect(
+			canUpdateManagedWorkbaseOpencodePlugin(
+				managedWorkbaseOpencodePlugin.replace("config.skills ??= {}", ""),
+			),
+		).toBe(false)
+	})
+
+	test("registers a TUI-only /agency-debug diagnostic", async () => {
+		const config = JSON.parse(managedBody(managedWorkbaseOpencodeTui))
+		expect(config).toEqual({
+			$schema: "https://opencode.ai/tui.json",
+			plugin: ["./tui/agency-debug.ts"],
+		})
+
+		const path = join(root, ".opencode/tui/agency-debug.ts")
+		await write(
+			root,
+			".opencode/tui/agency-debug.ts",
+			managedWorkbaseOpencodeTuiPlugin,
+		)
+		const module = await import(pathToFileURL(path).href)
+		let clientReads = 0
+
+		const runDiagnostic = async (paths: string[], ready = true) => {
+			let command:
+				| {
+						slashName?: string
+						namespace?: string
+						run: () => void
+				  }
+				| undefined
+			let toast: { variant: string; message: string } | undefined
+			await module.default.tui({
+				get client() {
+					clientReads += 1
+					throw new Error("diagnostic must not access the server client")
+				},
+				state: { ready, config: { skills: { paths } } },
+				keymap: {
+					registerLayer: (layer: { commands: (typeof command)[] }) => {
+						command = layer.commands[0]
+					},
+				},
+				ui: {
+					toast: (input: { variant: string; message: string }) => {
+						toast = input
+					},
+				},
+			} as never)
+			expect(command).toMatchObject({
+				namespace: "palette",
+				slashName: "agency-debug",
+			})
+			command?.run()
+			return toast
+		}
+
+		expect(await runDiagnostic(["/checkout/.agents/skills/."])).toMatchObject({
+			variant: "success",
+			message: expect.stringContaining("Server plugin: initialized"),
+		})
+		expect(await runDiagnostic([])).toMatchObject({
+			variant: "warning",
+			message: expect.stringContaining("Server plugin: indeterminate"),
+		})
+		expect(clientReads).toBe(0)
+		expect(managedWorkbaseOpencodeTuiPlugin).not.toContain("chat.message")
+		expect(
+			canUpdateManagedWorkbaseOpencodeTuiPlugin(
+				managedWorkbaseOpencodeTuiPlugin,
+			),
+		).toBe(true)
+	})
+
 	test("generates a positional OpenCode command for Agency workflows", () => {
 		expect(managedWorkbaseOpencodeCommand).toContain(
 			"description: Operate Agency work",
@@ -247,6 +376,9 @@ describe("IntegrationService", () => {
 			{ name: "agents", state: "customized", changed: false },
 			{ name: "opencode", state: "managed", changed: true },
 			{ name: "opencode-command", state: "managed", changed: true },
+			{ name: "opencode-plugin", state: "managed", changed: true },
+			{ name: "opencode-tui", state: "managed", changed: true },
+			{ name: "opencode-tui-plugin", state: "managed", changed: true },
 		])
 		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(
 			customRootAgents,
@@ -260,6 +392,17 @@ describe("IntegrationService", () => {
 		expect(
 			await Bun.file(join(root, ".opencode/command/agency.md")).text(),
 		).toBe(managedWorkbaseOpencodeCommand)
+		expect(
+			await Bun.file(
+				join(root, ".opencode/plugin/agency-repository-skills.ts"),
+			).text(),
+		).toBe(managedWorkbaseOpencodePlugin)
+		expect(await Bun.file(join(root, ".opencode/tui.jsonc")).text()).toBe(
+			managedWorkbaseOpencodeTui,
+		)
+		expect(
+			await Bun.file(join(root, ".opencode/tui/agency-debug.ts")).text(),
+		).toBe(managedWorkbaseOpencodeTuiPlugin)
 
 		await unlink(join(root, ".agency/AGENTS.md"))
 		const second = await sync(root)
@@ -272,6 +415,61 @@ describe("IntegrationService", () => {
 		)
 	})
 
+	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)
+
+		let result = await sync(root)
+		expect(result.files[3]).toMatchObject({
+			name: "opencode-plugin",
+			path: join(root, ".opencode/plugins/agency-repository-skills.ts"),
+			state: "customized",
+			changed: false,
+		})
+		expect(
+			await Bun.file(
+				join(root, ".opencode/plugin/agency-repository-skills.ts"),
+			).exists(),
+		).toBe(false)
+
+		await unlink(join(root, ".opencode/plugins/agency-repository-skills.ts"))
+		await write(root, ".opencode/plugin/agency-repository-skills.ts", custom)
+		result = await sync(root)
+		expect(result.files[3]).toMatchObject({
+			path: join(root, ".opencode/plugin/agency-repository-skills.ts"),
+			state: "customized",
+			changed: false,
+		})
+	})
+
+	test("preserves user-owned TUI config and diagnostic plugin", async () => {
+		const customConfig = '{"theme":"custom"}\n'
+		const customPlugin =
+			"export default { id: 'agency.debug', tui: async () => {} }\n"
+		await write(root, ".opencode/tui.json", customConfig)
+		await write(root, ".opencode/tui/agency-debug.ts", customPlugin)
+
+		const result = await sync(root)
+		expect(result.files[4]).toMatchObject({
+			name: "opencode-tui",
+			path: join(root, ".opencode/tui.json"),
+			state: "customized",
+			changed: false,
+			remediation: expect.stringContaining("plugin list"),
+		})
+		expect(result.files[5]).toMatchObject({
+			name: "opencode-tui-plugin",
+			state: "customized",
+			changed: false,
+		})
+		expect(await Bun.file(join(root, ".opencode/tui.json")).text()).toBe(
+			customConfig,
+		)
+		expect(
+			await Bun.file(join(root, ".opencode/tui/agency-debug.ts")).text(),
+		).toBe(customPlugin)
+	})
+
 	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)

package/src/services/IntegrationService.ts

@@ -14,11 +14,29 @@ import {
 	canUpdateManagedWorkbaseOpencodeCommand,
 	managedWorkbaseOpencodeCommand,
 } from "../workbase/opencode-command-file"
+import {
+	canUpdateManagedWorkbaseOpencodePlugin,
+	managedWorkbaseOpencodePlugin,
+} from "../workbase/opencode-plugin-file"
+import {
+	canUpdateManagedWorkbaseOpencodeTui,
+	managedWorkbaseOpencodeTui,
+} from "../workbase/opencode-tui-file"
+import {
+	canUpdateManagedWorkbaseOpencodeTuiPlugin,
+	managedWorkbaseOpencodeTuiPlugin,
+} from "../workbase/opencode-tui-plugin-file"
 
 type IntegrationFileState = "managed" | "customized" | "missing" | "drifted"
 
 interface IntegrationFileStatus {
-	readonly name: "agents" | "opencode" | "opencode-command"
+	readonly name:
+		| "agents"
+		| "opencode"
+		| "opencode-command"
+		| "opencode-plugin"
+		| "opencode-tui"
+		| "opencode-tui-plugin"
 	readonly path: string
 	readonly state: IntegrationFileState
 	readonly diagnostic: string
@@ -75,6 +93,67 @@ const describe = (
 							"Run 'agency integration sync' to install the managed /agency command.",
 					}
 	}
+	if (name === "opencode-plugin") {
+		return state === "managed"
+			? {
+					diagnostic:
+						"Agency's managed OpenCode plugin exposes writable-checkout skills to work-item sessions.",
+					remediation: null,
+				}
+			: state === "customized"
+				? {
+						diagnostic:
+							"A user-owned OpenCode checkout-skill plugin is present and was preserved.",
+						remediation: null,
+					}
+				: {
+						diagnostic:
+							"The managed OpenCode checkout-skill plugin needs synchronization.",
+						remediation:
+							"Run 'agency integration sync' to expose writable-checkout skills in OpenCode.",
+					}
+	}
+	if (name === "opencode-tui") {
+		return state === "managed"
+			? {
+					diagnostic:
+						"Agency's managed OpenCode TUI config explicitly loads /agency-debug.",
+					remediation: null,
+				}
+			: state === "customized"
+				? {
+						diagnostic:
+							"A user-owned OpenCode TUI config is present and was preserved.",
+						remediation:
+							"Add './tui/agency-debug.ts' to its plugin list to enable /agency-debug.",
+					}
+				: {
+						diagnostic:
+							"The managed OpenCode TUI config needs synchronization.",
+						remediation:
+							"Run 'agency integration sync' to register /agency-debug.",
+					}
+	}
+	if (name === "opencode-tui-plugin") {
+		return state === "managed"
+			? {
+					diagnostic:
+						"Agency's managed OpenCode TUI diagnostic companion is current.",
+					remediation: null,
+				}
+			: state === "customized"
+				? {
+						diagnostic:
+							"A user-owned OpenCode /agency-debug TUI plugin is present and was preserved.",
+						remediation: null,
+					}
+				: {
+						diagnostic:
+							"The managed OpenCode TUI diagnostic companion needs synchronization.",
+						remediation:
+							"Run 'agency integration sync' to install /agency-debug.",
+					}
+	}
 
 	return state === "missing" || state === "drifted"
 		? {
@@ -121,8 +200,21 @@ const inspect = (root: string) =>
 		const opencodeDirectory = join(root, ".opencode")
 		const opencodePath = join(opencodeDirectory, "opencode.jsonc")
 		const opencodeJsonPath = join(opencodeDirectory, "opencode.json")
+		const tuiPath = join(opencodeDirectory, "tui.jsonc")
+		const tuiJsonPath = join(opencodeDirectory, "tui.json")
 		const commandPath = join(opencodeDirectory, "command", "agency.md")
 		const pluralCommandPath = join(opencodeDirectory, "commands", "agency.md")
+		const pluginPath = join(
+			opencodeDirectory,
+			"plugin",
+			"agency-repository-skills.ts",
+		)
+		const pluralPluginPath = join(
+			opencodeDirectory,
+			"plugins",
+			"agency-repository-skills.ts",
+		)
+		const tuiPluginPath = join(opencodeDirectory, "tui", "agency-debug.ts")
 		const files: IntegrationFileStatus[] = []
 
 		files.push(
@@ -183,6 +275,64 @@ const inspect = (root: string) =>
 			files.push(fileStatus("opencode-command", commandPath, "missing"))
 		}
 
+		if ((yield* fs.readSymlinkTarget(pluginPath)) !== null) {
+			files.push(fileStatus("opencode-plugin", pluginPath, "customized"))
+		} else if (
+			(yield* fs.readSymlinkTarget(pluralPluginPath)) !== null ||
+			(yield* fs.exists(pluralPluginPath))
+		) {
+			files.push(fileStatus("opencode-plugin", pluralPluginPath, "customized"))
+		} else if (yield* fs.exists(pluginPath)) {
+			files.push(
+				classify(
+					"opencode-plugin",
+					pluginPath,
+					yield* fs.readFile(pluginPath),
+					managedWorkbaseOpencodePlugin,
+					canUpdateManagedWorkbaseOpencodePlugin,
+				),
+			)
+		} else {
+			files.push(fileStatus("opencode-plugin", pluginPath, "missing"))
+		}
+
+		if ((yield* fs.readSymlinkTarget(tuiPath)) !== null) {
+			files.push(fileStatus("opencode-tui", tuiPath, "customized"))
+		} else if (
+			(yield* fs.readSymlinkTarget(tuiJsonPath)) !== null ||
+			(yield* fs.exists(tuiJsonPath))
+		) {
+			files.push(fileStatus("opencode-tui", tuiJsonPath, "customized"))
+		} else if (yield* fs.exists(tuiPath)) {
+			files.push(
+				classify(
+					"opencode-tui",
+					tuiPath,
+					yield* fs.readFile(tuiPath),
+					managedWorkbaseOpencodeTui,
+					canUpdateManagedWorkbaseOpencodeTui,
+				),
+			)
+		} else {
+			files.push(fileStatus("opencode-tui", tuiPath, "missing"))
+		}
+
+		if ((yield* fs.readSymlinkTarget(tuiPluginPath)) !== null) {
+			files.push(fileStatus("opencode-tui-plugin", tuiPluginPath, "customized"))
+		} else if (yield* fs.exists(tuiPluginPath)) {
+			files.push(
+				classify(
+					"opencode-tui-plugin",
+					tuiPluginPath,
+					yield* fs.readFile(tuiPluginPath),
+					managedWorkbaseOpencodeTuiPlugin,
+					canUpdateManagedWorkbaseOpencodeTuiPlugin,
+				),
+			)
+		} else {
+			files.push(fileStatus("opencode-tui-plugin", tuiPluginPath, "missing"))
+		}
+
 		return files
 	})
 
@@ -232,9 +382,21 @@ export class IntegrationService extends Effect.Service<IntegrationService>()(
 							} else if (status.name === "opencode") {
 								yield* fs.createDirectory(join(root, ".opencode"))
 								yield* fs.writeFile(status.path, managedWorkbaseOpencode)
-							} else {
+							} else if (status.name === "opencode-command") {
 								yield* fs.createDirectory(join(root, ".opencode", "command"))
 								yield* fs.writeFile(status.path, managedWorkbaseOpencodeCommand)
+							} else if (status.name === "opencode-plugin") {
+								yield* fs.createDirectory(join(root, ".opencode", "plugin"))
+								yield* fs.writeFile(status.path, managedWorkbaseOpencodePlugin)
+							} else if (status.name === "opencode-tui") {
+								yield* fs.createDirectory(join(root, ".opencode"))
+								yield* fs.writeFile(status.path, managedWorkbaseOpencodeTui)
+							} else {
+								yield* fs.createDirectory(join(root, ".opencode", "tui"))
+								yield* fs.writeFile(
+									status.path,
+									managedWorkbaseOpencodeTuiPlugin,
+								)
 							}
 						}
 						files.push({

package/src/workbase/AGENTS.md

@@ -72,7 +72,9 @@ a refinement loop, or pausing or handing off completed implementation work):
 `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.
+workflows for active OpenCode sessions, a managed server plugin that exposes
+skills from the authoritative writable checkout, and an explicitly registered
+TUI companion providing `/agency-debug` without submitting an LLM prompt.
 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
@@ -81,6 +83,9 @@ files, and `agency work` reconciles them before launching an agent.
 
 OpenCode can access the complete workbase tree, but this filesystem permission
 does not expand Agency write authority beyond the checkout reported by
-`agency context`. OpenCode discovers the managed project config from task and
-epic launch directories. No machine-specific path or runtime permission overlay
-is required; agents must follow the authority reported by `agency context`.
+`agency context`. OpenCode remains rooted in the task or epic directory so the
+workbase instructions and config compose normally. The managed plugin resolves
+the writable checkout from launch context or `agency context`, then adds its
+supported skill directories through `skills.paths`; this does not make other
+checkout-local OpenCode configuration authoritative. Agents must follow the
+authority reported by `agency context`.

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

@@ -0,0 +1,61 @@
+import { createHash } from "node:crypto"
+
+const managedHeaderPattern =
+	/^\/\/ agency-managed: sha256=([a-f0-9]{64})\r?\n\r?\n/
+
+const checksum = (content: string) =>
+	createHash("sha256").update(content).digest("hex")
+
+const body = `import { existsSync } from "node:fs"
+import { join, sep } from "node:path"
+import type { Plugin } from "@opencode-ai/plugin"
+
+const contextCheckout = async (directory: string) => {
+  const task = process.env.AGENCY_TASK_ID
+  const phase = process.env.AGENCY_PHASE_ID
+  const args = task
+    ? ["agency", "context", "--task", task, ...(phase ? ["--phase", phase] : []), "--compact", "--json"]
+    : ["agency", "context", ".", "--compact", "--json"]
+  const child = Bun.spawn(args, { cwd: directory, stdout: "pipe", stderr: "ignore" })
+  const output = await new Response(child.stdout).text()
+  if ((await child.exited) !== 0) return
+  const envelope = JSON.parse(output)
+  if (envelope.ok !== true) return
+  return envelope.result?.authority?.writable?.checkoutPath as string | undefined
+}
+
+const plugin: Plugin = async ({ directory }) => ({
+  config: async (config) => {
+    const checkout =
+      process.env.AGENCY_WRITABLE_CHECKOUT ??
+      (await contextCheckout(directory).catch(() => undefined))
+    if (!checkout) return
+
+    const paths = [
+      join(checkout, ".claude", "skills"),
+      join(checkout, ".agents", "skills"),
+      join(checkout, ".opencode", "skill"),
+      join(checkout, ".opencode", "skills"),
+    ].filter(existsSync).map((path) => \`\${path}\${sep}.\`)
+    if (paths.length === 0) return
+
+    config.skills ??= {}
+    config.skills.paths = [...new Set([...(config.skills.paths ?? []), ...paths])]
+  },
+})
+
+export default plugin
+`
+
+const renderManagedWorkbaseOpencodePlugin = (content: string) =>
+	`// agency-managed: sha256=${checksum(content)}\n\n${content}`
+
+export const managedWorkbaseOpencodePlugin =
+	renderManagedWorkbaseOpencodePlugin(body)
+
+export const canUpdateManagedWorkbaseOpencodePlugin = (content: string) => {
+	const match = content.match(managedHeaderPattern)
+	if (!match?.[1]) return false
+
+	return checksum(content.slice(match[0].length)) === match[1]
+}

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

@@ -0,0 +1,30 @@
+import { createHash } from "node:crypto"
+
+const managedHeaderPattern =
+	/^\/\/ agency-managed: sha256=([a-f0-9]{64})\r?\n\r?\n/
+
+const checksum = (content: string) =>
+	createHash("sha256").update(content).digest("hex")
+
+const body = () =>
+	`${JSON.stringify(
+		{
+			$schema: "https://opencode.ai/tui.json",
+			plugin: ["./tui/agency-debug.ts"],
+		},
+		null,
+		2,
+	)}\n`
+
+const renderManagedWorkbaseOpencodeTui = (content: string) =>
+	`// agency-managed: sha256=${checksum(content)}\n\n${content}`
+
+export const managedWorkbaseOpencodeTui =
+	renderManagedWorkbaseOpencodeTui(body())
+
+export const canUpdateManagedWorkbaseOpencodeTui = (content: string) => {
+	const match = content.match(managedHeaderPattern)
+	if (!match?.[1]) return false
+
+	return checksum(content.slice(match[0].length)) === match[1]
+}

package/src/workbase/opencode-tui-plugin-file.ts

@@ -0,0 +1,65 @@
+import { createHash } from "node:crypto"
+
+const managedHeaderPattern =
+	/^\/\/ agency-managed: sha256=([a-f0-9]{64})\r?\n\r?\n/
+
+const checksum = (content: string) =>
+	createHash("sha256").update(content).digest("hex")
+
+const body = `import type { TuiPlugin, TuiPluginModule } from "@opencode-ai/plugin/tui"
+
+const serverMarker = /[\\\\/]\\.$/
+
+const tui: TuiPlugin = async (api) => {
+  api.keymap.registerLayer({
+    commands: [
+      {
+        name: "agency.debug",
+        title: "Agency integration diagnostic",
+        desc: "Check Agency's OpenCode TUI and server plugin initialization",
+        category: "Agency",
+        namespace: "palette",
+        slashName: "agency-debug",
+        run() {
+          const paths = api.state.config.skills?.paths
+          const serverInitialized = paths?.some(
+            (path) => typeof path === "string" && serverMarker.test(path),
+          )
+          const message = serverInitialized
+            ? "TUI companion: initialized. Server plugin: initialized; checkout skills registered."
+            : api.state.ready
+              ? "TUI companion: initialized. Server plugin: indeterminate; no checkout skill marker is present."
+              : "TUI companion: initialized. Server plugin: indeterminate; server state is not ready."
+
+          api.ui.toast({
+            variant: serverInitialized ? "success" : "warning",
+            title: "Agency integration",
+            message,
+            duration: 5000,
+          })
+        },
+      },
+    ],
+  })
+}
+
+const plugin: TuiPluginModule & { id: string } = {
+  id: "agency.debug",
+  tui,
+}
+
+export default plugin
+`
+
+const renderManagedWorkbaseOpencodeTuiPlugin = (content: string) =>
+	`// agency-managed: sha256=${checksum(content)}\n\n${content}`
+
+export const managedWorkbaseOpencodeTuiPlugin =
+	renderManagedWorkbaseOpencodeTuiPlugin(body)
+
+export const canUpdateManagedWorkbaseOpencodeTuiPlugin = (content: string) => {
+	const match = content.match(managedHeaderPattern)
+	if (!match?.[1]) return false
+
+	return checksum(content.slice(match[0].length)) === match[1]
+}