@markjaquith/agency 2.7.3 → 2.9.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
 
@@ -298,6 +302,7 @@ agency task create <id> --multi-phase
 ### Noninteractive Use
 
 Agency never prompts when `--no-input` is set or stdin/stderr are not TTYs.
+`--json` also disables prompts and selectors, even when a TTY is available.
 Commands with explicit inputs continue normally. `task new` fails immediately;
 `work` requires an explicit directory, task ID, or `--epic` and must run from a
 workbase; `validate` requires an explicit path or must run from a workbase.
@@ -404,6 +409,66 @@ unknown dependencies, and dependency cycles. YAML duplicate keys, anchors,
 aliases, and custom tags are rejected. When path is omitted outside a workbase,
 Agency prompts for a registered workbase.
 
+## Machine Protocol
+
+`--json` emits exactly one JSON value on stdout for success or failure. It takes
+precedence over `--silent`; progress, warnings, and verbose diagnostics remain on
+stderr. Version 1 success responses have this shape:
+
+```json
+{ "version": 1, "ok": true, "result": { "root": "/work/agency" } }
+```
+
+Failures exit nonzero and use the same versioned envelope:
+
+```json
+{
+	"version": 1,
+	"ok": false,
+	"error": {
+		"code": "CLI_USAGE",
+		"message": "Unknown command 'unknown'.\n\nUsage: agency <command> [options]",
+		"fields": {
+			"detail": "Unknown command 'unknown'.",
+			"usage": "agency <command> [options]"
+		},
+		"retryable": false,
+		"remediation": "Correct the arguments using the usage value in error.fields."
+	}
+}
+```
+
+Every error contains a stable `code`, human-readable `message`, structured
+`fields`, and `retryable`. `remediation` is included when Agency knows a specific
+recovery action. Version 1 defines these codes:
+
+| Code                      | Meaning                                                  |
+| ------------------------- | -------------------------------------------------------- |
+| `CLI_USAGE`               | Invalid command, option, argument, or option combination |
+| `WORKBASE_NOT_FOUND`      | No workbase could be resolved                            |
+| `WORKBASE_CONFIG_INVALID` | Invalid workbase configuration                           |
+| `WORKBASE_REGISTRY_ERROR` | Invalid or inaccessible workbase registry                |
+| `FILE_NOT_FOUND`          | A required path does not exist                           |
+| `FILESYSTEM_ERROR`        | A filesystem operation failed                            |
+| `FRONTMATTER_INVALID`     | A durable document has invalid frontmatter               |
+| `VALIDATION_FAILED`       | Workbase validation reported issues                      |
+| `REPOSITORY_ERROR`        | Repository operation failed                              |
+| `EPIC_ERROR`              | Epic operation failed                                    |
+| `TASK_ERROR`              | Task operation failed                                    |
+| `PHASE_ERROR`             | Phase operation failed                                   |
+| `ARCHIVE_ERROR`           | Archive operation failed                                 |
+| `WORKTREE_ERROR`          | Worktree operation failed                                |
+| `PULL_REQUEST_ERROR`      | Pull request operation failed                            |
+| `PROCESS_ERROR`           | A child process failed and may be retried                |
+| `PROTOCOL_OUTPUT_ERROR`   | A command violated the machine output contract           |
+| `COMMAND_FAILED`          | An otherwise unclassified command failure                |
+
+The Effect schemas are exported from `@markjaquith/agency` and
+`@markjaquith/agency/protocol`. The distributable JSON Schema is exported as
+`@markjaquith/agency/schemas/agency-envelope-v1.json`. Representative payloads
+are exported as `@markjaquith/agency/fixtures/protocol/success.json` and
+`@markjaquith/agency/fixtures/protocol/error.json`.
+
 ## Agent Skill
 
 `skills/agency/SKILL.md` contains an agent-oriented operating guide for Agency.

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,13 @@ 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"
+import {
+	collectCommandResult,
+	errorEnvelope,
+	successEnvelope,
+	writeEnvelope,
+} from "./src/protocol"
 
 // Create CLI layer with all services
 const CliLayer = Layer.mergeAll(
@@ -35,6 +46,7 @@ const CliLayer = Layer.mergeAll(
 	WorktreeService.Default,
 	PullRequestService.Default,
 	ArchiveService.Default,
+	IntegrationService.Default,
 )
 
 /**
@@ -70,7 +82,7 @@ async function runCommand<E>(
 			Effect.either,
 		),
 	)
-	if (Either.isLeft(result)) throw toError(result.left)
+	if (Either.isLeft(result)) throw result.left
 }
 
 // Read version from package.json
@@ -191,6 +203,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 +324,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
@@ -323,13 +352,19 @@ For more information about a command, run:
 	`)
 }
 
+const machineMode = process.argv.slice(2).includes("--json")
+
 try {
 	const args = process.argv.slice(2)
 	const { commandName, args: commandArgs, values } = parseCli(args)
 
 	// Handle global flags
 	if (values.version) {
-		console.log(`v${VERSION}`)
+		if (machineMode) {
+			writeEnvelope(successEnvelope({ version: VERSION }))
+		} else {
+			console.log(`v${VERSION}`)
+		}
 		process.exit(0)
 	}
 
@@ -342,9 +377,22 @@ try {
 
 	const command = commands[commandName]!
 	const inputAllowed =
-		!values["no-input"] && Boolean(process.stdin.isTTY && process.stderr.isTTY)
-	await command.run(commandArgs, { ...values, inputAllowed })
+		!values.json &&
+		!values["no-input"] &&
+		Boolean(process.stdin.isTTY && process.stderr.isTTY)
+	if (values.json) {
+		const result = await collectCommandResult(() =>
+			command.run(commandArgs, { ...values, inputAllowed }),
+		)
+		writeEnvelope(successEnvelope(result))
+	} else {
+		await command.run(commandArgs, { ...values, inputAllowed })
+	}
 } catch (error) {
+	if (machineMode) {
+		writeEnvelope(errorEnvelope(error))
+		process.exit(1)
+	}
 	if (error instanceof Error) {
 		let message = error.message
 

package/fixtures/protocol/error.json

@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "ok": false,
+  "error": {
+    "code": "CLI_USAGE",
+    "message": "Unknown command 'unknown'.\n\nUsage: agency <command> [options]",
+    "fields": {
+      "detail": "Unknown command 'unknown'.",
+      "usage": "agency <command> [options]"
+    },
+    "retryable": false,
+    "remediation": "Correct the arguments using the usage value in error.fields."
+  }
+}

package/fixtures/protocol/success.json

@@ -0,0 +1,7 @@
+{
+  "version": 1,
+  "ok": true,
+  "result": {
+    "root": "/work/agency"
+  }
+}

package/index.ts

@@ -1 +1,2 @@
 export * from "./src/workbase/schemas"
+export * from "./src/protocol"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "2.7.3",
+  "version": "2.9.0",
   "description": "Manage agentic work across repositories with durable workbases",
   "keywords": [
     "agents",
@@ -21,6 +21,8 @@
     "index.ts",
     "cli.ts",
     "src",
+    "schemas",
+    "fixtures/protocol",
     "skills",
     "README.md",
     "LICENSE"
@@ -31,6 +33,19 @@
     ".": {
       "types": "./index.ts",
       "import": "./index.ts"
+    },
+    "./protocol": {
+      "types": "./src/protocol.ts",
+      "import": "./src/protocol.ts"
+    },
+    "./schemas/agency-envelope-v1.json": {
+      "default": "./schemas/agency-envelope-v1.schema.json"
+    },
+    "./fixtures/protocol/success.json": {
+      "default": "./fixtures/protocol/success.json"
+    },
+    "./fixtures/protocol/error.json": {
+      "default": "./fixtures/protocol/error.json"
     }
   },
   "publishConfig": {

package/schemas/agency-envelope-v1.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/markjaquith/agency/schemas/agency-envelope-v1.schema.json",
+  "title": "Agency machine result envelope v1",
+  "oneOf": [
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["version", "ok", "result"],
+      "properties": {
+        "version": { "const": 1 },
+        "ok": { "const": true },
+        "result": true
+      }
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["version", "ok", "error"],
+      "properties": {
+        "version": { "const": 1 },
+        "ok": { "const": false },
+        "error": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["code", "message", "fields", "retryable"],
+          "properties": {
+            "code": { "type": "string" },
+            "message": { "type": "string" },
+            "fields": { "type": "object" },
+            "retryable": { "type": "boolean" },
+            "remediation": { "type": "string" }
+          }
+        }
+      }
+    }
+  ]
+}

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,
@@ -345,8 +363,20 @@ export interface ParsedCli {
 	>
 }
 
+class CliUsageError extends Error {
+	readonly _tag = "CliUsageError"
+
+	constructor(
+		readonly detail: string,
+		readonly usage: string,
+	) {
+		super(`${detail}\n\nUsage: ${usage}`)
+		this.name = "CliUsageError"
+	}
+}
+
 const usageError = (message: string, usage: string) =>
-	new Error(`${message}\n\nUsage: ${usage}`)
+	new CliUsageError(message, usage)
 
 const optionLabel = (name: string) => `--${name}`
 

package/src/cli.test.ts

@@ -34,7 +34,9 @@ async function runCli(
 function parseJson(result: CliResult) {
 	expect(result.exitCode).toBe(0)
 	expect(result.stderr).toBe("")
-	return JSON.parse(result.stdout)
+	const envelope = JSON.parse(result.stdout)
+	expect(envelope).toMatchObject({ version: 1, ok: true })
+	return envelope.result
 }
 
 describe("CLI", () => {
@@ -79,6 +81,46 @@ describe("CLI", () => {
 		expect(taggedError.stderr).not.toContain("An error has occurred")
 	})
 
+	test("emits one versioned error envelope for usage and command failures", async () => {
+		const usage = await runCli(["unknown", "--json"])
+		expect(usage.exitCode).toBe(1)
+		expect(usage.stderr).toBe("")
+		expect(usage.stdout.trim().split("\n")).toHaveLength(1)
+		expect(JSON.parse(usage.stdout)).toEqual({
+			version: 1,
+			ok: false,
+			error: {
+				code: "CLI_USAGE",
+				message:
+					"Unknown command 'unknown'.\n\nUsage: agency <command> [options]",
+				fields: {
+					detail: "Unknown command 'unknown'.",
+					usage: "agency <command> [options]",
+				},
+				retryable: false,
+				remediation:
+					"Correct the arguments using the usage value in error.fields.",
+			},
+		})
+
+		const cwd = await createTempDir()
+		tempDirs.push(cwd)
+		const commandFailure = await runCli(
+			["repo", "list", "--json", "--silent"],
+			cwd,
+		)
+		expect(commandFailure.exitCode).toBe(1)
+		expect(commandFailure.stderr).toBe("")
+		expect(JSON.parse(commandFailure.stdout)).toMatchObject({
+			version: 1,
+			ok: false,
+			error: {
+				code: "WORKBASE_NOT_FOUND",
+				retryable: false,
+			},
+		})
+	})
+
 	test("rejects malformed input before running a command", async () => {
 		const parent = await createTempDir()
 		tempDirs.push(parent)
@@ -106,6 +148,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 +179,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)
@@ -155,6 +220,30 @@ describe("CLI", () => {
 		).toEqual([await realpath(root)])
 	})
 
+	test("lets JSON override silent and disables interactive task input", async () => {
+		const root = await createTempDir()
+		tempDirs.push(root)
+		const result = await runCli(["init", root, "--json", "--silent"])
+		expect(parseJson(result)).toEqual({ root })
+
+		const interactive = await runCli(["task", "new", "--json"])
+		expect(interactive.exitCode).toBe(1)
+		expect(interactive.stderr).toBe("")
+		expect(JSON.parse(interactive.stdout)).toMatchObject({
+			version: 1,
+			ok: false,
+			error: { code: "COMMAND_FAILED", retryable: false },
+		})
+	})
+
+	test("envelopes help and version output in machine mode", async () => {
+		const help = await runCli(["status", "--help", "--json"])
+		expect(parseJson(help)).toContain("Usage: agency status")
+
+		const version = await runCli(["status", "--version", "--json"])
+		expect(parseJson(version)).toEqual({ version: "0.0.0-development" })
+	})
+
 	test("runs a multi-phase domain workflow through subprocesses", 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
+`