@markjaquith/agency 2.36.0 → 2.37.1

package/README.md

@@ -47,9 +47,11 @@ and customized documents remain valid.
 
 ```text
 workbase/
-  AGENTS.md                # managed workbase instructions
+  AGENTS.md                # optional user-owned workbase instructions
+  .agency/
+    AGENTS.md              # managed Agency instructions
   .opencode/
-    opencode.jsonc         # managed whole-workbase reference
+    opencode.jsonc         # managed instructions and whole-workbase reference
   agency.json              # tracked config and portable repository declarations
   repos/                   # ignored local materializations
     frontend/              # bare Git repository or symlink
@@ -77,17 +79,21 @@ workbase/
 ```
 
 Agency keeps discovery and other observational commands read-only. Run
-`agency integration status` to inspect `AGENTS.md` and
+`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 OpenCode config advertises the complete workbase as one portable relative
-reference. `agency work` sets `OPENCODE_CONFIG` to the managed file and injects
-runtime-only absolute rules that allow external access across the workbase while
-denying edits outside the execution unit's writable checkout. This makes the
-config effective from nested task and phase Git checkouts without persisting a
-machine-specific path or granting access outside the workbase. Bash and Agency
+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
+can load the hidden file. A customized root file, including a symlink, is
+preserved as user-owned content.
+
+The OpenCode config loads Agency's hidden instructions in addition to any
+user-owned root `AGENTS.md` and advertises the complete workbase as one portable
+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`.
 
 Repository aliases and canonical fetch remotes are declared in tracked
@@ -216,10 +222,8 @@ Every runner receives the same `AGENCY_RUNNER`, `AGENCY_CLAIMANT`,
 environment is added without overriding these normalized values.
 `AGENCY_CLAIM_REVISION` is empty for local `agency work` launches.
 `AGENCY_PROMPT` is empty unless `--auto` is set.
-The `opencode` runner additionally receives `OPENCODE_CONFIG` for the workbase's
-managed integration and `OPENCODE_CONFIG_CONTENT` with runtime-only,
-workbase-scoped access and edit rules. These values keep the Git-synced config
-portable while providing whole-workbase read access at every launch location.
+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.
 `--print-command` prints the exact cwd and argv plus non-secret environment keys

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "2.36.0",
+  "version": "2.37.1",
   "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, relative } from "node:path"
+import { join } from "node:path"
 import errorFixture from "../fixtures/protocol/error.json"
 import successFixture from "../fixtures/protocol/success.json"
 import { cleanupTempDir, createTempDir } from "./test-utils"
@@ -862,6 +862,9 @@ status: open
 			await runGit(["-C", source, "remote", "add", "origin", daemon.remote])
 
 			parseJson(await runCli(["init", root, "--json"], parent))
+			expect(
+				Bun.spawnSync(["git", "init", "--initial-branch=main", root]).exitCode,
+			).toBe(0)
 			const agencyConfigPath = join(root, "agency.json")
 			const agencyConfig = JSON.parse(await Bun.file(agencyConfigPath).text())
 			await Bun.write(
@@ -942,10 +945,8 @@ status: open
 				),
 			)
 
