@markjaquith/agency 2.7.3 → 2.8.0

package/README.md

@@ -71,11 +71,12 @@ workbase/
             backend/
 ```
 
-Agency creates `AGENTS.md` and `.opencode/opencode.jsonc` during initialization
-and ensures they exist whenever the workbase is discovered. The OpenCode config
-grants external-directory access to task and epic references. Checksums in the
-generated files let newer Agency versions refresh unmodified content while
-preserving custom or edited files.
+Agency keeps discovery and other observational commands read-only. Run
+`agency integration status` to inspect `AGENTS.md` and
+`.opencode/opencode.jsonc`, then `agency integration sync` to create missing
+files or refresh checksum-safe managed files. The OpenCode config grants
+external-directory access to task and epic references. Customized files are
+reported but never overwritten.
 
 Repository metadata comes directly from Git under `repos/{alias}`. Workbase
 configuration may provide a custom writable-worktree creation command.
@@ -242,6 +243,8 @@ agency pr create refresh-copy
 agency init [path] [--json]
 agency workbase add <path> [--json]
 agency workbase list [--json]
+agency integration status [--json]
+agency integration sync [--json]
 agency repo add <alias> <remote> [--json]
 agency repo link <alias> <path> [--json]
 agency repo list [--json]
@@ -253,7 +256,8 @@ Registered workbases are stored in
 repository. Alias names are then used by all documents and commands.
 
 Commands that print Agency-owned results accept `--json`, including initialization,
-repository mutations, entity creation/list/show, status, validation, and PR creation.
+integration inspection/sync, repository mutations, entity creation/list/show,
+status, validation, and PR creation.
 
 ### Epics
 

package/cli.ts

@@ -13,6 +13,10 @@ import { epic, help as epicHelp } from "./src/commands/epic"
 import { phase, help as phaseHelp } from "./src/commands/phase"
 import { archive, help as archiveHelp } from "./src/commands/archive"
 import { workbase, help as workbaseHelp } from "./src/commands/workbase"
+import {
+	integration,
+	help as integrationHelp,
+} from "./src/commands/integration"
 import type { Command } from "./src/types"
 import { FileSystemService } from "./src/services/FileSystemService"
 import { WorkbaseService } from "./src/services/WorkbaseService"
@@ -23,6 +27,7 @@ import { PhaseService } from "./src/services/PhaseService"
 import { WorktreeService } from "./src/services/WorktreeService"
 import { PullRequestService } from "./src/services/PullRequestService"
 import { ArchiveService } from "./src/services/ArchiveService"
+import { IntegrationService } from "./src/services/IntegrationService"
 
 // Create CLI layer with all services
 const CliLayer = Layer.mergeAll(
@@ -35,6 +40,7 @@ const CliLayer = Layer.mergeAll(
 	WorktreeService.Default,
 	PullRequestService.Default,
 	ArchiveService.Default,
+	IntegrationService.Default,
 )
 
 /**
@@ -191,6 +197,22 @@ const commands: Record<string, Command> = {
 			)
 		},
 	},
+	integration: {
+		run: async (args: string[], options: Record<string, any>) => {
+			if (options.help) {
+				console.log(integrationHelp)
+				return
+			}
+			await runCommand(
+				integration({
+					subcommand: args[0],
+					json: options.json,
+					silent: options.silent,
+					verbose: options.verbose,
+				}),
+			)
+		},
+	},
 	repo: {
 		run: async (args: string[], options: Record<string, any>) => {
 			if (options.help) {
@@ -296,6 +318,7 @@ Usage: agency <command> [options]
 Commands:
   init [path]            Initialize an Agency workbase
   workbase <subcommand>  Manage registered workbases
+  integration <command> Inspect or sync managed integration files
   epic <subcommand>      Manage epics
   phase <subcommand>     Manage task phases
   archive <type>         Archive a work item

package/package.json

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

package/skills/agency/SKILL.md

@@ -39,6 +39,7 @@ From anywhere beneath a workbase, run:
 ```bash
 agency status --json
 agency validate --json
