@markjaquith/agency 2.45.0 → 2.47.0

package/README.md

@@ -52,8 +52,10 @@ workbase/
     AGENTS.md              # managed Agency instructions
   .opencode/
     opencode.jsonc         # managed @agency subagent, instructions, and reference
+    tui.jsonc              # managed TUI plugin registration
     command/agency.md      # managed /agency workflow command
     plugin/agency-repository-skills.ts # managed checkout skill discovery
+    tui/agency-debug.ts    # managed /agency-debug TUI diagnostic
   agency.json              # tracked config and portable repository declarations
   repos/                   # ignored local materializations
     frontend/              # bare Git repository or symlink
@@ -82,9 +84,10 @@ workbase/
 
 Agency keeps discovery and other observational commands read-only. Run
 `agency integration status` to inspect `.agency/AGENTS.md` and
-`.opencode/opencode.jsonc`, and `.opencode/command/agency.md`, then `agency
-integration sync` to create missing files or refresh checksum-safe managed
-files. Customized files are reported but never overwritten. The root
+`.opencode/opencode.jsonc`, `.opencode/tui.jsonc`, and their managed command and
+plugin files, then `agency integration sync` to create missing files or refresh
+checksum-safe managed files. Customized files are reported but never
+overwritten. The root
 `AGENTS.md` is user-owned and is not inspected or modified by Agency.
 
 When upgrading an existing workbase, synchronization moves a checksum-valid
@@ -96,9 +99,18 @@ The OpenCode config defines an `@agency` subagent for delegated workbase
 orchestration, loads Agency's hidden instructions in addition to any user-owned
 root `AGENTS.md`, advertises the complete workbase as one portable reference,
 and replaces the built-in Plan agent with `agency-plan`. That planning agent can
-update `TASK.md`, `PHASE.md`, and `EPIC.md` while other edits remain disabled.
+update `TASK.md`, `PHASE.md`, and `EPIC.md`, inspect the workbase through
+read-only Agency commands, and use explicit Agency CLI permissions to create or
+update planning structure. Its normal research tools and the complete Agency CLI
+remain available; managed Agency instructions and reported authority govern each
+operation.
 When the subagent launches work in another agent, it verifies that the runner
 started and returns without waiting for the task to finish.
+The TUI-only `/agency-debug` command reports TUI companion initialization and
+whether the server plugin registered writable-checkout skills. It uses a native
+toast and does not submit a prompt to an LLM. When no writable checkout skill
+directory is available, server initialization is reported as indeterminate
+rather than inferred from plugin discovery.
 OpenCode discovers the config from task and epic launch directories. Agents
 receive whole-workbase visibility from that reference. Bash and Agency operations
 must still follow the write authority reported by `agency context`.

package/package.json

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

package/src/cli.test.ts

@@ -1,6 +1,6 @@
 import { afterAll, afterEach, describe, expect, test } from "bun:test"
 import { access, mkdir, realpath, symlink } from "node:fs/promises"
-import { join } from "node:path"
+import { join, sep } from "node:path"
 import errorFixture from "../fixtures/protocol/error.json"
 import successFixture from "../fixtures/protocol/success.json"
 import { cleanupTempDir, createTempDir } from "./test-utils"
@@ -528,6 +528,8 @@ describe("CLI", () => {
 			{ name: "opencode", state: "managed" },
 			{ name: "opencode-command", state: "managed" },
 			{ name: "opencode-plugin", state: "managed" },
+			{ name: "opencode-tui", state: "managed" },
+			{ name: "opencode-tui-plugin", state: "managed" },
 		])
 
 		const synced = parseJson(
@@ -538,6 +540,8 @@ describe("CLI", () => {
 			{ name: "opencode", state: "managed", changed: false },
 			{ name: "opencode-command", state: "managed", changed: false },
 			{ name: "opencode-plugin", state: "managed", changed: false },
+			{ name: "opencode-tui", state: "managed", changed: false },
+			{ name: "opencode-tui-plugin", state: "managed", changed: false },
 		])
 	})
 
