@markjaquith/agency 2.44.0 → 2.45.0

package/README.md

@@ -52,6 +52,8 @@ workbase/
     AGENTS.md              # managed Agency instructions
   .opencode/
     opencode.jsonc         # managed @agency subagent, instructions, and reference
+    command/agency.md      # managed /agency workflow command
+    plugin/agency-repository-skills.ts # managed checkout skill discovery
   agency.json              # tracked config and portable repository declarations
   repos/                   # ignored local materializations
     frontend/              # bare Git repository or symlink
@@ -232,12 +234,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.45.0",
   "description": "Manage agentic work across repositories with durable workbases",
   "keywords": [
     "agents",

package/src/cli.test.ts

@@ -1,5 +1,5 @@
 import { afterAll, afterEach, describe, expect, test } from "bun:test"
-import { access, mkdir, realpath } from "node:fs/promises"
+import { access, mkdir, realpath, symlink } from "node:fs/promises"
 import { join } from "node:path"
 import errorFixture from "../fixtures/protocol/error.json"
 import successFixture from "../fixtures/protocol/success.json"
@@ -527,6 +527,7 @@ describe("CLI", () => {
 			{ name: "agents", state: "managed" },
 			{ name: "opencode", state: "managed" },
 			{ name: "opencode-command", state: "managed" },
+			{ name: "opencode-plugin", state: "managed" },
 		])
 
 		const synced = parseJson(
@@ -536,6 +537,7 @@ 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 },
 		])
 	})
 
@@ -864,10 +866,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 +1010,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 +1050,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 +1083,41 @@ 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)
+					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.")
+				}
 				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 +1164,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 +1201,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 +1235,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,11 @@ 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")
 	})
 
 	test("preserves existing gitignore entries", async () => {

package/src/commands/integration.test.ts

@@ -41,6 +41,11 @@ describe("integration command", () => {
 					state: "missing",
 					remediation: expect.stringContaining("integration sync"),
 				},
+				{
+					name: "opencode-plugin",
+					state: "missing",
+					remediation: expect.stringContaining("integration sync"),
+				},
 			],
 		})
 	})
@@ -79,7 +84,12 @@ 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.`)
 	})
 
 	test("explicitly synchronizes integration files", async () => {
@@ -91,6 +101,7 @@ 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 },
 		])
 		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 +111,11 @@ 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)
 	})
 
 	test("formats integration sync results for people", async () => {
@@ -119,6 +135,10 @@ 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.`)
 	})
 })

package/src/commands/integration.ts

@@ -12,7 +12,11 @@ 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"
 		readonly path: string
 		readonly state: string
 		readonly diagnostic: string
@@ -25,6 +29,7 @@ const integrationNames = {
 	agents: "Agent instructions",
 	opencode: "OpenCode config",
 	"opencode-command": "OpenCode /agency command",
+	"opencode-plugin": "OpenCode checkout skills",
 } as const
 
 const logHumanResult = (
@@ -83,7 +88,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 and writable-checkout skills, 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

@@ -10,6 +10,10 @@ import {
 	managedWorkbaseOpencodeCommand,
 } from "../workbase/opencode-command-file"
 import { managedWorkbaseOpencode } from "../workbase/opencode-file"
+import {
+	canUpdateManagedWorkbaseOpencodePlugin,
+	managedWorkbaseOpencodePlugin,
+} from "../workbase/opencode-plugin-file"
 import { IntegrationService } from "./IntegrationService"
 
 const write = async (root: string, path: string, content: string) => {
@@ -51,6 +55,7 @@ describe("IntegrationService", () => {
 			"missing",
 			"missing",
 			"missing",
+			"missing",
 		])
 		expect(await Bun.file(join(root, ".agency/AGENTS.md")).exists()).toBe(false)
 
@@ -61,10 +66,16 @@ describe("IntegrationService", () => {
 			".opencode/command/agency.md",
 			managedWorkbaseOpencodeCommand,
 		)
+		await write(
+			root,
+			".opencode/plugin/agency-repository-skills.ts",
+			managedWorkbaseOpencodePlugin,
+		)
 		expect((await status(root)).files.map(({ state }) => state)).toEqual([
 			"managed",
 			"managed",
 			"managed",
+			"managed",
 		])
 	})
 
@@ -80,9 +91,39 @@ describe("IntegrationService", () => {
 			"customized",
 			"drifted",
 			"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(
+			canUpdateManagedWorkbaseOpencodePlugin(managedWorkbaseOpencodePlugin),
+		).toBe(true)
+		expect(
+			canUpdateManagedWorkbaseOpencodePlugin(
+				managedWorkbaseOpencodePlugin.replace("config.skills ??= {}", ""),
+			),
+		).toBe(false)
+	})
+
 	test("generates a positional OpenCode command for Agency workflows", () => {
 		expect(managedWorkbaseOpencodeCommand).toContain(
 			"description: Operate Agency work",
@@ -247,6 +288,7 @@ 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 },
 		])
 		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(
 			customRootAgents,
@@ -260,6 +302,11 @@ 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)
 
 		await unlink(join(root, ".agency/AGENTS.md"))
 		const second = await sync(root)
@@ -272,6 +319,33 @@ 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 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,15 @@ import {
 	canUpdateManagedWorkbaseOpencodeCommand,
 	managedWorkbaseOpencodeCommand,
 } from "../workbase/opencode-command-file"
+import {
+	canUpdateManagedWorkbaseOpencodePlugin,
+	managedWorkbaseOpencodePlugin,
+} from "../workbase/opencode-plugin-file"
 
 type IntegrationFileState = "managed" | "customized" | "missing" | "drifted"
 
 interface IntegrationFileStatus {
-	readonly name: "agents" | "opencode" | "opencode-command"
+	readonly name: "agents" | "opencode" | "opencode-command" | "opencode-plugin"
 	readonly path: string
 	readonly state: IntegrationFileState
 	readonly diagnostic: string
@@ -75,6 +79,26 @@ 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.",
+					}
+	}
 
 	return state === "missing" || state === "drifted"
 		? {
@@ -123,6 +147,16 @@ const inspect = (root: string) =>
 		const opencodeJsonPath = join(opencodeDirectory, "opencode.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 files: IntegrationFileStatus[] = []
 
 		files.push(
@@ -183,6 +217,27 @@ 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"))
+		}
+
 		return files
 	})
 
@@ -232,9 +287,12 @@ 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 {
+								yield* fs.createDirectory(join(root, ".opencode", "plugin"))
+								yield* fs.writeFile(status.path, managedWorkbaseOpencodePlugin)
 							}
 						}
 						files.push({

package/src/workbase/AGENTS.md

@@ -72,7 +72,8 @@ 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, and a managed plugin that exposes skills
+from the authoritative writable checkout without changing the project root.
 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 +82,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 } 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)
+    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]
+}