@markjaquith/agency 2.18.0 → 2.20.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
@@ -371,7 +406,7 @@ status, validation, graph export, reconciliation, and PR creation.
 ```text
 agency epic create <id> --ticket-url <url> [--description <text>] [--json]
   --repo <alias>:<ref> [--repo <alias>:<ref>...]
-agency epic list [--json]
+agency epic list [filters] [--json]
 agency epic show <id> [--json]
 ```
 
@@ -425,7 +460,7 @@ fully independent of process cwd and prompts.
 Inspect tasks:
 
 ```text
-agency task list [--json]
+agency task list [filters] [--json]
 agency task show <id> [--json]
 agency task status <id> <open|done|dropped> [--json]
 ```
@@ -452,7 +487,7 @@ agency phase create <task-id> <phase-id>
   [--description <text>] [--reference <alias>:<ref>...]
   [--depends-on <phase-id>...] [--first-phase <phase-id>] [--json]
 
-agency phase list <task-id> [--json]
+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]
 ```
@@ -470,6 +505,13 @@ work before changing its outcome.
 Delegation is now explicit: the claimant identifies the orchestrator and the
 runner identifies the assigned agent.
 
+Human list output is a compact table with lifecycle, readiness, parent,
+repository, branch, recorded PR, and worktree state where applicable. List and
+status views accept composable `--status <status>` and `--repository <alias>`
+filters, plus `--ready`, `--blocked`, `--pr`, and `--no-pr`. Status and repository
+filters are repeatable. Rows follow task and phase declaration order; plain text
+labels remain complete without color or icon fonts.
+
 ### Claims
 
 Claim mutations require the SHA-256 revision exposed by `agency context` or
@@ -493,9 +535,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
 
@@ -513,7 +555,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]
 ```
@@ -524,6 +566,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,
@@ -555,7 +601,7 @@ the owning `TASK.md` or `PHASE.md`.
 ### Status and Validation
 
 ```text
-agency status [--json]
+agency status [filters] [--json]
 agency validate [path] [--json]
 ```
 

package/cli.ts