@@ -1097,7 +1101,9 @@ status: open
 					]),
 				)
 				if (launch.skillPath) {
-					expect(effectiveConfig.skills.paths).toContain(launch.skillPath)
+					expect(effectiveConfig.skills.paths).toContain(
+						`${launch.skillPath}${sep}.`,
+					)
 					const skillProbe = Bun.spawnSync(
 						[
 							"opencode",
@@ -1115,6 +1121,12 @@ status: open
 					expect(
 						JSON.parse(skillProbe.stdout.toString()).result.output,
 					).toContain("Repository skill content.")
+				} else {
+					expect(
+						(effectiveConfig.skills?.paths ?? []).filter((path: string) =>
+							path.endsWith(`${sep}.`),
+						),
+					).toEqual([])
 				}
 				if (launch === launches[0]) {
 					expect(effectiveConfig.instructions).toContain(".agency/AGENTS.md")

package/src/commands/init.test.ts

@@ -49,6 +49,9 @@ describe("init command", () => {
 		expect(config.agent["agency-plan"]).toMatchObject({
 			mode: "primary",
 			permission: {
+				bash: {
+					"agency *": "allow",
+				},
 				edit: {
 					"*": "deny",
 					"tasks/*/TASK.md": "allow",
@@ -71,6 +74,17 @@ describe("init command", () => {
 		).text()
 		expect(plugin).toContain("AGENCY_WRITABLE_CHECKOUT")
 		expect(plugin).toContain("config.skills.paths")
+		const tui = await Bun.file(join(root, ".opencode/tui.jsonc")).text()
+		expect(JSON.parse(tui.slice(tui.indexOf("\n\n") + 2))).toEqual({
+			$schema: "https://opencode.ai/tui.json",
+			plugin: ["./tui/agency-debug.ts"],
+		})
+		const tuiPlugin = await Bun.file(
+			join(root, ".opencode/tui/agency-debug.ts"),
+		).text()
+		expect(tuiPlugin).toContain('slashName: "agency-debug"')
+		expect(tuiPlugin).toContain("api.ui.toast")
+		expect(tuiPlugin).not.toContain("chat.message")
 	})
 
 	test("preserves existing gitignore entries", async () => {

package/src/commands/integration.test.ts

@@ -46,6 +46,16 @@ describe("integration command", () => {
 					state: "missing",
 					remediation: expect.stringContaining("integration sync"),
 				},
+				{
+					name: "opencode-tui",
+					state: "missing",
+					remediation: expect.stringContaining("integration sync"),
+				},
+				{
+					name: "opencode-tui-plugin",
+					state: "missing",
+					remediation: expect.stringContaining("integration sync"),
+				},
 			],
 		})
 	})
@@ -89,7 +99,17 @@ OpenCode /agency command: missing
 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.`)
+  Action: Run 'agency integration sync' to expose writable-checkout skills in OpenCode.
+
+OpenCode TUI config: missing
+  Path: .opencode/tui.jsonc
+  The managed OpenCode TUI config needs synchronization.
+  Action: Run 'agency integration sync' to register /agency-debug.
+
+OpenCode /agency-debug: missing
+  Path: .opencode/tui/agency-debug.ts
+  The managed OpenCode TUI diagnostic companion needs synchronization.
+  Action: Run 'agency integration sync' to install /agency-debug.`)
 	})
 
 	test("explicitly synchronizes integration files", async () => {
@@ -102,6 +122,8 @@ OpenCode checkout skills: missing
 			{ name: "opencode", state: "managed", changed: true },
 			{ name: "opencode-command", state: "managed", changed: true },
 			{ name: "opencode-plugin", state: "managed", changed: true },
+			{ name: "opencode-tui", state: "managed", changed: true },
+			{ name: "opencode-tui-plugin", state: "managed", changed: true },
 		])
 		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(false)
 		expect(await Bun.file(join(root, ".agency/AGENTS.md")).exists()).toBe(true)
@@ -116,6 +138,12 @@ OpenCode checkout skills: missing
 				join(root, ".opencode/plugin/agency-repository-skills.ts"),
 			).exists(),
 		).toBe(true)
+		expect(await Bun.file(join(root, ".opencode/tui.jsonc")).exists()).toBe(
+			true,
+		)
+		expect(
+			await Bun.file(join(root, ".opencode/tui/agency-debug.ts")).exists(),
+		).toBe(true)
 	})
 
 	test("formats integration sync results for people", async () => {
@@ -139,6 +167,14 @@ OpenCode /agency command: synced
 
 OpenCode checkout skills: synced
   Path: .opencode/plugin/agency-repository-skills.ts
-  Agency's managed OpenCode plugin exposes writable-checkout skills to work-item sessions.`)
+  Agency's managed OpenCode plugin exposes writable-checkout skills to work-item sessions.
+
+OpenCode TUI config: synced
+  Path: .opencode/tui.jsonc
+  Agency's managed OpenCode TUI config explicitly loads /agency-debug.
+
+OpenCode /agency-debug: synced
+  Path: .opencode/tui/agency-debug.ts
+  Agency's managed OpenCode TUI diagnostic companion is current.`)
 	})
 })

