@markjaquith/agency 2.5.0 → 2.6.0

package/README.md

@@ -240,11 +240,15 @@ agency pr create refresh-copy
 
 ```text
 agency init [path] [--json]
+agency workbase add <path> [--json]
+agency workbase list [--json]
 agency repo add <alias> <remote> [--json]
 agency repo link <alias> <path> [--json]
 agency repo list [--json]
 ```
 
+Registered workbases are stored in
+`$XDG_CONFIG_HOME/agency/workbases.json` (or `~/.config/agency/workbases.json`).
 `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.
 
@@ -294,7 +298,7 @@ Inspect tasks:
 ```text
 agency task list [--json]
 agency task show <id> [--json]
-agency task status <id> <open|working|done|dropped> [--json]
+agency task status <id> <open|working|delegated|done|dropped> [--json]
 ```
 
 To add a phase to an existing single-phase task, name the phase that will own
@@ -321,14 +325,14 @@ agency phase create <task-id> <phase-id>
 
 agency phase list <task-id> [--json]
 agency phase show <task-id> <phase-id> [--json]
-agency phase status <task-id> <phase-id> <open|working|done|dropped> [--json]
+agency phase status <task-id> <phase-id> <open|working|delegated|done|dropped> [--json]
 ```
 
 Single-phase tasks and phases store status in YAML. New execution units start
 `open`, and `agency work` marks the selected execution unit `working` immediately
-before launch. Use the status subcommands to mark work `done`, `dropped`, or open
-it again. The interactive work selector displays status markers before execution
-units.
+before launch. Use the status subcommands to mark work `delegated`, `done`,
+`dropped`, or open it again. The interactive work selector displays status
+markers before execution units.
 
 ### Archive
 
@@ -351,8 +355,10 @@ agency pr create <task-id> [phase-id] [--draft] [--json]
 ```
 
 `agency work` infers an epic, task, or phase from the current directory. From
-elsewhere in the workbase, it presents the full hierarchy in `fzf`. If `fzf` is
-not installed, Agency prints the hierarchy and asks for an explicit target.
+elsewhere in the workbase, it presents the full hierarchy in `fzf`. Outside a
+workbase, it 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 target.
 
 Epic and multi-phase task targets launch orchestration agents beside their
 documents. Single-phase tasks and phases fetch repositories, create or reuse
@@ -380,13 +386,14 @@ the owning `TASK.md` or `PHASE.md`.
 
 ```text
 agency status [--json]
-agency validate [--json]
+agency validate [path] [--json]
 ```
 
 Validation checks JSON and YAML parsing, Effect Schema conformance, repository
 aliases, parent/child backlinks, phase directories, duplicate references,
 unknown dependencies, and dependency cycles. YAML duplicate keys, anchors,
-aliases, and custom tags are rejected.
+aliases, and custom tags are rejected. When path is omitted outside a workbase,
+Agency prompts for a registered workbase.
 
 ## Agent Skill
 

package/cli.ts

@@ -12,6 +12,7 @@ import { repo, help as repoHelp } from "./src/commands/repo"
 import { epic, help as epicHelp } from "./src/commands/epic"
 import { phase, help as phaseHelp } from "./src/commands/phase"
 import { archive, help as archiveHelp } from "./src/commands/archive"
+import { workbase, help as workbaseHelp } from "./src/commands/workbase"
 import type { Command } from "./src/types"
 import { FileSystemService } from "./src/services/FileSystemService"
 import { WorkbaseService } from "./src/services/WorkbaseService"
@@ -173,6 +174,23 @@ const commands: Record<string, Command> = {
 			)
 		},
 	},
+	workbase: {
+		run: async (args: string[], options: Record<string, any>) => {
+			if (options.help) {
+				console.log(workbaseHelp)
+				return
+			}
+			await runCommand(
+				workbase({
+					subcommand: args[0],
+					args: args.slice(1),
+					json: options.json,
+					silent: options.silent,
+					verbose: options.verbose,
+				}),
+			)
+		},
+	},
 	repo: {
 		run: async (args: string[], options: Record<string, any>) => {
 			if (options.help) {
@@ -251,13 +269,14 @@ const commands: Record<string, Command> = {
 		},
 	},
 	validate: {
-		run: async (_args: string[], options: Record<string, any>) => {
+		run: async (args: string[], options: Record<string, any>) => {
 			if (options.help) {
 				console.log(validateHelp)
 				return
 			}
 			await runCommand(
 				validate({
+					path: args[0],
 					silent: options.silent,
 					verbose: options.verbose,
 					json: options.json,
@@ -275,6 +294,7 @@ Usage: agency <command> [options]
 
 Commands:
   init [path]            Initialize an Agency workbase
+  workbase <subcommand>  Manage registered workbases
   epic <subcommand>      Manage epics
   phase <subcommand>     Manage task phases
   archive <type>         Archive a work item
@@ -283,7 +303,7 @@ Commands:
   pr create              Create a pull request for an execution unit
   repo <subcommand>      Manage workbase repositories
   status                 Show status for the current workbase
-  validate               Validate the current workbase
+  validate [path]        Validate a workbase
 
 Global Options:
   -h, --help             Show help for a command

package/package.json

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

package/skills/agency/SKILL.md

@@ -58,6 +58,13 @@ If no workbase is found, do not initialize one without user intent. When asked:
 agency init [path]
 ```
 
