@markjaquith/agency 2.18.0 → 2.19.0

package/README.md

@@ -371,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]
 ```
 
@@ -425,7 +425,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 +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]
 ```
@@ -470,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
@@ -555,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

@@ -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,
@@ -437,6 +452,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.19.0",
   "description": "Manage agentic work across repositories with durable workbases",
   "keywords": [
     "agents",

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"],

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]",
@@ -473,13 +503,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 +804,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 +974,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" &&

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
 `

package/src/commands/phase.ts

@@ -2,6 +2,8 @@ import { Effect } from "effect"
 import type { BaseCommandOptions } from "../utils/command"
 import { PhaseService } from "../services/PhaseService"
 import { createLoggers } from "../utils/effect"
+import { formatTable } from "../utils/table"
+import { getWorkViews } from "../work-view"
 import { parseRepositoryReferences } from "../workbase/repository-reference"
 
 interface PhaseOptions extends BaseCommandOptions {
@@ -15,6 +17,11 @@ interface PhaseOptions extends BaseCommandOptions {
 	readonly dependsOn?: readonly string[]
 	readonly firstPhase?: string
 	readonly json?: boolean
+	readonly statuses?: readonly string[]
+	readonly repositories?: readonly string[]
+	readonly ready?: boolean
+	readonly blocked?: boolean
+	readonly pr?: boolean
 }
 
 export const phase = (options: PhaseOptions) =>
@@ -64,15 +71,53 @@ export const phase = (options: PhaseOptions) =>
 			case "list": {
 				if (!taskId) return yield* Effect.fail(new Error("Task ID is required"))
 				const records = yield* phases.list(taskId, cwd)
+				const { phaseRows } = yield* getWorkViews({
+					cwd,
+					statuses: options.statuses,
+					repositories: options.repositories,
+					ready: options.ready,
+					blocked: options.blocked,
+					pr: options.pr,
+				})
+				const rows = phaseRows.filter((row) => row.parent === taskId)
+				const ordered = rows.flatMap((row) => {
+					const record = records.find((item) => item.id === row.id)
+					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)
+				} else {
+					log(
+						formatTable(
+							[
+								"PHASE",
+								"PARENT",
+								"STATUS",
+								"READINESS",
+								"REPOSITORIES",
+								"BRANCH",
+								"PR",
+								"WORKTREE",
+							],
+							rows.map((row) => [
+								row.id,
+								row.parent,
+								row.status,
+								row.readiness,
+								row.repositories,
+								row.branch,
+								row.pr,
+								row.worktree,
+							]),
+						),
+					)
+				}
 				return
 			}
 			case "show": {
@@ -139,4 +184,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 phases
+  --blocked             Include only blocked phases
+  --pr / --no-pr        Filter by recorded PR presence
 `

package/src/commands/status.test.ts

@@ -8,6 +8,7 @@ import {
 	runTestEffect,
 } from "../test-utils"
 import { status } from "./status"
+import { task } from "./task"
 
 describe("status command", () => {
 	let root: string
@@ -44,4 +45,47 @@ describe("status command", () => {
 			},
 		])
 	})
+
+	test("renders and filters the execution dashboard", async () => {
+		await runTestEffect(
+			task({
+				subcommand: "create",
+				args: ["example"],
+				repo: "agency",
+				branch: "feat/example",
+				base: "main",
+				cwd: root,
+				silent: true,
+			}),
+		)
+
+		const logs = await captureLogs(() =>
+			runTestEffect(
+				status({ cwd: root, repositories: ["agency"], ready: true, pr: false }),
+			),
+		)
+		expect(logs).toContain("Repositories: 1")
+		expect(logs.at(-1)).toContain(
+			"KIND  WORK     PARENT  STATUS  READINESS  REPOSITORIES  BRANCH",
+		)
+		expect(logs.at(-1)).toContain(
+			"task  example  -       open    ready      agency        feat/example  absent  absent",
+		)
+	})
+
+	test("reports validation issues without requiring a decodable graph", async () => {
+		await mkdir(join(root, "tasks/broken"), { recursive: true })
+		await Bun.write(
+			join(root, "tasks/broken/TASK.md"),
+			"---\nrepo: agency\nstatus: invalid\n---\n",
+		)
+
+		const logs = await captureLogs(() =>
+			runTestEffect(status({ cwd: root, json: true })),
+		)
+		const output = JSON.parse(logs[0]!)
+		expect(output.valid).toBe(false)
+		expect(output.issues.length).toBeGreaterThan(0)
+		expect(output.work).toEqual([])
+	})
 })