package/src/commands/integration.ts

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

package/src/services/IntegrationService.test.ts

@@ -3,6 +3,7 @@ import { Effect } from "effect"
 import { createHash } from "node:crypto"
 import { mkdir, stat, symlink, unlink, utimes } from "node:fs/promises"
 import { dirname, join } from "node:path"
+import { pathToFileURL } from "node:url"
 import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
 import { managedWorkbaseAgents } from "../workbase/agents-file"
 import {
@@ -14,6 +15,11 @@ import {
 	canUpdateManagedWorkbaseOpencodePlugin,
 	managedWorkbaseOpencodePlugin,
 } from "../workbase/opencode-plugin-file"
+import { managedWorkbaseOpencodeTui } from "../workbase/opencode-tui-file"
+import {
+	canUpdateManagedWorkbaseOpencodeTuiPlugin,
+	managedWorkbaseOpencodeTuiPlugin,
+} from "../workbase/opencode-tui-plugin-file"
 import { IntegrationService } from "./IntegrationService"
 
 const write = async (root: string, path: string, content: string) => {
@@ -56,6 +62,8 @@ describe("IntegrationService", () => {
 			"missing",
 			"missing",
 			"missing",
+			"missing",
+			"missing",
 		])
 		expect(await Bun.file(join(root, ".agency/AGENTS.md")).exists()).toBe(false)
 
@@ -71,11 +79,19 @@ describe("IntegrationService", () => {
 			".opencode/plugin/agency-repository-skills.ts",
 			managedWorkbaseOpencodePlugin,
 		)
+		await write(root, ".opencode/tui.jsonc", managedWorkbaseOpencodeTui)
+		await write(
+			root,
+			".opencode/tui/agency-debug.ts",
+			managedWorkbaseOpencodeTuiPlugin,
+		)
 		expect((await status(root)).files.map(({ state }) => state)).toEqual([
 			"managed",
 			"managed",
 			"managed",
 			"managed",
+			"managed",
+			"managed",
 		])
 	})
 
@@ -92,6 +108,8 @@ describe("IntegrationService", () => {
 			"drifted",
 			"missing",
 			"missing",
+			"missing",
+			"missing",
 		])
 	})
 