-			const taskWorkspace = parseJson(
-				await runCli(["work", "prepare", "example", "--json"], root),
-			)
-			const phaseWorkspace = parseJson(
+			parseJson(await runCli(["work", "prepare", "example", "--json"], root))
+			parseJson(
 				await runCli(
 					[
 						"work",
@@ -984,22 +985,18 @@ status: open
 				{
 					args: ["--task", "example"],
 					cwd: join(workbaseRoot, "tasks/example"),
-					writable: taskWorkspace.writablePath,
 				},
 				{
 					args: ["--task", "pipeline", "--phase", "build"],
 					cwd: join(workbaseRoot, "tasks/pipeline"),
-					writable: phaseWorkspace.writablePath,
 				},
 				{
 					args: ["--epic", "delivery"],
 					cwd: join(workbaseRoot, "epics/delivery"),
-					writable: null,
 				},
 				{
 					args: ["--task", "pipeline"],
 					cwd: join(workbaseRoot, "tasks/pipeline"),
-					writable: null,
 				},
 			]
 			for (const launch of launches) {
@@ -1011,9 +1008,8 @@ status: open
 				expect(printed.stderr).toBe("")
 				const contract = JSON.parse(printed.stdout)
 				expect(contract.cwd).toBe(launch.cwd)
-				expect(contract.environment.OPENCODE_CONFIG).toBe(
-					join(workbaseRoot, ".opencode/opencode.jsonc"),
-				)
+				expect(contract.environment.OPENCODE_CONFIG).toBeUndefined()
+				expect(contract.environment.OPENCODE_CONFIG_CONTENT).toBeUndefined()
 				const environment = {
 					...process.env,
 					...contract.environment,
@@ -1030,35 +1026,24 @@ status: open
 					expect.arrayContaining([
 						expect.objectContaining({
 							permission: "external_directory",
-							pattern: join(workbaseRoot, "**"),
+							pattern: join(workbaseRoot, "*"),
 							action: "allow",
 						}),
 					]),
 				)
-				expect(agent.permission).toEqual(
-					expect.arrayContaining([
-						expect.objectContaining({
-							permission: "edit",
-							pattern: "*",
-							action: "deny",
-						}),
-					]),
-				)
-				if (launch.writable) {
-					expect(agent.permission).toEqual(
-						expect.arrayContaining(
-							[workbaseRoot, launch.cwd].map((base) =>
-								expect.objectContaining({
-									permission: "edit",
-									pattern: join(relative(base, launch.writable!), "**"),
-									action: "allow",
-								}),
-							),
-						),
-					)
-				}
-
 				if (launch === launches[0]) {
+					const configProbe = Bun.spawnSync(["opencode", "debug", "config"], {
+						cwd: contract.cwd,
+						env: environment,
+					})
+					expect(configProbe.exitCode).toBe(0)
+					expect(JSON.parse(configProbe.stdout.toString()).references).toEqual({
+						workbase: {
+							path: "..",
+							description:
+								"Complete Agency workbase context; write authority still comes only from agency context",
+						},
+					})
 					for (const document of documents) {
 						const read = Bun.spawnSync(
 							[
@@ -1080,6 +1065,55 @@ status: open
 				}
 			}
 
+			const directEnvironment: Record<string, string | undefined> = {
+				...process.env,
+				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 [
+				join(workbaseRoot, "tasks/example"),
+				join(workbaseRoot, "tasks/pipeline"),
+				join(workbaseRoot, "epics/delivery"),
+			]) {
+				const probe = Bun.spawnSync(["opencode", "debug", "agent", "build"], {
+					cwd,
+					env: directEnvironment,
+				})
+				expect(probe.exitCode).toBe(0)
+				const agent = JSON.parse(probe.stdout.toString())
+				expect(agent.permission).toEqual(
+					expect.arrayContaining([
+						expect.objectContaining({
+							permission: "external_directory",
+							pattern: join(workbaseRoot, "*"),
+							action: "allow",
+						}),
+					]),
+				)
+				for (const document of documents) {
+					const read = Bun.spawnSync(
+						[
+							"opencode",
+							"debug",
+							"agent",
+							"build",
+							"--tool",
+							"read",
+							"--params",
+							JSON.stringify({ filePath: document }),
+						],
+						{ cwd, env: directEnvironment },
+					)
+					expect(read.exitCode).toBe(0)
+					expect(JSON.parse(read.stdout.toString()).result.output).toContain(
+						`<path>${document}</path>`,
+					)
+				}
+			}
+
 			parseJson(
 				await runCli(["task", "status", "example", "done", "--json"], root),
 			)
@@ -1135,7 +1169,7 @@ status: open
 				graph.nodes.find((node: any) => node.id === "task:pipeline").status,
 			).toBe("working")
 		},
-		30_000,
+		90_000,
 	)
 
 	test("envelopes help and version output in machine mode", async () => {

package/src/commands/doctor.test.ts

@@ -114,7 +114,7 @@ status: open
 	test("reports repository, ref, remote, and managed-file failures", async () => {
 		await Bun.$`git -C ${repository} remote remove origin`
 		await Bun.$`git -C ${repository} branch -m other`
-		await write(root, "AGENTS.md", managedAgents("old\n"))
+		await write(root, ".agency/AGENTS.md", managedAgents("old\n"))
 
 		const logs = await captureLogs(() =>
 			runTestEffect(doctor({ cwd: root, json: true })),
@@ -153,7 +153,7 @@ status: open
 		expect(check).toMatchObject({
 			level: "warning",
 			status: "fail",
-			message: expect.stringContaining("cannot guarantee whole-workbase"),
+			message: expect.stringContaining("cannot guarantee its instructions"),
 			remediation: expect.stringContaining("global config"),
 		})
 		expect(await Bun.file(join(root, ".opencode/opencode.jsonc")).text()).toBe(
@@ -181,6 +181,7 @@ status: open
 		}
 
 		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(false)
+		expect(await Bun.file(join(root, ".agency/AGENTS.md")).exists()).toBe(false)
 		expect(
 			await Bun.file(join(root, ".opencode/opencode.jsonc")).exists(),
 		).toBe(false)

package/src/commands/init.test.ts

@@ -33,11 +33,13 @@ describe("init command", () => {
 		expect(await Bun.file(join(root, ".gitignore")).text()).toBe(
 			"/repos/\n/tasks/*/code/\n/tasks/*/phases/*/code/\n",
 		)
-		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(true)
+		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(false)
+		expect(await Bun.file(join(root, ".agency/AGENTS.md")).exists()).toBe(true)
 		const opencode = await Bun.file(
 			join(root, ".opencode/opencode.jsonc"),
 		).text()
 		const config = JSON.parse(opencode.slice(opencode.indexOf("\n\n") + 2))
+		expect(config.instructions).toEqual([".agency/AGENTS.md"])
 		expect(config.references).toEqual({
 			workbase: expect.objectContaining({ path: ".." }),
 		})

package/src/commands/integration.test.ts

@@ -50,7 +50,7 @@ describe("integration command", () => {
 			runTestEffect(integration({ subcommand: "status", cwd: root })),
 		)
 
-		expect(logs.join("\n")).toContain("cannot guarantee whole-workbase")
+		expect(logs.join("\n")).toContain("cannot guarantee its instructions")
 		expect(logs.join("\n")).toContain("global config")
 	})
 
@@ -63,7 +63,8 @@ describe("integration command", () => {
 			{ name: "agents", state: "managed", changed: true },
 			{ name: "opencode", state: "managed", changed: true },
 		])
-		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(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)

package/src/commands/work.test.ts

@@ -486,23 +486,10 @@ describe("work command", () => {
 			],
 			cwd: "/workbase/epics/delivery",
 		})
-		expect(harness.launchEnvironments[0]?.OPENCODE_CONFIG).toBe(
-			"/workbase/.opencode/opencode.jsonc",
-		)
+		expect(harness.launchEnvironments[0]?.OPENCODE_CONFIG).toBeUndefined()
 		expect(
-			JSON.parse(harness.launchEnvironments[0]!.OPENCODE_CONFIG_CONTENT!),
-		).toEqual({
-			permission: {
-				external_directory: { "/workbase/**": "allow" },
-				edit: { "*": "deny" },
-			},
-			agent: {
-				build: { permission: { edit: { "*": "deny" } } },
-				plan: { permission: { edit: { "*": "deny" } } },
-				general: { permission: { edit: { "*": "deny" } } },
-				explore: { permission: { edit: { "*": "deny" } } },
-			},
-		})
+			harness.launchEnvironments[0]?.OPENCODE_CONFIG_CONTENT,
+		).toBeUndefined()
 	})
 
 	test("resolves an existing positional path before treating it as a task ID", async () => {
@@ -553,9 +540,7 @@ describe("work command", () => {
 			],
 			cwd: "/workbase/tasks/delivery",
 		})
-		expect(harness.launchEnvironments[0]?.OPENCODE_CONFIG).toBe(
-			"/workbase/.opencode/opencode.jsonc",
-		)
+		expect(harness.launchEnvironments[0]?.OPENCODE_CONFIG).toBeUndefined()
 	})
 
 	test("infers a phase from a nested checkout directory", async () => {
@@ -585,9 +570,7 @@ describe("work command", () => {
 		expect(harness.statusUpdates).toEqual([
 			"phase:example:implementation:working",
 		])
-		expect(harness.launchEnvironments[0]?.OPENCODE_CONFIG).toBe(
-			"/workbase/.opencode/opencode.jsonc",
-		)
+		expect(harness.launchEnvironments[0]?.OPENCODE_CONFIG).toBeUndefined()
 	})
 
 	test("infers a single-phase task from a nested checkout directory", async () => {
@@ -601,9 +584,7 @@ describe("work command", () => {
 
 		expect(harness.events[0]).toBe("materialize")
 		expect(harness.launches[0]?.cwd).toBe(taskDirectory)
-		expect(harness.launchEnvironments[0]?.OPENCODE_CONFIG).toBe(
-			"/workbase/.opencode/opencode.jsonc",
-		)
+		expect(harness.launchEnvironments[0]?.OPENCODE_CONFIG).toBeUndefined()
 	})
 
 	test("selects a target when no directory is provided", async () => {
@@ -781,9 +762,7 @@ describe("work command", () => {
 		])
 		expect(harness.launchEnvironments[0]?.AGENCY_PROMPT).toBe("")
 		expect(harness.statusUpdates).toEqual(["task:example:working"])
-		expect(harness.launchEnvironments[0]?.OPENCODE_CONFIG).toBe(
-			"/workbase/.opencode/opencode.jsonc",
-		)
+		expect(harness.launchEnvironments[0]?.OPENCODE_CONFIG).toBeUndefined()
 		expect(harness.progressUpdates).toEqual([
 			"start:Preparing workspace...",
 			"succeed:Workspace ready",
@@ -936,33 +915,15 @@ describe("work command", () => {
 		expect(harness.taskStatuses.example).toBe("done")
 	})
 
-	test("prints the runtime OpenCode integration config", async () => {
+	test("does not inject runtime OpenCode configuration", async () => {
 		const harness = createHarness()
 		const output = await captureLogs(() =>
 			harness.run({ taskId: "example", opencode: true, printCommand: true }),
 		)
 		const printed = JSON.parse(output.join("\n"))
 
-		expect(printed.environment.OPENCODE_CONFIG).toBe(
-			"/workbase/.opencode/opencode.jsonc",
-		)
-		const edit = {
-			"*": "deny",
-			"tasks/example/code/agency/**": "allow",
-			"code/agency/**": "allow",
-		}
-		expect(JSON.parse(printed.environment.OPENCODE_CONFIG_CONTENT)).toEqual({
-			permission: {
-				external_directory: { "/workbase/**": "allow" },
-				edit,
-			},
-			agent: {
-				build: { permission: { edit } },
-				plan: { permission: { edit } },
-				general: { permission: { edit } },
-				explore: { permission: { edit } },
-			},
-		})
+		expect(printed.environment.OPENCODE_CONFIG).toBeUndefined()
+		expect(printed.environment.OPENCODE_CONFIG_CONTENT).toBeUndefined()
 	})
 
 	test("does not override customized OpenCode access policy", async () => {

package/src/commands/work.ts

@@ -122,10 +122,7 @@ export const work = (
 		const inputAllowed = options.inputAllowed ?? true
 		const root = yield* resolveWorkbase(startPath, pickBase, inputAllowed)
 		if (!root) return
-		const integration = yield* integrations.sync(root)
-		const managedOpencode = integration.files.some(
-			(file) => file.name === "opencode" && file.state === "managed",
-		)
+		yield* integrations.sync(root)
 		const { config } = yield* workbase.loadConfig(root)
 
 		let target: WorkTarget | null = null
@@ -239,7 +236,6 @@ 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)
@@ -265,7 +261,6 @@ 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(
@@ -336,35 +331,6 @@ export const work = (
 			...resolved.environment,
 			...runnerEnvironment(runner, variables),
 		}
-		if (runner === "opencode" && managedOpencode) {
-			environment.OPENCODE_CONFIG = join(root, ".opencode", "opencode.jsonc")
-			const execution =
-				target.kind === "phase" ||
-				(target.kind === "task" && !target.multiPhase)
-			const edit = execution
-				? {
-						"*": "deny" as const,
-						...Object.fromEntries(
-							[root, launchPath].map((base) => [
-								join(relative(base, writablePath!), "**").split(sep).join("/"),
-								"allow" as const,
-							]),
-						),
-					}
-				: { "*": "deny" as const }
-			environment.OPENCODE_CONFIG_CONTENT = JSON.stringify({
-				permission: {
-					external_directory: { [join(root, "**")]: "allow" },
-					edit,
-				},
-				agent: {
-					build: { permission: { edit } },
-					plan: { permission: { edit } },
-					general: { permission: { edit } },
-					explore: { permission: { edit } },
-				},
-			})
-		}
 		if (options.printCommand) {
 			log(
 				JSON.stringify(

package/src/services/FileSystemService.ts

@@ -9,6 +9,7 @@ import {
 	rmdir,
 	stat,
 	symlink,
+	unlink,
 } from "node:fs/promises"
 import { spawnProcess } from "../utils/process"
 
@@ -117,6 +118,16 @@ export class FileSystemService extends Effect.Service<FileSystemService>()(
 						}),
 				}),
 
+			deleteFile: (path: string) =>
+				Effect.tryPromise({
+					try: () => unlink(path),
+					catch: (error) =>
+						new FileSystemError({
+							message: `Failed to delete file: ${path}`,
+							cause: error,
+						}),
+				}),
+
 			createDirectory: (path: string) =>
 				Effect.tryPromise({
 					try: () => mkdir(path, { recursive: true }),

package/src/services/IntegrationService.test.ts

@@ -47,9 +47,9 @@ describe("IntegrationService", () => {
 			"missing",
 			"missing",
 		])
-		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(false)
+		expect(await Bun.file(join(root, ".agency/AGENTS.md")).exists()).toBe(false)
 
-		await write(root, "AGENTS.md", managedWorkbaseAgents)
+		await write(root, ".agency/AGENTS.md", managedWorkbaseAgents)
 		await write(root, ".opencode/opencode.jsonc", managedWorkbaseOpencode)
 		expect((await status(root)).files.map(({ state }) => state)).toEqual([
 			"managed",
@@ -58,7 +58,7 @@ describe("IntegrationService", () => {
 	})
 
 	test("reports customized and checksum-safe drifted files", async () => {
-		await write(root, "AGENTS.md", "# Custom instructions\n")
+		await write(root, ".agency/AGENTS.md", "# Custom instructions\n")
 		await write(
 			root,
 			".opencode/opencode.jsonc",
@@ -97,6 +97,7 @@ describe("IntegrationService", () => {
 	test("grants OpenCode access to the complete workbase", () => {
 		const config = JSON.parse(managedBody(managedWorkbaseOpencode))
 
+		expect(config.instructions).toEqual([".agency/AGENTS.md"])
 		expect(config.references).toEqual({
 			workbase: {
 				path: "..",
@@ -151,8 +152,10 @@ describe("IntegrationService", () => {
 	})
 
 	test("syncs missing and drifted files while preserving customized files", async () => {
-		const customAgents = "# Custom instructions\n"
-		await write(root, "AGENTS.md", customAgents)
+		const customRootAgents = "# User-owned workbase instructions\n"
+		const customManagedAgents = "# Customized Agency instructions\n"
+		await write(root, "AGENTS.md", customRootAgents)
+		await write(root, ".agency/AGENTS.md", customManagedAgents)
 		await write(
 			root,
 			".opencode/opencode.jsonc",
@@ -164,14 +167,50 @@ describe("IntegrationService", () => {
 			{ name: "agents", state: "customized", changed: false },
 			{ name: "opencode", state: "managed", changed: true },
 		])
-		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(customAgents)
+		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(
+			customRootAgents,
+		)
+		expect(await Bun.file(join(root, ".agency/AGENTS.md")).text()).toBe(
+			customManagedAgents,
+		)
 		expect(await Bun.file(join(root, ".opencode/opencode.jsonc")).text()).toBe(
 			managedWorkbaseOpencode,
 		)
 
-		await unlink(join(root, "AGENTS.md"))
+		await unlink(join(root, ".agency/AGENTS.md"))
 		const second = await sync(root)
 		expect(second.files[0]).toMatchObject({ state: "managed", changed: true })
+		expect(await Bun.file(join(root, ".agency/AGENTS.md")).text()).toBe(
+			managedWorkbaseAgents,
+		)
+		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(
+			customRootAgents,
+		)
+	})
+
+	test("migrates checksum-valid root instructions", async () => {
+		await write(root, "AGENTS.md", managedWorkbaseAgents)
+
+		const result = await sync(root)
+
+		expect(result.files[0]).toMatchObject({ state: "managed", changed: true })
+		expect(await Bun.file(join(root, ".agency/AGENTS.md")).text()).toBe(
+			managedWorkbaseAgents,
+		)
+		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(false)
+	})
+
+	test("preserves legacy instructions when the OpenCode config is customized", async () => {
+		await write(root, "AGENTS.md", managedWorkbaseAgents)
+		await write(root, ".opencode/opencode.json", '{"model":"test/model"}\n')
+
+		const result = await sync(root)
+
+		expect(result.files[0]).toMatchObject({ state: "managed", changed: true })
+		expect(result.files[1]).toMatchObject({
+			state: "customized",
+			changed: false,
+		})
 		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(
 			managedWorkbaseAgents,
 		)
@@ -198,14 +237,16 @@ describe("IntegrationService", () => {
 			"# Previous Agency instructions\n",
 			" -->",
 		)}User edit\n`
-		await write(root, "AGENTS.md", tampered)
+		await write(root, ".agency/AGENTS.md", tampered)
 
 		const result = await sync(root)
 		expect(result.files[0]).toMatchObject({
 			state: "customized",
 			changed: false,
 		})
-		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(tampered)
+		expect(await Bun.file(join(root, ".agency/AGENTS.md")).text()).toBe(
+			tampered,
+		)
 	})
 
 	test("does not overwrite a user-modified OpenCode configuration", async () => {
@@ -228,7 +269,8 @@ describe("IntegrationService", () => {
 	test("does not follow symlinked integration files", async () => {
 		const target = join(root, "custom-agents.md")
 		await Bun.write(target, "# External instructions\n")
-		await symlink(target, join(root, "AGENTS.md"))
+		await mkdir(join(root, ".agency"), { recursive: true })
+		await symlink(target, join(root, ".agency/AGENTS.md"))
 
 		const result = await sync(root)
 		expect(result.files[0]).toMatchObject({

package/src/services/IntegrationService.ts

@@ -33,23 +33,23 @@ const describe = (
 		if (state === "managed") {
 			return {
 				diagnostic:
-					"Agency's managed OpenCode launch config is ready to provide whole-workbase read access.",
+					"Agency's managed OpenCode launch config is ready to load Agency instructions and provide whole-workbase read access.",
 				remediation: null,
 			}
 		}
 		if (state === "customized") {
 			return {
 				diagnostic:
-					"Agency cannot guarantee whole-workbase read access from this customized OpenCode config.",
+					"Agency cannot guarantee its instructions or whole-workbase read access from this customized OpenCode config.",
 				remediation:
 					"Back up and remove the customized file, run 'agency integration sync', then move any retained custom settings to OpenCode's global config.",
 			}
 		}
 		return {
 			diagnostic:
-				"Agency OpenCode launches cannot load current whole-workbase access.",
+				"Agency OpenCode launches cannot load current Agency instructions or whole-workbase access.",
 			remediation:
-				"Run 'agency integration sync' to install whole-workbase OpenCode access.",
+				"Run 'agency integration sync' to install Agency instructions and whole-workbase OpenCode access.",
 		}
 	}
 
@@ -94,7 +94,7 @@ const classify = (
 const inspect = (root: string) =>
 	Effect.gen(function* () {
 		const fs = yield* FileSystemService
-		const agentsPath = join(root, "AGENTS.md")
+		const agentsPath = join(root, ".agency", "AGENTS.md")
 		const opencodeDirectory = join(root, ".opencode")
 		const opencodePath = join(opencodeDirectory, "opencode.jsonc")
 		const opencodeJsonPath = join(opencodeDirectory, "opencode.json")
@@ -138,6 +138,18 @@ const inspect = (root: string) =>
 		return files
 	})
 
+const canRemoveLegacyAgents = (root: string) =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystemService
+		const path = join(root, "AGENTS.md")
+		if (
+			(yield* fs.readSymlinkTarget(path)) !== null ||
+			!(yield* fs.exists(path))
+		)
+			return false
+		return canUpdateManagedWorkbaseAgents(yield* fs.readFile(path))
+	})
+
 export class IntegrationService extends Effect.Service<IntegrationService>()(
 	"IntegrationService",
 	{
@@ -155,13 +167,19 @@ export class IntegrationService extends Effect.Service<IntegrationService>()(
 					const workbase = yield* WorkbaseService
 					const root = yield* workbase.discover(startPath)
 					const statuses = yield* inspect(root)
+					const removeLegacyAgents =
+						statuses.some(
+							(status) =>
+								status.name === "opencode" && status.state !== "customized",
+						) && (yield* canRemoveLegacyAgents(root))
 					const files: IntegrationSyncFile[] = []
 
 					for (const status of statuses) {
-						const changed =
+						const needsWrite =
 							status.state === "missing" || status.state === "drifted"
-						if (changed) {
+						if (needsWrite) {
 							if (status.name === "agents") {
+								yield* fs.createDirectory(join(root, ".agency"))
 								yield* fs.writeFile(status.path, managedWorkbaseAgents)
 							} else {
 								yield* fs.createDirectory(join(root, ".opencode"))
@@ -172,12 +190,15 @@ export class IntegrationService extends Effect.Service<IntegrationService>()(
 							...fileStatus(
 								status.name,
 								status.path,
-								changed ? "managed" : status.state,
+								needsWrite ? "managed" : status.state,
 							),
-							changed,
+							changed:
+								needsWrite || (status.name === "agents" && removeLegacyAgents),
 						})
 					}
 
+					if (removeLegacyAgents) yield* fs.deleteFile(join(root, "AGENTS.md"))
+
 					return { root, files }
 				}),
 		}),

package/src/workbase/AGENTS.md

@@ -67,13 +67,16 @@ a refinement loop, or pausing or handing off completed implementation work):
 ## Managed Integration
 
 `agency integration status` reports `managed`, `drifted`, `customized`, or
-`missing` generated files. `agency integration sync` updates only missing or
-checksum-safe drifted files and preserves user-customized files. `agency init`
-creates these files, and `agency work` reconciles them before launching an agent.
+`missing` generated files. Agency keeps these instructions in
+`.agency/AGENTS.md`, and its managed OpenCode config loads them automatically.
+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
+files and preserves user-customized files. `agency init` creates the managed
+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`. Agency launches expose the managed OpenCode config file at
-runtime and inject absolute access rules scoped to this workbase. Direct edits
-remain denied outside the writable checkout, and no machine-specific path is
-stored in the Git-synced config.
+`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`.

package/src/workbase/opencode-file.ts

@@ -10,6 +10,7 @@ const body = () =>
 	`${JSON.stringify(
 		{
 			$schema: "https://opencode.ai/config.json",
+			instructions: [".agency/AGENTS.md"],
 			references: {
 				workbase: {
 					path: "..",