@markjaquith/agency 2.28.0 → 2.29.0

package/src/cli-parser.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "bun:test"
+import orchestrationRecipes from "../fixtures/protocol/orchestration-recipes.json"
 import { parseCli } from "./cli-parser"
 
 const expectUsageError = (args: string[], usage: string) => {
@@ -6,6 +7,12 @@ const expectUsageError = (args: string[], usage: string) => {
 }
 
 describe("strict CLI parsing", () => {
+	test("accepts every documented orchestration recipe command", () => {
+		for (const args of orchestrationRecipes) {
+			expect(() => parseCli(args)).not.toThrow()
+		}
+	})
+
 	test("rejects misspelled and command-inapplicable options", () => {
 		expectUsageError(["task", "list", "--josn"], "agency task")
 		expectUsageError(
@@ -132,6 +139,7 @@ describe("strict CLI parsing", () => {
 			["repo", "remote", "agency", "https://example.com/repo.git"],
 			["repo", "verify", "agency"],
 			["workbase", "show", "primary", "--json"],
+			["workbase", "init", "new-workbase", "--json"],
 			["workbase", "name", "primary", "renamed"],
 			["workbase", "name", "primary", "--clear"],
 		]) {
@@ -157,6 +165,7 @@ describe("strict CLI parsing", () => {
 	test("enforces exact maximum positional arity for every leaf command", () => {
 		for (const [args, usage] of [
 			[["init", "one", "two"], "agency init"],
+			[["workbase", "init", "one", "two"], "agency workbase init"],
 			[["workbase", "add", "one", "two"], "agency workbase add"],
 			[["workbase", "list", "extra"], "agency workbase list"],
 			[["integration", "status", "extra"], "agency integration status"],

package/src/cli-parser.ts

@@ -127,13 +127,19 @@ const commands = {
 		},
 	},
 	workbase: {
-		usage: "agency workbase <add|list|show|name|remove|prune|default>",
+		usage: "agency workbase <init|add|list|show|name|remove|prune|default>",
 		options: {
 			...outputOptions,
 			name: { type: "string" },
 			clear: { type: "boolean" },
 		},
 		subcommands: {
+			init: {
+				usage: "agency workbase init [path] [--json]",
+				minArgs: 0,
+				maxArgs: 1,
+				options: ["json"],
+			},
 			add: {
 				usage: "agency workbase add <path> [--json]",
 				minArgs: 1,

package/src/cli.test.ts

@@ -1,6 +1,8 @@
 import { afterEach, describe, expect, test } from "bun:test"
 import { access, mkdir, realpath } from "node:fs/promises"
 import { join } from "node:path"
+import errorFixture from "../fixtures/protocol/error.json"
+import successFixture from "../fixtures/protocol/success.json"
 import { cleanupTempDir, createTempDir } from "./test-utils"
 
 const projectRoot = join(import.meta.dir, "..")
@@ -65,6 +67,28 @@ describe("CLI", () => {
 		expect(help.stderr).toBe("")
 	})
 
+	test("keeps the published protocol fixtures synchronized with CLI output", async () => {
+		const parent = await createTempDir()
+		tempDirs.push(parent)
+		const root = join(parent, "workbase")
+		const success = await runCli(["init", root, "--json"], parent)
+		expect(success.exitCode).toBe(0)
+		expect(success.stderr).toBe("")
+		expect(success.stdout.endsWith("\n")).toBe(true)
+		const successEnvelope = JSON.parse(success.stdout)
+		expect(successEnvelope.result.root).toBe(root)
+		expect({
+			...successEnvelope,
+			result: { ...successEnvelope.result, root: "/work/agency" },
+		}).toEqual(successFixture)
+
+		const failure = await runCli(["unknown", "--json"])
+		expect(failure.exitCode).toBe(1)
+		expect(failure.stderr).toBe("")
+		expect(failure.stdout.endsWith("\n")).toBe(true)
+		expect(JSON.parse(failure.stdout)).toEqual(errorFixture)
+	})
+
 	test("reports unknown commands and preserves tagged error messages", async () => {
 		const unknown = await runCli(["unknown"])
 		expect(unknown.exitCode).toBe(1)
@@ -432,16 +456,16 @@ describe("CLI", () => {
 			await runCli(["integration", "status", "--json"], root),
 		)
 		expect(before.files).toMatchObject([
-			{ name: "agents", state: "missing" },
-			{ name: "opencode", state: "missing" },
+			{ name: "agents", state: "managed" },
+			{ name: "opencode", state: "managed" },
 		])
 
 		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 },
+			{ name: "agents", state: "managed", changed: false },
+			{ name: "opencode", state: "managed", changed: false },
 		])
 	})
 

package/src/commands/init.test.ts

@@ -33,10 +33,14 @@ 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(false)
-		expect(
-			await Bun.file(join(root, ".opencode/opencode.jsonc")).exists(),
-		).toBe(false)
+		expect(await Bun.file(join(root, "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.permission.external_directory).toEqual({
+			"../**": "allow",
+		})
 	})
 
 	test("preserves existing gitignore entries", async () => {

package/src/commands/init.ts

@@ -1,6 +1,7 @@
 import { Effect } from "effect"
 import { resolve } from "node:path"
 import type { BaseCommandOptions } from "../utils/command"
+import { IntegrationService } from "../services/IntegrationService"
 import { WorkbaseService } from "../services/WorkbaseService"
 import { createLoggers } from "../utils/effect"
 
@@ -10,12 +11,14 @@ interface InitOptions extends BaseCommandOptions {
 
 export const init = (options: InitOptions = {}) =>
 	Effect.gen(function* () {
+		const integrations = yield* IntegrationService
 		const workbase = yield* WorkbaseService
 		const { log } = createLoggers(options)
 		const cwd = options.cwd ?? process.cwd()
 		const root = yield* workbase.initialize(
 			options.path ? resolve(cwd, options.path) : cwd,
 		)
+		yield* integrations.sync(root)
 		log(
 			options.json
 				? JSON.stringify({ root }, null, 2)

package/src/commands/work.test.ts

@@ -8,6 +8,7 @@ import { PhaseService } from "../services/PhaseService"
 import { WorktreeService } from "../services/WorktreeService"
 import { ClaimService } from "../services/ClaimService"
 import { ReadinessService } from "../services/ReadinessService"
+import { IntegrationService } from "../services/IntegrationService"
 import { captureErrors, captureLogs } from "../test-utils"
 import { work, workPrepare } from "./work"
 import type { PickWorkTarget } from "../workbase/work-target"
@@ -74,6 +75,7 @@ const createHarness = (options: HarnessOptions = {}) => {
 	const statusUpdates: string[] = []
 	const shownTasks: string[] = []
 	const progressUpdates: string[] = []
+	let integrationSyncs = 0
 	const guards: Array<{ target: string; override?: boolean }> = []
 	const launches: Array<{
 		cli: string
@@ -210,6 +212,12 @@ const createHarness = (options: HarnessOptions = {}) => {
 				: Effect.void
 		},
 	}
+	const integrations = {
+		sync: () => {
+			integrationSyncs += 1
+			return Effect.succeed({ root: "/workbase", files: [] })
+		},
+	}
 	const fs = {
 		isDirectory: (path: string) =>
 			Effect.succeed(options.existingDirectories?.includes(path) ?? true),
@@ -256,6 +264,7 @@ const createHarness = (options: HarnessOptions = {}) => {
 				Effect.provideService(PhaseService, phases as never),
 				Effect.provideService(ClaimService, claims as never),
 				Effect.provideService(ReadinessService, readiness as never),
+				Effect.provideService(IntegrationService, integrations as never),
 			) as Effect.Effect<void, unknown, never>,
 		)
 	const runPrepare = (commandOptions: Parameters<typeof workPrepare>[0]) =>
@@ -279,12 +288,23 @@ const createHarness = (options: HarnessOptions = {}) => {
 		shownTasks,
 		progressUpdates,
 		guards,
+		get integrationSyncs() {
+			return integrationSyncs
+		},
 		run,
 		runPrepare,
 	}
 }
 
 describe("work command", () => {
+	test("reconciles managed integration files before preparing work", async () => {
+		const harness = createHarness()
+
+		await harness.run({ taskId: "example", opencode: true })
+
+		expect(harness.integrationSyncs).toBe(1)
+	})
+
 	test("guards execution targets before materialization and honors --force", async () => {
 		const blocked = createHarness({ guardError: new Error("blocked") })
 		await expect(

package/src/commands/work.ts

@@ -9,6 +9,7 @@ import { TaskService } from "../services/TaskService"
 import { PhaseService } from "../services/PhaseService"
 import { ClaimService } from "../services/ClaimService"
 import { ReadinessService } from "../services/ReadinessService"
+import { IntegrationService } from "../services/IntegrationService"
 import { createLoggers } from "../utils/effect"
 import { execvp } from "../utils/exec"
 import { createProgress, type Progress } from "../utils/progress"
@@ -106,6 +107,7 @@ export const work = (
 		const phases = yield* PhaseService
 		const claims = yield* ClaimService
 		const readiness = yield* ReadinessService
+		const integrations = yield* IntegrationService
 		const { log, verboseLog } = createLoggers(options)
 		const cwd = options.cwd ?? process.cwd()
 		const directoryPath = options.directory
@@ -118,6 +120,7 @@ export const work = (
 		const inputAllowed = options.inputAllowed ?? true
 		const root = yield* resolveWorkbase(startPath, pickBase, inputAllowed)
 		if (!root) return
+		yield* integrations.sync(root)
 		const { config } = yield* workbase.loadConfig(root)
 
 		let target: WorkTarget | null = null

package/src/commands/workbase.ts

@@ -151,7 +151,7 @@ export const workbase = (options: WorkbaseOptions) =>
 			default:
 				return yield* Effect.fail(
 					new Error(
-						"Subcommand is required. Available: add, list, show, name, remove, prune, default",
+						"Subcommand is required. Available: init, add, list, show, name, remove, prune, default",
 					),
 				)
 		}
@@ -161,6 +161,7 @@ export const help = `
 Usage: agency workbase <subcommand>
 
 Subcommands:
+  init [path]       Initialize an Agency workbase
   add <path>        Register an Agency workbase
   list              List registered workbases
   show <selector>   Show a registered workbase

package/src/services/IntegrationService.test.ts

@@ -1,7 +1,7 @@
 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 { 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"
@@ -19,6 +19,9 @@ const managed = (prefix: string, body: string, suffix = "") => {
 	return `${prefix}${checksum}${suffix}\n\n${body}`
 }
 
+const managedBody = (content: string) =>
+	content.slice(content.indexOf("\n\n") + 2)
+
 const status = (root: string) =>
 	runTestEffect(
 		IntegrationService.pipe(Effect.flatMap((service) => service.status(root))),
@@ -47,7 +50,7 @@ describe("IntegrationService", () => {
 		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))
+		await write(root, ".opencode/opencode.jsonc", managedWorkbaseOpencode)
 		expect((await status(root)).files.map(({ state }) => state)).toEqual([
 			"managed",
 			"managed",
@@ -68,6 +71,48 @@ describe("IntegrationService", () => {
 		])
 	})
 
+	test("generates context-first safety and execution closeout guidance", () => {
+		const body = managedBody(managedWorkbaseAgents)
+
+		expect(body).toContain("agency context . --json")
+		expect(body).toContain("authority.writable.checkoutPath")
+		expect(body).toContain("Do not begin execution without a claim")
+		expect(body).toContain("Run `agency validate`")
+		expect(body).toContain("only with explicit user intent")
+		expect(body).toContain("An execution unit is `working`")
+		expect(body).toContain("It becomes `done`")
+		expect(body).toContain("solely because its PR")
+		expect(body).toContain("creating or updating a PR")
+		expect(body).toContain("marking it ready")
+		expect(body).toMatch(/completing\s+a refinement loop/)
+		expect(body).toContain("pausing or handing off")
+		expect(body).toContain("`agency task status` or `agency phase status`")
+		expect(body).toContain("`TASK.md` or `PHASE.md`")
+		expect(body).toContain("PR state, current head, diff summary")
+		expect(body).toContain("Run `agency validate` before reporting completion")
+		expect(body).toContain("agency integration status")
+	})
+
+	test("grants OpenCode access to the complete workbase", () => {
+		const config = JSON.parse(managedBody(managedWorkbaseOpencode))
+
+		expect(config.references).toEqual({
+			tasks: {
+				path: "../tasks",
+				description:
+					"Agency task definitions and execution context; authority still comes from agency context",
+			},
+			epics: {
+				path: "../epics",
+				description:
+					"Agency epic definitions and orchestration context; no implementation write authority",
+			},
+		})
+		expect(config.permission).toEqual({
+			external_directory: { "../**": "allow" },
+		})
+	})
+
 	test("treats an existing JSON OpenCode config as customized", async () => {
 		await write(root, ".opencode/opencode.json", '{"model":"test/model"}\n')
 
@@ -95,7 +140,7 @@ describe("IntegrationService", () => {
 		])
 		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(customAgents)
 		expect(await Bun.file(join(root, ".opencode/opencode.jsonc")).text()).toBe(
-			managedWorkbaseOpencode(root),
+			managedWorkbaseOpencode,
 		)
 
 		await unlink(join(root, "AGENTS.md"))
@@ -106,6 +151,21 @@ describe("IntegrationService", () => {
 		)
 	})
 
+	test("does not rewrite an already-current OpenCode configuration", async () => {
+		const path = join(root, ".opencode/opencode.jsonc")
+		await write(root, ".opencode/opencode.jsonc", managedWorkbaseOpencode)
+		const timestamp = new Date("2000-01-01T00:00:00.000Z")
+		await utimes(path, timestamp, timestamp)
+
+		const result = await sync(root)
+
+		expect(result.files[1]).toMatchObject({
+			state: "managed",
+			changed: false,
+		})
+		expect((await stat(path)).mtimeMs).toBe(timestamp.getTime())
+	})
+
 	test("does not overwrite managed files whose checksums no longer match", async () => {
 		const tampered = `${managed(
 			"<!-- agency-managed: sha256=",
@@ -122,6 +182,23 @@ describe("IntegrationService", () => {
 		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(tampered)
 	})
 
+	test("does not overwrite a user-modified OpenCode configuration", async () => {
+		const tampered = `${managed(
+			"// agency-managed: sha256=",
+			'{"references":{}}\n',
+		)}// User edit\n`
+		await write(root, ".opencode/opencode.jsonc", tampered)
+
+		const result = await sync(root)
+		expect(result.files[1]).toMatchObject({
+			state: "customized",
+			changed: false,
+		})
+		expect(await Bun.file(join(root, ".opencode/opencode.jsonc")).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")

package/src/services/IntegrationService.ts

@@ -75,7 +75,7 @@ const inspect = (root: string) =>
 					"opencode",
 					opencodePath,
 					yield* fs.readFile(opencodePath),
-					managedWorkbaseOpencode(root),
+					managedWorkbaseOpencode,
 					canUpdateManagedWorkbaseOpencode,
 				),
 			)
@@ -119,7 +119,7 @@ export class IntegrationService extends Effect.Service<IntegrationService>()(
 								yield* fs.writeFile(status.path, managedWorkbaseAgents)
 							} else {
 								yield* fs.createDirectory(join(root, ".opencode"))
-								yield* fs.writeFile(status.path, managedWorkbaseOpencode(root))
+								yield* fs.writeFile(status.path, managedWorkbaseOpencode)
 							}
 						}
 						files.push({

package/src/workbase/AGENTS.md

@@ -4,34 +4,68 @@ This directory is an Agency workbase. Epics, tasks, and phases are durable
 Markdown documents; repository aliases and generated Git worktrees provide code
 access.
 
-## Session Context
+## Bootstrap
 
-Before doing work, identify the current entity from the working directory and
-read its context:
+Start every session with one read-only command:
 
-- In `epics/<epic>/`, read `EPIC.md`. Coordinate the epic's tasks without
-  writing implementation code.
-- In `tasks/<task>/`, read `TASK.md`. A task with `phases` is an orchestration
-  session; a task without `phases` is a single execution unit.
-- In `tasks/<task>/phases/<phase>/`, read both `../../TASK.md` and `PHASE.md`.
-  The phase is the execution unit.
+```bash
+agency context . --json
+```
 
-For execution units, writable and reference checkouts live under `code/` when
-materialized. Write only through the checkout named by the singular `repo`
-field. Repositories listed in plural `repos` are read-only references.
+Use the returned target, document paths and revisions, dependency readiness,
+authority, checkout state, PR state, and validation result. Do not infer these
+from directory names or stale prose.
+
+## Authority
+
+- An epic or multi-phase task is orchestration context and has no implementation
+  write authority.
+- For an execution unit, write code only at
+  `authority.writable.checkoutPath`. Every `authority.references` checkout is
+  read-only, even if filesystem permissions allow writes.
+- Keep task-wide decisions in `TASK.md` and phase-specific delivery context in
+  `PHASE.md`. Use Agency commands for structural frontmatter mutations.
 
 ## 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`.
-- Coordinate execution ownership with `agency claim`, `agency release`, and
-  `agency finish`; `agency work` claims execution units before launch.
+- Stop on validation errors, dependency blockers, an unexpected writable
+  repository, or a conflicting active claim.
+- Do not begin execution without a claim. `agency work` claims before launch;
+  external orchestrators use `agency claim` with the revision from context.
 - Do not manually create, move, or remove worktrees under `code/`.
 - Use `agency archive`, rather than moving work item folders manually.
 - Do not edit bare repositories or repository symlinks under `repos/`.
 - Do not run `agency work` from an active agent session unless the user
   explicitly asks to launch another agent.
 - Run `agency validate` before worktree or pull-request operations.
-- Create a pull request only when the user explicitly requests it.
+- Create a pull request only with explicit user intent, using
+  `agency pr create <task> [phase]` so the URL is recorded durably.
+
+## Closeout
+
+An execution unit is `working` while implementation or requested delivery work
+remains. It becomes `done` when both are complete, even if its PR remains open
+for review or merge. Do not leave a task or phase `working` solely because its PR
+is open; if merge was requested, merge remains delivery work.
+
+At each closeout trigger (creating or updating a PR, marking it ready, completing
+a refinement loop, or pausing or handing off completed implementation work):
+
+- Use `agency task status` or `agency phase status` to set the execution unit's
+  current status. Finish an active claim with the current revision via
+  `agency finish`.
+- Refresh durable delivery context in `TASK.md` or `PHASE.md`, including recorded
+  PR state, current head, diff summary, and verification results after later
+  pushes when those details are maintained there.
+- Run `agency validate` before reporting completion.
+
+## 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.
+
+OpenCode can access the complete workbase tree, but this filesystem permission
+does not expand Agency write authority beyond the checkout reported by
+`agency context`.

package/src/workbase/opencode-file.ts

@@ -1,5 +1,4 @@
 import { createHash } from "node:crypto"
-import { join } from "node:path"
 
 const managedHeaderPattern =
 	/^\/\/ agency-managed: sha256=([a-f0-9]{64})\r?\n\r?\n/
@@ -7,24 +6,25 @@ const managedHeaderPattern =
 const checksum = (content: string) =>
 	createHash("sha256").update(content).digest("hex")
 
-const body = (root: string) =>
+const body = () =>
 	`${JSON.stringify(
 		{
 			$schema: "https://opencode.ai/config.json",
 			references: {
 				tasks: {
 					path: "../tasks",
-					description: "Agency task definitions and execution context",
+					description:
+						"Agency task definitions and execution context; authority still comes from agency context",
 				},
 				epics: {
 					path: "../epics",
-					description: "Agency epic definitions and orchestration context",
+					description:
+						"Agency epic definitions and orchestration context; no implementation write authority",
 				},
 			},
 			permission: {
 				external_directory: {
-					[`${join(root, "tasks")}/*`]: "allow",
-					[`${join(root, "epics")}/*`]: "allow",
+					"../**": "allow",
 				},
 			},
 		},
@@ -35,8 +35,7 @@ const body = (root: string) =>
 const renderManagedWorkbaseOpencode = (content: string) =>
 	`// agency-managed: sha256=${checksum(content)}\n\n${content}`
 
-export const managedWorkbaseOpencode = (root: string) =>
-	renderManagedWorkbaseOpencode(body(root))
+export const managedWorkbaseOpencode = renderManagedWorkbaseOpencode(body())
 
 export const canUpdateManagedWorkbaseOpencode = (content: string) => {
 	const match = content.match(managedHeaderPattern)