@markjaquith/agency 3.11.0 → 3.13.0

package/README.md

@@ -184,8 +184,50 @@ existing Git repositories.
 Existing version 2 workbases without `repositories` remain valid. Run
 `agency repo setup` to preview deterministic adoption of legacy local aliases;
 `agency repo setup --apply` writes declarations only when a portable origin is
-unambiguous. Workbase configuration may also provide a custom writable-worktree
-creation command.
+unambiguous. Workbase configuration may also provide custom writable-worktree
+creation and removal commands.
+
+### Custom Branch Names
+
+Set `branchNameCommand` to an argv template to choose the branch recorded for a
+new execution unit when `--branch` is omitted:
+
+```json
+{
+	"version": 2,
+	"branchNameCommand": ["wt-resolve-new-branch-name", "{ticket}"]
+}
+```
+
+Agency invokes the command directly, without a shell, from the workbase root and
+uses its trimmed stdout as the branch name. The command has 120 seconds to
+finish. A non-zero exit, empty output, timeout, or output rejected by
+`git check-ref-format --branch` fails creation without falling back. Explicit
+`--branch` always wins. Multi-phase task containers and review tasks do not have
+writable branches and therefore do not invoke this command.
+
+Available placeholders are:
+
+| Placeholder      | Value                                              |
+| ---------------- | -------------------------------------------------- |
+| `{id}`           | ID of the task or phase being created              |
+| `{ticket}`       | Task ticket URL, or `{id}` when there is no ticket |
+| `{ticketUrl}`    | Task ticket URL, or an empty string when absent    |
+| `{repo}`         | Writable repository alias                          |
+| `{base}`         | Base branch                                        |
+| `{workbaseRoot}` | Absolute workbase root                             |
+| `{taskId}`       | Task ID                                            |
+| `{phaseId}`      | Phase ID, or an empty string when creating a task  |
+
+Resolver failures are reported with the `BRANCH_NAME_COMMAND_FAILED` error code
+in JSON output.
+
+Matching `AGENCY_ID`, `AGENCY_TICKET`, `AGENCY_TICKET_URL`, `AGENCY_REPO`,
+`AGENCY_BASE`, `AGENCY_WORKBASE_ROOT`, `AGENCY_TASK_ID`, and `AGENCY_PHASE_ID`
+environment variables are also set. Without `branchNameCommand`, task branches
+remain `task/<id>` and phase branches default to `task/<task-id>-<phase-id>`.
+Callers should omit `--branch` when they want the workbase policy; do not pass a
+hard-coded value merely to reproduce Agency's built-in default.
 
 ### Custom Worktree Command
 
@@ -257,6 +299,43 @@ The configured command applies only to the writable checkout.
 Supplemental read-only repositories remain detached Git worktrees at their
 declared refs so they do not acquire writable branches.
 
+### Custom Worktree Remove Command
+
+Git workbases remove worktrees with `git worktree remove`. Set
+`worktreeRemoveCommand` to an argv template when another tool should remove
+writable worktrees:
+
+```json
+{
+	"version": 2,
+	"worktreeRemoveCommand": [
+		"wt",
+		"-C",
+		"{repo}",
+		"-y",
+		"remove",
+		"{worktree}",
+		"--no-delete-branch",
+		"--foreground",
+		"--format",
+		"json"
+	]
+}
+```
+
+It accepts the same placeholders and environment variables as
+`worktreeCreateCommand`, and `{repo}` and `{worktree}` are required. Agency
+invokes it directly without a shell whenever it removes an existing writable
+checkout, including `agency worktree remove`, rebuilds, archives, and rollback
+of a failed materialization. Agency still refuses dirty or mismatched checkouts
+before running the command.
+
+The command must remove the checkout synchronously, unregister it from Git, and
+preserve the execution branch; Agency verifies all three afterward. Rollback of
+a newly created checkout may delete the branch because Agency discards it
+anyway. Reference checkouts and stale registrations are still removed or pruned
+with Git.
+
 ### Post-checkout Commands
 
 Each repository declaration may provide a `postCheckoutCommand` argv

package/package.json

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

package/src/act-schema.ts

