@markjaquith/agency 2.17.0 → 2.19.0

package/README.md

@@ -342,8 +342,11 @@ conditions remain visible in `warnings` or `unresolved` with a suggested action.
 
 ```text
 agency init [path] [--json]
-agency workbase add <path> [--json]
+agency workbase add <path> [--name <name>] [--json]
 agency workbase list [--json]
+agency workbase remove <id|name|path> [--json]
+agency workbase prune [--json]
+agency workbase default [<id|name> | --clear] [--json]
 agency integration status [--json]
 agency integration sync [--json]
 agency repo add <alias> <remote> [--json]
@@ -353,6 +356,9 @@ agency repo list [--json]
 
 Registered workbases are stored in
 `$XDG_CONFIG_HOME/agency/workbases.json` (or `~/.config/agency/workbases.json`).
+Each registration has a stable ID and may have a unique name. A default workbase
+is used when the current directory is outside every workbase. `prune` removes
+registrations whose workbase configuration no longer exists.
 `repo add` creates a bare clone. `repo link` creates a symlink to an existing Git
 repository. Alias names are then used by all documents and commands.
 
@@ -365,7 +371,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]
 ```
 
@@ -404,14 +410,22 @@ agency task create <id> --multi-phase
 
 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.
+Commands with explicit inputs continue normally. `--workbase <id|name|path>`
+selects a workbase directly; `--cwd <path>` performs the same inference Agency
+would perform from that directory. These options are mutually exclusive and take
+precedence over ambient cwd and the configured default.
+
+Targeted commands accept `--epic`, `--task`, and `--phase` where those entity
+kinds apply. A phase selector requires a task selector. Entity selectors cannot
+be mixed with positional target IDs, and an epic selector cannot be mixed with
+task or phase selectors. This makes commands such as
+`agency phase status done --task ship --phase release --workbase primary --no-input`
+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]
 ```
@@ -438,7 +452,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]
 ```
@@ -456,6 +470,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
@@ -541,7 +562,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

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 
 import { Effect, Either, Layer } from "effect"
+import { join, resolve } from "node:path"
 import { parseCli } from "./src/cli-parser"
 import { init, help as initHelp } from "./src/commands/init"
 import { task, help as taskHelp } from "./src/commands/task"
@@ -72,11 +73,9 @@ const CliLayer = Layer.mergeAll(
 /**
  * Run a command Effect with all services provided
  */
-async function runCommand<E>(
-	effect: Effect.Effect<void, E, any>,
-): Promise<void> {
+async function runEffect<A, E>(effect: Effect.Effect<A, E, any>): Promise<A> {
 	const providedEffect = Effect.provide(effect, CliLayer) as Effect.Effect<
-		void,
+		A,
 		E,
 		never
 	>
@@ -103,8 +102,44 @@ async function runCommand<E>(
 		),
 	)
 	if (Either.isLeft(result)) throw result.left
+	return result.right
 }
 
+const runCommand = <E>(effect: Effect.Effect<void, E, any>) => runEffect(effect)
+
+const resolveInvocationCwd = (
+	commandName: string,
+	options: Record<string, any>,
+) =>
+	runEffect(
+		Effect.gen(function* () {
+			if (
+				options.help ||
+				commandName === "init" ||
+				commandName === "workbase"
+			) {
+				return resolve(options.cwd ?? process.cwd())
+			}
+			const workbases = yield* WorkbaseService
+			if (options.workbase) {
+				return yield* workbases.resolveRegistered(options.workbase)
+			}
+			if (options.cwd) {
+				const selectedCwd = resolve(options.cwd)
+				yield* workbases.discover(selectedCwd)
+				return selectedCwd
+			}
+			return yield* workbases.discover(process.cwd()).pipe(
+				Effect.as(process.cwd()),
+				Effect.catchTag("WorkbaseNotFoundError", () =>
+					workbases
+						.getDefault()
+						.pipe(Effect.map((entry) => entry?.path ?? process.cwd())),
+				),
+			)
+		}),
+	)
+
 // Read version from package.json
 const packageJson = await Bun.file(
 	new URL("./package.json", import.meta.url),
@@ -129,6 +164,7 @@ const commands: Record<string, Command> = {
 					json: options.json,
 					silent: options.silent,
 					verbose: options.verbose,
+					cwd: options.cwd,
 				}),
 			)
 		},
@@ -146,6 +182,7 @@ const commands: Record<string, Command> = {
 					json: options.json,
 					silent: options.silent,
 					verbose: options.verbose,
+					cwd: options.cwd,
 				}),
 			)
 		},
@@ -164,6 +201,7 @@ const commands: Record<string, Command> = {
 					json: options.json,
 					silent: options.silent,
 					verbose: options.verbose,
+					cwd: options.cwd,
 				}),
 			)
 		},
