@markjaquith/agency 2.19.0 → 2.21.0

package/README.md

@@ -10,7 +10,7 @@ or write.
 - [Bun](https://bun.sh) 1.0 or newer
 - Git
 - [GitHub CLI](https://cli.github.com/) for `agency pr create`
-- OpenCode or Claude Code for `agency work`
+- OpenCode, Claude Code, or a configured runner for `agency work`
 
 ## Installation
 
@@ -145,6 +145,41 @@ The configured command applies only to the writable checkout. Supplemental
 read-only repositories remain detached Git worktrees at their declared refs so
 they do not acquire writable branches.
 
+### Agent Runners
+
+OpenCode and Claude Code are built-in runner presets. Select either preset or a
+configured runner with `agency work --runner <name>`. A launch is fresh unless
+`AGENCY_SESSION_ID` is already set; resumed launches use the runner's
+`resumeCommand` when configured. The built-in presets use `--continue` only for
+resumed launches.
+
+Custom runners are direct argv commands, never shell snippets:
+
+```json
+{
+	"version": 2,
+	"runners": {
+		"custom": {
+			"command": ["my-agent", "--prompt", "{prompt}"],
+			"resumeCommand": ["my-agent", "resume", "{sessionId}", "{prompt}"],
+			"environment": { "MY_AGENT_TARGET": "{target}" }
+		}
+	}
+}
+```
+
+Available placeholders are `{prompt}`, `{workbase}`, `{target}`, `{task}`,
+`{phase}`, `{claimant}`, `{sessionId}`, and `{claimRevision}`. Task and phase
+placeholders are empty when they do not apply. If `resumeCommand` is omitted,
+the fresh command is also used for resumed sessions.
+
+Every runner receives the same `AGENCY_RUNNER`, `AGENCY_CLAIMANT`,
+`AGENCY_SESSION_ID`, `AGENCY_CLAIM_REVISION`, `AGENCY_WORKBASE`, `AGENCY_TARGET`,
+`AGENCY_TASK_ID`, `AGENCY_PHASE_ID`, and `AGENCY_PROMPT` environment. Configured
+environment is added without overriding these normalized values.
+`--print-command` prints the exact cwd and argv plus non-secret environment keys
+without launching the runner.
+
 ### Custom Chooser Command
 
 Interactive selection uses a native numbered chooser by default. To use an
@@ -373,6 +408,9 @@ agency epic create <id> --ticket-url <url> [--description <text>] [--json]
   --repo <alias>:<ref> [--repo <alias>:<ref>...]
 agency epic list [filters] [--json]
 agency epic show <id> [--json]
+agency epic update <id> [--ticket-url <url>] [--description <text>]
+  [--clear-description] [--repo <alias>:<ref>...] [--json]
+agency epic rename <id> <new-id> [--json]
 ```
 
 Creating a task with `--epic <id>` adds the task to the epic and writes the task
@@ -428,8 +466,18 @@ Inspect tasks:
 agency task list [filters] [--json]
 agency task show <id> [--json]
 agency task status <id> <open|done|dropped> [--json]
+agency task update <id> [metadata options] [--json]
+agency task rename <id> <new-id> [--json]
+agency task move <id> (--epic <epic-id> | --no-epic) [--json]
+agency task dependency <add|remove> <task-id> <dependency-id> [--json]
 ```
 
+Task updates can replace or clear descriptions, tickets, repository references,
+and pull request URLs, or replace writable repository, branch, and base metadata.
+Execution metadata changes refuse to run while code is materialized. Moving a
+task with scoped incoming or outgoing dependencies also refuses until those
+dependencies are removed.
+
 To add a phase to an existing single-phase task, name the phase that will own
 the task's current execution fields with `--first-phase`:
 
@@ -455,8 +503,18 @@ agency phase create <task-id> <phase-id>
 agency phase list <task-id> [filters] [--json]
 agency phase show <task-id> <phase-id> [--json]
 agency phase status <task-id> <phase-id> <open|done|dropped> [--json]
+agency phase update <task-id> <phase-id> [metadata options] [--json]
+agency phase rename <task-id> <phase-id> <new-id> [--json]
+agency phase dependency <add|remove> <task-id> <phase-id> <dependency-id>
+  [--json]
 ```
 
+Dependency additions append without reordering existing declarations and reject
+unknown IDs, self-dependencies, and cycles. Rename operations update structured
+references as one rollback-capable mutation and refuse when a materialized
+worktree would make the directory move unsafe. Mutation JSON includes changed
+paths and the focused validation scope.
+
 Single-phase tasks and phases store status in YAML. New execution units start
 `open`, and `agency work` marks the selected execution unit `working` immediately
 before launch. Use claims for coordinated ownership and the status subcommands
@@ -500,9 +558,9 @@ replaced with a revision-guarded claim.
 
 `agency work` claims an execution unit before launching its agent. Set
 `AGENCY_CLAIMANT`, `AGENCY_RUNNER`, or `AGENCY_SESSION_ID` to supply orchestrator
-identities; otherwise Agency derives them from the user, selected agent, and
-process. The launched agent receives `AGENCY_SESSION_ID` and
-`AGENCY_CLAIM_REVISION` for a later release or finish operation.
+identities; otherwise Agency derives them from the user and process. The selected
+runner name is recorded on the claim. The launched agent receives the normalized
+runner environment documented above for a later release or finish operation.
 
 ### Archive
 
@@ -520,7 +578,7 @@ before moving files, refuses dirty worktrees, and preserves branches.
 ### Work and Pull Requests
 
 ```text
-agency work [<directory> | --epic <epic-id>] [--opencode | --claude]
+agency work [<directory> | --epic <epic-id>] [--runner <name>] [--print-command]
 agency work prepare [target] [--dry-run] [--json]
 agency pr create <task-id> [phase-id] [--draft] [--json]
 ```
@@ -531,6 +589,10 @@ workbase, Agency first presents the registered workbases, then the selected
 workbase's hierarchy. If `fzf` is not installed, Agency prints the available
 choices and asks for an explicit directory.
 
+OpenCode is the default runner, with automatic Claude fallback when neither is
+explicitly selected. `--opencode` and `--claude` remain aliases for requiring
+their built-in presets.
+
 `agency work prepare` resolves an execution unit and creates or reuses its
 writable and reference worktrees without launching an agent or changing status.
 Its JSON result includes document and checkout paths, resolved commits, actions,

package/cli.ts

@@ -38,6 +38,7 @@ import { GraphService } from "./src/services/GraphService"
 import { ClaimService } from "./src/services/ClaimService"
 import { SyncService } from "./src/services/SyncService"
 import { ReadinessService } from "./src/services/ReadinessService"
+import { GraphMutationService } from "./src/services/GraphMutationService"
 import {
 	claimCommand,
 	claimHelp,
@@ -68,6 +69,7 @@ const CliLayer = Layer.mergeAll(
 	ClaimService.Default,
 	SyncService.Default,
 	ReadinessService.Default,
+	GraphMutationService.Default,
 )
 
 /**
@@ -235,6 +237,7 @@ const commands: Record<string, Command> = {
 					args: args.slice(1),
 					ticketUrl: options["ticket-url"],
 					description: options.description,
+					clearDescription: options["clear-description"],
 					repos: options.repo,
 					json: options.json,
 					statuses: options.status,
@@ -278,10 +281,14 @@ const commands: Record<string, Command> = {
 					subcommand: args[0],
 					args: args.slice(1),
 					description: options.description,
+					clearDescription: options["clear-description"],
 					repo: options.repo?.[0],
 					references: options.reference,
 					branch: options.branch,
 					base: options.base,
+					clearReferences: options["clear-references"],
+					prUrl: options["pr-url"],
+					clearPr: options["clear-pr"],
 					dependsOn: options["depends-on"],
 					firstPhase: options["first-phase"],
 					json: options.json,
@@ -381,12 +388,18 @@ const commands: Record<string, Command> = {
 					subcommand: args[0],
 					args: args.slice(1),
 					ticketUrl: options["ticket-url"],
+					clearTicket: options["clear-ticket"],
 					description: options.description,
+					clearDescription: options["clear-description"],
 					epic: options.epic,
 					repo: options.repo?.[0],
 					references: options.reference,
 					branch: options.branch,
 					base: options.base,
+					clearReferences: options["clear-references"],
+					prUrl: options["pr-url"],
+					clearPr: options["clear-pr"],
+					noEpic: options["no-epic"],
 					multiPhase: options["multi-phase"],
 					json: options.json,
 					statuses: options.status,
@@ -419,6 +432,8 @@ const commands: Record<string, Command> = {
 					verbose: options.verbose,
 					opencode: options.opencode,
 					claude: options.claude,
+					runner: options.runner,
+					printCommand: options["print-command"],
 					force: options.force,
 					inputAllowed: options.inputAllowed,
 					cwd: options.cwd,

package/package.json

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

package/skills/agency/SKILL.md

@@ -279,7 +279,10 @@ agency work --epic <epic-id>
 agency work --task <task-id> [--phase <phase-id>] --workbase <selector>
 ```
 
-Use `--opencode` or `--claude` to require a specific agent. This command fetches
+Use `--runner <name>` to select a configured runner or the built-in `opencode`
+and `claude` presets. `--opencode` and `--claude` remain shorthand. Use
+`--print-command` to inspect the resolved cwd, argv, and non-secret environment
+without launching. This command fetches
 repositories for execution targets, creates or reuses their worktrees, and
 replaces the current process with the selected agent. With no directory it opens
 an `fzf` picker containing the workbase hierarchy. Pass `.`, or another

package/src/cli-parser.test.ts

@@ -321,6 +321,22 @@ describe("strict CLI parsing", () => {
 		)
 	})
 
+	test("accepts runner selection and command inspection for work", () => {
+		expect(
+			parseCli(["work", "example", "--runner", "custom", "--print-command"]),
+		).toMatchObject({
+			commandName: "work",
+			args: ["example"],
+			values: { runner: "custom", "print-command": true },
+		})
+		expect(() =>
+			parseCli(["work", "example", "--runner", "custom", "--claude"]),
+		).toThrow("cannot be combined")
+		expect(() => parseCli(["work", "prepare", "--print-command"])).toThrow(
+			"cannot be combined",
+		)
+	})
+
 	test("accepts repeatable graph filters and rejects output conflicts", () => {
 		expect(
 			parseCli([
@@ -371,7 +387,51 @@ describe("strict CLI parsing", () => {
 		)
 		expectUsageError(
 			["task", "crate"],
-			"agency task <new|create|list|show|status>",
+			"agency task <new|create|list|show|status|update|rename|move|dependency>",
+		)
+	})
+
+	test("parses graph mutation commands and rejects unsafe ambiguity", () => {
+		expect(
+			parseCli([
+				"task",
+				"update",
+				"example",
+				"--description",
+				"Revised",
+				"--reference",
+				"docs:main",
+				"--reference",
+				"api:main",
+				"--clear-pr",
+			]),
+		).toMatchObject({
+			args: ["update", "example"],
+			values: {
+				description: "Revised",
+				reference: ["docs:main", "api:main"],
+				"clear-pr": true,
+			},
+		})
+		expect(
+			parseCli(["task", "move", "example", "--no-epic"]).values,
+		).toMatchObject({
+			"no-epic": true,
+		})
+		expect(parseCli(["phase", "rename", "task", "old", "new"]).args).toEqual([
+			"rename",
+			"task",
+			"old",
+			"new",
+		])
+		expect(() => parseCli(["task", "update", "example"])).toThrow(
+			"At least one update option",
+		)
+		expect(() =>
+			parseCli(["task", "move", "example", "--epic", "one", "--no-epic"]),
+		).toThrow("cannot be combined")
+		expect(() => parseCli(["task", "dependency", "replace", "a", "b"])).toThrow(
+			"must be 'add' or 'remove'",
 		)
 	})
 

package/src/cli-parser.ts

@@ -90,6 +90,15 @@ const phaseCreateOptions = {
 	"first-phase": { type: "string" },
 } satisfies OptionConfig
 
+const mutationOptions = {
+	"clear-description": { type: "boolean" },
+	"clear-ticket": { type: "boolean" },
+	"clear-references": { type: "boolean" },
+	"pr-url": { type: "string" },
+	"clear-pr": { type: "boolean" },
+	"no-epic": { type: "boolean" },
+} satisfies OptionConfig
+
 const claimOptions = {
 	...outputOptions,
 	claimant: { type: "string" },
@@ -200,8 +209,13 @@ const commands = {
 		},
 	},
 	epic: {
-		usage: "agency epic <create|list|show>",
-		options: { ...createOptions, ...viewOptions, epic: { type: "string" } },
+		usage: "agency epic <create|list|show|update|rename>",
+		options: {
+			...createOptions,
+			...viewOptions,
+			...mutationOptions,
+			epic: { type: "string" },
+		},
 		subcommands: {
 			create: {
 				usage:
@@ -226,11 +240,38 @@ const commands = {
 				maxArgs: 1,
 				options: ["json", "epic"],
 			},
+			update: {
+				usage: "agency epic update <id> [options] [--json]",
+				minArgs: 1,
+				maxArgs: 1,
+				options: [
+					"description",
+					"clear-description",
+					"ticket-url",
+					"repo",
+					"json",
+				],
+				repeatable: ["repo"],
+				conflicts: [["description", "clear-description"]],
+			},
+			rename: {
+				usage: "agency epic rename <id> <new-id> [--json]",
+				minArgs: 2,
+				maxArgs: 2,
+				options: ["json"],
+			},
 		},
 	},
 	task: {
-		usage: "agency task <new|create|list|show|status>",
-		options: { ...taskCreateOptions, ...viewOptions, task: { type: "string" } },
+		usage:
+			"agency task <new|create|list|show|status|update|rename|move|dependency>",
+		options: {
+			...taskCreateOptions,
+			...viewOptions,
+			...mutationOptions,
+			"pr-url": { type: "string" },
+			task: { type: "string" },
+		},
 		subcommands: {
 			new: {
 				usage: "agency task new [id] [options]",
@@ -287,13 +328,61 @@ const commands = {
 				maxArgs: 2,
 				options: ["json", "task"],
 			},
+			update: {
+				usage: "agency task update <id> [options] [--json]",
+				minArgs: 1,
+				maxArgs: 1,
+				options: [
+					"ticket-url",
+					"clear-ticket",
+					"description",
+					"clear-description",
+					"repo",
+					"reference",
+					"clear-references",
+					"branch",
+					"base",
+					"pr-url",
+					"clear-pr",
+					"json",
+				],
+				repeatable: ["reference"],
+				conflicts: [
+					["ticket-url", "clear-ticket"],
+					["description", "clear-description"],
+					["reference", "clear-references"],
+					["pr-url", "clear-pr"],
+				],
+			},
+			rename: {
+				usage: "agency task rename <id> <new-id> [--json]",
+				minArgs: 2,
+				maxArgs: 2,
+				options: ["json"],
+			},
+			move: {
+				usage: "agency task move <id> (--epic <id> | --no-epic) [--json]",
+				minArgs: 1,
+				maxArgs: 1,
+				options: ["epic", "no-epic", "json"],
+				conflicts: [["epic", "no-epic"]],
+			},
+			dependency: {
+				usage:
+					"agency task dependency <add|remove> <task-id> <dependency-id> [--json]",
+				minArgs: 3,
+				maxArgs: 3,
+				options: ["json"],
+			},
 		},
 	},
 	phase: {
-		usage: "agency phase <create|list|show|status>",
+		usage: "agency phase <create|list|show|status|update|rename|dependency>",
 		options: {
 			...phaseCreateOptions,
 			...viewOptions,
+			...mutationOptions,
+			"pr-url": { type: "string" },
 			task: { type: "string" },
 			phase: { type: "string" },
 		},
@@ -338,6 +427,42 @@ const commands = {
 				maxArgs: 3,
 				options: ["json", "task", "phase"],
 			},
+			update: {
+				usage: "agency phase update <task-id> <phase-id> [options] [--json]",
+				minArgs: 2,
+				maxArgs: 2,
+				options: [
+					"description",
+					"clear-description",
+					"repo",
+					"reference",
+					"clear-references",
+					"branch",
+					"base",
+					"pr-url",
+					"clear-pr",
+					"json",
+				],
+				repeatable: ["reference"],
+				conflicts: [
+					["description", "clear-description"],
+					["reference", "clear-references"],
+					["pr-url", "clear-pr"],
+				],
+			},
+			rename: {
+				usage: "agency phase rename <task-id> <phase-id> <new-id> [--json]",
+				minArgs: 3,
+				maxArgs: 3,
+				options: ["json"],
+			},
+			dependency: {
+				usage:
+					"agency phase dependency <add|remove> <task-id> <phase-id> <dependency-id> [--json]",
+				minArgs: 4,
+				maxArgs: 4,
+				options: ["json"],
+			},
 		},
 	},
 	claim: {
@@ -439,19 +564,21 @@ const commands = {
 	},
 	work: {
 		usage:
-			"agency work [<directory-or-task-id> | --epic <epic-id>] | agency work prepare [target] [--dry-run] [--json]",
+			"agency work [<directory-or-task-id> | --epic <epic-id>] [--runner <name>] | agency work prepare [target] [--dry-run] [--json]",
 		options: {
 			...commonOptions,
 			...entitySelectorOptions,
 			json: { type: "boolean" },
 			"dry-run": { type: "boolean" },
+			runner: { type: "string" },
+			"print-command": { type: "boolean" },
 			opencode: { type: "boolean" },
 			claude: { type: "boolean" },
 			force: { type: "boolean" },
 		},
 		command: {
 			usage:
-				"agency work [<directory-or-task-id> | --epic <epic-id>] | agency work prepare [target] [--dry-run] [--json]",
+				"agency work [<directory-or-task-id> | --epic <epic-id>] [--runner <name>] | agency work prepare [target] [--dry-run] [--json]",
 			minArgs: 0,
 			maxArgs: 2,
 			options: [
@@ -460,12 +587,16 @@ const commands = {
 				"epic",
 				"task",
 				"phase",
+				"runner",
+				"print-command",
 				"opencode",
 				"claude",
 				"force",
 			],
 			conflicts: [
 				["opencode", "claude"],
+				["runner", "opencode"],
+				["runner", "claude"],
 				["epic", "$positional"],
 			],
 		},
@@ -971,6 +1102,34 @@ export function parseCli(args: readonly string[]): ParsedCli {
 	) {
 		validateTaskCreate(parsed.values, spec, subcommand === "create")
 	}
+	if (["task", "phase"].includes(commandName) && subcommand === "dependency") {
+		if (!["add", "remove"].includes(commandPositionals[0] ?? "")) {
+			throw usageError(
+				"Dependency operation must be 'add' or 'remove'.",
+				spec.usage,
+			)
+		}
+	}
+	if (commandName === "task" && subcommand === "move") {
+		if (
+			parsed.values.epic === undefined &&
+			parsed.values["no-epic"] === undefined
+		) {
+			throw usageError(
+				"One of '--epic' or '--no-epic' is required.",
+				spec.usage,
+			)
+		}
+	}
+	if (
+		["epic", "task", "phase"].includes(commandName) &&
+		subcommand === "update"
+	) {
+		const mutationNames = (spec.options ?? []).filter((name) => name !== "json")
+		if (!mutationNames.some((name) => parsed.values[name] !== undefined)) {
+			throw usageError("At least one update option is required.", spec.usage)
+		}
+	}
 	if (commandName === "graph") {
 		validateGraphOptions(parsed.values, spec)
 	}
@@ -998,6 +1157,8 @@ export function parseCli(args: readonly string[]): ParsedCli {
 				(parsed.values.epic ||
 					parsed.values.opencode ||
 					parsed.values.claude ||
+					parsed.values.runner ||
+					parsed.values["print-command"] ||
 					parsed.values.force))
 		) {
 			throw usageError(

package/src/cli.test.ts

@@ -166,6 +166,68 @@ describe("CLI", () => {
 		expect(finished.claim).toMatchObject({ state: "finished", outcome: "done" })
 	})
 
+	test("routes graph mutations through structured output", async () => {
+		const root = await createTempDir()
+		tempDirs.push(root)
+		await Bun.write(join(root, "agency.json"), '{"version":2}\n')
+		await mkdir(join(root, "repos", "agency"), { recursive: true })
+		parseJson(
+			await runCli(
+				[
+					"epic",
+					"create",
+					"delivery",
+					"--ticket-url",
+					"https://example.com/delivery",
+					"--repo",
+					"agency:main",
+					"--json",
+				],
+				root,
+			),
+		)
+		for (const id of ["first", "second"]) {
+			parseJson(
+				await runCli(
+					[
+						"task",
+						"create",
+						id,
+						"--repo",
+						"agency",
+						"--epic",
+						"delivery",
+						"--json",
+					],
+					root,
+				),
+			)
+		}
+
+		const updated = parseJson(
+			await runCli(
+				["task", "update", "second", "--description", "Revised", "--json"],
+				root,
+			),
+		)
+		expect(updated).toMatchObject({
+			operation: "task.update",
+			entity: { kind: "task", id: "second" },
+			validation: { valid: true, scope: ["tasks/second/TASK.md"] },
+		})
+
+		const dependency = parseJson(
+			await runCli(
+				["task", "dependency", "add", "second", "first", "--json"],
+				root,
+			),
+		)
+		expect(dependency).toMatchObject({
+			operation: "task.dependency.add",
+			changedPaths: ["epics/delivery/EPIC.md"],
+		})
+	})
+
 	test("emits one versioned error envelope for usage and command failures", async () => {
 		const usage = await runCli(["unknown", "--json"])
 		expect(usage.exitCode).toBe(1)