@markjaquith/agency 3.11.0 → 3.12.0

package/README.md

@@ -187,6 +187,48 @@ Existing version 2 workbases without `repositories` remain valid. Run
 unambiguous. Workbase configuration may also provide a custom writable-worktree
 creation command.
 
+### 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
 
 Git workbases create worktrees with Git. Set `worktreeCreateCommand` to an

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "3.11.0",
+  "version": "3.12.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/WorkbaseService.ts

@@ -22,6 +22,7 @@ import {
 } from "../workbase/schemas"
 import { validateWorktreeCreateCommand } 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"
@@ -329,6 +330,19 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 										})
 									}
 								}
+								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",
+										})
+									}
+								}
 								for (const [alias, repository] of Object.entries(
 									decoded.value.repositories ?? {},
 								)) {

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,6 +107,7 @@ 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)),
 	agents: Schema.optional(
 		Schema.Record({