@@ -180,6 +218,7 @@ const commands: Record<string, Command> = {
 					json: options.json,
 					silent: options.silent,
 					verbose: options.verbose,
+					cwd: options.cwd,
 				}),
 			)
 		},
@@ -198,8 +237,14 @@ 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,
 				}),
 			)
 		},
@@ -220,6 +265,7 @@ const commands: Record<string, Command> = {
 					json: options.json,
 					silent: options.silent,
 					verbose: options.verbose,
+					cwd: options.cwd,
 				}),
 			)
 		},
@@ -239,8 +285,14 @@ 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,
 				}),
 			)
 		},
@@ -258,6 +310,7 @@ const commands: Record<string, Command> = {
 					json: options.json,
 					silent: options.silent,
 					verbose: options.verbose,
+					cwd: options.cwd,
 				}),
 			)
 		},
@@ -273,8 +326,11 @@ const commands: Record<string, Command> = {
 					subcommand: args[0],
 					args: args.slice(1),
 					json: options.json,
+					name: options.name,
+					clear: options.clear,
 					silent: options.silent,
 					verbose: options.verbose,
+					cwd: options.cwd,
 				}),
 			)
 		},
@@ -291,6 +347,7 @@ const commands: Record<string, Command> = {
 					json: options.json,
 					silent: options.silent,
 					verbose: options.verbose,
+					cwd: options.cwd,
 				}),
 			)
 		},
@@ -308,6 +365,7 @@ const commands: Record<string, Command> = {
 					silent: options.silent,
 					verbose: options.verbose,
 					json: options.json,
+					cwd: options.cwd,
 				}),
 			)
 		},
@@ -331,9 +389,15 @@ 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,
+					cwd: options.cwd,
 				}),
 			)
 		},
@@ -357,6 +421,9 @@ const commands: Record<string, Command> = {
 					claude: options.claude,
 					force: options.force,
 					inputAllowed: options.inputAllowed,
+					cwd: options.cwd,
+					taskId: options.task,
+					phaseId: options.phase,
 				}),
 			)
 		},
@@ -385,6 +452,12 @@ 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,
 				}),
 			)
 		},
@@ -402,6 +475,7 @@ const commands: Record<string, Command> = {
 					verbose: options.verbose,
 					json: options.json,
 					inputAllowed: options.inputAllowed,
+					cwd: options.cwd,
 				}),
 			)
 		},
@@ -414,11 +488,18 @@ const commands: Record<string, Command> = {
 			}
 			await runCommand(
 				context({
-					target: args[0],
+					target: options.epic
+						? join("epics", options.epic)
+						: options.phase
+							? join("tasks", options.task, "phases", options.phase)
+							: options.task
+								? join("tasks", options.task)
+								: args[0],
 					compact: options.compact,
 					json: options.json,
 					silent: options.silent,
 					verbose: options.verbose,
+					cwd: options.cwd,
 				}),
 			)
 		},
@@ -441,6 +522,7 @@ const commands: Record<string, Command> = {
 					include: options.include,
 					silent: options.silent,
 					verbose: options.verbose,
+					cwd: options.cwd,
 				}),
 			)
 		},
@@ -458,6 +540,7 @@ const commands: Record<string, Command> = {
 					json: options.json,
 					silent: options.silent,
 					verbose: options.verbose,
+					cwd: options.cwd,
 				}),
 			)
 		},
@@ -497,6 +580,8 @@ Global Options:
   -s, --silent           Suppress output messages
   -v, --verbose          Show verbose output including detailed debugging info
   --no-input             Never open an interactive prompt or selector
+  --workbase <selector>  Use a registered workbase ID, name, or path
+  --cwd <path>           Resolve context from this directory
 
 Examples:
   agency init                         # Initialize the current directory
