@markjaquith/agency 2.5.0 → 2.7.0

package/README.md

@@ -230,7 +230,7 @@ agency repo link backend ~/Dev/backend
 agency task new
 
 agency validate
-agency work refresh-copy
+agency work tasks/refresh-copy
 agency pr create refresh-copy
 ```
 
@@ -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
 
@@ -346,19 +350,21 @@ before moving files, refuses dirty worktrees, and preserves branches.
 ### Work and Pull Requests
 
 ```text
-agency work [<task-id> [phase-id] | --epic <epic-id>] [--opencode | --claude]
+agency work [<directory> | --epic <epic-id>] [--opencode | --claude]
 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.
+`agency work` presents the full hierarchy in `fzf`. Pass a directory, including
+`.` for the current directory, to infer its epic, task, or phase. Outside a
+workbase, Agency first presents the registered workbases, then the selected
+workbase's hierarchy. If `fzf` is not installed, Agency prints the available
+choices and asks for an explicit directory.
 
 Epic and multi-phase task targets launch orchestration agents beside their
 documents. Single-phase tasks and phases fetch repositories, create or reuse
 worktrees under `code/`, and launch an execution agent in the writable checkout
-with absolute context paths. Explicit task, phase, and `--epic` targets override
-current-directory inference.
+with absolute context paths. An explicit directory or `--epic` target bypasses
+the hierarchy chooser.
 
 Each writable `(repo, branch)` pair may belong to only one task or phase. Agency
 validation reports duplicate ownership, and `agency work` checks Git's worktree
@@ -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) {
@@ -221,11 +239,13 @@ const commands: Record<string, Command> = {
 				console.log(workHelp)
 				return
 			}
+			if (args.length > 1) {
+				throw new Error("Usage: agency work [<directory> | --epic <epic-id>]")
+			}
 
 			await runCommand(
 				work({
-					taskId: args[0],
-					phaseId: args[1],
+					directory: args[0],
 					epicId: options.epic,
 					silent: options.silent,
 					verbose: options.verbose,
@@ -251,13 +271,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,15 +296,16 @@ 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
   task <subcommand>      Manage tasks
-  work [task] [phase]    Work on an epic, task, or phase
+  work [directory]       Work on an epic, task, or phase
   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
@@ -294,7 +316,7 @@ Global Options:
 Examples:
   agency init                         # Initialize the current directory
   agency task list                    # List tasks
-  agency work refresh-cli-copy        # Start working on a task
+  agency work tasks/refresh-cli-copy  # Start working on a task
 
 For more information about a command, run:
   agency <command> --help

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "2.5.0",
+  "version": "2.7.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,27 +233,29 @@ 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
 
 ```bash
 agency work
-agency work <task-id> [phase-id]
+agency work <directory>
 agency work --epic <epic-id>
 ```
 
 Use `--opencode` or `--claude` to require a specific agent. This command fetches
 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.
+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.
 
 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/init.test.ts

@@ -39,6 +39,9 @@ describe("init command", () => {
 		expect(
 			await Bun.file(join(root, ".opencode/opencode.jsonc")).text(),
 		).toContain('"path": "../tasks"')
+		expect(
+			await Bun.file(join(root, ".opencode/opencode.jsonc")).text(),
+		).toContain(`"${join(root, "tasks")}/*": "allow"`)
 	})
 
 	test("preserves existing gitignore entries", async () => {

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