@@ -237,6 +237,11 @@ const commands: Record<string, Command> = {
 					description: options.description,
 					repos: options.repo,
 					json: options.json,
+					statuses: options.status,
+					repositories: options.repository,
+					ready: options.ready,
+					blocked: options.blocked,
+					pr: options.pr ? true : options["no-pr"] ? false : undefined,
 					silent: options.silent,
 					verbose: options.verbose,
 					cwd: options.cwd,
@@ -280,6 +285,11 @@ const commands: Record<string, Command> = {
 					dependsOn: options["depends-on"],
 					firstPhase: options["first-phase"],
 					json: options.json,
+					statuses: options.status,
+					repositories: options.repository,
+					ready: options.ready,
+					blocked: options.blocked,
+					pr: options.pr ? true : options["no-pr"] ? false : undefined,
 					silent: options.silent,
 					verbose: options.verbose,
 					cwd: options.cwd,
@@ -379,6 +389,11 @@ const commands: Record<string, Command> = {
 					base: options.base,
 					multiPhase: options["multi-phase"],
 					json: options.json,
+					statuses: options.status,
+					repositories: options.repository,
+					ready: options.ready,
+					blocked: options.blocked,
+					pr: options.pr ? true : options["no-pr"] ? false : undefined,
 					silent: options.silent,
 					verbose: options.verbose,
 					inputAllowed: options.inputAllowed,
@@ -404,6 +419,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,
@@ -437,6 +454,11 @@ const commands: Record<string, Command> = {
 					silent: options.silent,
 					verbose: options.verbose,
 					json: options.json,
+					statuses: options.status,
+					repositories: options.repository,
+					ready: options.ready,
+					blocked: options.blocked,
+					pr: options.pr ? true : options["no-pr"] ? false : undefined,
 					cwd: options.cwd,
 				}),
 			)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "2.18.0",
+  "version": "2.20.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

@@ -10,9 +10,9 @@ describe("strict CLI parsing", () => {
 		expectUsageError(["task", "list", "--josn"], "agency task")
 		expectUsageError(
 			["task", "list", "--repo", "agency"],
-			"agency task list [--json]",
+			"agency task list [filters] [--json]",
 		)
-		expectUsageError(["status", "--draft"], "agency status [--json]")
+		expectUsageError(["status", "--draft"], "agency status [filters] [--json]")
 	})
 
 	test("rejects duplicate scalar, boolean, and single-value multiple options", () => {
@@ -77,6 +77,41 @@ describe("strict CLI parsing", () => {
 		})
 	})
 
+	test("parses composable view filters", () => {
+		expect(
+			parseCli([
+				"task",
+				"list",
+				"--status",
+				"open",
+				"--status",
+				"working",
+				"--repository",
+				"agency",
+				"--ready",
+				"--pr",
+			]).values,
+		).toMatchObject({
+			status: ["open", "working"],
+			repository: ["agency"],
+			ready: true,
+			pr: true,
+		})
+		expect(parseCli(["status", "--no-pr"]).values["no-pr"]).toBe(true)
+	})
+
+	test("validates view filter values and conflicts", () => {
+		expect(() => parseCli(["epic", "list", "--status", "invalid"])).toThrow(
+			"Invalid '--status' value",
+		)
+		expect(() =>
+			parseCli(["phase", "list", "task", "--ready", "--blocked"]),
+		).toThrow("cannot be combined")
+		expect(() => parseCli(["status", "--pr", "--no-pr"])).toThrow(
+			"cannot be combined",
+		)
+	})
+
 	test("enforces exact maximum positional arity for every leaf command", () => {
 		for (const [args, usage] of [
 			[["init", "one", "two"], "agency init"],
@@ -286,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([

package/src/cli-parser.ts

@@ -40,6 +40,29 @@ const outputOptions = {
 	json: { type: "boolean" },
 } satisfies OptionConfig
 
+const viewOptions = {
+	status: { type: "string", multiple: true },
+	repository: { type: "string", multiple: true },
+	ready: { type: "boolean" },
+	blocked: { type: "boolean" },
+	pr: { type: "boolean" },
+	"no-pr": { type: "boolean" },
+} satisfies OptionConfig
+
+const viewOptionNames = [
+	"status",
+	"repository",
+	"ready",
+	"blocked",
+	"pr",
+	"no-pr",
+] as const
+
+const viewConflicts = [
+	["ready", "blocked"],
+	["pr", "no-pr"],
+] as const
+
 const createOptions = {
 	...outputOptions,
 	"ticket-url": { type: "string" },
@@ -178,7 +201,7 @@ const commands = {
 	},
 	epic: {
 		usage: "agency epic <create|list|show>",
-		options: { ...createOptions, epic: { type: "string" } },
+		options: { ...createOptions, ...viewOptions, epic: { type: "string" } },
 		subcommands: {
 			create: {
 				usage:
@@ -190,10 +213,12 @@ const commands = {
 				repeatable: ["repo"],
 			},
 			list: {
-				usage: "agency epic list [--json]",
+				usage: "agency epic list [filters] [--json]",
 				minArgs: 0,
 				maxArgs: 0,
-				options: ["json"],
+				options: ["json", ...viewOptionNames],
+				repeatable: ["status", "repository"],
+				conflicts: viewConflicts,
 			},
 			show: {
 				usage: "agency epic show <id> [--json]",
@@ -205,7 +230,7 @@ const commands = {
 	},
 	task: {
 		usage: "agency task <new|create|list|show|status>",
-		options: { ...taskCreateOptions, task: { type: "string" } },
+		options: { ...taskCreateOptions, ...viewOptions, task: { type: "string" } },
 		subcommands: {
 			new: {
 				usage: "agency task new [id] [options]",
@@ -243,10 +268,12 @@ const commands = {
 				repeatable: ["reference"],
 			},
 			list: {
-				usage: "agency task list [--json]",
+				usage: "agency task list [filters] [--json]",
 				minArgs: 0,
 				maxArgs: 0,
-				options: ["json"],
+				options: ["json", ...viewOptionNames],
+				repeatable: ["status", "repository"],
+				conflicts: viewConflicts,
 			},
 			show: {
 				usage: "agency task show <id> [--json]",
@@ -266,6 +293,7 @@ const commands = {
 		usage: "agency phase <create|list|show|status>",
 		options: {
 			...phaseCreateOptions,
+			...viewOptions,
 			task: { type: "string" },
 			phase: { type: "string" },
 		},
@@ -291,10 +319,12 @@ const commands = {
 				repeatable: ["reference", "depends-on"],
 			},
 			list: {
-				usage: "agency phase list <task-id> [--json]",
+				usage: "agency phase list <task-id> [filters] [--json]",
 				minArgs: 1,
 				maxArgs: 1,
-				options: ["json", "task"],
+				options: ["json", "task", ...viewOptionNames],
+				repeatable: ["status", "repository"],
+				conflicts: viewConflicts,
 			},
 			show: {
 				usage: "agency phase show <task-id> <phase-id> [--json]",
@@ -409,19 +439,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: [
@@ -430,12 +462,16 @@ const commands = {
 				"epic",
 				"task",
 				"phase",
+				"runner",
+				"print-command",
 				"opencode",
 				"claude",
 				"force",
 			],
 			conflicts: [
 				["opencode", "claude"],
+				["runner", "opencode"],
+				["runner", "claude"],
 				["epic", "$positional"],
 			],
 		},
@@ -473,13 +509,15 @@ const commands = {
 		},
 	},
 	status: {
-		usage: "agency status [--json]",
-		options: outputOptions,
+		usage: "agency status [filters] [--json]",
+		options: { ...outputOptions, ...viewOptions },
 		command: {
-			usage: "agency status [--json]",
+			usage: "agency status [filters] [--json]",
 			minArgs: 0,
 			maxArgs: 0,
-			options: ["json"],
+			options: ["json", ...viewOptionNames],
+			repeatable: ["status", "repository"],
+			conflicts: viewConflicts,
 		},
 	},
 	validate: {
@@ -772,6 +810,24 @@ function validateGraphOptions(values: ParsedCli["values"], spec: LeafCommand) {
 	}
 }
 
+function validateViewOptions(values: ParsedCli["values"], spec: LeafCommand) {
+	const supplied = values.status
+	const statuses = Array.isArray(supplied)
+		? supplied
+		: supplied === undefined
+			? []
+			: [supplied]
+	const accepted = new Set(["open", "working", "delegated", "done", "dropped"])
+	for (const status of statuses) {
+		if (typeof status !== "string" || !accepted.has(status)) {
+			throw usageError(
+				`Invalid '--status' value '${String(status)}'. Expected one of: ${[...accepted].join(", ")}.`,
+				spec.usage,
+			)
+		}
+	}
+}
+
 export function parseCli(args: readonly string[]): ParsedCli {
 	const commandIndex = findCommandIndex(args)
 	if (commandIndex === -1) {
@@ -924,6 +980,12 @@ export function parseCli(args: readonly string[]): ParsedCli {
 	if (commandName === "graph") {
 		validateGraphOptions(parsed.values, spec)
 	}
+	if (
+		commandName === "status" ||
+		(["epic", "task", "phase"].includes(commandName) && subcommand === "list")
+	) {
+		validateViewOptions(parsed.values, spec)
+	}
 	if (
 		commandName === "finish" &&
 		parsed.values.outcome !== "done" &&
@@ -942,6 +1004,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

@@ -774,10 +774,20 @@ status: open
 			await runCli(["phase", "list", "ship", "--json"], root),
 		)
 		expect(phaseList.map((phase: { id: string }) => phase.id)).toEqual([
-			"implement",
 			"prepare",
+			"implement",
 			"release",
 		])
+		const phaseTable = await runCli(
+			["phase", "list", "ship", "--repository", "agency", "--no-pr"],
+			root,
+		)
+		expect(phaseTable.stdout).toMatch(
+			/PHASE\s+PARENT\s+STATUS\s+READINESS\s+REPOSITORIES\s+BRANCH/,
+		)
+		expect(phaseTable.stdout.indexOf("prepare")).toBeLessThan(
+			phaseTable.stdout.indexOf("implement"),
+		)
 
 		const phaseShow = parseJson(
 			await runCli(["phase", "show", "ship", "release", "--json"], root),

package/src/commands/epic.test.ts

@@ -100,4 +100,26 @@ describe("epic command", () => {
 			},
 		})
 	})
+
+	test("renders a readable operational table", async () => {
+		await runTestEffect(
+			epic({
+				subcommand: "create",
+				args: ["example"],
+				ticketUrl: "https://example.com/epic",
+				repos: ["agency:main"],
+				cwd: root,
+				silent: true,
+			}),
+		)
+
+		const logs = await captureLogs(() =>
+			runTestEffect(epic({ subcommand: "list", args: [], cwd: root })),
+		)
+		expect(logs[0]).toContain(
+			"EPIC     STATUS  READINESS  REPOSITORIES  PR  WORKTREE",
+		)
+		expect(logs[0]).toContain("example  open    waiting    agency")
+		expect(logs[0]).not.toMatch(/[\u{e000}-\u{f8ff}]/u)
+	})
 })

package/src/commands/epic.ts

@@ -2,6 +2,8 @@ import { Effect } from "effect"
 import type { BaseCommandOptions } from "../utils/command"
 import { EpicService } from "../services/EpicService"
 import { createLoggers } from "../utils/effect"
+import { formatTable } from "../utils/table"
+import { getWorkViews } from "../work-view"
 import { parseRepositoryReferences } from "../workbase/repository-reference"
 
 interface EpicOptions extends BaseCommandOptions {
@@ -11,6 +13,11 @@ interface EpicOptions extends BaseCommandOptions {
 	readonly description?: string
 	readonly repos?: readonly string[]
 	readonly json?: boolean
+	readonly statuses?: readonly string[]
+	readonly repositories?: readonly string[]
+	readonly ready?: boolean
+	readonly blocked?: boolean
+	readonly pr?: boolean
 }
 
 export const epic = (options: EpicOptions) =>
@@ -47,16 +54,40 @@ export const epic = (options: EpicOptions) =>
 
 			case "list": {
 				const records = yield* epics.list(cwd)
+				const { epicRows } = yield* getWorkViews({
+					cwd,
+					statuses: options.statuses,
+					repositories: options.repositories,
+					ready: options.ready,
+					blocked: options.blocked,
+					pr: options.pr,
+				})
+				const ordered = epicRows.flatMap((row) => {
+					const record = records.find((item) => item.id === row.key)
+					return record ? [record] : []
+				})
 				if (options.json) {
 					log(
 						JSON.stringify(
-							records.map(({ content: _, ...record }) => record),
+							ordered.map(({ content: _, ...record }) => record),
 							null,
 							2,
 						),
 					)
 				} else {
-					for (const record of records) log(record.id)
+					log(
+						formatTable(
+							["EPIC", "STATUS", "READINESS", "REPOSITORIES", "PR", "WORKTREE"],
+							epicRows.map((row) => [
+								row.id,
+								row.status,
+								row.readiness,
+								row.repositories,
+								row.pr,
+								row.worktree,
+							]),
+						),
+					)
 				}
 				return
 			}
@@ -98,4 +129,9 @@ Create options:
 
 Options:
   --json                Output results as JSON
+  --status <status>     Filter list by status; repeatable
+  --repository <alias>  Filter list by repository; repeatable
+  --ready               Include only ready epics
+  --blocked             Include only blocked epics
+  --pr / --no-pr        Filter by recorded PR presence
 `