+Register known workbases so `agency work` can select one when run elsewhere:
+
+```bash
+agency workbase add <path>
+agency workbase list
+```
+
 ## Repository Aliases
 
 Add a remote as an Agency-managed bare repository:
@@ -195,8 +202,8 @@ output, including mutations, entity inspection, status, validation, and PR creat
 - Multi-phase task frontmatter owns the phase dependency graph.
 - Epic frontmatter owns the child-task dependency graph.
 - `pr` is either a GitHub PR URL string or `null`.
-- Execution-unit `status` is `open`, `working`, `done`, or `dropped`. New work
-  starts open, and `agency work` marks it working before agent launch.
+- Execution-unit `status` is `open`, `working`, `delegated`, `done`, or `dropped`.
+  New work starts open, and `agency work` marks it working before agent launch.
 - Keep directory IDs stable; encode sequencing with `dependsOn`, not numeric
   directory prefixes.
 - Do not use YAML duplicate keys, anchors, aliases, or custom tags.
@@ -207,8 +214,8 @@ prose, preserve backlinks and run validation immediately afterward.
 Update execution status with:
 
 ```bash
-agency task status <task-id> <open|working|done|dropped>
-agency phase status <task-id> <phase-id> <open|working|done|dropped>
+agency task status <task-id> <open|working|delegated|done|dropped>
+agency phase status <task-id> <phase-id> <open|working|delegated|done|dropped>
 ```
 
 ## Archive Completed Work
@@ -226,13 +233,14 @@ branches. It refuses dirty worktrees and active sibling dependencies.
 ## Validate Every Structural Change
 
 ```bash
-agency validate
+agency validate [path]
 ```
 
 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.
 
 ## Worktrees And Agent Launch
 
@@ -247,6 +255,7 @@ repositories for execution targets, creates or reuses their worktrees, and
 replaces the current process with the selected agent. It infers the nearest
 epic, task, or phase from the current directory; otherwise it opens an `fzf`
 picker containing the workbase hierarchy.
+Outside a workbase, it first opens a picker containing registered workbases.
 
 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.test.ts

@@ -12,9 +12,14 @@ interface CliResult {
 	stderr: string
 }
 