package/src/commands/status.ts

@@ -3,9 +3,16 @@ import type { BaseCommandOptions } from "../utils/command"
 import { WorkbaseService } from "../services/WorkbaseService"
 import { RepositoryService } from "../services/RepositoryService"
 import { createLoggers } from "../utils/effect"
+import { formatTable } from "../utils/table"
+import { getWorkViews } from "../work-view"
 
 interface StatusOptions extends BaseCommandOptions {
 	readonly json?: boolean
+	readonly statuses?: readonly string[]
+	readonly repositories?: readonly string[]
+	readonly ready?: boolean
+	readonly blocked?: boolean
+	readonly pr?: boolean
 }
 
 export const status = (options: StatusOptions = {}) =>
@@ -16,7 +23,17 @@ export const status = (options: StatusOptions = {}) =>
 		const cwd = options.cwd ?? process.cwd()
 		const report = yield* workbase.validate(cwd)
 		const repos = yield* repositories.list(report.root)
-		const data = { ...report, repositories: repos }
+		const executionRows = report.valid
+			? (yield* getWorkViews({
+					cwd,
+					statuses: options.statuses,
+					repositories: options.repositories,
+					ready: options.ready,
+					blocked: options.blocked,
+					pr: options.pr,
+				})).executionRows
+			: []
+		const data = { ...report, repositories: repos, work: executionRows }
 
 		if (options.json) {
 			log(JSON.stringify(data, null, 2))
@@ -31,6 +48,33 @@ export const status = (options: StatusOptions = {}) =>
 		log(
 			`Validation: ${report.valid ? "valid" : `${report.issues.length} issues`}`,
 		)
+		log("")
+		log(
+			formatTable(
+				[
+					"KIND",
+					"WORK",
+					"PARENT",
+					"STATUS",
+					"READINESS",
+					"REPOSITORIES",
+					"BRANCH",
+					"PR",
+					"WORKTREE",
+				],
+				executionRows.map((row) => [
+					row.kind,
+					row.kind === "phase" ? row.key : row.id,
+					row.parent,
+					row.status,
+					row.readiness,
+					row.repositories,
+					row.branch,
+					row.pr,
+					row.worktree,
+				]),
+			),
+		)
 	})
 
 export const help = `
@@ -39,5 +83,10 @@ Usage: agency status [options]
 Show workbase repository, entity, and validation status.
 
 Options:
-  --json              Output status as JSON
+  --json                Output status as JSON
+  --status <status>     Filter by status; repeatable
+  --repository <alias>  Filter by repository; repeatable
+  --ready               Include only ready work
+  --blocked             Include only blocked work
+  --pr / --no-pr        Filter by recorded PR presence
 `

package/src/commands/task-phase.test.ts

@@ -124,6 +124,26 @@ describe("task and phase command JSON output", () => {
 		})
 	})
 
