@markjaquith/agency 2.25.0 → 2.27.0

package/README.md

@@ -379,14 +379,24 @@ conditions remain visible in `warnings` or `unresolved` with a suggested action.
 agency init [path] [--json]
 agency workbase add <path> [--name <name>] [--json]
 agency workbase list [--json]
+agency workbase show <id|name|path> [--json]
+agency workbase name <id|name|path> <name> [--json]
+agency workbase name <id|name|path> --clear [--json]
 agency workbase remove <id|name|path> [--json]
 agency workbase prune [--json]
-agency workbase default [<id|name> | --clear] [--json]
+agency workbase default [<id|name|path> | --clear] [--json]
 agency integration status [--json]
 agency integration sync [--json]
 agency repo add <alias> <remote> [--json]
 agency repo link <alias> <path> [--json]
 agency repo list [--json]
+agency repo show <alias> [--json]
+agency repo fetch <alias> [--json]
+agency repo remove <alias> [--json]
+agency repo unlink <alias> [--json]
+agency repo rename <alias> <new-alias> [--json]
+agency repo remote <alias> [remote] [--json]
+agency repo verify <alias> [--json]
 ```
 
 Registered workbases are stored in
@@ -395,7 +405,9 @@ Each registration has a stable ID and may have a unique name. A default workbase
 is used when the current directory is outside every workbase. `prune` removes
 registrations whose workbase configuration no longer exists.
 `repo add` creates a bare clone. `repo link` creates a symlink to an existing Git
-repository. Alias names are then used by all documents and commands.
+repository. Alias names are then used by all documents and commands. Remove,
+unlink, and rename refuse aliases referenced by active work or backed by linked
+worktrees, and report each blocker.
 
 Commands that print Agency-owned results accept `--json`, including initialization,
 integration inspection/sync, repository mutations, entity creation/list/show,
@@ -598,6 +610,7 @@ for restoration. Archived IDs are reserved until restored.
 ```text
 agency work [<directory> | --epic <epic-id>] [--runner <name>] [--print-command]
 agency work prepare [target] [--dry-run] [--json]
+agency worktree <list|inspect|prepare|remove|rebuild|repair>
 agency pr create <task-id> [phase-id] [--draft] [--json]
 ```
 
@@ -617,6 +630,15 @@ Its JSON result includes document and checkout paths, resolved commits, actions,
 and Git operations. Use `--dry-run` to report planned fetch, branch, and worktree
 changes without applying them.
 
+`agency worktree list` and `inspect` report each declared checkout's expected and
+registered path, branch, commit, Agency owner, dirtiness, and conflicts. `prepare`
+is the explicit lifecycle form of `agency work prepare`. `remove`, `rebuild`, and
+`repair` preflight every writable and reference checkout before changing any of
+them and accept `--dry-run`. Removal preserves branches. Rebuild rejects dirty or
+conflicting worktrees. Repair is deliberately conservative: it repairs safe Git
+registration issues and materializes missing checkouts, but never switches a
+branch, resets a commit, or discards uncommitted work.
+
 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

package/cli.ts

@@ -7,6 +7,7 @@ import { init, help as initHelp } from "./src/commands/init"
 import { task, help as taskHelp } from "./src/commands/task"
 import { pr, help as prHelp } from "./src/commands/pr"
 import { work, workPrepare, help as workHelp } from "./src/commands/work"
+import { worktree, help as worktreeHelp } from "./src/commands/worktree"
 import { status, help as statusHelp } from "./src/commands/status"
 import { validate, help as validateHelp } from "./src/commands/validate"
 import { context, help as contextHelp } from "./src/commands/context"
@@ -470,6 +471,25 @@ const commands: Record<string, Command> = {
 			)
 		},
 	},
+	worktree: {
+		run: async (args: string[], options: Record<string, any>) => {
+			if (options.help) {
+				console.log(worktreeHelp)
+				return
+			}
+			await runCommand(
+				worktree({
+					subcommand: args[0],
+					args: args.slice(1),
+					dryRun: options["dry-run"],
+					json: options.json,
+					silent: options.silent,
+					verbose: options.verbose,
+					cwd: options.cwd,
+				}),
+			)
+		},
+	},
 	next: {
 		run: async (_args: string[], options: Record<string, any>) => {
 			if (options.help) return console.log(nextHelp)
@@ -607,6 +627,7 @@ Commands:
   archive <type>         Archive a work item
   task <subcommand>      Manage tasks
   work [directory|task]  Work on an epic, task, or phase
+  worktree <subcommand>  Inspect and maintain managed worktrees
   next                   List or select ready execution units
   pr create              Create a pull request for an execution unit
   repo <subcommand>      Manage workbase repositories

package/package.json

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

package/skills/agency/SKILL.md

@@ -65,7 +65,9 @@ Register and name known workbases so commands can select one from anywhere:
 ```bash
 agency workbase add <path> [--name <name>]
 agency workbase list