@@ -538,15 +623,16 @@ try {
 		!values.json &&
 		!values["no-input"] &&
 		Boolean(process.stdin.isTTY && process.stderr.isTTY)
+	const cwd = await resolveInvocationCwd(commandName, values)
 	if (values.json || (values.jsonl && values.help)) {
 		const result = await collectCommandResult(() =>
-			command.run(commandArgs, { ...values, inputAllowed }),
+			command.run(commandArgs, { ...values, cwd, inputAllowed }),
 		)
 		writeEnvelope(successEnvelope(result))
 	} else if (values.jsonl) {
-		await command.run(commandArgs, { ...values, inputAllowed: false })
+		await command.run(commandArgs, { ...values, cwd, inputAllowed: false })
 	} else {
-		await command.run(commandArgs, { ...values, inputAllowed })
+		await command.run(commandArgs, { ...values, cwd, inputAllowed })
 	}
 } catch (error) {
 	if (machineMode) {

package/package.json

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

package/skills/agency/SKILL.md

@@ -60,13 +60,19 @@ agency init [path]
 agency integration sync
 ```
 
-Register known workbases so `agency work` can select one when run elsewhere:
+Register and name known workbases so commands can select one from anywhere:
 
 ```bash
-agency workbase add <path>
+agency workbase add <path> [--name <name>]
 agency workbase list
+agency workbase default [<id|name> | --clear]
+agency workbase remove <id|name|path>
+agency workbase prune
 ```
 
+Use `--workbase <id|name|path>` to bypass cwd inference, or `--cwd <path>` to
+infer context from a specific directory. The options are mutually exclusive.
+
 ## Repository Aliases
 
 Add a remote as an Agency-managed bare repository:
@@ -261,8 +267,8 @@ Use `--json` when diagnostics will be consumed programmatically. Resolve all
 validation errors before materializing worktrees or creating PRs. Validation
 checks schemas, aliases, backlinks, phase directories, duplicate references,
 duplicate writable branch ownership, unknown dependencies, and dependency cycles.
-Outside a workbase, omitting path opens the registered-workbase picker.
-With `--no-input` or without a TTY, pass a path or run from a workbase instead.
+Outside a workbase, Agency uses the configured default or opens the registered
+workbase picker. With `--no-input` or without a TTY, pass `--workbase` or `--cwd`.
 
 ## Worktrees And Agent Launch
 
@@ -270,6 +276,7 @@ With `--no-input` or without a TTY, pass a path or run from a workbase instead.
 agency work
 agency work <directory>
 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
@@ -278,8 +285,8 @@ replaces the current process with the selected agent. With no directory it opens
 an `fzf` picker containing the workbase hierarchy. Pass `.`, or another
 directory, to infer the nearest epic, task, or phase.
 Outside a workbase, it first opens a picker containing registered workbases.
-With `--no-input` or without a TTY, run from a workbase and provide an explicit
-directory, task ID, or `--epic` so no picker is needed.
+With `--no-input` or without a TTY, provide an explicit workbase or cwd and an
+`--epic`, `--task`, or `--task` plus `--phase` selector so no picker is needed.
 
 Epic and multi-phase task targets are orchestration sessions launched beside
 their documents. Single-phase tasks and phases are execution sessions launched

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"],
@@ -384,6 +419,80 @@ describe("strict CLI parsing", () => {
 		).toBe(true)
 	})
 
+	test("normalizes explicit entity selectors into command targets", () => {
+		expect(
+			parseCli([
+				"phase",
+				"status",
+				"done",
+				"--task",
+				"ship",
+				"--phase",
+				"release",
+			]),
+		).toMatchObject({
+			commandName: "phase",
+			args: ["status", "ship", "release", "done"],
+		})
+		expect(
+			parseCli([
+				"claim",
+				"--task",
+				"ship",
+				"--phase",
+				"release",
+				"--claimant",
+				"agent",
+				"--runner",
+				"opencode",
+				"--session-id",
+				"session",
+				"--revision",
+				"0".repeat(64),
+			]),
+		).toMatchObject({ args: ["ship", "release"] })
+		expect(parseCli(["context", "--epic", "delivery"]).values.epic).toBe(
+			"delivery",
+		)
+	})
+
+	test("enforces explicit selector precedence and exclusions", () => {
+		expect(() =>
+			parseCli(["task", "show", "positional", "--task", "explicit"]),
+		).toThrow("cannot be combined with positional target IDs")
+		expect(() => parseCli(["context", "--phase", "release"])).toThrow(
+			"--phase' requires '--task",
+		)
+		expect(() =>
+			parseCli(["work", "--epic", "delivery", "--task", "ship"]),
+		).toThrow("cannot be combined with '--task'")
+		expect(() =>
+			parseCli(["status", "--workbase", "primary", "--cwd", "/tmp"]),
+		).toThrow("--workbase' and '--cwd' cannot be combined")
+	})
+
+	test("accepts explicit workbase context before or after commands", () => {
+		expect(
+			parseCli(["--workbase", "primary", "task", "list", "--no-input"]).values
+				.workbase,
+		).toBe("primary")
+		expect(parseCli(["status", "--cwd", "/tmp"]).values.cwd).toBe("/tmp")
+		expect(
+			parseCli(["--workbase=primary", "task", "list"]).values.workbase,
+		).toBe("primary")
+		expect(parseCli(["--cwd=/tmp", "status"]).values.cwd).toBe("/tmp")
+	})
+
+	test("rejects empty selectors", () => {
+		for (const args of [
+			["status", "--workbase="],
+			["status", "--cwd="],
+			["context", "--task="],
+		]) {
+			expect(() => parseCli(args)).toThrow("requires a non-empty value")
+		}
+	})
+
 	test("accepts grouped global short options before a command", () => {
 		const parsed = parseCli(["-sh", "task"])
 		expect(parsed.values).toMatchObject({ silent: true, help: true })