@@ -114,6 +132,9 @@ describe("IntegrationService", () => {
 		expect(managedWorkbaseOpencodePlugin).toContain(
 			"config.skills.paths = [...new Set",
 		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			".map((path) => `${path}${sep}.`)",
+		)
 		expect(
 			canUpdateManagedWorkbaseOpencodePlugin(managedWorkbaseOpencodePlugin),
 		).toBe(true)
@@ -124,6 +145,73 @@ describe("IntegrationService", () => {
 		).toBe(false)
 	})
 
+	test("registers a TUI-only /agency-debug diagnostic", async () => {
+		const config = JSON.parse(managedBody(managedWorkbaseOpencodeTui))
+		expect(config).toEqual({
+			$schema: "https://opencode.ai/tui.json",
+			plugin: ["./tui/agency-debug.ts"],
+		})
+
+		const path = join(root, ".opencode/tui/agency-debug.ts")
+		await write(
+			root,
+			".opencode/tui/agency-debug.ts",
+			managedWorkbaseOpencodeTuiPlugin,
+		)
+		const module = await import(pathToFileURL(path).href)
+		let clientReads = 0
+
+		const runDiagnostic = async (paths: string[], ready = true) => {
+			let command:
+				| {
+						slashName?: string
+						namespace?: string
+						run: () => void
+				  }
+				| undefined
+			let toast: { variant: string; message: string } | undefined
+			await module.default.tui({
+				get client() {
+					clientReads += 1
+					throw new Error("diagnostic must not access the server client")
+				},
+				state: { ready, config: { skills: { paths } } },
+				keymap: {
+					registerLayer: (layer: { commands: (typeof command)[] }) => {
+						command = layer.commands[0]
+					},
+				},
+				ui: {
+					toast: (input: { variant: string; message: string }) => {
+						toast = input
+					},
+				},
+			} as never)
+			expect(command).toMatchObject({
+				namespace: "palette",
+				slashName: "agency-debug",
+			})
+			command?.run()
+			return toast
+		}
+
+		expect(await runDiagnostic(["/checkout/.agents/skills/."])).toMatchObject({
+			variant: "success",
+			message: expect.stringContaining("Server plugin: initialized"),
+		})
+		expect(await runDiagnostic([])).toMatchObject({
+			variant: "warning",
+			message: expect.stringContaining("Server plugin: indeterminate"),
+		})
+		expect(clientReads).toBe(0)
+		expect(managedWorkbaseOpencodeTuiPlugin).not.toContain("chat.message")
+		expect(
+			canUpdateManagedWorkbaseOpencodeTuiPlugin(
+				managedWorkbaseOpencodeTuiPlugin,
+			),
+		).toBe(true)
+	})
+
 	test("generates a positional OpenCode command for Agency workflows", () => {
 		expect(managedWorkbaseOpencodeCommand).toContain(
 			"description: Operate Agency work",
@@ -195,11 +283,14 @@ describe("IntegrationService", () => {
 			},
 			"agency-plan": {
 				description:
-					"Agency planning mode. May edit only Agency planning documents.",
+					"Agency planning mode. May update Agency plans and planning structure.",
 				mode: "primary",
 				prompt: expect.stringContaining("You are in Agency Plan mode"),
 				permission: {
 					question: "allow",
+					bash: {
+						"agency *": "allow",
+					},
 					edit: {
 						"*": "deny",
 						"tasks/*/TASK.md": "allow",
@@ -219,6 +310,23 @@ describe("IntegrationService", () => {
 		expect(config.agent.agency.prompt).toContain(
 			"return without waiting for the task to finish",
 		)
+		expect(config.agent["agency-plan"].prompt).toContain(
+			"Start with `agency context . --json`",
+		)
+		expect(config.agent["agency-plan"].prompt).toContain(
+			"decompose it into independently deliverable tasks",
+		)
+		expect(config.agent["agency-plan"].prompt).toContain("Use `--if-revision`")
+		expect(config.agent["agency-plan"].prompt).toContain(
+			"available ticket tools",
+		)
+		expect(config.agent["agency-plan"].prompt).toContain(
+			"changing lifecycle state",
+		)
+		expect(config.agent["agency-plan"].prompt).toContain(
+			"Follow the managed Agency instructions and reported authority",
+		)
+		expect(config.agent["agency-plan"].permission.bash["*"]).toBeUndefined()
 		expect(config.references).toEqual({
 			workbase: {
 				path: "..",
@@ -289,6 +397,8 @@ describe("IntegrationService", () => {
 			{ name: "opencode", state: "managed", changed: true },
 			{ name: "opencode-command", state: "managed", changed: true },
 			{ name: "opencode-plugin", state: "managed", changed: true },
+			{ name: "opencode-tui", state: "managed", changed: true },
+			{ name: "opencode-tui-plugin", state: "managed", changed: true },
 		])
 		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(
 			customRootAgents,
@@ -307,6 +417,12 @@ describe("IntegrationService", () => {
 				join(root, ".opencode/plugin/agency-repository-skills.ts"),
 			).text(),
 		).toBe(managedWorkbaseOpencodePlugin)
+		expect(await Bun.file(join(root, ".opencode/tui.jsonc")).text()).toBe(
+			managedWorkbaseOpencodeTui,
+		)
+		expect(
+			await Bun.file(join(root, ".opencode/tui/agency-debug.ts")).text(),
+		).toBe(managedWorkbaseOpencodeTuiPlugin)
 
 		await unlink(join(root, ".agency/AGENTS.md"))
 		const second = await sync(root)
@@ -346,6 +462,34 @@ describe("IntegrationService", () => {
 		})
 	})
 
+	test("preserves user-owned TUI config and diagnostic plugin", async () => {
+		const customConfig = '{"theme":"custom"}\n'
+		const customPlugin =
+			"export default { id: 'agency.debug', tui: async () => {} }\n"
+		await write(root, ".opencode/tui.json", customConfig)
+		await write(root, ".opencode/tui/agency-debug.ts", customPlugin)
+
+		const result = await sync(root)
+		expect(result.files[4]).toMatchObject({
+			name: "opencode-tui",
+			path: join(root, ".opencode/tui.json"),
+			state: "customized",
+			changed: false,
+			remediation: expect.stringContaining("plugin list"),
+		})
+		expect(result.files[5]).toMatchObject({
+			name: "opencode-tui-plugin",
+			state: "customized",
+			changed: false,
+		})
+		expect(await Bun.file(join(root, ".opencode/tui.json")).text()).toBe(
+			customConfig,
+		)
+		expect(
+			await Bun.file(join(root, ".opencode/tui/agency-debug.ts")).text(),
+		).toBe(customPlugin)
+	})
+
 	test("preserves user-owned OpenCode commands at either supported path", async () => {
 		const custom = "---\ndescription: Custom Agency command\n---\n\nCustom.\n"
 		await write(root, ".opencode/commands/agency.md", custom)

package/src/services/IntegrationService.ts

@@ -18,11 +18,25 @@ import {
 	canUpdateManagedWorkbaseOpencodePlugin,
 	managedWorkbaseOpencodePlugin,
 } from "../workbase/opencode-plugin-file"
+import {
+	canUpdateManagedWorkbaseOpencodeTui,
+	managedWorkbaseOpencodeTui,
+} from "../workbase/opencode-tui-file"
+import {
+	canUpdateManagedWorkbaseOpencodeTuiPlugin,
+	managedWorkbaseOpencodeTuiPlugin,
+} from "../workbase/opencode-tui-plugin-file"
 
 type IntegrationFileState = "managed" | "customized" | "missing" | "drifted"
 
 interface IntegrationFileStatus {
-	readonly name: "agents" | "opencode" | "opencode-command" | "opencode-plugin"
+	readonly name:
+		| "agents"
+		| "opencode"
+		| "opencode-command"
+		| "opencode-plugin"
+		| "opencode-tui"
+		| "opencode-tui-plugin"
 	readonly path: string
 	readonly state: IntegrationFileState
 	readonly diagnostic: string
@@ -99,6 +113,47 @@ const describe = (
 							"Run 'agency integration sync' to expose writable-checkout skills in OpenCode.",
 					}
 	}
+	if (name === "opencode-tui") {
+		return state === "managed"
+			? {
+					diagnostic:
+						"Agency's managed OpenCode TUI config explicitly loads /agency-debug.",
+					remediation: null,
+				}
+			: state === "customized"
+				? {
+						diagnostic:
+							"A user-owned OpenCode TUI config is present and was preserved.",
+						remediation:
+							"Add './tui/agency-debug.ts' to its plugin list to enable /agency-debug.",
+					}
+				: {
+						diagnostic:
+							"The managed OpenCode TUI config needs synchronization.",
+						remediation:
+							"Run 'agency integration sync' to register /agency-debug.",
+					}
+	}
+	if (name === "opencode-tui-plugin") {
+		return state === "managed"
+			? {
+					diagnostic:
+						"Agency's managed OpenCode TUI diagnostic companion is current.",
+					remediation: null,
+				}
+			: state === "customized"
+				? {
+						diagnostic:
+							"A user-owned OpenCode /agency-debug TUI plugin is present and was preserved.",
+						remediation: null,
+					}
+				: {
+						diagnostic:
+							"The managed OpenCode TUI diagnostic companion needs synchronization.",
+						remediation:
+							"Run 'agency integration sync' to install /agency-debug.",
+					}
+	}
 
 	return state === "missing" || state === "drifted"
 		? {
@@ -145,6 +200,8 @@ const inspect = (root: string) =>
 		const opencodeDirectory = join(root, ".opencode")
 		const opencodePath = join(opencodeDirectory, "opencode.jsonc")
 		const opencodeJsonPath = join(opencodeDirectory, "opencode.json")
+		const tuiPath = join(opencodeDirectory, "tui.jsonc")
+		const tuiJsonPath = join(opencodeDirectory, "tui.json")
 		const commandPath = join(opencodeDirectory, "command", "agency.md")
 		const pluralCommandPath = join(opencodeDirectory, "commands", "agency.md")
 		const pluginPath = join(
@@ -157,6 +214,7 @@ const inspect = (root: string) =>
 			"plugins",
 			"agency-repository-skills.ts",
 		)
+		const tuiPluginPath = join(opencodeDirectory, "tui", "agency-debug.ts")
 		const files: IntegrationFileStatus[] = []
 
 		files.push(
@@ -238,6 +296,43 @@ const inspect = (root: string) =>
 			files.push(fileStatus("opencode-plugin", pluginPath, "missing"))
 		}
 
+		if ((yield* fs.readSymlinkTarget(tuiPath)) !== null) {
+			files.push(fileStatus("opencode-tui", tuiPath, "customized"))
+		} else if (
+			(yield* fs.readSymlinkTarget(tuiJsonPath)) !== null ||
+			(yield* fs.exists(tuiJsonPath))
+		) {
+			files.push(fileStatus("opencode-tui", tuiJsonPath, "customized"))
+		} else if (yield* fs.exists(tuiPath)) {
+			files.push(
+				classify(
+					"opencode-tui",
+					tuiPath,
+					yield* fs.readFile(tuiPath),
+					managedWorkbaseOpencodeTui,
+					canUpdateManagedWorkbaseOpencodeTui,
+				),
+			)
+		} else {
+			files.push(fileStatus("opencode-tui", tuiPath, "missing"))
+		}
+
+		if ((yield* fs.readSymlinkTarget(tuiPluginPath)) !== null) {
+			files.push(fileStatus("opencode-tui-plugin", tuiPluginPath, "customized"))
+		} else if (yield* fs.exists(tuiPluginPath)) {
+			files.push(
+				classify(
+					"opencode-tui-plugin",
+					tuiPluginPath,
+					yield* fs.readFile(tuiPluginPath),
+					managedWorkbaseOpencodeTuiPlugin,
+					canUpdateManagedWorkbaseOpencodeTuiPlugin,
+				),
+			)
+		} else {
+			files.push(fileStatus("opencode-tui-plugin", tuiPluginPath, "missing"))
+		}
+
 		return files
 	})
 
@@ -290,9 +385,18 @@ export class IntegrationService extends Effect.Service<IntegrationService>()(
 							} else if (status.name === "opencode-command") {
 								yield* fs.createDirectory(join(root, ".opencode", "command"))
 								yield* fs.writeFile(status.path, managedWorkbaseOpencodeCommand)
-							} else {
+							} else if (status.name === "opencode-plugin") {
 								yield* fs.createDirectory(join(root, ".opencode", "plugin"))
 								yield* fs.writeFile(status.path, managedWorkbaseOpencodePlugin)
+							} else if (status.name === "opencode-tui") {
+								yield* fs.createDirectory(join(root, ".opencode"))
+								yield* fs.writeFile(status.path, managedWorkbaseOpencodeTui)
+							} else {
+								yield* fs.createDirectory(join(root, ".opencode", "tui"))
+								yield* fs.writeFile(
+									status.path,
+									managedWorkbaseOpencodeTuiPlugin,
+								)
 							}
 						}
 						files.push({

package/src/workbase/AGENTS.md

@@ -72,8 +72,9 @@ a refinement loop, or pausing or handing off completed implementation work):
 `missing` generated files. Agency keeps these instructions in
 `.agency/AGENTS.md`, and its managed OpenCode config loads them automatically.
 It also installs `.opencode/command/agency.md`, which provides safe `/agency`
-workflows for active OpenCode sessions, and a managed plugin that exposes skills
-from the authoritative writable checkout without changing the project root.
+workflows for active OpenCode sessions, a managed server plugin that exposes
+skills from the authoritative writable checkout, and an explicitly registered
+TUI companion providing `/agency-debug` without submitting an LLM prompt.
 The workbase-root `AGENTS.md`, when present, belongs entirely to the workbase
 owner and composes with these instructions through OpenCode's normal discovery.
 `agency integration sync` updates only missing or checksum-safe drifted managed

package/src/workbase/opencode-file.ts

@@ -8,7 +8,17 @@ const checksum = (content: string) =>
 
 const agencyPlanPrompt = `You are in Agency Plan mode. Think, read, search, and delegate exploration to construct a well-formed plan for the user's goal. Keep the plan comprehensive but concise, and ask clarifying questions when important tradeoffs or intent are unclear.
 
-You may edit TASK.md, PHASE.md, and EPIC.md to record the outcome, current approach, and important decisions. Do not edit any other file or use shell commands to modify the system.`
+Start with \`agency context . --json\`. Use its document paths and revisions, then inspect the graph, related epics, tasks, phases, linked tickets, and repository declarations needed to understand the work. Use machine-readable Agency output when available instead of inferring structure from directory names.
+
+When planning an epic, decompose it into independently deliverable tasks with explicit dependencies. Add phases only when one task genuinely requires multiple ordered delivery units. Reuse or update existing work instead of creating duplicate tasks or phases.
+
+Use the Agency CLI for full workbase orchestration when the plan requires it, including creating or updating related epics, tasks, and phases; moving tasks; maintaining dependencies; and changing lifecycle state. Use \`--if-revision\` with the revision returned by context for mutations that support it, and run \`agency validate\` after changing workbase structure. Use available ticket tools to inspect or update a linked external ticket when the plan requires it.
+
+You may edit TASK.md, PHASE.md, and EPIC.md to record the outcome, current approach, and important decisions. Do not edit any other file or use shell commands to modify the system. Follow the managed Agency instructions and reported authority for every Agency operation.`
+
+const agencyPlanBashPermissions = {
+	"agency *": "allow",
+}
 
 const body = () =>
 	`${JSON.stringify(
@@ -28,11 +38,12 @@ const body = () =>
 				},
 				"agency-plan": {
 					description:
-						"Agency planning mode. May edit only Agency planning documents.",
+						"Agency planning mode. May update Agency plans and planning structure.",
 					mode: "primary",
 					prompt: agencyPlanPrompt,
 					permission: {
 						question: "allow",
+						bash: agencyPlanBashPermissions,
 						edit: {
 							"*": "deny",
 							"tasks/*/TASK.md": "allow",

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

@@ -7,7 +7,7 @@ const checksum = (content: string) =>
 	createHash("sha256").update(content).digest("hex")
 
 const body = `import { existsSync } from "node:fs"
-import { join } from "node:path"
+import { join, sep } from "node:path"
 import type { Plugin } from "@opencode-ai/plugin"
 
 const contextCheckout = async (directory: string) => {
@@ -36,7 +36,7 @@ const plugin: Plugin = async ({ directory }) => ({
       join(checkout, ".agents", "skills"),
       join(checkout, ".opencode", "skill"),
       join(checkout, ".opencode", "skills"),
-    ].filter(existsSync)
+    ].filter(existsSync).map((path) => \`\${path}\${sep}.\`)
     if (paths.length === 0) return
 
     config.skills ??= {}

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

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

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

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