@markjaquith/agency 2.36.0 → 2.37.0

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,18 +79,26 @@ 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
-operations must still follow the write authority reported by `agency context`.
+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
+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 operations must still follow the write authority reported by
+`agency context`.
 
 Repository aliases and canonical fetch remotes are declared in tracked
 `agency.json`; local bare clones and symlinks remain ignored under

package/package.json

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

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/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,9 +67,13 @@ 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

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: "..",