@markjaquith/agency 2.40.1 → 2.41.0

package/README.md

@@ -80,10 +80,10 @@ workbase/
 
 Agency keeps discovery and other observational commands read-only. Run
 `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 root `AGENTS.md` is user-owned and is not inspected or
-modified by Agency.
+`.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
+`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
@@ -96,6 +96,13 @@ 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`.
 
+OpenCode also discovers a managed `/agency` command. Use `/agency status` for a
+read-only current-work summary, `/agency start [target]` to begin or resume work
+in the active session, `/agency next` to inspect ready work, `/agency validate`
+to check the workbase, and `/agency finish [target]` for verified closeout. The
+command uses OpenCode positional arguments internally and defaults to the safe
+`status` workflow when no subcommand is supplied.
+
 Repository aliases and canonical fetch remotes are declared in tracked
 `agency.json`; local bare clones and symlinks remain ignored under
 `repos/{alias}`. A declaration contains no local path, symlink target, checkout,

package/package.json

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

package/src/cli.test.ts

@@ -526,6 +526,7 @@ describe("CLI", () => {
 		expect(before.files).toMatchObject([
 			{ name: "agents", state: "managed" },
 			{ name: "opencode", state: "managed" },
+			{ name: "opencode-command", state: "managed" },
 		])
 
 		const synced = parseJson(
@@ -534,6 +535,7 @@ describe("CLI", () => {
 		expect(synced.files).toMatchObject([
 			{ name: "agents", state: "managed", changed: false },
 			{ name: "opencode", state: "managed", changed: false },
+			{ name: "opencode-command", state: "managed", changed: false },
 		])
 	})
 

package/src/commands/init.test.ts

@@ -44,6 +44,11 @@ describe("init command", () => {
 			workbase: expect.objectContaining({ path: ".." }),
 		})
 		expect(config.permission).toBeUndefined()
+		const command = await Bun.file(
+			join(root, ".opencode/command/agency.md"),
+		).text()
+		expect(command).toContain("Workflow: `$1`")
+		expect(command).toContain("Optional target: `$2`")
 	})
 
 	test("preserves existing gitignore entries", async () => {

package/src/commands/integration.test.ts

@@ -36,6 +36,11 @@ describe("integration command", () => {
 					diagnostic: expect.stringContaining("cannot load"),
 					remediation: expect.stringContaining("integration sync"),
 				},
+				{
+					name: "opencode-command",
+					state: "missing",
+					remediation: expect.stringContaining("integration sync"),
+				},
 			],
 		})
 	})
@@ -62,11 +67,15 @@ describe("integration command", () => {
 		expect(JSON.parse(logs[0]!).files).toMatchObject([
 			{ name: "agents", state: "managed", changed: true },
 			{ name: "opencode", state: "managed", changed: true },
+			{ name: "opencode-command", 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)
 		expect(
 			await Bun.file(join(root, ".opencode/opencode.jsonc")).exists(),
 		).toBe(true)
+		expect(
+			await Bun.file(join(root, ".opencode/command/agency.md")).exists(),
+		).toBe(true)
 	})
 })

package/src/commands/integration.ts

