@markjaquith/agency 2.16.0 → 2.18.0

package/README.md

@@ -304,6 +304,21 @@ inspection are opt-in include layers.
 `end` record with counts. Combining the metadata with the streamed node and edge
 records reconstructs the same result as `--json`.
 
+### Next Ready Work
+
+`agency next` lists ready execution units in descending unlock priority, with
+their epic and task context. `agency next --select` returns only the highest-
+priority ready unit in human output.
+
+`agency next --json` returns the same ranked `ready` set plus every `excluded`
+execution unit. Excluded entries retain status, terminal state, `blockedBy`, and
+detailed dependency, validation, or status blockers for orchestrators.
+
+`agency work` and `agency pr create` consult this shared readiness model before
+materializing or pushing. Blocked, done, and dropped targets are rejected unless
+`--force` is supplied explicitly. PR creation permits active `working` and
+`delegated` targets when they have no dependency or validation blocker.
+
 ### Reconciliation
 
 `agency sync` compares every execution declaration with local branch and worktree
@@ -327,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]
@@ -338,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.
 
@@ -389,9 +410,17 @@ 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:
 

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"
@@ -10,6 +11,7 @@ import { status, help as statusHelp } from "./src/commands/status"
 import { validate, help as validateHelp } from "./src/commands/validate"
 import { context, help as contextHelp } from "./src/commands/context"
 import { graph, help as graphHelp } from "./src/commands/graph"
+import { next, help as nextHelp } from "./src/commands/next"
 import { sync, help as syncHelp } from "./src/commands/sync"
 import { repo, help as repoHelp } from "./src/commands/repo"
 import { epic, help as epicHelp } from "./src/commands/epic"