+agency integration status --json
 agency repo list --json
 agency epic list --json
 agency task list --json
@@ -56,6 +57,7 @@ If no workbase is found, do not initialize one without user intent. When asked:
 
 ```bash
 agency init [path]
+agency integration sync
 ```
 
 Register known workbases so `agency work` can select one when run elsewhere:

package/src/cli-parser.test.ts

@@ -82,6 +82,8 @@ describe("strict CLI parsing", () => {
 			[["init", "one", "two"], "agency init"],
 			[["workbase", "add", "one", "two"], "agency workbase add"],
 			[["workbase", "list", "extra"], "agency workbase list"],
+			[["integration", "status", "extra"], "agency integration status"],
+			[["integration", "sync", "extra"], "agency integration sync"],
 			[["repo", "add", "a", "b", "extra"], "agency repo add"],
 			[["repo", "link", "a", "b", "extra"], "agency repo link"],
 			[["repo", "list", "extra"], "agency repo list"],

package/src/cli-parser.ts

@@ -88,6 +88,24 @@ const commands = {
 			},
 		},
 	},
+	integration: {
+		usage: "agency integration <status|sync>",
+		options: outputOptions,
+		subcommands: {
+			status: {
+				usage: "agency integration status [--json]",
+				minArgs: 0,
+				maxArgs: 0,
+				options: ["json"],
+			},
+			sync: {
+				usage: "agency integration sync [--json]",
+				minArgs: 0,
+				maxArgs: 0,
+				options: ["json"],
+			},
+		},
+	},
 	repo: {
 		usage: "agency repo <add|link|list>",
 		options: outputOptions,

package/src/cli.test.ts

@@ -106,6 +106,7 @@ describe("CLI", () => {
 		for (const [command, usage] of [
 			["init", "Usage: agency init"],
 			["workbase", "Usage: agency workbase"],
+			["integration", "Usage: agency integration"],
 			["repo", "Usage: agency repo"],
 			["epic", "Usage: agency epic"],
 			["task", "Usage: agency task"],
@@ -136,6 +137,28 @@ describe("CLI", () => {
 		expect(after).toEqual({ exitCode: 0, stdout: "", stderr: "" })
 	})
 
+	test("reports and synchronizes managed integration files", async () => {
+		const root = await createTempDir()
+		tempDirs.push(root)
+		expect((await runCli(["init", root])).exitCode).toBe(0)
+
+		const before = parseJson(
+			await runCli(["integration", "status", "--json"], root),
+		)
+		expect(before.files).toMatchObject([
+			{ name: "agents", state: "missing" },
+			{ name: "opencode", state: "missing" },
+		])
+
+		const synced = parseJson(
+			await runCli(["integration", "sync", "--json"], root),
+		)
+		expect(synced.files).toMatchObject([
+			{ name: "agents", state: "managed", changed: true },
+			{ name: "opencode", state: "managed", changed: true },
+		])
+	})
+
 	test("registers and lists workbases", async () => {
 		const parent = await createTempDir()
 		tempDirs.push(parent)

package/src/commands/init.test.ts

@@ -33,15 +33,10 @@ 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")).text()).toContain(
-			"# Agency Workbase",
-		)
-		expect(
-			await Bun.file(join(root, ".opencode/opencode.jsonc")).text(),
-		).toContain('"path": "../tasks"')
+		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(false)
 		expect(
-			await Bun.file(join(root, ".opencode/opencode.jsonc")).text(),
-		).toContain(`"${join(root, "tasks")}/*": "allow"`)
+			await Bun.file(join(root, ".opencode/opencode.jsonc")).exists(),
+		).toBe(false)
 	})
 
 	test("preserves existing gitignore entries", async () => {

package/src/commands/integration.test.ts

@@ -0,0 +1,51 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { join } from "node:path"
+import {
+	captureLogs,
+	cleanupTempDir,
+	createTempDir,
+	runTestEffect,
+} from "../test-utils"
+import { integration } from "./integration"
+
+describe("integration command", () => {
+	let root: string
+
+	beforeEach(async () => {
+		root = await createTempDir()
+		await Bun.write(join(root, "agency.json"), '{"version":2}\n')
+	})
+
+	afterEach(async () => cleanupTempDir(root))
+
+	test("reports integration status as JSON", async () => {
+		const logs = await captureLogs(() =>
+			runTestEffect(
+				integration({ subcommand: "status", cwd: root, json: true }),
+			),
+		)
+
+		expect(JSON.parse(logs[0]!)).toMatchObject({
+			root,
+			files: [
+				{ name: "agents", state: "missing" },
+				{ name: "opencode", state: "missing" },
+			],
+		})
+	})
+
+	test("explicitly synchronizes integration files", async () => {
+		const logs = await captureLogs(() =>
+			runTestEffect(integration({ subcommand: "sync", cwd: root, json: true })),
+		)
+
+		expect(JSON.parse(logs[0]!).files).toMatchObject([
+			{ 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, ".opencode/opencode.jsonc")).exists(),
+		).toBe(true)
+	})
+})

package/src/commands/integration.ts

@@ -0,0 +1,62 @@
+import { Effect } from "effect"
+import type { BaseCommandOptions } from "../utils/command"
+import { IntegrationService } from "../services/IntegrationService"
+import { createLoggers } from "../utils/effect"
+
+interface IntegrationOptions extends BaseCommandOptions {
+	readonly subcommand?: string
+	readonly json?: boolean
+}
+
+export const integration = (options: IntegrationOptions) =>
+	Effect.gen(function* () {
+		const service = yield* IntegrationService
+		const { log } = createLoggers(options)
+		const cwd = options.cwd ?? process.cwd()
+
+		switch (options.subcommand) {
+			case "status": {
+				const result = yield* service.status(cwd)
+				if (options.json) {
+					log(JSON.stringify(result, null, 2))
+					return
+				}
+				for (const file of result.files) {
+					log(`${file.name}\t${file.state}\t${file.path}`)
+				}
+				return
+			}
+
+			case "sync": {
+				const result = yield* service.sync(cwd)
+				if (options.json) {
+					log(JSON.stringify(result, null, 2))
+					return
+				}
+				for (const file of result.files) {
+					log(
+						`${file.name}\t${file.changed ? "synced" : file.state}\t${file.path}`,
+					)
+				}
+				return
+			}
+
+			default:
+				return yield* Effect.fail(
+					new Error("Subcommand is required. Available: status, sync"),
+				)
+		}
+	})
+
+export const help = `
+Usage: agency integration <subcommand>
+
+Inspect or explicitly synchronize managed agent integration files.
+
+Subcommands:
+  status  Report managed, customized, missing, and drifted files
+  sync    Create or update checksum-safe managed files
+
+Options:
+  --json  Output results as JSON
+`

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

@@ -0,0 +1,144 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { chmod, lstat, mkdir, readdir } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
+import { WorkbaseService } from "../services/WorkbaseService"
+import { epic } from "./epic"
+import { integration } from "./integration"
+import { phase } from "./phase"
+import { repo } from "./repo"
+import { status } from "./status"
+import { task } from "./task"
+import { validate } from "./validate"
+
+const write = async (root: string, path: string, content: string) => {
+	const fullPath = join(root, path)
+	await mkdir(dirname(fullPath), { recursive: true })
+	await Bun.write(fullPath, content)
+}
+
+const setReadOnly = async (path: string, readOnly: boolean): Promise<void> => {
+	const metadata = await lstat(path)
+	if (!metadata.isDirectory()) {
+		await chmod(path, readOnly ? 0o444 : 0o644)
+		return
+	}
+
+	if (!readOnly) await chmod(path, 0o755)
+	for (const entry of await readdir(path)) {
+		await setReadOnly(join(path, entry), readOnly)
+	}
+	if (readOnly) await chmod(path, 0o555)
+}
+
+describe("observational commands", () => {
+	let root: string
+
+	beforeEach(async () => {
+		root = await createTempDir()
+		await write(root, "agency.json", '{"version":2}\n')
+		await mkdir(join(root, "repos/agency"), { recursive: true })
+		await write(
+			root,
+			"epics/example/EPIC.md",
+			`---
+ticketUrl: https://example.com/epics/example
+repos:
+  - repo: agency
+    ref: main
+tasks:
+  - id: example-task
+---
+
+# Example
+`,
+		)
+		await write(
+			root,
+			"tasks/example-task/TASK.md",
+			`---
+ticketUrl: null
+epic: example
+phases:
+  - id: implementation
+---
+
+# Example task
+`,
+		)
+		await write(
+			root,
+			"tasks/example-task/phases/implementation/PHASE.md",
+			`---
+repo: agency
+branch: feat/example
+base: main
+pr: null
+status: open
+---
+
+# Implementation
+`,
+		)
+	})
+
+	afterEach(async () => {
+		await setReadOnly(root, false)
+		await cleanupTempDir(root)
+	})
+
+	test("remain usable when the workbase is read-only", async () => {
+		await setReadOnly(root, true)
+
+		await runTestEffect(
+			WorkbaseService.pipe(Effect.flatMap((service) => service.discover(root))),
+		)
+		await runTestEffect(
+			integration({ subcommand: "status", cwd: root, silent: true }),
+		)
+		await runTestEffect(
+			epic({ subcommand: "list", args: [], cwd: root, silent: true }),
+		)
+		await runTestEffect(
+			epic({ subcommand: "show", args: ["example"], cwd: root, silent: true }),
+		)
+		await runTestEffect(
+			task({ subcommand: "list", args: [], cwd: root, silent: true }),
+		)
+		await runTestEffect(
+			task({
+				subcommand: "show",
+				args: ["example-task"],
+				cwd: root,
+				silent: true,
+			}),
+		)
+		await runTestEffect(
+			phase({
+				subcommand: "list",
+				args: ["example-task"],
+				cwd: root,
+				silent: true,
+			}),
+		)
+		await runTestEffect(
+			phase({
+				subcommand: "show",
+				args: ["example-task", "implementation"],
+				cwd: root,
+				silent: true,
+			}),
+		)
+		await runTestEffect(
+			repo({ subcommand: "list", args: [], cwd: root, silent: true }),
+		)
+		await runTestEffect(status({ cwd: root, silent: true }))
+		await runTestEffect(validate({ path: root, silent: true }))
+
+		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(false)
+		expect(
+			await Bun.file(join(root, ".opencode/opencode.jsonc")).exists(),
+		).toBe(false)
+	})
+})

package/src/services/IntegrationService.test.ts

@@ -0,0 +1,137 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { createHash } from "node:crypto"
+import { mkdir, symlink, unlink } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
+import { managedWorkbaseAgents } from "../workbase/agents-file"
+import { managedWorkbaseOpencode } from "../workbase/opencode-file"
+import { IntegrationService } from "./IntegrationService"
+
+const write = async (root: string, path: string, content: string) => {
+	const fullPath = join(root, path)
+	await mkdir(dirname(fullPath), { recursive: true })
+	await Bun.write(fullPath, content)
+}
+
+const managed = (prefix: string, body: string, suffix = "") => {
+	const checksum = createHash("sha256").update(body).digest("hex")
+	return `${prefix}${checksum}${suffix}\n\n${body}`
+}
+
+const status = (root: string) =>
+	runTestEffect(
+		IntegrationService.pipe(Effect.flatMap((service) => service.status(root))),
+	)
+
+const sync = (root: string) =>
+	runTestEffect(
+		IntegrationService.pipe(Effect.flatMap((service) => service.sync(root))),
+	)
+
+describe("IntegrationService", () => {
+	let root: string
+
+	beforeEach(async () => {
+		root = await createTempDir()
+		await write(root, "agency.json", '{"version":2}\n')
+	})
+
+	afterEach(async () => cleanupTempDir(root))
+
+	test("reports missing and current managed files without writing", async () => {
+		expect((await status(root)).files.map(({ state }) => state)).toEqual([
+			"missing",
+			"missing",
+		])
+		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(false)
+
+		await write(root, "AGENTS.md", managedWorkbaseAgents)
+		await write(root, ".opencode/opencode.jsonc", managedWorkbaseOpencode(root))
+		expect((await status(root)).files.map(({ state }) => state)).toEqual([
+			"managed",
+			"managed",
+		])
+	})
+
+	test("reports customized and checksum-safe drifted files", async () => {
+		await write(root, "AGENTS.md", "# Custom instructions\n")
+		await write(
+			root,
+			".opencode/opencode.jsonc",
+			managed("// agency-managed: sha256=", '{"references":{}}\n'),
+		)
+
+		expect((await status(root)).files.map(({ state }) => state)).toEqual([
+			"customized",
+			"drifted",
+		])
+	})
+
+	test("treats an existing JSON OpenCode config as customized", async () => {
+		await write(root, ".opencode/opencode.json", '{"model":"test/model"}\n')
+
+		const result = await status(root)
+		expect(result.files[1]).toEqual({
+			name: "opencode",
+			path: join(root, ".opencode/opencode.json"),
+			state: "customized",
+		})
+	})
+
+	test("syncs missing and drifted files while preserving customized files", async () => {
+		const customAgents = "# Custom instructions\n"
+		await write(root, "AGENTS.md", customAgents)
+		await write(
+			root,
+			".opencode/opencode.jsonc",
+			managed("// agency-managed: sha256=", '{"references":{}}\n'),
+		)
+
+		const first = await sync(root)
+		expect(first.files).toMatchObject([
+			{ 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, ".opencode/opencode.jsonc")).text()).toBe(
+			managedWorkbaseOpencode(root),
+		)
+
+		await unlink(join(root, "AGENTS.md"))
+		const second = await sync(root)
+		expect(second.files[0]).toMatchObject({ state: "managed", changed: true })
+		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(
+			managedWorkbaseAgents,
+		)
+	})
+
+	test("does not overwrite managed files whose checksums no longer match", async () => {
+		const tampered = `${managed(
+			"<!-- agency-managed: sha256=",
+			"# Previous Agency instructions\n",
+			" -->",
+		)}User edit\n`
+		await write(root, "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)
+	})
+
+	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"))
+
+		const result = await sync(root)
+		expect(result.files[0]).toMatchObject({
+			state: "customized",
+			changed: false,
+		})
+		expect(await Bun.file(target).text()).toBe("# External instructions\n")
+	})
+})

package/src/services/IntegrationService.ts

@@ -0,0 +1,136 @@
+import { Effect } from "effect"
+import { join } from "node:path"
+import { FileSystemService } from "./FileSystemService"
+import { WorkbaseService } from "./WorkbaseService"
+import {
+	canUpdateManagedWorkbaseAgents,
+	managedWorkbaseAgents,
+} from "../workbase/agents-file"
+import {
+	canUpdateManagedWorkbaseOpencode,
+	managedWorkbaseOpencode,
+} from "../workbase/opencode-file"
+
+type IntegrationFileState = "managed" | "customized" | "missing" | "drifted"
+
+interface IntegrationFileStatus {
+	readonly name: "agents" | "opencode"
+	readonly path: string
+	readonly state: IntegrationFileState
+}
+
+interface IntegrationSyncFile extends IntegrationFileStatus {
+	readonly changed: boolean
+}
+
+const classify = (
+	name: IntegrationFileStatus["name"],
+	path: string,
+	content: string,
+	managed: string,
+	canUpdate: (content: string) => boolean,
+): IntegrationFileStatus => ({
+	name,
+	path,
+	state:
+		content === managed
+			? "managed"
+			: canUpdate(content)
+				? "drifted"
+				: "customized",
+})
+
+const inspect = (root: string) =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystemService
+		const agentsPath = join(root, "AGENTS.md")
+		const opencodeDirectory = join(root, ".opencode")
+		const opencodePath = join(opencodeDirectory, "opencode.jsonc")
+		const opencodeJsonPath = join(opencodeDirectory, "opencode.json")
+		const files: IntegrationFileStatus[] = []
+
+		files.push(
+			(yield* fs.readSymlinkTarget(agentsPath)) !== null
+				? { name: "agents", path: agentsPath, state: "customized" }
+				: (yield* fs.exists(agentsPath))
+					? classify(
+							"agents",
+							agentsPath,
+							yield* fs.readFile(agentsPath),
+							managedWorkbaseAgents,
+							canUpdateManagedWorkbaseAgents,
+						)
+					: { name: "agents", path: agentsPath, state: "missing" },
+		)
+
+		if ((yield* fs.readSymlinkTarget(opencodePath)) !== null) {
+			files.push({
+				name: "opencode",
+				path: opencodePath,
+				state: "customized",
+			})
+		} else if (yield* fs.exists(opencodePath)) {
+			files.push(
+				classify(
+					"opencode",
+					opencodePath,
+					yield* fs.readFile(opencodePath),
+					managedWorkbaseOpencode(root),
+					canUpdateManagedWorkbaseOpencode,
+				),
+			)
+		} else if (yield* fs.exists(opencodeJsonPath)) {
+			files.push({
+				name: "opencode",
+				path: opencodeJsonPath,
+				state: "customized",
+			})
+		} else {
+			files.push({ name: "opencode", path: opencodePath, state: "missing" })
+		}
+
+		return files
+	})
+
+export class IntegrationService extends Effect.Service<IntegrationService>()(
+	"IntegrationService",
+	{
+		sync: () => ({
+			status: (startPath: string = process.cwd()) =>
+				Effect.gen(function* () {
+					const workbase = yield* WorkbaseService
+					const root = yield* workbase.discover(startPath)
+					return { root, files: yield* inspect(root) }
+				}),
+
+			sync: (startPath: string = process.cwd()) =>
+				Effect.gen(function* () {
+					const fs = yield* FileSystemService
+					const workbase = yield* WorkbaseService
+					const root = yield* workbase.discover(startPath)
+					const statuses = yield* inspect(root)
+					const files: IntegrationSyncFile[] = []
+
+					for (const status of statuses) {
+						const changed =
+							status.state === "missing" || status.state === "drifted"
+						if (changed) {
+							if (status.name === "agents") {
+								yield* fs.writeFile(status.path, managedWorkbaseAgents)
+							} else {
+								yield* fs.createDirectory(join(root, ".opencode"))
+								yield* fs.writeFile(status.path, managedWorkbaseOpencode(root))
+							}
+						}
+						files.push({
+							...status,
+							state: changed ? "managed" : status.state,
+							changed,
+						})
+					}
+
+					return { root, files }
+				}),
+		}),
+	},
+) {}

package/src/services/WorkbaseService.test.ts

@@ -1,11 +1,8 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test"
 import { Effect } from "effect"
-import { createHash } from "node:crypto"
 import { mkdir, realpath } from "node:fs/promises"
 import { dirname, join } from "node:path"
 import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
-import { managedWorkbaseAgents } from "../workbase/agents-file"
-import { managedWorkbaseOpencode } from "../workbase/opencode-file"
 import { WorkbaseService } from "./WorkbaseService"
 
 const write = async (root: string, path: string, content: string) => {
@@ -14,16 +11,6 @@ const write = async (root: string, path: string, content: string) => {
 	await Bun.write(fullPath, content)
 }
 
-const managedAgents = (body: string) => {
-	const checksum = createHash("sha256").update(body).digest("hex")
-	return `<!-- agency-managed: sha256=${checksum} -->\n\n${body}`
-}
-
-const managedOpencode = (body: string) => {
-	const checksum = createHash("sha256").update(body).digest("hex")
-	return `// agency-managed: sha256=${checksum}\n\n${body}`
-}
-
 describe("WorkbaseService", () => {
 	let root: string
 
@@ -48,12 +35,10 @@ describe("WorkbaseService", () => {
 		)
 
 		expect(discovered).toBe(root)
-		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(
-			managedWorkbaseAgents,
-		)
-		expect(await Bun.file(join(root, ".opencode/opencode.jsonc")).text()).toBe(
-			managedWorkbaseOpencode(root),
-		)
+		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(false)
+		expect(
+			await Bun.file(join(root, ".opencode/opencode.jsonc")).exists(),
+		).toBe(false)
 	})
 
 	test("registers canonical workbase paths without duplicates", async () => {
@@ -88,105 +73,6 @@ describe("WorkbaseService", () => {
 		).toEqual({ version: 1, workbases: [first] })
 	})
 
-	test("preserves an unmanaged workbase OpenCode config", async () => {
-		await write(root, "agency.json", '{"version":2}\n')
-		await write(root, ".opencode/opencode.jsonc", '{"model":"test/model"}\n')
-
-		await runTestEffect(
-			WorkbaseService.pipe(Effect.flatMap((service) => service.discover(root))),
-		)
-
-		expect(await Bun.file(join(root, ".opencode/opencode.jsonc")).text()).toBe(
-			'{"model":"test/model"}\n',
-		)
-	})
-
-	test("does not override an existing JSON OpenCode config", async () => {
-		await write(root, "agency.json", '{"version":2}\n')
-		await write(root, ".opencode/opencode.json", '{"model":"test/model"}\n')
-
-		await runTestEffect(
-			WorkbaseService.pipe(Effect.flatMap((service) => service.discover(root))),
-		)
-
-		expect(
-			await Bun.file(join(root, ".opencode/opencode.jsonc")).exists(),
-		).toBe(false)
-	})
-
-	test("updates an unmodified managed workbase OpenCode config", async () => {
-		await write(root, "agency.json", '{"version":2}\n')
-		await write(
-			root,
-			".opencode/opencode.jsonc",
-			managedOpencode('{"references":{}}\n'),
-		)
-
-		await runTestEffect(
-			WorkbaseService.pipe(Effect.flatMap((service) => service.discover(root))),
-		)
-
-		expect(await Bun.file(join(root, ".opencode/opencode.jsonc")).text()).toBe(
-			managedWorkbaseOpencode(root),
-		)
-	})
-
-	test("preserves a modified managed workbase OpenCode config", async () => {
-		await write(root, "agency.json", '{"version":2}\n')
-		const content = `${managedOpencode('{"references":{}}\n')}\n// User edit\n`
-		await write(root, ".opencode/opencode.jsonc", content)
-
-		await runTestEffect(
-			WorkbaseService.pipe(Effect.flatMap((service) => service.discover(root))),
-		)
-
-		expect(await Bun.file(join(root, ".opencode/opencode.jsonc")).text()).toBe(
-			content,
-		)
-	})
-
-	test("preserves an unmanaged workbase AGENTS.md", async () => {
-		await write(root, "agency.json", '{"version":2}\n')
-		await write(root, "AGENTS.md", "# Custom instructions\n")
-
-		await runTestEffect(
-			WorkbaseService.pipe(Effect.flatMap((service) => service.discover(root))),
-		)
-
-		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(
-			"# Custom instructions\n",
-		)
-	})
-
-	test("updates an unmodified managed workbase AGENTS.md", async () => {
-		await write(root, "agency.json", '{"version":2}\n')
-		await write(
-			root,
-			"AGENTS.md",
-			managedAgents("# Previous Agency instructions\n"),
-		)
-
-		await runTestEffect(
-			WorkbaseService.pipe(Effect.flatMap((service) => service.discover(root))),
-		)
-
-		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(
-			managedWorkbaseAgents,
-		)
-	})
-
-	test("preserves a modified managed workbase AGENTS.md", async () => {
-		await write(root, "agency.json", '{"version":2}\n')
-		const content = `${managedAgents("# Previous Agency instructions\n")}\nUser edit\n`
-		await write(root, "AGENTS.md", content)
-
-		await runTestEffect(
-			WorkbaseService.pipe(Effect.flatMap((service) => service.discover(root))),
-		)
-
-		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(content)
-	})
-
 	test("rejects an invalid worktree command template", async () => {
 		await write(
 			root,

package/src/services/WorkbaseService.ts

@@ -17,14 +17,6 @@ import {
 	type TaskFrontmatter as TaskData,
 } from "../workbase/schemas"
 import { validateWorktreeCreateCommand } from "../workbase/worktree-command"
-import {
-	canUpdateManagedWorkbaseAgents,
-	managedWorkbaseAgents,
-} from "../workbase/agents-file"
-import {
-	canUpdateManagedWorkbaseOpencode,
-	managedWorkbaseOpencode,
-} from "../workbase/opencode-file"
 
 class WorkbaseNotFoundError extends Data.TaggedError("WorkbaseNotFoundError")<{
 	readonly message: string
@@ -119,48 +111,6 @@ const readRegistry = (configDirectory?: string) =>
 		return { path, registry: decoded.value }
 	})
 
-const ensureWorkbaseAgents = (root: string) =>
-	Effect.gen(function* () {
-		const fs = yield* FileSystemService
-		const path = join(root, "AGENTS.md")
-		if (!(yield* fs.exists(path))) {
-			yield* fs.writeFile(path, managedWorkbaseAgents)
-			return
-		}
-
-		const content = yield* fs.readFile(path)
-		if (
-			content !== managedWorkbaseAgents &&
-			canUpdateManagedWorkbaseAgents(content)
-		) {
-			yield* fs.writeFile(path, managedWorkbaseAgents)
-		}
-	})
-
-const ensureWorkbaseOpencode = (root: string) =>
-	Effect.gen(function* () {
-		const fs = yield* FileSystemService
-		const directory = join(root, ".opencode")
-		const path = join(directory, "opencode.jsonc")
-		const managed = managedWorkbaseOpencode(root)
-		if (!(yield* fs.exists(path))) {
-			if (yield* fs.exists(join(directory, "opencode.json"))) return
-			yield* fs.createDirectory(directory)
-			yield* fs.writeFile(path, managed)
-			return
-		}
-
-		const content = yield* fs.readFile(path)
-		if (content !== managed && canUpdateManagedWorkbaseOpencode(content)) {
-			yield* fs.writeFile(path, managed)
-		}
-	})
-
-const ensureWorkbaseAgentFiles = (root: string) =>
-	Effect.all([ensureWorkbaseAgents(root), ensureWorkbaseOpencode(root)], {
-		concurrency: "unbounded",
-	})
-
 const findCycles = (nodes: readonly Dependency[]): readonly string[] => {
 	const dependencies = new Map(
 		nodes.map((node) => [node.id, [...(node.dependsOn ?? [])]]),
@@ -239,8 +189,6 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 							`${existing}${prefix}${missing.join("\n")}\n`,
 						)
 					}
-					yield* ensureWorkbaseAgentFiles(root)
-
 					return root
 				}),
 
@@ -296,7 +244,6 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 										})
 									}
 								}
-								yield* ensureWorkbaseAgentFiles(current)
 								return current
 							}
 						}

package/src/test-utils.ts

@@ -12,6 +12,7 @@ import { PhaseService } from "./services/PhaseService"
 import { WorktreeService } from "./services/WorktreeService"
 import { PullRequestService } from "./services/PullRequestService"
 import { ArchiveService } from "./services/ArchiveService"
+import { IntegrationService } from "./services/IntegrationService"
 
 export const createTempDir = () => mkdtemp(join(tmpdir(), "agency-test-"))
 
@@ -28,6 +29,7 @@ const TestLayer = Layer.mergeAll(
 	WorktreeService.Default,
 	PullRequestService.Default,
 	ArchiveService.Default,
+	IntegrationService.Default,
 )
 
 export async function runTestEffect<A, E>(

package/src/workbase/AGENTS.md

@@ -22,6 +22,8 @@ field. Repositories listed in plural `repos` are read-only references.
 
 ## Safety
 
+- Discovery and observational commands are read-only; use
+  `agency integration sync` to update managed agent files explicitly.
 - Keep task-level decisions in `TASK.md` and phase-specific delivery context in
   `PHASE.md`.
 - Keep execution-unit `status` current with `agency task status` or