@@ -54,8 +54,8 @@ export const help = `
 Usage: agency integration <subcommand>
 
 Inspect or explicitly synchronize managed agent integration files. OpenCode
-launches load the managed file at runtime to provide whole-workbase read
-access without changing Agency write authority.
+launches load the managed instructions and project config at runtime, and expose
+the managed /agency command, without changing Agency write authority.
 
 Subcommands:
   status  Report file state, access diagnostics, and safe remediation

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

@@ -154,5 +154,8 @@ status: open
 		expect(
 			await Bun.file(join(root, ".opencode/opencode.jsonc")).exists(),
 		).toBe(false)
+		expect(
+			await Bun.file(join(root, ".opencode/command/agency.md")).exists(),
+		).toBe(false)
 	})
 })

package/src/services/IntegrationService.test.ts

@@ -5,6 +5,10 @@ import { mkdir, stat, symlink, unlink, utimes } from "node:fs/promises"
 import { dirname, join } from "node:path"
 import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
 import { managedWorkbaseAgents } from "../workbase/agents-file"
+import {
+	canUpdateManagedWorkbaseOpencodeCommand,
+	managedWorkbaseOpencodeCommand,
+} from "../workbase/opencode-command-file"
 import { managedWorkbaseOpencode } from "../workbase/opencode-file"
 import { IntegrationService } from "./IntegrationService"
 
@@ -46,14 +50,21 @@ describe("IntegrationService", () => {
 		expect((await status(root)).files.map(({ state }) => state)).toEqual([
 			"missing",
 			"missing",
+			"missing",
 		])
 		expect(await Bun.file(join(root, ".agency/AGENTS.md")).exists()).toBe(false)
 
 		await write(root, ".agency/AGENTS.md", managedWorkbaseAgents)
 		await write(root, ".opencode/opencode.jsonc", managedWorkbaseOpencode)
+		await write(
+			root,
+			".opencode/command/agency.md",
+			managedWorkbaseOpencodeCommand,
+		)
 		expect((await status(root)).files.map(({ state }) => state)).toEqual([
 			"managed",
 			"managed",
+			"managed",
 		])
 	})
 
@@ -68,9 +79,40 @@ describe("IntegrationService", () => {
 		expect((await status(root)).files.map(({ state }) => state)).toEqual([
 			"customized",
 			"drifted",
+			"missing",
 		])
 	})
 
+	test("generates a positional OpenCode command for Agency workflows", () => {
+		expect(managedWorkbaseOpencodeCommand).toContain(
+			"description: Operate Agency work",
+		)
+		expect(managedWorkbaseOpencodeCommand).toContain("Workflow: `$1`")
+		expect(managedWorkbaseOpencodeCommand).toContain("Optional target: `$2`")
+		expect(managedWorkbaseOpencodeCommand).toContain(
+			"Complete request: `$ARGUMENTS`",
+		)
+		for (const workflow of [
+			"start",
+			"status",
+			"next",
+			"validate",
+			"finish",
+			"help",
+		]) {
+			expect(managedWorkbaseOpencodeCommand).toContain(`- \`${workflow}\`:`)
+		}
+		expect(managedWorkbaseOpencodeCommand).toContain("Never run `agency work`")
+		expect(
+			canUpdateManagedWorkbaseOpencodeCommand(managedWorkbaseOpencodeCommand),
+		).toBe(true)
+		expect(
+			canUpdateManagedWorkbaseOpencodeCommand(
+				managedWorkbaseOpencodeCommand.replace("Workflow: `$1`", "Workflow"),
+			),
+		).toBe(false)
+	})
+
 	test("generates context-first safety and execution closeout guidance", () => {
 		const body = managedBody(managedWorkbaseAgents)
 
@@ -93,6 +135,7 @@ describe("IntegrationService", () => {
 		expect(body).toContain("PR state, current head, diff summary")
 		expect(body).toContain("Run `agency validate` before reporting completion")
 		expect(body).toContain("agency integration status")
+		expect(body).toContain(".opencode/command/agency.md")
 	})
 
 	test("grants OpenCode access to the complete workbase", () => {
@@ -167,6 +210,7 @@ describe("IntegrationService", () => {
 		expect(first.files).toMatchObject([
 			{ name: "agents", state: "customized", changed: false },
 			{ name: "opencode", state: "managed", changed: true },
+			{ name: "opencode-command", state: "managed", changed: true },
 		])
 		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(
 			customRootAgents,
@@ -177,6 +221,9 @@ describe("IntegrationService", () => {
 		expect(await Bun.file(join(root, ".opencode/opencode.jsonc")).text()).toBe(
 			managedWorkbaseOpencode,
 		)
+		expect(
+			await Bun.file(join(root, ".opencode/command/agency.md")).text(),
+		).toBe(managedWorkbaseOpencodeCommand)
 
 		await unlink(join(root, ".agency/AGENTS.md"))
 		const second = await sync(root)
@@ -189,6 +236,34 @@ describe("IntegrationService", () => {
 		)
 	})
 
+	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)
+
+		let result = await sync(root)
+		expect(result.files[2]).toMatchObject({
+			name: "opencode-command",
+			path: join(root, ".opencode/commands/agency.md"),
+			state: "customized",
+			changed: false,
+		})
+		expect(
+			await Bun.file(join(root, ".opencode/command/agency.md")).exists(),
+		).toBe(false)
+
+		await unlink(join(root, ".opencode/commands/agency.md"))
+		await write(root, ".opencode/command/agency.md", custom)
+		result = await sync(root)
+		expect(result.files[2]).toMatchObject({
+			path: join(root, ".opencode/command/agency.md"),
+			state: "customized",
+			changed: false,
+		})
+		expect(
+			await Bun.file(join(root, ".opencode/command/agency.md")).text(),
+		).toBe(custom)
+	})
+
 	test("migrates checksum-valid root instructions", async () => {
 		await write(root, "AGENTS.md", managedWorkbaseAgents)
 

package/src/services/IntegrationService.ts

@@ -10,11 +10,15 @@ import {
 	canUpdateManagedWorkbaseOpencode,
 	managedWorkbaseOpencode,
 } from "../workbase/opencode-file"
+import {
+	canUpdateManagedWorkbaseOpencodeCommand,
+	managedWorkbaseOpencodeCommand,
+} from "../workbase/opencode-command-file"
 
 type IntegrationFileState = "managed" | "customized" | "missing" | "drifted"
 
 interface IntegrationFileStatus {
-	readonly name: "agents" | "opencode"
+	readonly name: "agents" | "opencode" | "opencode-command"
 	readonly path: string
 	readonly state: IntegrationFileState
 	readonly diagnostic: string
@@ -52,6 +56,25 @@ const describe = (
 				"Run 'agency integration sync' to install Agency instructions and whole-workbase OpenCode access.",
 		}
 	}
+	if (name === "opencode-command") {
+		return state === "managed"
+			? {
+					diagnostic: "Agency's managed OpenCode /agency command is current.",
+					remediation: null,
+				}
+			: state === "customized"
+				? {
+						diagnostic:
+							"A user-owned OpenCode /agency command is present and was preserved.",
+						remediation: null,
+					}
+				: {
+						diagnostic:
+							"The managed OpenCode /agency command needs synchronization.",
+						remediation:
+							"Run 'agency integration sync' to install the managed /agency command.",
+					}
+	}
 
 	return state === "missing" || state === "drifted"
 		? {
@@ -98,6 +121,8 @@ const inspect = (root: string) =>
 		const opencodeDirectory = join(root, ".opencode")
 		const opencodePath = join(opencodeDirectory, "opencode.jsonc")
 		const opencodeJsonPath = join(opencodeDirectory, "opencode.json")
+		const commandPath = join(opencodeDirectory, "command", "agency.md")
+		const pluralCommandPath = join(opencodeDirectory, "commands", "agency.md")
 		const files: IntegrationFileStatus[] = []
 
 		files.push(
@@ -135,6 +160,29 @@ const inspect = (root: string) =>
 			files.push(fileStatus("opencode", opencodePath, "missing"))
 		}
 
+		if ((yield* fs.readSymlinkTarget(commandPath)) !== null) {
+			files.push(fileStatus("opencode-command", commandPath, "customized"))
+		} else if (
+			(yield* fs.readSymlinkTarget(pluralCommandPath)) !== null ||
+			(yield* fs.exists(pluralCommandPath))
+		) {
+			files.push(
+				fileStatus("opencode-command", pluralCommandPath, "customized"),
+			)
+		} else if (yield* fs.exists(commandPath)) {
+			files.push(
+				classify(
+					"opencode-command",
+					commandPath,
+					yield* fs.readFile(commandPath),
+					managedWorkbaseOpencodeCommand,
+					canUpdateManagedWorkbaseOpencodeCommand,
+				),
+			)
+		} else {
+			files.push(fileStatus("opencode-command", commandPath, "missing"))
+		}
+
 		return files
 	})
 
@@ -181,9 +229,12 @@ export class IntegrationService extends Effect.Service<IntegrationService>()(
 							if (status.name === "agents") {
 								yield* fs.createDirectory(join(root, ".agency"))
 								yield* fs.writeFile(status.path, managedWorkbaseAgents)
-							} else {
+							} else if (status.name === "opencode") {
 								yield* fs.createDirectory(join(root, ".opencode"))
 								yield* fs.writeFile(status.path, managedWorkbaseOpencode)
+							} else {
+								yield* fs.createDirectory(join(root, ".opencode", "command"))
+								yield* fs.writeFile(status.path, managedWorkbaseOpencodeCommand)
 							}
 						}
 						files.push({

package/src/workbase/AGENCY_COMMAND.md

@@ -0,0 +1,48 @@
+---
+description: Operate Agency work with safe start, status, next, validate, and finish workflows
+---
+
+Operate the current Agency workbase using the managed Agency instructions.
+
+Invocation inputs:
+
+- Workflow: `$1`
+- Optional target: `$2`
+- Complete request: `$ARGUMENTS`
+
+Use `status` when the workflow is empty. Treat words after the optional target as
+additional user instructions. If the workflow is unknown, make no changes and
+list the supported workflows.
+
+Always follow these rules:
+
+- Run `agency context . --json` first when no target is provided. With a target,
+  pass that target to `agency context` instead.
+- Use the returned document paths, readiness, authority, checkout state, claim,
+  and validation result. Do not infer them from directory names.
+- Stop on validation errors, dependency blockers, an unexpected writable
+  repository, or a conflicting active claim.
+- Write code only in `authority.writable.checkoutPath`; references are read-only.
+- Never run `agency work` to start the current agent again.
+- Create a pull request only when the complete request explicitly asks for one.
+
+Dispatch the workflow as follows:
+
+- `start`: Read the returned task and phase documents, inspect the writable
+  checkout, then begin or resume the requested work in this session. Keep durable
+  decisions current and carry the work through focused verification.
+- `status`: Make no changes. Summarize the target, readiness, authority, durable
+  status, claim and PR state, checkout state, current Git changes, blockers, and
+  the most useful next action.
+- `next`: Run `agency next --json`, summarize ready and blocked execution units,
+  and recommend the highest-priority ready unit. Do not launch another agent.
+- `validate`: Run Agency validation for the discovered workbase. Explain every
+  issue and, when safe and within authority, repair requested non-structural
+  problems before validating again.
+- `finish`: Complete any remaining requested implementation first. Run focused
+  repository checks, refresh the task or phase delivery context, and run
+  `agency validate`. Finish an active claim with its current revision; otherwise
+  update unclaimed status only when the requested outcome and delivery work are
+  actually complete. Do not create a PR unless explicitly requested.
+- `help`: Make no changes. Briefly explain these workflows and the positional
+  form `/agency <workflow> [target] [additional instructions]`.

package/src/workbase/AGENTS.md

@@ -71,6 +71,8 @@ a refinement loop, or pausing or handing off completed implementation work):
 `agency integration status` reports `managed`, `drifted`, `customized`, or
 `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.
 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-command-file.ts

@@ -0,0 +1,30 @@
+import { createHash } from "node:crypto"
+import commandTemplate from "./AGENCY_COMMAND.md" with { type: "text" }
+
+const managedHeaderPattern =
+	/^---\r?\n# agency-managed: sha256=([a-f0-9]{64})\r?\n/
+
+const checksum = (content: string) =>
+	createHash("sha256").update(content).digest("hex")
+
+const canonicalBody = commandTemplate.endsWith("\n")
+	? commandTemplate
+	: `${commandTemplate}\n`
+
+const renderManagedWorkbaseOpencodeCommand = (
+	content: string = canonicalBody,
+) =>
+	content.replace(
+		/^---\n/,
+		`---\n# agency-managed: sha256=${checksum(content)}\n`,
+	)
+
+export const managedWorkbaseOpencodeCommand =
+	renderManagedWorkbaseOpencodeCommand()
+
+export const canUpdateManagedWorkbaseOpencodeCommand = (content: string) => {
+	const match = content.match(managedHeaderPattern)
+	if (!match?.[1]) return false
+
+	return checksum(content.replace(managedHeaderPattern, "---\n")) === match[1]
+}