@@ -35,6 +37,7 @@ import { ContextService } from "./src/services/ContextService"
 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 {
 	claimCommand,
 	claimHelp,
@@ -64,16 +67,15 @@ const CliLayer = Layer.mergeAll(
 	GraphService.Default,
 	ClaimService.Default,
 	SyncService.Default,
+	ReadinessService.Default,
 )
 
 /**
  * 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
 	>
@@ -100,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),
@@ -126,6 +164,7 @@ const commands: Record<string, Command> = {
 					json: options.json,
 					silent: options.silent,
 					verbose: options.verbose,
+					cwd: options.cwd,
 				}),
 			)
 		},
@@ -143,6 +182,7 @@ const commands: Record<string, Command> = {
 					json: options.json,
 					silent: options.silent,
 					verbose: options.verbose,
+					cwd: options.cwd,
 				}),
 			)
 		},
@@ -161,6 +201,7 @@ const commands: Record<string, Command> = {
 					json: options.json,
 					silent: options.silent,
 					verbose: options.verbose,
+					cwd: options.cwd,
 				}),
 			)
 		},
@@ -177,6 +218,7 @@ const commands: Record<string, Command> = {
 					json: options.json,
 					silent: options.silent,
 					verbose: options.verbose,
+					cwd: options.cwd,
 				}),
 			)
 		},
@@ -197,6 +239,7 @@ const commands: Record<string, Command> = {
 					json: options.json,
 					silent: options.silent,
 					verbose: options.verbose,
+					cwd: options.cwd,
 				}),
 			)
 		},
@@ -213,9 +256,11 @@ const commands: Record<string, Command> = {
 					taskId: args[1],
 					phaseId: args[2],
 					draft: options.draft,
+					force: options.force,
 					json: options.json,
 					silent: options.silent,
 					verbose: options.verbose,
+					cwd: options.cwd,
 				}),
 			)
 		},
@@ -237,6 +282,7 @@ const commands: Record<string, Command> = {
 					json: options.json,
 					silent: options.silent,
 					verbose: options.verbose,
+					cwd: options.cwd,
 				}),
 			)
 		},
@@ -254,6 +300,7 @@ const commands: Record<string, Command> = {
 					json: options.json,
 					silent: options.silent,
 					verbose: options.verbose,
+					cwd: options.cwd,
 				}),
 			)
 		},
@@ -269,8 +316,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,
 				}),
 			)
 		},
@@ -287,6 +337,7 @@ const commands: Record<string, Command> = {
 					json: options.json,
 					silent: options.silent,
 					verbose: options.verbose,
+					cwd: options.cwd,
 				}),
 			)
 		},
@@ -304,6 +355,7 @@ const commands: Record<string, Command> = {
 					silent: options.silent,
 					verbose: options.verbose,
 					json: options.json,
+					cwd: options.cwd,
 				}),
 			)
 		},
@@ -330,6 +382,7 @@ const commands: Record<string, Command> = {
 					silent: options.silent,
 					verbose: options.verbose,
 					inputAllowed: options.inputAllowed,
+					cwd: options.cwd,
 				}),
 			)
 		},
@@ -351,7 +404,24 @@ const commands: Record<string, Command> = {
 					verbose: options.verbose,
 					opencode: options.opencode,
 					claude: options.claude,
+					force: options.force,
 					inputAllowed: options.inputAllowed,
+					cwd: options.cwd,
+					taskId: options.task,
+					phaseId: options.phase,
+				}),
+			)
+		},
+	},
+	next: {
+		run: async (_args: string[], options: Record<string, any>) => {
+			if (options.help) return console.log(nextHelp)
+			await runCommand(
+				next({
+					select: options.select,
+					json: options.json,
+					silent: options.silent,
+					verbose: options.verbose,
 				}),
 			)
 		},
@@ -367,6 +437,7 @@ const commands: Record<string, Command> = {
 					silent: options.silent,
 					verbose: options.verbose,
 					json: options.json,
+					cwd: options.cwd,
 				}),
 			)
 		},
@@ -384,6 +455,7 @@ const commands: Record<string, Command> = {
 					verbose: options.verbose,
 					json: options.json,
 					inputAllowed: options.inputAllowed,
+					cwd: options.cwd,
 				}),
 			)
 		},
@@ -396,11 +468,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,
 				}),
 			)
 		},
@@ -423,6 +502,7 @@ const commands: Record<string, Command> = {
 					include: options.include,
 					silent: options.silent,
 					verbose: options.verbose,
+					cwd: options.cwd,
 				}),
 			)
 		},
@@ -440,6 +520,7 @@ const commands: Record<string, Command> = {
 					json: options.json,
 					silent: options.silent,
 					verbose: options.verbose,
+					cwd: options.cwd,
 				}),
 			)
 		},
@@ -464,6 +545,7 @@ Commands:
   archive <type>         Archive a work item
   task <subcommand>      Manage tasks
   work [directory|task]  Work on an epic, task, or phase
+  next                   List or select ready execution units
   pr create              Create a pull request for an execution unit
   repo <subcommand>      Manage workbase repositories
   status                 Show status for the current workbase
@@ -478,6 +560,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
@@ -519,15 +603,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.16.0",
+  "version": "2.18.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

@@ -141,6 +141,7 @@ describe("strict CLI parsing", () => {
 			[["validate", "one", "two"], "agency validate"],
 			[["context", "one", "two"], "agency context"],
 			[["graph", "extra"], "agency graph"],
+			[["next", "extra"], "agency next"],
 			[["sync", "extra"], "agency sync"],
 			[
 				[
@@ -192,6 +193,24 @@ describe("strict CLI parsing", () => {
 		}
 	})
 
+	test("parses readiness selection and explicit guard overrides", () => {
+		expect(parseCli(["next", "--select", "--json"])).toMatchObject({
+			commandName: "next",
+			values: { select: true, json: true },
+		})
+		expect(parseCli(["work", "example", "--force"])).toMatchObject({
+			commandName: "work",
+			values: { force: true },
+		})
+		expect(parseCli(["pr", "create", "example", "--force"])).toMatchObject({
+			commandName: "pr",
+			values: { force: true },
+		})
+		expect(() => parseCli(["work", "prepare", "example", "--force"])).toThrow(
+			"cannot be combined",
+		)
+	})
+
 	test("parses reconciliation modes and rejects conflicting modes", () => {
 		expect(parseCli(["sync", "--dry-run", "--json"])).toMatchObject({
 			commandName: "sync",
@@ -365,6 +384,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 })