+	test("renders task and phase operational tables", async () => {
+		const taskLogs = await captureLogs(() =>
+			runTestEffect(task({ subcommand: "list", args: [], cwd: root })),
+		)
+		expect(taskLogs[0]).toContain(
+			"TASK   PARENT  STATUS  READINESS  REPOSITORIES  BRANCH",
+		)
+		expect(taskLogs[0]).toContain("multi  -       open    ready")
+
+		const phaseLogs = await captureLogs(() =>
+			runTestEffect(phase({ subcommand: "list", args: ["multi"], cwd: root })),
+		)
+		expect(phaseLogs[0]).toContain(
+			"PHASE  PARENT  STATUS  READINESS  REPOSITORIES  BRANCH",
+		)
+		expect(phaseLogs[0]).toContain(
+			"first  multi   open    ready      agency        task/first  absent  absent",
+		)
+	})
+
 	test("outputs created task and phase records as JSON", async () => {
 		const taskLogs = await captureLogs(() =>
 			runTestEffect(

package/src/commands/task.ts

@@ -8,6 +8,8 @@ import { createLoggers } from "../utils/effect"
 import { parseRepositoryReferences } from "../workbase/repository-reference"
 import { WorkbaseService } from "../services/WorkbaseService"
 import { choose } from "../utils/chooser"
+import { formatTable } from "../utils/table"
+import { getWorkViews } from "../work-view"
 
 interface TaskOptions extends BaseCommandOptions {
 	readonly subcommand?: string
@@ -21,6 +23,11 @@ interface TaskOptions extends BaseCommandOptions {
 	readonly base?: string
 	readonly multiPhase?: boolean
 	readonly json?: boolean
+	readonly statuses?: readonly string[]
+	readonly repositories?: readonly string[]
+	readonly ready?: boolean
+	readonly blocked?: boolean
+	readonly pr?: boolean
 }
 
 export interface TaskInteraction {
@@ -208,16 +215,51 @@ export const task = (options: TaskOptions, interaction?: TaskInteraction) =>
 			}
 			case "list": {
 				const records = yield* tasks.list(cwd)
+				const { taskRows } = yield* getWorkViews({
+					cwd,
+					statuses: options.statuses,
+					repositories: options.repositories,
+					ready: options.ready,
+					blocked: options.blocked,
+					pr: options.pr,
+				})
+				const ordered = taskRows.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(
+							[
+								"TASK",
+								"PARENT",
+								"STATUS",
+								"READINESS",
+								"REPOSITORIES",
+								"BRANCH",
+								"PR",
+								"WORKTREE",
+							],
+							taskRows.map((row) => [
+								row.id,
+								row.parent,
+								row.status,
+								row.readiness,
+								row.repositories,
+								row.branch,
+								row.pr,
+								row.worktree,
+							]),
+						),
+					)
 				}
 				return
 			}
@@ -286,4 +328,9 @@ through task new, which fails when --no-input is set or no TTY is available.
 Options:
   --json                Output results as JSON
   --no-input            Never open interactive task creation
+  --status <status>     Filter list by status; repeatable
+  --repository <alias>  Filter list by repository; repeatable
+  --ready               Include only ready tasks
+  --blocked             Include only blocked tasks
+  --pr / --no-pr        Filter by recorded PR presence
 `

package/src/utils/table.ts

@@ -0,0 +1,19 @@
+export const formatTable = (
+	headings: readonly string[],
+	rows: readonly (readonly string[])[],
+) => {
+	const widths = headings.map((heading, index) =>
+		Math.max(heading.length, ...rows.map((row) => row[index]?.length ?? 0)),
+	)
+	const line = (cells: readonly string[]) =>
+		cells
+			.map((cell, index) => cell.padEnd(widths[index] ?? cell.length))
+			.join("  ")
+			.trimEnd()
+
+	return [
+		line(headings),
+		line(widths.map((width) => "-".repeat(width))),
+		...rows.map(line),
+	].join("\n")
+}

package/src/work-view.test.ts

@@ -0,0 +1,151 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { mkdir } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import { cleanupTempDir, createTempDir, runTestEffect } from "./test-utils"
+import { getWorkViews } from "./work-view"
+
+const write = async (root: string, path: string, content: string) => {
+	const fullPath = join(root, path)
+	await mkdir(dirname(fullPath), { recursive: true })
+	await Bun.write(fullPath, content)
+}
+
+describe("work views", () => {
+	let root: string
+
+	beforeEach(async () => {
+		root = await createTempDir()
+		await write(root, "agency.json", '{"version":2}\n')
+		await mkdir(join(root, "repos/agency"), { recursive: true })
+		await write(
+			root,
+			"epics/delivery/EPIC.md",
+			`---
+ticketUrl: https://example.com/delivery
+repos:
+  - repo: agency
+    ref: main
+tasks:
+  - id: zeta
+  - id: alpha
+---
+`,
+		)
+		await write(
+			root,
+			"tasks/zeta/TASK.md",
+			`---
+ticketUrl: null
+epic: delivery
+phases:
+  - id: verify
+    dependsOn: [implement]
+  - id: implement
+---
+`,
+		)
+		await write(
+			root,
+			"tasks/zeta/phases/verify/PHASE.md",
+			`---
+repo: agency
+branch: feat/verify
+base: main
+pr: null
+status: open
+---
+`,
+		)
+		await write(
+			root,
+			"tasks/zeta/phases/implement/PHASE.md",
+			`---
+repo: agency
+branch: feat/implement
+base: main
+pr: https://github.com/example/agency/pull/1
+status: dropped
+---
+`,
+		)
+		await mkdir(join(root, "tasks/zeta/phases/implement/code/agency"), {
+			recursive: true,
+		})
+		await write(
+			root,
+			"tasks/alpha/TASK.md",
+			`---
+ticketUrl: null
+epic: delivery
+repo: agency
+branch: feat/alpha
+base: main
+pr: null
+status: open
+---
+`,
+		)
+	})
+
+	afterEach(async () => cleanupTempDir(root))
+
+	const views = (options: Record<string, unknown> = {}) =>
+		runTestEffect(Effect.suspend(() => getWorkViews({ cwd: root, ...options })))
+
+	test("uses declared graph order and exposes operational state", async () => {
+		const result = await views()
+
+		expect(result.taskRows.map((row) => row.id)).toEqual(["zeta", "alpha"])
+		expect(result.phaseRows.map((row) => row.id)).toEqual([
+			"verify",
+			"implement",
+		])
+		expect(result.executionRows.map((row) => row.key)).toEqual([
+			"zeta/verify",
+			"zeta/implement",
+			"alpha",
+		])
+		expect(result.phaseRows[0]).toMatchObject({
+			parent: "zeta",
+			status: "open",
+			readiness: "blocked",
+			repositories: "agency",
+			branch: "feat/verify",
+			pr: "absent",
+			worktree: "absent",
+		})
+		expect(result.phaseRows[1]).toMatchObject({
+			readiness: "terminal",
+			pr: "present",
+			worktree: "materialized",
+		})
+		expect(result.taskRows[0]).toMatchObject({
+			parent: "delivery",
+			branch: "multiple",
+			pr: "1/2 present",
+			worktree: "1/2 materialized",
+		})
+	})
+
+	test("composes lifecycle, repository, readiness, and PR filters", async () => {
+		expect(
+			(await views({ statuses: ["dropped"] })).executionRows.map(
+				(row) => row.key,
+			),
+		).toEqual(["zeta/implement"])
+		expect(
+			(await views({ repositories: ["agency"], blocked: true })).phaseRows.map(
+				(row) => row.id,
+			),
+		).toEqual(["verify"])
+		expect(
+			(await views({ ready: true, pr: false })).executionRows.map(
+				(row) => row.key,
+			),
+		).toEqual(["alpha"])
+		expect((await views({ pr: true })).phaseRows.map((row) => row.id)).toEqual([
+			"implement",
+		])
+	})
+})

package/src/work-view.ts

@@ -0,0 +1,253 @@
+import { Effect } from "effect"
+import type { GraphNode } from "./graph-schema"
+import { GraphService } from "./services/GraphService"
+import type { WorkStatus } from "./workbase/schemas"
+
+type WorkNode = Extract<
+	GraphNode,
+	{ readonly kind: "epic" | "task" | "phase" | "execution-unit" }
+>
+type EntityNode = Exclude<WorkNode, { readonly kind: "execution-unit" }>
+type ExecutionNode = Extract<WorkNode, { readonly kind: "execution-unit" }>
+
+export interface WorkViewOptions {
+	readonly cwd?: string
+	readonly statuses?: readonly string[]
+	readonly repositories?: readonly string[]
+	readonly ready?: boolean
+	readonly blocked?: boolean
+	readonly pr?: boolean
+}
+
+export interface WorkViewRow {
+	readonly kind: "epic" | "task" | "phase"
+	readonly id: string
+	readonly key: string
+	readonly parent: string
+	readonly status: WorkStatus
+	readonly readiness: "ready" | "blocked" | "waiting" | "terminal"
+	readonly repositories: string
+	readonly branch: string
+	readonly pr: string
+	readonly worktree: string
+	readonly hasPr: boolean
+}
+
+const allowedStatuses = new Set<WorkStatus>([
+	"open",
+	"working",
+	"delegated",
+	"done",
+	"dropped",
+])
+
+const validatedStatuses = (values: readonly string[] | undefined) =>
+	(values ?? []).map((value) => {
+		if (!allowedStatuses.has(value as WorkStatus)) {
+			throw new Error(
+				`Invalid --status value '${value}'. Expected one of: ${[...allowedStatuses].join(", ")}`,
+			)
+		}
+		return value as WorkStatus
+	})
+
+const readinessLabel = (node: EntityNode): WorkViewRow["readiness"] =>
+	node.readiness.ready
+		? "ready"
+		: node.readiness.terminal
+			? "terminal"
+			: node.readiness.blocked
+				? "blocked"
+				: "waiting"
+
+const aggregateLabel = (
+	executions: readonly ExecutionNode[],
+	predicate: (node: ExecutionNode) => boolean,
+	singular: readonly [present: string, absent: string],
+) => {
+	if (executions.length === 0) return "-"
+	const count = executions.filter(predicate).length
+	if (executions.length === 1) return count === 1 ? singular[0] : singular[1]
+	return `${count}/${executions.length} ${singular[0]}`
+}
+
+const rowFor = (
+	node: EntityNode,
+	executions: readonly ExecutionNode[],
+): WorkViewRow => {
+	const branches = [
+		...new Set(executions.map((execution) => execution.data.branch)),
+	]
+	const parent =
+		node.kind === "task"
+			? (node.data.epic ?? "-")
+			: node.kind === "phase"
+				? node.key.slice(0, node.key.indexOf("/"))
+				: "-"
+	const id =
+		node.kind === "phase" ? node.key.slice(node.key.indexOf("/") + 1) : node.key
+
+	return {
+		kind: node.kind,
+		id,
+		key: node.key,
+		parent,
+		status: node.status,
+		readiness: readinessLabel(node),
+		repositories: node.repositories.join(",") || "-",
+		branch:
+			branches.length === 0
+				? "-"
+				: branches.length === 1
+					? branches[0]!
+					: "multiple",
+		pr: aggregateLabel(executions, (execution) => Boolean(execution.data.pr), [
+			"present",
+			"absent",
+		]),
+		worktree: aggregateLabel(
+			executions,
+			(execution) => execution.workspace?.materialized === true,
+			["materialized", "absent"],
+		),
+		hasPr: executions.some((execution) => Boolean(execution.data.pr)),
+	}
+}
+
+const orderedTasks = (
+	epics: readonly Extract<EntityNode, { readonly kind: "epic" }>[],
+	tasks: ReadonlyMap<string, Extract<EntityNode, { readonly kind: "task" }>>,
+) => {
+	const ordered: Extract<EntityNode, { readonly kind: "task" }>[] = []
+	const seen = new Set<string>()
+	for (const epic of epics) {
+		for (const item of epic.data.tasks) {
+			const task = tasks.get(item.id)
+			if (task && !seen.has(task.key)) {
+				ordered.push(task)
+				seen.add(task.key)
+			}
+		}
+	}
+	for (const task of [...tasks.values()].sort((a, b) =>
+		a.key.localeCompare(b.key),
+	)) {
+		if (!seen.has(task.key)) ordered.push(task)
+	}
+	return ordered
+}
+
+const orderedPhases = (
+	task: Extract<EntityNode, { readonly kind: "task" }>,
+	phases: ReadonlyMap<string, Extract<EntityNode, { readonly kind: "phase" }>>,
+) => {
+	const ordered: Extract<EntityNode, { readonly kind: "phase" }>[] = []
+	const seen = new Set<string>()
+	if ("phases" in task.data) {
+		for (const item of task.data.phases) {
+			const phase = phases.get(`${task.key}/${item.id}`)
+			if (phase) {
+				ordered.push(phase)
+				seen.add(phase.key)
+			}
+		}
+	}
+	for (const phase of [...phases.values()]
+		.filter((value) => value.key.startsWith(`${task.key}/`))
+		.sort((a, b) => a.key.localeCompare(b.key))) {
+		if (!seen.has(phase.key)) ordered.push(phase)
+	}
+	return ordered
+}
+
+export const getWorkViews = (options: WorkViewOptions = {}) =>
+	Effect.gen(function* () {
+		const graphService = yield* GraphService
+		const statuses = yield* Effect.sync(() =>
+			validatedStatuses(options.statuses),
+		)
+		const graph = yield* graphService.get({
+			cwd: options.cwd,
+			include: ["workspace"],
+		})
+		const workNodes = graph.nodes.filter(
+			(node): node is WorkNode => node.kind !== "repository",
+		)
+		const epics = workNodes
+			.filter(
+				(node): node is Extract<EntityNode, { readonly kind: "epic" }> =>
+					node.kind === "epic",
+			)
+			.sort((a, b) => a.key.localeCompare(b.key))
+		const tasks = new Map(
+			workNodes
+				.filter(
+					(node): node is Extract<EntityNode, { readonly kind: "task" }> =>
+						node.kind === "task",
+				)
+				.map((node) => [node.key, node]),
+		)
+		const phases = new Map(
+			workNodes
+				.filter(
+					(node): node is Extract<EntityNode, { readonly kind: "phase" }> =>
+						node.kind === "phase",
+				)
+				.map((node) => [node.key, node]),
+		)
+		const executions = workNodes.filter(
+			(node): node is ExecutionNode => node.kind === "execution-unit",
+		)
+		const taskOrder = orderedTasks(epics, tasks)
+		const phaseOrder = taskOrder.flatMap((task) => orderedPhases(task, phases))
+		const executionsFor = (node: EntityNode) => {
+			if (node.kind === "phase") {
+				const separator = node.key.indexOf("/")
+				const taskId = node.key.slice(0, separator)
+				const phaseId = node.key.slice(separator + 1)
+				return executions.filter(
+					(execution) =>
+						execution.data.taskId === taskId &&
+						execution.data.phaseId === phaseId,
+				)
+			}
+			if (node.kind === "task") {
+				return executions.filter(
+					(execution) => execution.data.taskId === node.key,
+				)
+			}
+			const taskIds = new Set(node.data.tasks.map((item) => item.id))
+			return executions.filter((execution) =>
+				taskIds.has(execution.data.taskId),
+			)
+		}
+		const makeRows = (nodes: readonly EntityNode[]) =>
+			nodes.map((node) => rowFor(node, executionsFor(node)))
+		const filterRows = (rows: readonly WorkViewRow[]) =>
+			rows
+				.filter((row) => statuses.length === 0 || statuses.includes(row.status))
+				.filter(
+					(row) =>
+						!options.repositories?.length ||
+						row.repositories
+							.split(",")
+							.some((repo) => options.repositories!.includes(repo)),
+				)
+				.filter((row) => options.ready !== true || row.readiness === "ready")
+				.filter(
+					(row) => options.blocked !== true || row.readiness === "blocked",
+				)
+				.filter((row) => options.pr === undefined || row.hasPr === options.pr)
+
+		const epicRows = filterRows(makeRows(epics))
+		const taskRows = filterRows(makeRows(taskOrder))
+		const phaseRows = filterRows(makeRows(phaseOrder))
+		const executionEntities: EntityNode[] = []
+		for (const task of taskOrder) {
+			const taskPhases = orderedPhases(task, phases)
+			executionEntities.push(...(taskPhases.length > 0 ? taskPhases : [task]))
+		}
+		const executionRows = filterRows(makeRows(executionEntities))
+
+		return { epicRows, taskRows, phaseRows, executionRows }
+	})