@@ -49,6 +49,19 @@ const EntityFields = {
 }
 
 export const ActDiscovery = Schema.Struct({
+	creationDefaults: Schema.Struct({
+		branch: Schema.Union(
+			Schema.Struct({
+				configured: Schema.Literal(true),
+				guidance: Schema.String,
+			}),
+			Schema.Struct({
+				configured: Schema.Literal(false),
+				task: Schema.String,
+				phase: Schema.String,
+			}),
+		),
+	}),
 	workbase: Schema.Struct({
 		root: Schema.String,
 		repositories: Argv,

package/src/cli-parser.ts

@@ -573,7 +573,7 @@ const commands = {
 		subcommands: {
 			new: {
 				usage:
-					"agency phase new <task-id> <phase-id> --repo <alias> --branch <name> --base <name> [options] [--work [--auto]]",
+					"agency phase new <task-id> <phase-id> --repo <alias> --base <name> [--branch <name>] [options] [--work [--auto]]",
 				minArgs: 2,
 				maxArgs: 2,
 				options: [
@@ -596,7 +596,7 @@ const commands = {
 			},
 			create: {
 				usage:
-					"agency phase create <task-id> <phase-id> --repo <alias> --branch <name> --base <name> [options]",
+					"agency phase create <task-id> <phase-id> --repo <alias> --base <name> [--branch <name>] [options]",
 				minArgs: 2,
 				maxArgs: 2,
 				options: [

package/src/commands/act.ts

@@ -160,6 +160,21 @@ const shellCommand = (argv: readonly string[]) =>
 				: `'${arg.replaceAll("'", `'\\''`)}'`,
 		)
 		.join(" ")
+const creationDefaults = (config: {
+	readonly branchNameCommand?: readonly string[]
+}) => ({
+	branch: config.branchNameCommand
+		? {
+				configured: true as const,
+				guidance:
+					"Omit --branch to use the workbase branchNameCommand; pass it only for an explicit override.",
+			}
+		: {
+				configured: false as const,
+				task: "task/<id>",
+				phase: "task/<task-id>-<phase-id>",
+			},
+})
 const available = (action: ActAction) => !action.blockedReason
 const checkoutState = (inspection: {
 	readonly checkouts: readonly {
@@ -463,6 +478,7 @@ const actStep = (
 			log(
 				JSON.stringify(
 					yield* Schema.decodeUnknown(ActDiscovery)({
+						creationDefaults: creationDefaults(config),
 						workbase: {
 							root,
 							repositories: graph.nodes
@@ -772,6 +788,8 @@ or exits from the front screen; Ctrl-C quits. A recap is printed when you exit.
 An existing directory or file selects its containing epic, task, or phase.
 A workbase path opens Workbase actions. Otherwise the positional value is a
 task ID. Selectors skip item selection.
+JSON discovery includes creation defaults identifying when callers should omit
+--branch so the workbase branchNameCommand can choose it.
 
 Options:
   --action <id>         Start an action or filter discovery (IDs from --json)

package/src/commands/phase.ts

@@ -7,6 +7,8 @@ import { getWorkViews } from "../work-view"
 import { parseRepositoryReferences } from "../workbase/repository-reference"
 import { GraphMutationService } from "../services/GraphMutationService"
 import { work as startWork, type StartWork } from "./work"
+import { TaskService } from "../services/TaskService"
+import { resolveBranchName } from "../workbase/branch-name-command"
 
 interface PhaseOptions extends BaseCommandOptions {
 	readonly subcommand?: string
@@ -39,6 +41,7 @@ interface PhaseOptions extends BaseCommandOptions {
 export const phase = (options: PhaseOptions, work: StartWork = startWork) =>
 	Effect.gen(function* () {
 		const phases = yield* PhaseService
+		const tasks = yield* TaskService
 		const mutations = yield* GraphMutationService
 		const { log } = createLoggers(options)
 		const cwd = options.cwd ?? process.cwd()
@@ -47,19 +50,26 @@ export const phase = (options: PhaseOptions, work: StartWork = startWork) =>
 		switch (options.subcommand) {
 			case "new":
 			case "create": {
-				if (
-					!taskId ||
-					!phaseId ||
-					!options.repo ||
-					!options.branch ||
-					!options.base
-				) {
+				if (!taskId || !phaseId || !options.repo || !options.base) {
 					return yield* Effect.fail(
 						new Error(
-							"Usage: agency phase create <task-id> <phase-id> --repo <alias> --branch <name> --base <name>",
+							"Usage: agency phase create <task-id> <phase-id> --repo <alias> --base <name> [--branch <name>]",
 						),
 					)
 				}
+				const parent = yield* tasks.show(taskId, cwd)
+				const branch =
+					options.branch ??
+					(yield* resolveBranchName({
+						id: phaseId,
+						taskId,
+						phaseId,
+						ticketUrl: parent.data.ticketUrl,
+						repo: options.repo,
+						base: options.base,
+						defaultBranch: `task/${taskId}-${phaseId}`,
+						startPath: cwd,
+					}))
 				const record = yield* phases.create(
 					{
 						taskId,
@@ -67,7 +77,7 @@ export const phase = (options: PhaseOptions, work: StartWork = startWork) =>
 						description: options.description,
 						repo: options.repo,
 						repos: parseRepositoryReferences(options.references),
-						branch: options.branch,
+						branch,
 						base: options.base,
 						dependsOn: options.dependsOn,
 						firstPhase: options.firstPhase,
@@ -311,7 +321,7 @@ Create options:
   --repo <alias>        Writable repository
   --reference <alias>:<ref>
                         Read-only repository reference; repeatable
-  --branch <name>       Working branch
+  --branch <name>       Working branch (default: configured resolver or task/<task>-<phase>)
   --base <name>         Base branch
   --depends-on <id>     Phase dependency; repeatable
   --first-phase <id>    Existing execution phase ID when converting a task

package/src/commands/task.ts

@@ -16,6 +16,7 @@ import {
 	buildValidationEvidence,
 	normalizeRecalledContext,
 } from "../workbase/execution-contract"
+import { resolveBranchName } from "../workbase/branch-name-command"
 
 interface TaskOptions extends BaseCommandOptions {
 	readonly subcommand?: string
@@ -188,6 +189,19 @@ export const task = (
 					}
 				}
 
+				const base = options.base ?? "main"
+				const branch =
+					multiPhase || options.branch
+						? options.branch
+						: yield* resolveBranchName({
+								id,
+								taskId: id,
+								ticketUrl,
+								repo: repo!,
+								base,
+								defaultBranch: `task/${id}`,
+								startPath: cwd,
+							})
 				const record = yield* tasks.create(
 					{
 						id,
@@ -197,8 +211,8 @@ export const task = (
 						multiPhase,
 						repo,
 						repos: parseRepositoryReferences(options.references),
-						branch: multiPhase ? undefined : (options.branch ?? `task/${id}`),
-						base: multiPhase ? undefined : (options.base ?? "main"),
+						branch: multiPhase ? undefined : branch,
+						base: multiPhase ? undefined : base,
 						purpose: options.purpose as "investigation" | undefined,
 					},
 					cwd,
@@ -275,10 +289,23 @@ export const task = (
 							cwd,
 						)
 					: undefined
+				const ticketUrl = options.ticketUrl?.trim() || null
+				const branch =
+					multiPhase || review || options.branch
+						? options.branch
+						: yield* resolveBranchName({
+								id,
+								taskId: id,
+								ticketUrl,
+								repo: repo!,
+								base,
+								defaultBranch: `task/${id}`,
+								startPath: cwd,
+							})
 				const record = yield* tasks.create(
 					{
 						id,
-						ticketUrl: options.ticketUrl?.trim() || null,
+						ticketUrl,
 						description: options.description?.trim() || undefined,
 						epic: options.epic,
 						multiPhase,
@@ -287,10 +314,7 @@ export const task = (
 						repos: review
 							? undefined
 							: parseRepositoryReferences(options.references),
-						branch:
-							multiPhase || review
-								? undefined
-								: (options.branch ?? `task/${id}`),
+						branch: multiPhase || review ? undefined : branch,
 						base: multiPhase || review ? undefined : base,
 						purpose: options.purpose as "investigation" | undefined,
 					},
@@ -337,18 +361,31 @@ export const task = (
 						new Error("Writable repository is required for task handoff"),
 					)
 				}
+				const ticketUrl = options.ticketUrl?.trim() || null
+				const base = options.base ?? "main"
+				const branch =
+					options.branch ??
+					(yield* resolveBranchName({
+						id,
+						taskId: id,
+						ticketUrl,
+						repo: options.repo,
+						base,
+						defaultBranch: `task/${id}`,
+						startPath: cwd,
+					}))
 				const output = yield* tasks.handoff(
 					{
 						sourceTaskId,
 						sourcePhaseId: options.sourcePhase,
 						id,
-						ticketUrl: options.ticketUrl?.trim() || null,
+						ticketUrl,
 						description: options.description?.trim() || undefined,
 						epic: options.epic,
 						repo: options.repo,
 						repos: parseRepositoryReferences(options.references),
-						branch: options.branch ?? `task/${id}`,
-						base: options.base ?? "main",
+						branch,
+						base,
 					},
 					cwd,
 				)
@@ -591,7 +628,7 @@ Create options:
   --repo <alias>        Writable repository
   --reference <alias>:<ref>
                         Read-only repository reference; repeatable
-  --branch <name>       Working branch (default: task/<id>)
+  --branch <name>       Working branch (default: configured resolver or task/<id>)
   --base <name>         Base branch (default: main)
 	--context-repo <alias> Recalled repository; must agree with --repo
 	--context-base <name>  Recalled base; must agree with --base

package/src/protocol.ts

@@ -113,6 +113,12 @@ const errorMetadata: Readonly<Record<string, ErrorMetadata>> = {
 		retryable: false,
 		remediation: "Resolve workbase validation errors before reconciling.",
 	},
+	BranchNameCommandError: {
+		code: "BRANCH_NAME_COMMAND_FAILED",
+		retryable: false,
+		remediation:
+			"Fix the workbase branchNameCommand or pass an explicit --branch.",
+	},
 	ProcessError: { code: "PROCESS_ERROR", retryable: true },
 	ProtocolOutputError: {
 		code: "PROTOCOL_OUTPUT_ERROR",

package/src/services/DoctorService.ts

@@ -172,6 +172,15 @@ export class DoctorService extends Effect.Service<DoctorService>()(
 									] as const,
 								]
 							: []),
+						...(config.worktreeRemoveCommand
+							? [
+									[
+										"integration.worktree-remove",
+										config.worktreeRemoveCommand,
+										"Worktree remover",
+									] as const,
+								]
+							: []),
 						...Object.entries(config.repositories ?? {}).flatMap(
 							([alias, repository]) =>
 								repository.postCheckoutCommand

package/src/services/WorkbaseService.ts

@@ -20,8 +20,9 @@ import {
 	type WorkbaseRegistry as WorkbaseRegistryData,
 	type WorkbaseRegistration,
 } from "../workbase/schemas"
-import { validateWorktreeCreateCommand } from "../workbase/worktree-command"
+import { validateWorktreeCommand } from "../workbase/worktree-command"
 import { validatePostCheckoutCommand } from "../workbase/checkout-command"
+import { validateBranchNameCommand } from "../workbase/branch-name-template"
 import { validateAgents } from "../workbase/agent-command"
 import { findDependencyCycles } from "../workbase/dependency-graph"
 import { validateDelivery } from "../workbase/delivery-command"
@@ -314,18 +315,34 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 										message: `Invalid workbase configuration in ${configPath}:\n${decoded.error}`,
 									})
 								}
-								if (decoded.value.worktreeCreateCommand) {
+								for (const setting of [
+									"worktreeCreateCommand",
+									"worktreeRemoveCommand",
+								] as const) {
+									const command = decoded.value[setting]
+									if (!command) continue
 									try {
-										validateWorktreeCreateCommand(
-											decoded.value.worktreeCreateCommand,
-										)
+										validateWorktreeCommand(setting, command)
 									} catch (cause) {
 										return yield* new WorkbaseConfigError({
 											path: configPath,
 											message:
 												cause instanceof Error
 													? cause.message
-													: "Invalid worktreeCreateCommand",
+													: `Invalid ${setting}`,
+										})
+									}
+								}
+								if (decoded.value.branchNameCommand) {
+									try {
+										validateBranchNameCommand(decoded.value.branchNameCommand)
+									} catch (cause) {
+										return yield* new WorkbaseConfigError({
+											path: configPath,
+											message:
+												cause instanceof Error
+													? cause.message
+													: "Invalid branchNameCommand",
 										})
 									}
 								}

package/src/services/WorktreeService.ts

@@ -5,7 +5,7 @@ import { WorkbaseService } from "./WorkbaseService"
 import { TaskService } from "./TaskService"
 import { PhaseService } from "./PhaseService"
 import {
-	expandWorktreeCreateCommand,
+	expandWorktreeCommand,
 	worktreeCommandEnvironment,
 } from "../workbase/worktree-command"
 import {
@@ -258,6 +258,105 @@ const runPostCheckoutHook = (options: {
 		})
 	})
 
+const runWorktreeRemoveCommand = (options: {
+	readonly command: readonly string[]
+	readonly alias: string
+	readonly repositoryPath: string
+	readonly checkoutPath: string
+	readonly branch: string
+	readonly base: string
+	readonly preserveBranch: boolean
+	readonly forwardOutput: boolean
+	readonly verboseLog: (...args: unknown[]) => void
+}) =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystemService
+		const variables = {
+			repo: options.repositoryPath,
+			worktree: options.checkoutPath,
+			branch: options.branch,
+			base: options.base,
+		}
+		let args: string[]
+		try {
+			args = expandWorktreeCommand(
+				"worktreeRemoveCommand",
+				options.command,
+				variables,
+			)
+		} catch (cause) {
+			return yield* new WorktreeError({
+				message:
+					cause instanceof Error
+						? cause.message
+						: "Invalid worktreeRemoveCommand",
+			})
+		}
+		const canonicalCheckoutPath = yield* fs.realPath(options.checkoutPath)
+		options.verboseLog(
+			`Running worktree remove command: ${formatCommand(args)}`,
+		)
+		const result = yield* fs.runCommand(args, {
+			cwd: options.repositoryPath,
+			captureOutput: true,
+			forwardOutput: options.forwardOutput,
+			env: worktreeCommandEnvironment(variables),
+		})
+		if (result.exitCode !== 0) {
+			return yield* new WorktreeError({
+				message: `Failed to remove worktree for '${options.alias}': ${result.stderr}`,
+			})
+		}
+		if (yield* fs.exists(options.checkoutPath)) {
+			return yield* new WorktreeError({
+				message: `Worktree remove command did not remove ${options.checkoutPath}`,
+			})
+		}
+		const listed = yield* fs.runCommand(
+			[
+				"git",
+				"-C",
+				options.repositoryPath,
+				"worktree",
+				"list",
+				"--porcelain",
+				"-z",
+			],
+			{ captureOutput: true },
+		)
+		if (
+			listed.exitCode !== 0 ||
+			parseWorktreeList(listed.stdout).some(
+				(worktree) =>
+					resolve(worktree.path) === canonicalCheckoutPath ||
+					resolve(worktree.path) === resolve(options.checkoutPath),
+			)
+		) {
+			return yield* new WorktreeError({
+				message: `Worktree remove command left ${options.checkoutPath} registered as a Git worktree`,
+			})
+		}
+		if (options.preserveBranch) {
+			const branchExists = yield* fs.runCommand(
+				[
+					"git",
+					"-C",
+					options.repositoryPath,
+					"show-ref",
+					"--verify",
+					"--quiet",
+					`refs/heads/${options.branch}`,
+				],
+				{ captureOutput: true },
+			)
+			if (branchExists.exitCode !== 0) {
+				return yield* new WorktreeError({
+					message: `Worktree remove command deleted branch '${options.branch}' in repository '${options.alias}'; it must preserve the branch`,
+				})
+			}
+		}
+	})
+
 const isCommitId = (ref: string) => /^[0-9a-f]{40,64}$/i.test(ref)
 
 const originRef = (ref: string) =>
@@ -1083,12 +1182,16 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 								}
 								if (config.worktreeCreateCommand) {
 									try {
-										expandWorktreeCreateCommand(config.worktreeCreateCommand, {
-											repo: repositoryPath,
-											worktree: checkoutPath,
-											branch: checkout.branch,
-											base: executionBase,
-										})
+										expandWorktreeCommand(
+											"worktreeCreateCommand",
+											config.worktreeCreateCommand,
+											{
+												repo: repositoryPath,
+												worktree: checkoutPath,
+												branch: checkout.branch,
+												base: executionBase,
+											},
+										)
 									} catch (cause) {
 										return yield* new WorktreeError({
 											message:
@@ -1364,7 +1467,8 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 											base: executionBase,
 										}
 										try {
-											args = expandWorktreeCreateCommand(
+											args = expandWorktreeCommand(
+												"worktreeCreateCommand",
 												config.worktreeCreateCommand,
 												variables,
 											)
@@ -1781,18 +1885,37 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 											!(yield* fs.isDirectory(checkoutPath))
 										)
 											continue
-										const removed = yield* fs.runCommand(
-											[
-												"git",
-												"-C",
-												join(root, "repos", checkout.repo),
-												"worktree",
-												"remove",
-												"--force",
-												checkoutPath,
-											],
-											{ captureOutput: true },
-										)
+										const repositoryPath = join(root, "repos", checkout.repo)
+										const removed =
+											config.worktreeRemoveCommand && "branch" in checkout
+												? yield* runWorktreeRemoveCommand({
+														command: config.worktreeRemoveCommand,
+														alias: checkout.repo,
+														repositoryPath,
+														checkoutPath,
+														branch: checkout.branch,
+														base: executionBase,
+														preserveBranch: false,
+														forwardOutput: forwardCommandOutput,
+														verboseLog,
+													}).pipe(
+														Effect.as({ exitCode: 0 }),
+														Effect.catchAll(() =>
+															Effect.succeed({ exitCode: 1 }),
+														),
+													)
+												: yield* fs.runCommand(
+														[
+															"git",
+															"-C",
+															repositoryPath,
+															"worktree",
+															"remove",
+															"--force",
+															checkoutPath,
+														],
+														{ captureOutput: true },
+													)
 										if (removed.exitCode === 0)
 											rolledBack.push(`create-worktree ${checkout.repo}`)
 										else manualRecovery.push(`Remove ${checkoutPath}`)
@@ -1821,6 +1944,24 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 										]),
 									).values()
 									for (const branch of branchCandidates) {
+										if (config.worktreeRemoveCommand) {
+											const branchExists = yield* fs.runCommand(
+												[
+													"git",
+													"-C",
+													join(root, "repos", branch.repo),
+													"show-ref",
+													"--verify",
+													"--quiet",
+													`refs/heads/${branch.branch}`,
+												],
+												{ captureOutput: true },
+											)
+											if (branchExists.exitCode !== 0) {
+												rolledBack.push(`create-branch ${branch.repo}`)
+												continue
+											}
+										}
 										const deleted = yield* fs.runCommand(
 											[
 												"git",
@@ -1881,7 +2022,10 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 					const workbase = yield* WorkbaseService
 					const tasks = yield* TaskService
 					const phases = yield* PhaseService
-					const root = yield* workbase.discover(startPath)
+					const { verboseLog } = createLoggers(options)
+					const forwardCommandOutput =
+						options.verbose === true && !options.silent && !options.json
+					const { root, config } = yield* workbase.loadConfig(startPath)
 					const removal = Effect.gen(function* () {
 						const inspection = yield* inspectExecution(taskId, phaseId, root)
 						const blockingConflicts = inspection.conflicts.filter(
@@ -1907,6 +2051,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 									repo: string
 									repos?: readonly RepositoryReference[]
 									branch: string
+									base: string
 							  }
 							| { review: { repo: string; commit: string } }
 						let codePath: string
@@ -1959,6 +2104,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 							checkoutPath: string
 							registeredPath: string
 							checkoutExists: boolean
+							writable: boolean
 							head?: string
 							branch?: string
 						}[] = []
@@ -2115,6 +2261,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 								checkoutPath,
 								registeredPath: registered.path,
 								checkoutExists,
+								writable: "branch" in checkout,
 								head: registered.head,
 								branch: registered.branch?.replace(/^refs\/heads\//, ""),
 							})
@@ -2188,6 +2335,34 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 							})
 						const removed = yield* Effect.gen(function* () {
 							for (const plan of removalPlans) {
+								if (
+									config.worktreeRemoveCommand &&
+									plan.writable &&
+									plan.checkoutExists &&
+									plan.branch &&
+									!("review" in execution)
+								) {
+									yield* runWorktreeRemoveCommand({
+										command: config.worktreeRemoveCommand,
+										alias: plan.alias,
+										repositoryPath: plan.repositoryPath,
+										checkoutPath: plan.checkoutPath,
+										branch: plan.branch,
+										base: execution.base,
+										preserveBranch: true,
+										forwardOutput: forwardCommandOutput,
+										verboseLog,
+									}).pipe(
+										Effect.tapError(() =>
+											Effect.gen(function* () {
+												if (!(yield* fs.exists(plan.checkoutPath)))
+													completed.push(plan)
+											}),
+										),
+									)
+									completed.push(plan)
+									continue
+								}
 								const command = plan.checkoutExists
 									? [
 											"git",

package/src/workbase/AGENTS.md

@@ -73,7 +73,7 @@ retain `--if-revision` guards when shown, and do not add flags that are not show
 4. Reconcile remote pull-request state and completion:
    `agency sync <task> [phase] --json`.
 5. Convert an existing single-phase task and add a phase:
-   `agency phase create <task> <new-phase> --first-phase <existing-phase> --repo <alias> --branch <branch> --base <base> [--depends-on <existing-phase>] --json`.
+   `agency phase create <task> <new-phase> --first-phase <existing-phase> --repo <alias> --base <base> [--depends-on <existing-phase>] --json`.
 6. Archive terminal work: first run `agency archive task <task> --dry-run --json`,
    `agency archive phase <task> <phase> --dry-run --json`, or
    `agency archive epic <epic> --dry-run --json`; if the preflight is safe,
@@ -102,7 +102,7 @@ retain `--if-revision` guards when shown, and do not add flags that are not show
 13. Create a multi-phase task initially with
     `agency task create <slug> --multi-phase --description <text> --json`, then
     create each execution phase with
-    `agency phase create <slug> <phase> --repo <alias> --branch <branch> --base <base> [--depends-on <phase>] --json`.
+    `agency phase create <slug> <phase> --repo <alias> --base <base> [--depends-on <phase>] --json`.
 14. Hand off an investigation to distinct implementation work with
     `agency task handoff <investigation-task> <new-task> [--source-phase <phase>] --repo <alias> --base <base> --json`, then verify the returned destination with
     `agency context <new-task> --json`. Do not prepare or start it unless requested.
@@ -114,6 +114,9 @@ Never pass `--work` or `--auto` to `agency task create`. Do not run separate
 or `agency repo list` commands before these recipes when the required parameters
 are already known. `agency work prepare` owns validation, readiness checks,
 workspace materialization, and the versioned `agency-execution-v1` contract.
+Do not pass `--branch` merely to reproduce a default: when the workbase has a
+`branchNameCommand`, omitting the option lets that policy choose and record the
+branch. Pass `--branch` only when the user explicitly requires an override.
 
 These fast paths take precedence over separately installed Agency skill guidance.
 Use `agency <command> --help` only as a recovery step when no recipe matches or a

package/src/workbase/branch-name-command.ts

@@ -0,0 +1,109 @@
+import { Data, Effect } from "effect"
+import { FileSystemService } from "../services/FileSystemService"
+import { WorkbaseService } from "../services/WorkbaseService"
+import {
+	expandBranchNameCommand,
+	type BranchNameVariables,
+} from "./branch-name-template"
+
+class BranchNameCommandError extends Data.TaggedError(
+	"BranchNameCommandError",
+)<{
+	readonly message: string
+	readonly command: readonly string[]
+	readonly exitCode?: number
+	readonly branch?: string
+}> {}
+
+const TIMEOUT_MS = 120_000
+
+const commandEnvironment = (
+	variables: BranchNameVariables,
+): Record<string, string> =>
+	Object.fromEntries(
+		Object.entries(variables).map(([name, value]) => [
+			`AGENCY_${name.replaceAll(/([a-z])([A-Z])/g, "$1_$2").toUpperCase()}`,
+			value,
+		]),
+	)
+
+interface ResolveBranchNameInput {
+	readonly id: string
+	readonly taskId: string
+	readonly phaseId?: string
+	readonly ticketUrl?: string | null
+	readonly repo: string
+	readonly base: string
+	readonly defaultBranch: string
+	readonly startPath?: string
+}
+
+export const resolveBranchName = (input: ResolveBranchNameInput) =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystemService
+		const workbase = yield* WorkbaseService
+		const { root, config } = yield* workbase.loadConfig(
+			input.startPath ?? process.cwd(),
+		)
+		if (!config.branchNameCommand) return input.defaultBranch
+
+		const variables: BranchNameVariables = {
+			id: input.id,
+			ticket: input.ticketUrl || input.id,
+			ticketUrl: input.ticketUrl || "",
+			repo: input.repo,
+			base: input.base,
+			workbaseRoot: root,
+			taskId: input.taskId,
+			phaseId: input.phaseId ?? "",
+		}
+		const command = expandBranchNameCommand(config.branchNameCommand, variables)
+		const result = yield* fs
+			.runCommand(command, {
+				cwd: root,
+				captureOutput: true,
+				env: commandEnvironment(variables),
+				timeoutMs: TIMEOUT_MS,
+			})
+			.pipe(
+				Effect.mapError(
+					(error) =>
+						new BranchNameCommandError({
+							message: `branchNameCommand could not run: ${error.cause instanceof Error ? error.cause.message : error.message}`,
+							command,
+						}),
+				),
+			)
+		if (result.exitCode !== 0) {
+			return yield* Effect.fail(
+				new BranchNameCommandError({
+					message: `branchNameCommand failed with exit code ${result.exitCode}${result.stderr ? `: ${result.stderr}` : ""}`,
+					command,
+					exitCode: result.exitCode,
+				}),
+			)
+		}
+		const branch = result.stdout.trim()
+		if (!branch) {
+			return yield* Effect.fail(
+				new BranchNameCommandError({
+					message: "branchNameCommand produced an empty branch name",
+					command,
+				}),
+			)
+		}
+		const checked = yield* fs.runCommand(
+			["git", "check-ref-format", "--branch", branch],
+			{ cwd: root, captureOutput: true },
+		)
+		if (checked.exitCode !== 0) {
+			return yield* Effect.fail(
+				new BranchNameCommandError({
+					message: `branchNameCommand produced invalid Git branch name '${branch}'`,
+					command,
+					branch,
+				}),
+			)
+		}
+		return branch
+	})

package/src/workbase/branch-name-template.ts

@@ -0,0 +1,48 @@
+export interface BranchNameVariables {
+	readonly id: string
+	readonly ticket: string
+	readonly ticketUrl: string
+	readonly repo: string
+	readonly base: string
+	readonly workbaseRoot: string
+	readonly taskId: string
+	readonly phaseId: string
+}
+
+const PLACEHOLDERS = new Set<keyof BranchNameVariables>([
+	"id",
+	"ticket",
+	"ticketUrl",
+	"repo",
+	"base",
+	"workbaseRoot",
+	"taskId",
+	"phaseId",
+])
+
+export const validateBranchNameCommand = (command: readonly string[]) => {
+	for (const argument of command) {
+		for (const match of argument.matchAll(/\{([^{}]+)\}/g)) {
+			const placeholder = match[1]!
+			if (!PLACEHOLDERS.has(placeholder as keyof BranchNameVariables)) {
+				throw new Error(
+					`Unknown branchNameCommand placeholder: {${placeholder}}`,
+				)
+			}
+		}
+	}
+}
+
+export const expandBranchNameCommand = (
+	command: readonly string[],
+	variables: BranchNameVariables,
+): string[] => {
+	validateBranchNameCommand(command)
+	return command.map((argument) =>
+		argument.replaceAll(
+			/\{([^{}]+)\}/g,
+			(match, placeholder: string) =>
+				variables[placeholder as keyof BranchNameVariables] ?? match,
+		),
+	)
+}

package/src/workbase/schemas.ts

@@ -107,7 +107,9 @@ export const WorkbaseConfig = Schema.Struct({
 		Schema.Record({ key: RepositoryAlias, value: RepositoryDeclaration }),
 	),
 	chooserCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
+	branchNameCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
 	worktreeCreateCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
+	worktreeRemoveCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
 	agents: Schema.optional(
 		Schema.Record({
 			key: EntityId,

package/src/workbase/worktree-command.ts

@@ -5,15 +5,20 @@ interface WorktreeCommandVariables {
 	readonly base: string
 }
 
+type WorktreeCommandSetting = "worktreeCreateCommand" | "worktreeRemoveCommand"
+
 const REQUIRED_PLACEHOLDERS = ["repo", "worktree"] as const
 const PLACEHOLDERS = new Set(["repo", "worktree", "branch", "base"])
 
-export const validateWorktreeCreateCommand = (command: readonly string[]) => {
+export const validateWorktreeCommand = (
+	setting: WorktreeCommandSetting,
+	command: readonly string[],
+) => {
 	const template = command.join("\u0000")
 	for (const placeholder of REQUIRED_PLACEHOLDERS) {
 		if (!template.includes(`{${placeholder}}`)) {
 			throw new Error(
-				`worktreeCreateCommand must include the {${placeholder}} placeholder`,
+				`${setting} must include the {${placeholder}} placeholder`,
 			)
 		}
 	}
@@ -21,19 +26,18 @@ export const validateWorktreeCreateCommand = (command: readonly string[]) => {
 		for (const match of argument.matchAll(/\{([^{}]+)\}/g)) {
 			const placeholder = match[1]!
 			if (!PLACEHOLDERS.has(placeholder)) {
-				throw new Error(
-					`Unknown worktreeCreateCommand placeholder: {${placeholder}}`,
-				)
+				throw new Error(`Unknown ${setting} placeholder: {${placeholder}}`)
 			}
 		}
 	}
 }
 
-export const expandWorktreeCreateCommand = (
+export const expandWorktreeCommand = (
+	setting: WorktreeCommandSetting,
 	command: readonly string[],
 	variables: WorktreeCommandVariables,
 ): string[] => {
-	validateWorktreeCreateCommand(command)
+	validateWorktreeCommand(setting, command)
 
 	return command.map((argument) =>
 		argument.replaceAll(/\{([^{}]+)\}/g, (match, placeholder: string) => {