@markjaquith/agency 2.33.0 → 2.34.0

package/README.md

@@ -498,6 +498,8 @@ complete Markdown document.
 ### Epics
 
 ```text
+agency epic new <id> --ticket-url <url> [--description <text>]
+  --repo <alias>:<ref> [--repo <alias>:<ref>...] [--work [--auto]]
 agency epic create <id> --ticket-url <url> [--description <text>] [--json]
   --repo <alias>:<ref> [--repo <alias>:<ref>...]
 agency epic list [filters] [--json]
@@ -517,9 +519,13 @@ repository is available, Agency selects it without presenting a redundant
 choice. This command requires a TTY and fails with `--no-input`:
 
 ```text
-agency task new [id]
+agency task new [id] [--work [--auto]]
 ```
 
+`--work` starts work on the newly created entity. Add `--auto` to pass the
+generated context prompt to the selected runner. These launch options are also
+available on `epic new` and `phase new`; they cannot be combined with `--json`.
+
 Create a single-phase task:
 
 ```text
@@ -590,6 +596,8 @@ phase. Dependencies remain explicit through `--depends-on`.
 ### Phases
 
 ```text
+agency phase new <task-id> <phase-id>
+  --repo <alias> --branch <name> --base <name> [--work [--auto]]
 agency phase create <task-id> <phase-id>
   --repo <alias> --branch <name> --base <name>
   [--description <text>] [--reference <alias>:<ref>...]

package/cli.ts

@@ -251,8 +251,11 @@ const commands: Record<string, Command> = {
 					ready: options.ready,
 					blocked: options.blocked,
 					pr: options.pr ? true : options["no-pr"] ? false : undefined,
+					work: options.work,
+					auto: options.auto,
 					silent: options.silent,
 					verbose: options.verbose,
+					inputAllowed: options.inputAllowed,
 					cwd: options.cwd,
 				}),
 			)
@@ -304,8 +307,11 @@ const commands: Record<string, Command> = {
 					ready: options.ready,
 					blocked: options.blocked,
 					pr: options.pr ? true : options["no-pr"] ? false : undefined,
+					work: options.work,
+					auto: options.auto,
 					silent: options.silent,
 					verbose: options.verbose,
+					inputAllowed: options.inputAllowed,
 					cwd: options.cwd,
 				}),
 			)
@@ -452,6 +458,8 @@ const commands: Record<string, Command> = {
 					ready: options.ready,
 					blocked: options.blocked,
 					pr: options.pr ? true : options["no-pr"] ? false : undefined,
+					work: options.work,
+					auto: options.auto,
 					silent: options.silent,
 					verbose: options.verbose,
 					inputAllowed: options.inputAllowed,

package/package.json

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

package/src/cli-parser.test.ts

@@ -477,6 +477,56 @@ describe("strict CLI parsing", () => {
 		)
 	})
 
+	test("accepts work launch options on new entities", () => {
+		expect(
+			parseCli(["task", "new", "example", "--work", "--auto"]),
+		).toMatchObject({
+			commandName: "task",
+			args: ["new", "example"],
+			values: { work: true, auto: true },
+		})
+		expect(
+			parseCli([
+				"epic",
+				"new",
+				"delivery",
+				"--ticket-url",
+				"https://example.com/delivery",
+				"--repo",
+				"agency:main",
+				"--work",
+			]),
+		).toMatchObject({ commandName: "epic", args: ["new", "delivery"] })
+		expect(
+			parseCli([
+				"phase",
+				"new",
+				"delivery",
+				"implementation",
+				"--repo",
+				"agency",
+				"--branch",
+				"task/implementation",
+				"--base",
+				"main",
+				"--work",
+			]),
+		).toMatchObject({
+			commandName: "phase",
+			args: ["new", "delivery", "implementation"],
+		})
+		expect(() => parseCli(["task", "new", "example", "--auto"])).toThrow(
+			"Option '--auto' requires '--work'",
+		)
+		expect(() =>
+			parseCli(["task", "new", "example", "--work", "--json"]),
+		).toThrow("cannot be combined")
+		expectUsageError(
+			["task", "create", "example", "--repo", "agency", "--work"],
+			"agency task create",
+		)
+	})
+
 	test("accepts repeatable graph filters and rejects output conflicts", () => {
 		expect(
 			parseCli([

package/src/cli-parser.ts

@@ -70,6 +70,11 @@ const createOptions = {
 	repo: { type: "string", multiple: true },
 } satisfies OptionConfig
 
+const newWorkOptions = {
+	work: { type: "boolean" },
+	auto: { type: "boolean" },
+} satisfies OptionConfig
+
 const taskCreateOptions = {
 	...createOptions,
 	reference: { type: "string", multiple: true },
@@ -282,14 +287,25 @@ const commands = {
 		},
 	},
 	epic: {
-		usage: "agency epic <create|list|show|update|rename>",
+		usage: "agency epic <new|create|list|show|update|rename>",
 		options: {
 			...createOptions,
+			...newWorkOptions,
 			...viewOptions,
 			...mutationOptions,
 			epic: { type: "string" },
 		},
 		subcommands: {
+			new: {
+				usage:
+					"agency epic new <id> --ticket-url <url> --repo <alias>:<ref> [--repo <alias>:<ref>...] [--work [--auto]]",
+				minArgs: 1,
+				maxArgs: 1,
+				options: ["ticket-url", "description", "repo", "work", "auto", "json"],
+				required: ["ticket-url", "repo"],
+				repeatable: ["repo"],
+				conflicts: [["work", "json"]],
+			},
 			create: {
 				usage:
 					"agency epic create <id> --ticket-url <url> --repo <alias>:<ref> [--repo <alias>:<ref>...]",
@@ -341,6 +357,7 @@ const commands = {
 			"agency task <new|create|list|show|status|update|rename|move|dependency>",
 		options: {
 			...taskCreateOptions,
+			...newWorkOptions,
 			...viewOptions,
 			...mutationOptions,
 			"pr-url": { type: "string" },
@@ -348,7 +365,7 @@ const commands = {
 		},
 		subcommands: {
 			new: {
-				usage: "agency task new [id] [options]",
+				usage: "agency task new [id] [options] [--work [--auto]]",
 				minArgs: 0,
 				maxArgs: 1,
 				options: [
@@ -360,9 +377,12 @@ const commands = {
 					"branch",
 					"base",
 					"multi-phase",
+					"work",
+					"auto",
 					"json",
 				],
 				repeatable: ["reference"],
+				conflicts: [["work", "json"]],
 			},
 			create: {
 				usage:
@@ -452,9 +472,11 @@ const commands = {
 		},
 	},
 	phase: {
-		usage: "agency phase <create|list|show|status|update|rename|dependency>",
+		usage:
+			"agency phase <new|create|list|show|status|update|rename|dependency>",
 		options: {
 			...phaseCreateOptions,
+			...newWorkOptions,
 			...viewOptions,
 			...mutationOptions,
 			"pr-url": { type: "string" },
@@ -462,6 +484,29 @@ const commands = {
 			phase: { type: "string" },
 		},
 		subcommands: {
+			new: {
+				usage:
+					"agency phase new <task-id> <phase-id> --repo <alias> --branch <name> --base <name> [options] [--work [--auto]]",
+				minArgs: 2,
+				maxArgs: 2,
+				options: [
+					"description",
+					"repo",
+					"reference",
+					"branch",
+					"base",
+					"depends-on",
+					"first-phase",
+					"work",
+					"auto",
+					"json",
+					"task",
+					"phase",
+				],
+				required: ["repo", "branch", "base"],
+				repeatable: ["reference", "depends-on"],
+				conflicts: [["work", "json"]],
+			},
 			create: {
 				usage:
 					"agency phase create <task-id> <phase-id> --repo <alias> --branch <name> --base <name> [options]",
@@ -1295,6 +1340,14 @@ export function parseCli(args: readonly string[]): ParsedCli {
 	) {
 		validateTaskCreate(parsed.values, spec, subcommand === "create")
 	}
+	if (
+		["epic", "task", "phase"].includes(commandName) &&
+		subcommand === "new" &&
+		parsed.values.auto &&
+		!parsed.values.work
+	) {
+		throw usageError("Option '--auto' requires '--work'.", spec.usage)
+	}
 	if (["task", "phase"].includes(commandName) && subcommand === "dependency") {
 		if (!["add", "remove"].includes(commandPositionals[0] ?? "")) {
 			throw usageError(

package/src/commands/epic.test.ts

@@ -1,6 +1,7 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test"
 import { mkdir } from "node:fs/promises"
 import { join } from "node:path"
+import { Effect } from "effect"
 import {
 	captureLogs,
 	cleanupTempDir,
@@ -131,4 +132,36 @@ describe("epic command", () => {
 		expect(logs[0]).toContain("example  open    waiting    agency")
 		expect(logs[0]).not.toMatch(/[\u{e000}-\u{f8ff}]/u)
 	})
+
+	test("starts work on a newly created epic", async () => {
+		const launches: unknown[] = []
+
+		await runTestEffect(
+			epic(
+				{
+					subcommand: "new",
+					args: ["immediate"],
+					ticketUrl: "https://example.com/immediate",
+					repos: ["agency:main"],
+					work: true,
+					auto: true,
+					cwd: root,
+					silent: true,
+				},
+				(options) =>
+					Effect.sync(() => {
+						launches.push(options)
+						return undefined
+					}),
+			),
+		)
+
+		expect(launches).toEqual([
+			expect.objectContaining({
+				epicId: "immediate",
+				auto: true,
+				cwd: root,
+			}),
+		])
+	})
 })

package/src/commands/epic.ts

@@ -6,6 +6,7 @@ import { formatTable } from "../utils/table"
 import { getWorkViews } from "../work-view"
 import { parseRepositoryReferences } from "../workbase/repository-reference"
 import { GraphMutationService } from "../services/GraphMutationService"
+import { work as startWork, type StartWork } from "./work"
 
 interface EpicOptions extends BaseCommandOptions {
 	readonly subcommand?: string
@@ -21,9 +22,11 @@ interface EpicOptions extends BaseCommandOptions {
 	readonly ready?: boolean
 	readonly blocked?: boolean
 	readonly pr?: boolean
+	readonly work?: boolean
+	readonly auto?: boolean
 }
 
-export const epic = (options: EpicOptions) =>
+export const epic = (options: EpicOptions, work: StartWork = startWork) =>
 	Effect.gen(function* () {
 		const epics = yield* EpicService
 		const mutations = yield* GraphMutationService
@@ -31,6 +34,7 @@ export const epic = (options: EpicOptions) =>
 		const cwd = options.cwd ?? process.cwd()
 
 		switch (options.subcommand) {
+			case "new":
 			case "create": {
 				const id = options.args[0]
 				if (!id || !options.ticketUrl || !options.repos?.length) {
@@ -53,6 +57,16 @@ export const epic = (options: EpicOptions) =>
 						? JSON.stringify(output, null, 2)
 						: `Created epic '${record.id}'`,
 				)
+				if (options.subcommand === "new" && options.work) {
+					yield* work({
+						epicId: record.id,
+						auto: options.auto,
+						cwd,
+						inputAllowed: options.inputAllowed,
+						silent: options.silent,
+						verbose: options.verbose,
+					})
+				}
 				return
 			}
 
@@ -157,7 +171,7 @@ export const epic = (options: EpicOptions) =>
 			default:
 				return yield* Effect.fail(
 					new Error(
-						"Subcommand is required. Available subcommands: create, list, show, update, rename",
+						"Subcommand is required. Available subcommands: new, create, list, show, update, rename",
 					),
 				)
 		}
@@ -167,6 +181,7 @@ export const help = `
 Usage: agency epic <subcommand>
 
 Subcommands:
+  new <id>              Create an epic, optionally starting work
   create <id>           Create an epic
   list                  List epics
   show <id>             Show an epic
@@ -177,6 +192,8 @@ Create options:
   --ticket-url <url>    External ticket URL
   --description <text>  Short description of the epic
   --repo <alias>:<ref>  Read-only repository reference; repeatable
+  --work                Start work on the new epic after creating it
+  --auto                Pass --auto to work; requires --work
 
 Update options:
   --ticket-url <url>    Replace the external ticket URL

package/src/commands/phase.ts

@@ -6,6 +6,7 @@ import { formatTable } from "../utils/table"
 import { getWorkViews } from "../work-view"
 import { parseRepositoryReferences } from "../workbase/repository-reference"
 import { GraphMutationService } from "../services/GraphMutationService"
+import { work as startWork, type StartWork } from "./work"
 
 interface PhaseOptions extends BaseCommandOptions {
 	readonly subcommand?: string
@@ -28,9 +29,11 @@ interface PhaseOptions extends BaseCommandOptions {
 	readonly ready?: boolean
 	readonly blocked?: boolean
 	readonly pr?: boolean
+	readonly work?: boolean
+	readonly auto?: boolean
 }
 
-export const phase = (options: PhaseOptions) =>
+export const phase = (options: PhaseOptions, work: StartWork = startWork) =>
 	Effect.gen(function* () {
 		const phases = yield* PhaseService
 		const mutations = yield* GraphMutationService
@@ -39,6 +42,7 @@ export const phase = (options: PhaseOptions) =>
 		const [taskId, phaseId] = options.args
 
 		switch (options.subcommand) {
+			case "new":
 			case "create": {
 				if (
 					!taskId ||
@@ -73,6 +77,17 @@ export const phase = (options: PhaseOptions) =>
 						? JSON.stringify(output, null, 2)
 						: `Created phase '${record.id}' on task '${record.taskId}'`,
 				)
+				if (options.subcommand === "new" && options.work) {
+					yield* work({
+						taskId: record.taskId,
+						phaseId: record.id,
+						auto: options.auto,
+						cwd,
+						inputAllowed: options.inputAllowed,
+						silent: options.silent,
+						verbose: options.verbose,
+					})
+				}
 				return
 			}
 			case "list": {
@@ -245,7 +260,7 @@ export const phase = (options: PhaseOptions) =>
 			default:
 				return yield* Effect.fail(
 					new Error(
-						"Subcommand is required. Available: create, list, show, status, update, rename, dependency",
+						"Subcommand is required. Available: new, create, list, show, status, update, rename, dependency",
 					),
 				)
 		}
@@ -255,6 +270,7 @@ export const help = `
 Usage: agency phase <subcommand> <task-id> [phase-id]
 
 Subcommands:
+  new <task> <phase>    Create a phase, optionally starting work
   create <task> <phase> Create a phase
   list <task>           List task phases
   show <task> <phase>   Show a phase
@@ -278,6 +294,8 @@ Create options:
   --base <name>         Base branch
   --depends-on <id>     Phase dependency; repeatable
   --first-phase <id>    Existing execution phase ID when converting a task
+  --work                Start work on the new phase after creating it
+  --auto                Pass --auto to work; requires --work
 
 Update options:
   --description <text> / --clear-description

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

@@ -1,6 +1,7 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test"
 import { mkdir } from "node:fs/promises"
 import { join } from "node:path"
+import { Effect } from "effect"
 import {
 	captureLogs,
 	cleanupTempDir,
@@ -199,6 +200,40 @@ describe("task and phase command JSON output", () => {
 		})
 	})
 
+	test("starts work on a newly created phase", async () => {
+		const launches: unknown[] = []
+
+		await runTestEffect(
+			phase(
+				{
+					subcommand: "new",
+					args: ["multi", "immediate"],
+					repo: "agency",
+					branch: "task/immediate",
+					base: "main",
+					work: true,
+					auto: true,
+					cwd: root,
+					silent: true,
+				},
+				(options) =>
+					Effect.sync(() => {
+						launches.push(options)
+						return undefined
+					}),
+			),
+		)
+
+		expect(launches).toEqual([
+			expect.objectContaining({
+				taskId: "multi",
+				phaseId: "immediate",
+				auto: true,
+				cwd: root,
+			}),
+		])
+	})
+
 	test("sets task and phase status", async () => {
 		const phaseLogs = await captureLogs(() =>
 			runTestEffect(

package/src/commands/task.test.ts

@@ -167,4 +167,39 @@ describe("task creation input", () => {
 			),
 		).rejects.toThrow("task new requires interactive input")
 	})
+
+	test("starts work on a newly created task", async () => {
+		const launches: unknown[] = []
+
+		await runTestEffect(
+			task(
+				{
+					subcommand: "new",
+					args: ["immediate"],
+					ticketUrl: "",
+					description: "",
+					multiPhase: false,
+					repo: "agency",
+					work: true,
+					auto: true,
+					cwd: root,
+					silent: true,
+				},
+				undefined,
+				(options) =>
+					Effect.sync(() => {
+						launches.push(options)
+						return undefined
+					}),
+			),
+		)
+
+		expect(launches).toEqual([
+			expect.objectContaining({
+				taskId: "immediate",
+				auto: true,
+				cwd: root,
+			}),
+		])
+	})
 })

package/src/commands/task.ts

@@ -10,6 +10,7 @@ import { choose } from "../utils/chooser"
 import { formatTable } from "../utils/table"
 import { getWorkViews } from "../work-view"
 import { GraphMutationService } from "../services/GraphMutationService"
+import { work as startWork, type StartWork } from "./work"
 
 interface TaskOptions extends BaseCommandOptions {
 	readonly subcommand?: string
@@ -35,6 +36,8 @@ interface TaskOptions extends BaseCommandOptions {
 	readonly ready?: boolean
 	readonly blocked?: boolean
 	readonly pr?: boolean
+	readonly work?: boolean
+	readonly auto?: boolean
 }
 
 export interface TaskInteraction {
@@ -68,7 +71,11 @@ const defaultInteraction = (
 		),
 })
 
-export const task = (options: TaskOptions, interaction?: TaskInteraction) =>
+export const task = (
+	options: TaskOptions,
+	interaction?: TaskInteraction,
+	work: StartWork = startWork,
+) =>
 	Effect.gen(function* () {
 		const tasks = yield* TaskService
 		const epics = yield* EpicService
@@ -183,6 +190,16 @@ export const task = (options: TaskOptions, interaction?: TaskInteraction) =>
 						? JSON.stringify(output, null, 2)
 						: `Created task '${record.id}'`,
 				)
+				if (options.subcommand === "new" && options.work) {
+					yield* work({
+						taskId: record.id,
+						auto: options.auto,
+						cwd,
+						inputAllowed: options.inputAllowed,
+						silent: options.silent,
+						verbose: options.verbose,
+					})
+				}
 				return
 			}
 			case "create": {
@@ -426,6 +443,8 @@ Create options:
   --branch <name>       Working branch (default: task/<id>)
   --base <name>         Base branch (default: main)
   --multi-phase         Create a task container for phases
+  --work                Start work on the new task after creating it
+  --auto                Pass --auto to work; requires --work
 
 Update options:
   --ticket-url <url> / --clear-ticket

package/src/commands/work.ts

@@ -29,7 +29,7 @@ import {
 	runnerEnvironment,
 } from "../workbase/runner-command"
 
-interface WorkOptions extends BaseCommandOptions {
+export interface WorkOptions extends BaseCommandOptions {
 	readonly directory?: string
 	readonly taskId?: string
 	readonly phaseId?: string
@@ -42,6 +42,8 @@ interface WorkOptions extends BaseCommandOptions {
 	readonly force?: boolean
 }
 
+export type StartWork = (options: WorkOptions) => ReturnType<typeof work>
+
 type LaunchAgent = (
 	cli: string,
 	args: readonly string[],