-async function runCli(args: string[], cwd = projectRoot): Promise<CliResult> {
+async function runCli(
+	args: string[],
+	cwd = projectRoot,
+	env?: Record<string, string>,
+): Promise<CliResult> {
 	const subprocess = Bun.spawn([process.execPath, cliPath, ...args], {
 		cwd,
+		env: env ? { ...process.env, ...env } : undefined,
 		stdout: "pipe",
 		stderr: "pipe",
 	})
@@ -76,6 +81,7 @@ describe("CLI", () => {
 	test("routes command help and global options on either side of commands", async () => {
 		for (const [command, usage] of [
 			["init", "Usage: agency init"],
+			["workbase", "Usage: agency workbase"],
 			["repo", "Usage: agency repo"],
 			["epic", "Usage: agency epic"],
 			["task", "Usage: agency task"],
@@ -106,6 +112,25 @@ describe("CLI", () => {
 		expect(after).toEqual({ exitCode: 0, stdout: "", stderr: "" })
 	})
 
+	test("registers and lists workbases", async () => {
+		const parent = await createTempDir()
+		tempDirs.push(parent)
+		const root = join(parent, "workbase")
+		const env = { XDG_CONFIG_HOME: join(parent, "config") }
+
+		expect(
+			parseJson(await runCli(["init", root, "--json"], parent, env)),
+		).toEqual({
+			root,
+		})
+		expect(
+			parseJson(await runCli(["workbase", "add", root, "--json"], parent, env)),
+		).toEqual({ path: await realpath(root) })
+		expect(
+			parseJson(await runCli(["workbase", "list", "--json"], parent, env)),
+		).toEqual([await realpath(root)])
+	})
+
 	test("runs a multi-phase domain workflow through subprocesses", async () => {
 		const parent = await createTempDir()
 		tempDirs.push(parent)
@@ -278,9 +303,11 @@ describe("CLI", () => {
 			issues: [],
 		})
 
-		const validation = parseJson(await runCli(["validate", "--json"], root))
+		const validation = parseJson(
+			await runCli(["validate", root, "--json"], parent),
+		)
 		expect(validation).toEqual({
-			root: workbaseRoot,
+			root,
 			issues: [],
 			epicCount: 1,
 			taskCount: 1,

package/src/commands/phase.ts

@@ -125,7 +125,7 @@ Subcommands:
   list <task>           List task phases
   show <task> <phase>   Show a phase
   status <task> <phase> <status>
-                        Set open, working, done, or dropped
+                        Set open, working, delegated, done, or dropped
 
 Create options:
   --description <text>  Short description of the phase

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

@@ -172,13 +172,13 @@ describe("task and phase command JSON output", () => {
 			runTestEffect(
 				phase({
 					subcommand: "status",
-					args: ["multi", "first", "done"],
+					args: ["multi", "first", "delegated"],
 					cwd: root,
 					json: true,
 				}),
 			),
 		)
-		expect(JSON.parse(phaseLogs[0]!).data.status).toBe("done")
+		expect(JSON.parse(phaseLogs[0]!).data.status).toBe("delegated")
 
 		await runTestEffect(
 			task({
@@ -196,13 +196,13 @@ describe("task and phase command JSON output", () => {
 			runTestEffect(
 				task({
 					subcommand: "status",
-					args: ["single-status", "dropped"],
+					args: ["single-status", "delegated"],
 					cwd: root,
 					json: true,
 				}),
 			),
 		)
-		expect(JSON.parse(taskLogs[0]!).data.status).toBe("dropped")
+		expect(JSON.parse(taskLogs[0]!).data.status).toBe("delegated")
 	})
 
 	test("converts a single-phase task with an explicit first phase ID", async () => {

package/src/commands/task.ts

@@ -237,7 +237,7 @@ Subcommands:
   create <id>           Create a task; omitted metadata uses defaults
   list                  List tasks
   show <id>             Show a task
-  status <id> <status>  Set open, working, done, or dropped
+  status <id> <status>  Set open, working, delegated, done, or dropped
 
 Create options:
   --ticket-url <url>    External ticket URL (optional)

package/src/commands/validate.test.ts

@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { Effect } from "effect"
 import { mkdir } from "node:fs/promises"
 import { join } from "node:path"
 import {
@@ -7,6 +8,9 @@ import {
 	createTempDir,
 	runTestEffect,
 } from "../test-utils"
+import { FileSystemService } from "../services/FileSystemService"
+import { WorkbaseService } from "../services/WorkbaseService"
+import type { PickWorkbase } from "../workbase/workbase-choice"
 import { validate } from "./validate"
 
 describe("validate command", () => {
@@ -43,6 +47,67 @@ pr: null
 		).resolves.toBeUndefined()
 	})
 
+	test("validates an explicit workbase path", async () => {
+		await Bun.write(
+			join(root, "tasks/example/TASK.md"),
+			`---
+ticketUrl: null
+repo: agency
+branch: task/example
+base: main
+pr: null
+---
+`,
+		)
+
+		await expect(
+			runTestEffect(
+				validate({ path: root, cwd: join(root, "outside"), silent: true }),
+			),
+		).resolves.toBeUndefined()
+	})
+
+	test("selects a registered workbase when local discovery fails", async () => {
+		const discovered: string[] = []
+		const workbase = {
+			discover: (path: string) => {
+				discovered.push(path)
+				return path === "/outside"
+					? Effect.fail({
+							_tag: "WorkbaseNotFoundError" as const,
+							message: "No Agency workbase found from /outside",
+						})
+					: Effect.succeed(path)
+			},
+			listRegistered: () => Effect.succeed(["/first", "/selected"]),
+			validate: (path: string) =>
+				Effect.succeed({
+					root: path,
+					issues: [],
+					epicCount: 0,
+					taskCount: 0,
+					phaseCount: 0,
+					valid: true,
+				}),
+		}
+		const fs = {
+			runCommand: () => Effect.succeed({ exitCode: 0, stdout: "", stderr: "" }),
+		}
+		const pick: PickWorkbase = (workbases) => {
+			expect(workbases).toEqual(["/first", "/selected"])
+			return Effect.succeed("/selected")
+		}
+
+		await Effect.runPromise(
+			validate({ cwd: "/outside", silent: true }, pick).pipe(
+				Effect.provideService(WorkbaseService, workbase as never),
+				Effect.provideService(FileSystemService, fs as never),
+			) as Effect.Effect<void, unknown, never>,
+		)
+
+		expect(discovered).toEqual(["/outside", "/selected"])
+	})
+
 	test("outputs the validation report as JSON", async () => {
 		await Bun.write(
 			join(root, "tasks/example/TASK.md"),

package/src/commands/validate.ts

@@ -2,8 +2,14 @@ import { Data, Effect } from "effect"
 import type { BaseCommandOptions } from "../utils/command"
 import { WorkbaseService } from "../services/WorkbaseService"
 import { createLoggers } from "../utils/effect"
+import {
+	pickWorkbase,
+	resolveWorkbase,
+	type PickWorkbase,
+} from "../workbase/workbase-choice"
 
 interface ValidateOptions extends BaseCommandOptions {
+	readonly path?: string
 	readonly json?: boolean
 }
 
@@ -11,11 +17,19 @@ class ValidationFailedError extends Data.TaggedError("ValidationFailedError")<{
 	readonly message: string
 }> {}
 
-export const validate = (options: ValidateOptions = {}) =>
+export const validate = (
+	options: ValidateOptions = {},
+	pick: PickWorkbase = pickWorkbase,
+) =>
 	Effect.gen(function* () {
 		const workbase = yield* WorkbaseService
 		const { log } = createLoggers(options)
-		const report = yield* workbase.validate(options.cwd ?? process.cwd())
+		const startPath = options.path ?? options.cwd ?? process.cwd()
+		const root = options.path
+			? yield* workbase.discover(startPath)
+			: yield* resolveWorkbase(startPath, log, pick)
+		if (!root) return
+		const report = yield* workbase.validate(root)
 
 		if (options.json) {
 			log(JSON.stringify(report, null, 2))
@@ -40,10 +54,10 @@ export const validate = (options: ValidateOptions = {}) =>
 	})
 
 export const help = `
-Usage: agency validate [options]
+Usage: agency validate [path] [options]
 
-Validate the current workbase configuration, frontmatter, references, and
-dependency graphs.
+Validate a workbase's configuration, frontmatter, references, and dependency
+graphs. The current or selected registered workbase is used when path is omitted.
 
 Options:
   --json              Output the validation report as JSON

package/src/commands/work.test.ts

@@ -9,6 +9,7 @@ import { WorktreeService } from "../services/WorktreeService"
 import { captureLogs } from "../test-utils"
 import { work } from "./work"
 import type { PickWorkTarget } from "../workbase/work-target"
+import type { PickWorkbase } from "../workbase/workbase-choice"
 import type { Progress } from "../utils/progress"
 
 type ExecutionWorkspace = Effect.Effect.Success<
@@ -43,6 +44,8 @@ interface HarnessOptions {
 	readonly epicRecords?: readonly any[]
 	readonly taskRecords?: readonly any[]
 	readonly phaseRecords?: readonly any[]
+	readonly outsideWorkbase?: boolean
+	readonly registeredWorkbases?: readonly string[]
 }
 
 const createHarness = (options: HarnessOptions = {}) => {
@@ -73,7 +76,14 @@ const createHarness = (options: HarnessOptions = {}) => {
 		},
 	}
 	const workbase = {
-		discover: () => Effect.succeed("/workbase"),
+		discover: (path: string) =>
+			options.outsideWorkbase && path === "/outside"
+				? Effect.fail({
+						_tag: "WorkbaseNotFoundError" as const,
+						message: "No Agency workbase found from /outside",
+					})
+				: Effect.succeed("/workbase"),
+		listRegistered: () => Effect.succeed(options.registeredWorkbases ?? []),
 	}
 	const epics = {
 		show: (id: string) =>
@@ -130,6 +140,7 @@ const createHarness = (options: HarnessOptions = {}) => {
 		launches.push({ cli, args, cwd })
 	}
 	const defaultPick: PickWorkTarget = () => Effect.succeed(null)
+	const defaultPickWorkbase: PickWorkbase = () => Effect.succeed(null)
 	const progress: Progress = {
 		start: (message) => progressUpdates.push(`start:${message}`),
 		succeed: (message) => progressUpdates.push(`succeed:${message}`),
@@ -138,9 +149,10 @@ const createHarness = (options: HarnessOptions = {}) => {
 	const run = (
 		commandOptions: Parameters<typeof work>[0],
 		pick: PickWorkTarget = defaultPick,
+		pickBase: PickWorkbase = defaultPickWorkbase,
 	) =>
 		Effect.runPromise(
-			work(commandOptions, launch, pick, progress).pipe(
+			work(commandOptions, launch, pick, progress, pickBase).pipe(
 				Effect.provideService(WorktreeService, worktrees as never),
 				Effect.provideService(FileSystemService, fs as never),
 				Effect.provideService(WorkbaseService, workbase as never),
@@ -255,6 +267,41 @@ describe("work command", () => {
 		)
 	})
 
+	test("selects a registered workbase when local discovery fails", async () => {
+		const harness = createHarness({
+			outsideWorkbase: true,
+			registeredWorkbases: ["/first", "/workbase"],
+		})
+		const selections: string[][] = []
+		const pickBase: PickWorkbase = (workbases) => {
+			selections.push([...workbases])
+			return Effect.succeed("/workbase")
+		}
+
+		await harness.run(
+			{ cwd: "/outside", taskId: "example", opencode: true },
+			undefined,
+			pickBase,
+		)
+
+		expect(selections).toEqual([["/first", "/workbase"]])
+		expect(harness.events).toEqual([
+			"probe:fzf",
+			"materialize",
+			"probe:opencode",
+			"launch:opencode",
+		])
+	})
+
+	test("explains how to register a workbase when none are known", async () => {
+		const harness = createHarness({ outsideWorkbase: true })
+
+		await expect(harness.run({ cwd: "/outside" })).rejects.toThrow(
+			"agency workbase add <path>",
+		)
+		expect(harness.events).toEqual([])
+	})
+
 	test("prints the target tree when fzf is unavailable", async () => {
 		const harness = createHarness({
 			available: { fzf: false },

package/src/commands/work.ts

@@ -16,6 +16,11 @@ import {
 	type PickWorkTarget,
 	type WorkTarget,
 } from "../workbase/work-target"
+import {
+	pickWorkbase,
+	resolveWorkbase,
+	type PickWorkbase,
+} from "../workbase/workbase-choice"
 
 interface WorkOptions extends BaseCommandOptions {
 	readonly taskId?: string
@@ -37,6 +42,7 @@ export const work = (
 	launch: LaunchAgent = launchAgent,
 	pick: PickWorkTarget = pickWorkTarget,
 	progress: Progress = createProgress(options),
+	pickBase: PickWorkbase = pickWorkbase,
 ) =>
 	Effect.gen(function* () {
 		if (options.opencode && options.claude) {
@@ -58,7 +64,8 @@ export const work = (
 		const phases = yield* PhaseService
 		const { log, verboseLog } = createLoggers(options)
 		const cwd = options.cwd ?? process.cwd()
-		const root = yield* workbase.discover(cwd)
+		const root = yield* resolveWorkbase(cwd, log, pickBase)
+		if (!root) return
 
 		let target: WorkTarget | null = null
 		if (options.epicId) {
@@ -201,7 +208,8 @@ export const help = `
 Usage: agency work [<task-id> [phase-id] | --epic <epic-id>]
 
 Launch an agent for the current epic, task, or phase. Outside an entity
-directory, select one with fzf.
+directory, select one with fzf. Outside a workbase, select a registered
+workbase first.
 
 Options:
   --epic <id>         Work on an epic

package/src/commands/workbase.test.ts

@@ -0,0 +1,62 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { join } from "node:path"
+import {
+	captureLogs,
+	cleanupTempDir,
+	createTempDir,
+	runTestEffect,
+} from "../test-utils"
+import { workbase } from "./workbase"
+
+describe("workbase command", () => {
+	let root: string
+	let configDirectory: string
+
+	beforeEach(async () => {
+		root = await createTempDir()
+		configDirectory = join(root, "config")
+		await Bun.write(join(root, "agency.json"), '{"version":2}\n')
+	})
+
+	afterEach(async () => cleanupTempDir(root))
+
+	test("adds and lists workbases as JSON", async () => {
+		const added = await captureLogs(() =>
+			runTestEffect(
+				workbase({
+					subcommand: "add",
+					args: [root],
+					configDirectory,
+					json: true,
+				}),
+			),
+		)
+		const path = JSON.parse(added[0]!).path
+
+		const listed = await captureLogs(() =>
+			runTestEffect(
+				workbase({
+					subcommand: "list",
+					args: [],
+					configDirectory,
+					json: true,
+				}),
+			),
+		)
+
+		expect(JSON.parse(listed[0]!)).toEqual([path])
+	})
+
+	test("requires an add path", async () => {
+		await expect(
+			runTestEffect(
+				workbase({
+					subcommand: "add",
+					args: [],
+					configDirectory,
+					silent: true,
+				}),
+			),
+		).rejects.toThrow("Usage: agency workbase add <path>")
+	})
+})

package/src/commands/workbase.ts

@@ -0,0 +1,58 @@
+import { Effect } from "effect"
+import type { BaseCommandOptions } from "../utils/command"
+import { WorkbaseService } from "../services/WorkbaseService"
+import { createLoggers } from "../utils/effect"
+
+interface WorkbaseOptions extends BaseCommandOptions {
+	readonly subcommand?: string
+	readonly args: readonly string[]
+	readonly configDirectory?: string
+}
+
+export const workbase = (options: WorkbaseOptions) =>
+	Effect.gen(function* () {
+		const service = yield* WorkbaseService
+		const { log } = createLoggers(options)
+
+		switch (options.subcommand) {
+			case "add": {
+				const path = options.args[0]
+				if (!path) {
+					return yield* Effect.fail(
+						new Error("Usage: agency workbase add <path>"),
+					)
+				}
+				const root = yield* service.register(path, options.configDirectory)
+				log(
+					options.json
+						? JSON.stringify({ path: root }, null, 2)
+						: `Added workbase ${root}`,
+				)
+				return
+			}
+			case "list": {
+				const workbases = yield* service.listRegistered(options.configDirectory)
+				if (options.json) {
+					log(JSON.stringify(workbases, null, 2))
+				} else {
+					for (const path of workbases) log(path)
+				}
+				return
+			}
+			default:
+				return yield* Effect.fail(
+					new Error("Subcommand is required. Available: add, list"),
+				)
+		}
+	})
+
+export const help = `
+Usage: agency workbase <subcommand>
+
+Subcommands:
+  add <path>  Register an Agency workbase
+  list        List registered workbases
+
+Options:
+  --json      Output results as JSON
+`

package/src/services/TaskPhaseService.test.ts

@@ -237,12 +237,12 @@ describe("task and phase services", () => {
 		const task = await runTestEffect(
 			TaskService.pipe(
 				Effect.flatMap((service) =>
-					service.setStatus("single-status", "done", root),
+					service.setStatus("single-status", "delegated", root),
 				),
 			),
 		)
-		expect(task.data.status).toBe("done")
-		expect(task.content).toContain("status: done")
+		expect(task.data.status).toBe("delegated")
+		expect(task.content).toContain("status: delegated")
 		expect(task.content).toContain("Describe the task outcome.")
 
 		await runTestEffect(

package/src/services/WorkbaseService.test.ts

@@ -1,7 +1,7 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test"
 import { Effect } from "effect"
 import { createHash } from "node:crypto"
-import { mkdir } from "node:fs/promises"
+import { mkdir, realpath } from "node:fs/promises"
 import { dirname, join } from "node:path"
 import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
 import { managedWorkbaseAgents } from "../workbase/agents-file"
@@ -56,6 +56,38 @@ describe("WorkbaseService", () => {
 		)
 	})
 
+	test("registers canonical workbase paths without duplicates", async () => {
+		const workbaseRoot = join(root, "workbase")
+		const nested = join(workbaseRoot, "nested")
+		const configDirectory = join(root, "config")
+		await write(workbaseRoot, "agency.json", '{"version":2}\n')
+		await mkdir(nested, { recursive: true })
+
+		const first = await runTestEffect(
+			WorkbaseService.pipe(
+				Effect.flatMap((service) => service.register(nested, configDirectory)),
+			),
+		)
+		await runTestEffect(
+			WorkbaseService.pipe(
+				Effect.flatMap((service) =>
+					service.register(workbaseRoot, configDirectory),
+				),
+			),
+		)
+		const registered = await runTestEffect(
+			WorkbaseService.pipe(
+				Effect.flatMap((service) => service.listRegistered(configDirectory)),
+			),
+		)
+
+		expect(first).toBe(await realpath(workbaseRoot))
+		expect(registered).toEqual([first])
+		expect(
+			await Bun.file(join(configDirectory, "agency/workbases.json")).json(),
+		).toEqual({ version: 1, workbases: [first] })
+	})
+
 	test("preserves an unmanaged workbase OpenCode config", async () => {
 		await write(root, "agency.json", '{"version":2}\n')
 		await write(root, ".opencode/opencode.jsonc", '{"model":"test/model"}\n')

package/src/services/WorkbaseService.ts

@@ -1,6 +1,7 @@
 import { Schema } from "@effect/schema"
 import { TreeFormatter } from "@effect/schema"
 import { Data, Effect, Either } from "effect"
+import { homedir } from "node:os"
 import { dirname, join, relative, resolve } from "node:path"
 import { FileSystemService } from "./FileSystemService"
 import { parseFrontmatter } from "../workbase/frontmatter"
@@ -9,6 +10,7 @@ import {
 	PhaseFrontmatter,
 	TaskFrontmatter,
 	WorkbaseConfig,
+	WorkbaseRegistry,
 	type Dependency,
 	type EpicFrontmatter as EpicData,
 	type PhaseFrontmatter as PhaseData,
@@ -34,6 +36,12 @@ class WorkbaseConfigError extends Data.TaggedError("WorkbaseConfigError")<{
 	readonly cause?: unknown
 }> {}
 
+class WorkbaseRegistryError extends Data.TaggedError("WorkbaseRegistryError")<{
+	readonly message: string
+	readonly path: string
+	readonly cause?: unknown
+}> {}
+
 interface ValidationIssue {
 	readonly path: string
 	readonly message: string
@@ -72,6 +80,45 @@ const decode = <S extends Schema.Schema.AnyNoContext>(
 		: { success: true, value: result.right }
 }
 
+const registryPath = (configDirectory?: string) =>
+	join(
+		configDirectory ||
+			process.env.XDG_CONFIG_HOME ||
+			join(homedir(), ".config"),
+		"agency",
+		"workbases.json",
+	)
+
+const readRegistry = (configDirectory?: string) =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystemService
+		const path = registryPath(configDirectory)
+		if (!(yield* fs.exists(path))) {
+			return { path, registry: { version: 1, workbases: [] } as const }
+		}
+
+		const content = yield* fs.readFile(path)
+		let input: unknown
+		try {
+			input = JSON.parse(content)
+		} catch (cause) {
+			return yield* new WorkbaseRegistryError({
+				path,
+				message: `Invalid JSON in workbase registry ${path}`,
+				cause,
+			})
+		}
+
+		const decoded = decode(WorkbaseRegistry, input)
+		if (!decoded.success) {
+			return yield* new WorkbaseRegistryError({
+				path,
+				message: `Invalid workbase registry in ${path}:\n${decoded.error}`,
+			})
+		}
+		return { path, registry: decoded.value }
+	})
+
 const ensureWorkbaseAgents = (root: string) =>
 	Effect.gen(function* () {
 		const fs = yield* FileSystemService
@@ -293,6 +340,28 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 					return { root, config: decoded.value }
 				}),
 
+			register: (startPath: string, configDirectory?: string) =>
+				Effect.gen(function* () {
+					const service = yield* WorkbaseService
+					const fs = yield* FileSystemService
+					const discovered = yield* service.discover(startPath)
+					const root = yield* fs.realPath(discovered)
+					const { path, registry } = yield* readRegistry(configDirectory)
+					if (registry.workbases.includes(root)) return root
+
+					yield* fs.createDirectory(dirname(path))
+					yield* fs.writeJSON(path, {
+						version: 1,
+						workbases: [...registry.workbases, root],
+					})
+					return root
+				}),
+
+			listRegistered: (configDirectory?: string) =>
+				readRegistry(configDirectory).pipe(
+					Effect.map(({ registry }) => registry.workbases),
+				),
+
 			validate: (startPath: string = process.cwd()) =>
 				Effect.gen(function* () {
 					const service = yield* WorkbaseService

package/src/workbase/schemas.test.ts

@@ -5,7 +5,9 @@ import {
 	EpicFrontmatter,
 	PhaseFrontmatter,
 	TaskFrontmatter,
+	WorkStatus,
 	WorkbaseConfig,
+	WorkbaseRegistry,
 } from "./schemas"
 
 describe("body-of-work descriptions", () => {
@@ -76,6 +78,14 @@ describe("body-of-work descriptions", () => {
 })
 
 describe("work status", () => {
+	const supportedStatuses: Record<WorkStatus, true> = {
+		open: true,
+		working: true,
+		delegated: true,
+		done: true,
+		dropped: true,
+	}
+
 	test("defaults execution units to open", () => {
 		const task = Schema.decodeUnknownSync(TaskFrontmatter)({
 			ticketUrl: "https://example.com/task",
@@ -95,17 +105,36 @@ describe("work status", () => {
 		expect(phase.status).toBe("open")
 	})
 
-	test("accepts supported statuses and rejects other values", () => {
-		const phase = Schema.decodeUnknownSync(PhaseFrontmatter)({
-			repo: "agency",
-			branch: "task/done",
-			base: "main",
-			pr: null,
-			status: "done",
-		})
-		expect(phase.status).toBe("done")
+	test("accepts every supported status on tasks and phases", () => {
+		for (const status of Object.keys(supportedStatuses) as WorkStatus[]) {
+			expect(Schema.decodeUnknownSync(WorkStatus)(status)).toBe(status)
+
+			const task = Schema.decodeUnknownSync(TaskFrontmatter)({
+				ticketUrl: null,
+				repo: "agency",
+				branch: `task/${status}`,
+				base: "main",
+				pr: null,
+				status,
+			})
+			const phase = Schema.decodeUnknownSync(PhaseFrontmatter)({
+				repo: "agency",
+				branch: `phase/${status}`,
+				base: "main",
+				pr: null,
+				status,
+			})
+
+			expect("status" in task && task.status).toBe(status)
+			expect(phase.status).toBe(status)
+		}
+	})
+
+	test("rejects unsupported statuses on tasks and phases", () => {
+		expect(() => Schema.decodeUnknownSync(WorkStatus)("blocked")).toThrow()
 		expect(() =>
-			Schema.decodeUnknownSync(PhaseFrontmatter)({
+			Schema.decodeUnknownSync(TaskFrontmatter)({
+				ticketUrl: null,
 				repo: "agency",
 				branch: "task/invalid",
 				base: "main",
@@ -113,6 +142,41 @@ describe("work status", () => {
 				status: "blocked",
 			}),
 		).toThrow()
+		expect(() =>
+			Schema.decodeUnknownSync(PhaseFrontmatter)({
+				repo: "agency",
+				branch: "phase/invalid",
+				base: "main",
+				pr: null,
+				status: "blocked",
+			}),
+		).toThrow()
+	})
+})
+
+describe("workbase registry", () => {
+	test("accepts registered paths", () => {
+		expect(
+			Schema.decodeUnknownSync(WorkbaseRegistry)({
+				version: 1,
+				workbases: ["/work/one", "/work/two"],
+			}),
+		).toEqual({ version: 1, workbases: ["/work/one", "/work/two"] })
+	})
+
+	test("rejects invalid versions and empty paths", () => {
+		expect(() =>
+			Schema.decodeUnknownSync(WorkbaseRegistry)({
+				version: 2,
+				workbases: [],
+			}),
+		).toThrow()
+		expect(() =>
+			Schema.decodeUnknownSync(WorkbaseRegistry)({
+				version: 1,
+				workbases: [""],
+			}),
+		).toThrow()
 	})
 })
 

package/src/workbase/schemas.ts

@@ -15,7 +15,13 @@ export const RepositoryReference = Schema.Struct({
 	ref: NonEmptyString,
 })
 
-export const WorkStatus = Schema.Literal("open", "working", "done", "dropped")
+export const WorkStatus = Schema.Literal(
+	"open",
+	"working",
+	"delegated",
+	"done",
+	"dropped",
+)
 
 const Url = NonEmptyString.pipe(Schema.pattern(/^[a-zA-Z][a-zA-Z0-9+.-]*:/))
 
@@ -28,6 +34,11 @@ export const WorkbaseConfig = Schema.Struct({
 	worktreeCreateCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
 })
 
+export const WorkbaseRegistry = Schema.Struct({
+	version: Schema.Literal(1),
+	workbases: Schema.Array(NonEmptyString),
+})
+
 export const Dependency = Schema.Struct({
 	id: EntityId,
 	dependsOn: Schema.optional(Schema.Array(EntityId)),
@@ -74,6 +85,7 @@ export const PhaseFrontmatter = Schema.Struct({
 })
 
 export type WorkbaseConfig = Schema.Schema.Type<typeof WorkbaseConfig>
+export type WorkbaseRegistry = Schema.Schema.Type<typeof WorkbaseRegistry>
 export type Dependency = Schema.Schema.Type<typeof Dependency>
 export type RepositoryReference = Schema.Schema.Type<typeof RepositoryReference>
 export type WorkStatus = Schema.Schema.Type<typeof WorkStatus>

package/src/workbase/work-target.test.ts

@@ -32,6 +32,11 @@ describe("work target choices", () => {
 					path: "/workbase/tasks/standalone/TASK.md",
 					data: { description: "Independent work" },
 				},
+				{
+					id: "delegated",
+					path: "/workbase/tasks/delegated/TASK.md",
+					data: { status: "delegated" },
+				},
 			],
 			[
 				{
@@ -63,6 +68,7 @@ describe("work target choices", () => {
 			"    \x1b[31m⊘\x1b[0m \x1b[33m󰔚\x1b[0m unlisted",
 			"  \x1b[32m✓\x1b[0m \x1b[36m󰗡\x1b[0m single",
 			"\x1b[2m○\x1b[0m \x1b[36m󰗡\x1b[0m standalone\x1b[2m - Independent work\x1b[0m",
+			"\x1b[35m↗\x1b[0m \x1b[36m󰗡\x1b[0m delegated",
 		])
 		expect(choices.map((choice) => choice.target.kind)).toEqual([
 			"epic",
@@ -72,6 +78,7 @@ describe("work target choices", () => {
 			"phase",
 			"task",
 			"task",
+			"task",
 		])
 	})
 })

package/src/workbase/work-target.ts

@@ -58,6 +58,7 @@ export interface WorkTargetChoice {
 const statusIcons: Record<WorkStatus, string> = {
 	open: "\x1b[2m○\x1b[0m",
 	working: "\x1b[34m◐\x1b[0m",
+	delegated: "\x1b[35m↗\x1b[0m",
 	done: "\x1b[32m✓\x1b[0m",
 	dropped: "\x1b[31m⊘\x1b[0m",
 }

package/src/workbase/workbase-choice.ts

@@ -0,0 +1,71 @@
+import { Effect } from "effect"
+import { resolve } from "node:path"
+import { FileSystemService } from "../services/FileSystemService"
+import { WorkbaseService } from "../services/WorkbaseService"
+
+export type PickWorkbase = (
+	workbases: readonly string[],
+) => Effect.Effect<string | null, Error>
+
+export const pickWorkbase: PickWorkbase = (workbases) =>
+	Effect.tryPromise({
+		try: async () => {
+			const input = workbases
+				.map((workbase, index) => `${index}\t${workbase}`)
+				.join("\n")
+			const process = Bun.spawn(
+				["fzf", "--delimiter=\t", "--with-nth=2..", "--prompt=Workbase> "],
+				{ stdin: new Blob([input]), stdout: "pipe", stderr: "inherit" },
+			)
+			const [exitCode, output] = await Promise.all([
+				process.exited,
+				new Response(process.stdout).text(),
+			])
+			if (exitCode === 1 || exitCode === 130) return null
+			if (exitCode !== 0) throw new Error(`fzf exited with code ${exitCode}`)
+			const index = Number.parseInt(output.split("\t", 1)[0] ?? "", 10)
+			return workbases[index] ?? null
+		},
+		catch: (cause) =>
+			new Error("Failed to select a workbase with fzf", { cause }),
+	})
+
+export const resolveWorkbase = (
+	startPath: string,
+	log: (message: string) => void,
+	pick: PickWorkbase = pickWorkbase,
+) =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystemService
+		const workbase = yield* WorkbaseService
+
+		return yield* workbase.discover(startPath).pipe(
+			Effect.catchTag("WorkbaseNotFoundError", () =>
+				Effect.gen(function* () {
+					const registered = yield* workbase.listRegistered()
+					if (registered.length === 0) {
+						return yield* Effect.fail(
+							new Error(
+								`No Agency workbase found from ${resolve(startPath)}. Register one with 'agency workbase add <path>'.`,
+							),
+						)
+					}
+
+					const fzf = yield* fs.runCommand(["which", "fzf"], {
+						captureOutput: true,
+					})
+					if (fzf.exitCode !== 0) {
+						for (const path of registered) log(path)
+						return yield* Effect.fail(
+							new Error(
+								"fzf is required to select a workbase; install fzf or run Agency from a registered workbase",
+							),
+						)
+					}
+
+					const selected = yield* pick(registered)
+					return selected ? yield* workbase.discover(selected) : null
+				}),
+			),
+		)
+	})