-agency workbase default [<id|name> | --clear]
+agency workbase show <id|name|path>
+agency workbase name <id|name|path> <name> | --clear
+agency workbase default [<id|name|path> | --clear]
 agency workbase remove <id|name|path>
 agency workbase prune
 ```
@@ -85,6 +87,13 @@ Link an existing local Git repository:
 
 ```bash
 agency repo link <alias> <path>
+agency repo show <alias>
+agency repo fetch <alias>
+agency repo remove <alias>
+agency repo unlink <alias>
+agency repo rename <alias> <new-alias>
+agency repo remote <alias> [remote]
+agency repo verify <alias>
 ```
 
 Use aliases, never absolute paths or Git URLs, in epic/task/phase frontmatter.

package/src/cli-parser.test.ts

@@ -121,6 +121,23 @@ describe("strict CLI parsing", () => {
 		expect(parseCli(["status", "--no-pr"]).values["no-pr"]).toBe(true)
 	})
 
+	test("parses addressable resource maintenance commands", () => {
+		for (const args of [
+			["repo", "show", "agency", "--json"],
+			["repo", "fetch", "agency"],
+			["repo", "remove", "agency"],
+			["repo", "unlink", "agency"],
+			["repo", "rename", "agency", "renamed"],
+			["repo", "remote", "agency", "https://example.com/repo.git"],
+			["repo", "verify", "agency"],
+			["workbase", "show", "primary", "--json"],
+			["workbase", "name", "primary", "renamed"],
+			["workbase", "name", "primary", "--clear"],
+		]) {
+			expect(() => parseCli(args)).not.toThrow()
+		}
+	})
+
 	test("validates view filter values and conflicts", () => {
 		expect(() => parseCli(["epic", "list", "--status", "invalid"])).toThrow(
 			"Invalid '--status' value",
@@ -387,6 +404,36 @@ describe("strict CLI parsing", () => {
 		)
 	})
 
+	test("parses worktree lifecycle commands and selectors", () => {
+		expect(parseCli(["worktree", "list", "--json"])).toMatchObject({
+			commandName: "worktree",
+			args: ["list"],
+			values: { json: true },
+		})
+		expect(
+			parseCli([
+				"worktree",
+				"rebuild",
+				"--task",
+				"example",
+				"--phase",
+				"verify",
+				"--dry-run",
+			]),
+		).toMatchObject({
+			commandName: "worktree",
+			args: ["rebuild", "example", "verify"],
+			values: { task: "example", phase: "verify", "dry-run": true },
+		})
+		expectUsageError(
+			["worktree", "inspect", "example", "--dry-run"],
+			"agency worktree inspect",
+		)
+		expect(() => parseCli(["worktree", "repair", "--phase", "verify"])).toThrow(
+			"requires '--task'",
+		)
+	})
+
 	test("accepts runner selection and command inspection for work", () => {
 		expect(
 			parseCli(["work", "example", "--runner", "custom", "--print-command"]),

package/src/cli-parser.ts

@@ -127,7 +127,7 @@ const commands = {
 		},
 	},
 	workbase: {
-		usage: "agency workbase <add|list|remove|prune|default>",
+		usage: "agency workbase <add|list|show|name|remove|prune|default>",
 		options: {
 			...outputOptions,
 			name: { type: "string" },
@@ -146,6 +146,18 @@ const commands = {
 				maxArgs: 0,
 				options: ["json"],
 			},
+			show: {
+				usage: "agency workbase show <selector> [--json]",
+				minArgs: 1,
+				maxArgs: 1,
+				options: ["json"],
+			},
+			name: {
+				usage: "agency workbase name <selector> <name> | --clear [--json]",
+				minArgs: 1,
+				maxArgs: 2,
+				options: ["json", "clear"],
+			},
 			remove: {
 				usage: "agency workbase remove <selector> [--json]",
 				minArgs: 1,
@@ -186,7 +198,8 @@ const commands = {
 		},
 	},
 	repo: {
-		usage: "agency repo <add|link|list>",
+		usage:
+			"agency repo <add|link|list|show|fetch|remove|unlink|rename|remote|verify>",
 		options: outputOptions,
 		subcommands: {
 			add: {
@@ -207,6 +220,48 @@ const commands = {
 				maxArgs: 0,
 				options: ["json"],
 			},
+			show: {
+				usage: "agency repo show <alias> [--json]",
+				minArgs: 1,
+				maxArgs: 1,
+				options: ["json"],
+			},
+			fetch: {
+				usage: "agency repo fetch <alias> [--json]",
+				minArgs: 1,
+				maxArgs: 1,
+				options: ["json"],
+			},
+			remove: {
+				usage: "agency repo remove <alias> [--json]",
+				minArgs: 1,
+				maxArgs: 1,
+				options: ["json"],
+			},
+			unlink: {
+				usage: "agency repo unlink <alias> [--json]",
+				minArgs: 1,
+				maxArgs: 1,
+				options: ["json"],
+			},
+			rename: {
+				usage: "agency repo rename <alias> <new-alias> [--json]",
+				minArgs: 2,
+				maxArgs: 2,
+				options: ["json"],
+			},
+			remote: {
+				usage: "agency repo remote <alias> [remote] [--json]",
+				minArgs: 1,
+				maxArgs: 2,
+				options: ["json"],
+			},
+			verify: {
+				usage: "agency repo verify <alias> [--json]",
+				minArgs: 1,
+				maxArgs: 1,
+				options: ["json"],
+			},
 		},
 	},
 	epic: {
@@ -616,6 +671,56 @@ const commands = {
 			},
 		},
 	},
+	worktree: {
+		usage: "agency worktree <list|inspect|prepare|remove|rebuild|repair>",
+		options: {
+			...outputOptions,
+			...entitySelectorOptions,
+			"dry-run": { type: "boolean" },
+		},
+		subcommands: {
+			list: {
+				usage: "agency worktree list [--json]",
+				minArgs: 0,
+				maxArgs: 0,
+				options: ["json"],
+			},
+			inspect: {
+				usage: "agency worktree inspect <task-id> [phase-id] [--json]",
+				minArgs: 1,
+				maxArgs: 2,
+				options: ["json", "task", "phase"],
+			},
+			prepare: {
+				usage:
+					"agency worktree prepare <task-id> [phase-id] [--dry-run] [--json]",
+				minArgs: 1,
+				maxArgs: 2,
+				options: ["dry-run", "json", "task", "phase"],
+			},
+			remove: {
+				usage:
+					"agency worktree remove <task-id> [phase-id] [--dry-run] [--json]",
+				minArgs: 1,
+				maxArgs: 2,
+				options: ["dry-run", "json", "task", "phase"],
+			},
+			rebuild: {
+				usage:
+					"agency worktree rebuild <task-id> [phase-id] [--dry-run] [--json]",
+				minArgs: 1,
+				maxArgs: 2,
+				options: ["dry-run", "json", "task", "phase"],
+			},
+			repair: {
+				usage:
+					"agency worktree repair <task-id> [phase-id] [--dry-run] [--json]",
+				minArgs: 1,
+				maxArgs: 2,
+				options: ["dry-run", "json", "task", "phase"],
+			},
+		},
+	},
 	work: {
 		usage:
 			"agency work [<directory-or-task-id> | --epic <epic-id>] [--runner <name>] | agency work prepare [target] [--dry-run] [--json]",
@@ -847,6 +952,9 @@ const targetSlots = (
 				: subcommand === "phase"
 					? ["task", "phase"]
 					: []
+	if (commandName === "worktree" && subcommand !== "list") {
+		return ["task", "phase"]
+	}
 	if (commandName === "pr" && subcommand === "create") return ["task", "phase"]
 	return []
 }

package/src/cli.test.ts

@@ -692,6 +692,40 @@ status: open
 			await runCli(["task", "show", "example", "--json"], root),
 		)
 		expect(task.data.status).toBe("open")
+
+		const listed = parseJson(await runCli(["worktree", "list", "--json"], root))
+		expect(listed).toEqual([
+			expect.objectContaining({
+				owner: expect.objectContaining({ kind: "task", taskId: "example" }),
+				checkouts: [
+					expect.objectContaining({
+						repo: "agency",
+						kind: "writable",
+						registered: true,
+						actualBranch: "feat/example",
+						actualCommit: expect.stringMatching(/^[0-9a-f]{40}$/),
+						dirty: false,
+					}),
+				],
+			}),
+		])
+		const rebuild = parseJson(
+			await runCli(
+				["worktree", "rebuild", "example", "--dry-run", "--json"],
+				root,
+			),
+		)
+		expect(rebuild).toMatchObject({
+			operation: "rebuild",
+			dryRun: true,
+			actions: [
+				`remove ${join(workbaseRoot, "tasks/example/code/agency")}`,
+				`create ${join(workbaseRoot, "tasks/example/code/agency")}`,
+			],
+		})
+		expect(
+			await Bun.file(join(root, "tasks/example/code/agency/README.md")).text(),
+		).toBe("example\n")
 	})
 
 	test("envelopes help and version output in machine mode", async () => {

package/src/commands/repo.test.ts

@@ -52,6 +52,21 @@ describe("repo command", () => {
 		])
 	})
 
+	test("shows a repository by alias as JSON", async () => {
+		const logs = await captureLogs(() =>
+			runTestEffect(
+				repo({
+					subcommand: "show",
+					args: ["agency"],
+					cwd: root,
+					json: true,
+				}),
+			),
+		)
+
+		expect(JSON.parse(logs[0]!).alias).toBe("agency")
+	})
+
 	test("outputs a linked repository as JSON", async () => {
 		const target = join(root, "source")
 		await mkdir(target)
@@ -77,4 +92,33 @@ describe("repo command", () => {
 			path: join(root, "repos/linked"),
 		})
 	})
+
+	test("unlinks a linked repository by alias", async () => {
+		const target = join(root, "unlink-source")
+		await mkdir(target)
+		const git = Bun.spawn(["git", "init", target], {
+			stdout: "ignore",
+			stderr: "ignore",
+		})
+		expect(await git.exited).toBe(0)
+		await runTestEffect(
+			repo({
+				subcommand: "link",
+				args: ["linked", target],
+				cwd: root,
+				silent: true,
+			}),
+		)
+
+		await runTestEffect(
+			repo({
+				subcommand: "unlink",
+				args: ["linked"],
+				cwd: root,
+				silent: true,
+			}),
+		)
+
+		expect(await Bun.file(join(target, ".git/HEAD")).exists()).toBe(true)
+	})
 })

package/src/commands/repo.ts

@@ -9,6 +9,9 @@ interface RepoOptions extends BaseCommandOptions {
 	readonly json?: boolean
 }
 
+const requireArg = (args: readonly string[], index: number, usage: string) =>
+	args[index] ? Effect.succeed(args[index]) : Effect.fail(new Error(usage))
+
 export const repo = (options: RepoOptions) =>
 	Effect.gen(function* () {
 		const repositories = yield* RepositoryService
@@ -61,10 +64,106 @@ export const repo = (options: RepoOptions) =>
 				return
 			}
 
+			case "show": {
+				const alias = yield* requireArg(
+					options.args,
+					0,
+					"Usage: agency repo show <alias>",
+				)
+				const item = yield* repositories.show(alias, cwd)
+				log(
+					options.json
+						? JSON.stringify(item, null, 2)
+						: `${item.alias}\t${item.kind}\t${item.target ?? item.remote ?? item.path}`,
+				)
+				return
+			}
+
+			case "fetch": {
+				const alias = yield* requireArg(
+					options.args,
+					0,
+					"Usage: agency repo fetch <alias>",
+				)
+				const item = yield* repositories.fetch(alias, cwd)
+				log(options.json ? JSON.stringify(item, null, 2) : `Fetched '${alias}'`)
+				return
+			}
+
+			case "remove":
+			case "unlink": {
+				const alias = yield* requireArg(
+					options.args,
+					0,
+					`Usage: agency repo ${options.subcommand} <alias>`,
+				)
+				const item = yield* repositories[options.subcommand](alias, cwd)
+				log(
+					options.json
+						? JSON.stringify(item, null, 2)
+						: `${options.subcommand === "unlink" ? "Unlinked" : "Removed"} '${alias}'`,
+				)
+				return
+			}
+
+			case "rename": {
+				const alias = yield* requireArg(
+					options.args,
+					0,
+					"Usage: agency repo rename <alias> <new-alias>",
+				)
+				const newAlias = yield* requireArg(
+					options.args,
+					1,
+					"Usage: agency repo rename <alias> <new-alias>",
+				)
+				const item = yield* repositories.rename(alias, newAlias, cwd)
+				log(
+					options.json
+						? JSON.stringify(item, null, 2)
+						: `Renamed '${alias}' to '${newAlias}'`,
+				)
+				return
+			}
+
+			case "remote": {
+				const alias = yield* requireArg(
+					options.args,
+					0,
+					"Usage: agency repo remote <alias> [remote]",
+				)
+				const item = yield* repositories.remote(alias, options.args[1], cwd)
+				log(
+					options.json
+						? JSON.stringify(item, null, 2)
+						: (item.remote ?? "No origin remote configured"),
+				)
+				return
+			}
+
+			case "verify": {
+				const alias = yield* requireArg(
+					options.args,
+					0,
+					"Usage: agency repo verify <alias>",
+				)
+				const report = yield* repositories.verify(alias, cwd)
+				if (options.json) log(JSON.stringify(report, null, 2))
+				if (!report.valid) {
+					return yield* Effect.fail(
+						new Error(
+							`Repository '${alias}' verification failed:\n${report.issues.map((issue) => `- ${issue}`).join("\n")}`,
+						),
+					)
+				}
+				if (!options.json) log(`Verified repository '${alias}'`)
+				return
+			}
+
 			default:
 				return yield* Effect.fail(
 					new Error(
-						"Subcommand is required. Available subcommands: add, link, list",
+						"Subcommand is required. Available subcommands: add, link, list, show, fetch, remove, unlink, rename, remote, verify",
 					),
 				)
 		}
@@ -77,6 +176,13 @@ Subcommands:
   add <alias> <remote>  Create a bare clone
   link <alias> <path>   Link an existing Git repository
   list                  List repository aliases
+  show <alias>          Show a repository alias
+  fetch <alias>         Fetch and prune a repository
+  remove <alias>        Remove an unused repository alias
+  unlink <alias>        Remove an unused linked alias
+  rename <old> <new>    Rename an unused repository alias
+  remote <alias> [url]  Show or update the origin remote
+  verify <alias>        Verify repository operation
 
 Options:
   --json                Output repository aliases as JSON

package/src/commands/workbase.test.ts

@@ -108,6 +108,53 @@ describe("workbase command", () => {
 		).toEqual({ version: 2, workbases: [] })
 	})
 
+	test("names, shows, and clears a workbase name", async () => {
+		const added = await captureLogs(() =>
+			runTestEffect(
+				workbase({
+					subcommand: "add",
+					args: [root],
+					configDirectory,
+					json: true,
+				}),
+			),
+		)
+		const registration = JSON.parse(added[0]!)
+		await runTestEffect(
+			workbase({
+				subcommand: "name",
+				args: [registration.id, "primary"],
+				configDirectory,
+				silent: true,
+			}),
+		)
+
+		const shown = await captureLogs(() =>
+			runTestEffect(
+				workbase({
+					subcommand: "show",
+					args: ["primary"],
+					configDirectory,
+					json: true,
+				}),
+			),
+		)
+		expect(JSON.parse(shown[0]!).name).toBe("primary")
+
+		await runTestEffect(
+			workbase({
+				subcommand: "name",
+				args: [registration.id],
+				clear: true,
+				configDirectory,
+				silent: true,
+			}),
+		)
+		expect(
+			await Bun.file(join(configDirectory, "agency/workbases.json")).json(),
+		).toEqual({ version: 2, workbases: [registration] })
+	})
+
 	test("requires an add path", async () => {
 		await expect(
 			runTestEffect(