@markjaquith/agency 2.54.0 → 2.54.1

package/README.md

@@ -805,6 +805,7 @@ for restoration. Archived IDs are reserved until restored.
 agency work [<directory> | --epic <epic-id>] [--runner <name>] [--auto] [--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] [--force] [--json]
 agency pr [args...]
 ```
 
@@ -851,9 +852,12 @@ Agency resolves the ref to a commit and creates a detached worktree. Existing
 reference worktrees are reused only while their commit still matches the declared
 ref; use a commit SHA as `ref` when reproducibility matters.
 
-`agency pr` forwards every argument to `gh pr`. From an execution task or phase
-directory, including descendants, it runs in that execution unit's authoritative
-writable checkout. Otherwise it runs in the caller's current directory.
+Task-aware `agency pr create <task-id> [phase-id]` uses Agency's delivery flow,
+including readiness checks and durable PR recording. Other `agency pr`
+invocations forward every argument to `gh pr`. From an execution task or phase
+directory, including descendants, passthrough runs in that execution unit's
+authoritative writable checkout. Otherwise it runs in the caller's current
+directory.
 
 ### Status and Validation
 

package/cli-main.ts

@@ -5,7 +5,7 @@ import { join, resolve } from "node:path"
 import { parseCli } from "./src/cli-parser"
 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 { pr, prCreate, 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"
@@ -134,7 +134,7 @@ const resolveInvocationCwd = (
 ) =>
 	runEffect(
 		Effect.gen(function* () {
-			if (commandName === "pr") {
+			if (commandName === "pr" && options.passthrough) {
 				return resolve(options.cwd ?? process.cwd())
 			}
 			if (
@@ -287,7 +287,22 @@ const commands: Record<string, Command> = {
 				console.log(prHelp)
 				return
 			}
-			process.exitCode = await runEffect(pr(args, options.cwd))
+			if (options.passthrough) {
+				process.exitCode = await runEffect(pr(args, options.cwd))
+				return
+			}
+			await runCommand(
+				prCreate({
+					taskId: args[1]!,
+					phaseId: args[2],
+					draft: options.draft,
+					force: options.force,
+					json: options.json,
+					silent: options.silent,
+					verbose: options.verbose,
+					cwd: options.cwd,
+				}),
+			)
 		},
 	},
 	phase: {
@@ -726,7 +741,7 @@ Commands:
   worktree <subcommand>  Inspect and maintain managed workspaces
   vcs <subcommand>       Inspect or migrate the version-control backend
   next                   List or select ready execution units
-  pr [args...]           Run gh pr with Agency repository focus
+  pr create / pr [...]  Create an Agency PR or run gh pr with repository focus
   review refresh         Explicitly refresh a pinned review task
   repo <subcommand>      Manage workbase repositories
   status                 Show status for the current workbase
@@ -761,7 +776,7 @@ const machineMode = process.argv
 
 try {
 	const args = process.argv.slice(2)
-	const { commandName, args: commandArgs, values } = parseCli(args)
+	const { commandName, args: commandArgs, passthrough, values } = parseCli(args)
 
 	// Handle global flags
 	if (values.version) {
@@ -785,16 +800,29 @@ try {
 		!values.json &&
 		!values["no-input"] &&
 		Boolean(process.stdin.isTTY && process.stdout.isTTY)
-	const cwd = await resolveInvocationCwd(commandName, values)
+	const cwd = await resolveInvocationCwd(commandName, {
+		...values,
+		passthrough,
+	})
 	if (values.json || (values.jsonl && values.help)) {
 		const result = await collectCommandResult(() =>
-			command.run(commandArgs, { ...values, cwd, inputAllowed }),
+			command.run(commandArgs, { ...values, cwd, inputAllowed, passthrough }),
 		)
 		writeEnvelope(successEnvelope(result))
 	} else if (values.jsonl) {
-		await command.run(commandArgs, { ...values, cwd, inputAllowed: false })
+		await command.run(commandArgs, {
+			...values,
+			cwd,
+			inputAllowed: false,
+			passthrough,
+		})
 	} else {
-		await command.run(commandArgs, { ...values, cwd, inputAllowed })
+		await command.run(commandArgs, {
+			...values,
+			cwd,
+			inputAllowed,
+			passthrough,
+		})
 	}
 } catch (error) {
 	if (machineMode) {

package/package.json

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

package/src/cli-parser.test.ts

@@ -367,10 +367,34 @@ describe("strict CLI parsing", () => {
 		expect(parseCli(["--cwd", "/workbase", "pr", ...args])).toEqual({
 			commandName: "pr",
 			args,
+			passthrough: true,
 			values: { cwd: "/workbase" },
 		})
 	})
 
+	test("parses task-aware pr create without routing it to passthrough", () => {
+		expect(
+			parseCli([
+				"pr",
+				"create",
+				"ship",
+				"release",
+				"--draft",
+				"--force",
+				"--json",
+			]),
+		).toEqual({
+			commandName: "pr",
+			args: ["create", "ship", "release"],
+			values: { draft: true, force: true, json: true },
+		})
+		const selected = parseCli(["pr", "create", "--task", "ship"])
+		expect(selected).toMatchObject({
+			args: ["create", "ship"],
+		})
+		expect(selected.passthrough).toBeUndefined()
+	})
+
 	test("parses explicit dry-run reconciliation", () => {
 		expect(parseCli(["sync"])).toMatchObject({
 			commandName: "sync",

package/src/cli-parser.ts

@@ -895,12 +895,22 @@ const commands = {
 		},
 	},
 	pr: {
-		usage: "agency pr [args...]",
-		options: commonOptions,
-		command: {
-			usage: "agency pr [args...]",
-			minArgs: 0,
-			maxArgs: Number.POSITIVE_INFINITY,
+		usage: "agency pr create <task-id> [phase-id] | agency pr [args...]",
+		options: {
+			...outputOptions,
+			draft: { type: "boolean" },
+			force: { type: "boolean" },
+			task: { type: "string" },
+			phase: { type: "string" },
+		},
+		subcommands: {
+			create: {
+				usage:
+					"agency pr create <task-id> [phase-id] [--draft] [--force] [--json]",
+				minArgs: 1,
+				maxArgs: 2,
+				options: ["draft", "force", "json", "task", "phase"],
+			},
 		},
 	},
 	next: {
@@ -1019,6 +1029,7 @@ const preCommandValueOptions = new Set(["--workbase", "--cwd"])
 export interface ParsedCli {
 	readonly commandName?: keyof typeof commands
 	readonly args: string[]
+	readonly passthrough?: boolean
 	readonly values: Record<
 		string,
 		boolean | string | (boolean | string)[] | undefined
@@ -1091,6 +1102,7 @@ const targetSlots = (
 	if (commandName === "worktree" && subcommand !== "list") {
 		return ["task", "phase"]
 	}
+	if (commandName === "pr" && subcommand === "create") return ["task", "phase"]
 	return []
 }
 
@@ -1311,7 +1323,15 @@ export function parseCli(args: readonly string[]): ParsedCli {
 			"agency <command> [options]",
 		)
 	}
-	if (commandName === "pr") {
+	const prArgs = args.slice(commandIndex + 1)
+	const taskAwarePrCreate =
+		commandName === "pr" &&
+		prArgs[0] === "create" &&
+		((prArgs[1] !== undefined && !prArgs[1].startsWith("-")) ||
+			prArgs.some(
+				(argument) => argument === "--task" || argument.startsWith("--task="),
+			))
+	if (commandName === "pr" && !taskAwarePrCreate) {
 		const parsed = parse(
 			args.slice(0, commandIndex),
 			rootOptions,
@@ -1336,7 +1356,8 @@ export function parseCli(args: readonly string[]): ParsedCli {
 		}
 		return {
 			commandName,
-			args: [...args.slice(commandIndex + 1)],
+			args: prArgs,
+			passthrough: true,
 			values: parsed.values,
 		}
 	}

package/src/cli.test.ts

@@ -598,6 +598,20 @@ exit 23
 				blockers: [{ kind: "status", reason: "Task status is dropped" }],
 			},
 		])
+
+		const blockedPr = await runCli(["pr", "create", "finished", "--json"], root)
+		expect(blockedPr.exitCode).toBe(1)
+		expect(blockedPr.stderr).toBe("")
+		expect(JSON.parse(blockedPr.stdout)).toMatchObject({
+			ok: false,
+			error: {
+				code: "EXECUTION_BLOCKED",
+				fields: {
+					status: "dropped",
+					blockers: [{ kind: "status", reason: "Task status is dropped" }],
+				},
+			},
+		})
 	})
 
 	test("reports and synchronizes managed integration files", async () => {

package/src/commands/pr.test.ts

@@ -1,8 +1,15 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { Effect } from "effect"
 import { chmod, mkdir, realpath } from "node:fs/promises"
 import { dirname, join } from "node:path"
-import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
-import { pr } from "./pr"
+import { PullRequestService } from "../services/PullRequestService"
+import {
+	captureLogs,
+	cleanupTempDir,
+	createTempDir,
+	runTestEffect,
+} from "../test-utils"
+import { pr, prCreate } from "./pr"
 
 const write = async (root: string, path: string, content: string) => {
 	const fullPath = join(root, path)
@@ -95,6 +102,39 @@ status: open
 		return root
 	}
 
+	test("creates and records an Agency pull request", async () => {
+		const url = "https://github.com/markjaquith/agency/pull/123"
+		let received: unknown[] = []
+		const logs = await captureLogs(() =>
+			Effect.runPromise(
+				prCreate({
+					taskId: "example",
+					phaseId: "implementation",
+					draft: true,
+					force: true,
+					cwd: "/workbase",
+					json: true,
+				}).pipe(
+					Effect.provideService(PullRequestService, {
+						create: (...args: unknown[]) => {
+							received = args
+							return Effect.succeed(url)
+						},
+					} as never),
+				) as Effect.Effect<void, unknown, never>,
+			),
+		)
+
+		expect(JSON.parse(logs[0]!)).toEqual({ url })
+		expect(received).toEqual([
+			"example",
+			"implementation",
+			true,
+			"/workbase",
+			expect.objectContaining({ force: true, draft: true, json: true }),
+		])
+	})
+
 	test("focuses task and descendant invocations on the writable checkout", async () => {
 		const root = await createExecutionWorkbase()
 		const task = join(root, "tasks/single")

package/src/commands/pr.ts

@@ -2,6 +2,30 @@ import { Effect } from "effect"
 import { resolve } from "node:path"
 import { ContextService } from "../services/ContextService"
 import { FileSystemService } from "../services/FileSystemService"
+import { PullRequestService } from "../services/PullRequestService"
+import type { BaseCommandOptions } from "../utils/command"
+import { createLoggers } from "../utils/effect"
+
+interface PrCreateOptions extends BaseCommandOptions {
+	readonly taskId: string
+	readonly phaseId?: string
+	readonly draft?: boolean
+	readonly force?: boolean
+}
+
+export const prCreate = (options: PrCreateOptions) =>
+	Effect.gen(function* () {
+		const pullRequests = yield* PullRequestService
+		const { log } = createLoggers(options)
+		const url = yield* pullRequests.create(
+			options.taskId,
+			options.phaseId,
+			options.draft,
+			options.cwd ?? process.cwd(),
+			options,
+		)
+		log(options.json ? JSON.stringify({ url }, null, 2) : url)
+	})
 
 export const pr = (args: readonly string[], cwd: string = process.cwd()) =>
 	Effect.gen(function* () {
@@ -24,8 +48,10 @@ export const pr = (args: readonly string[], cwd: string = process.cwd()) =>
 	})
 
 export const help = `
-Usage: agency pr [args...]
+Usage: agency pr create <task-id> [phase-id] [--draft] [--force] [--json]
+       agency pr [args...]
 
-Run gh pr unchanged, focusing the writable repository checkout when invoked
-from an Agency execution task or phase.
+Create records a pull request for an Agency execution unit. Other invocations
+run gh pr unchanged, focusing the writable repository checkout when invoked from
+an Agency execution task or phase.
 `

package/src/workbase/AGENTS.md

@@ -59,8 +59,8 @@ to override readiness.
 - Do not run `agency work` from an active agent session unless the user
   explicitly asks to launch another agent.
 - Run `agency validate` before worktree or pull-request operations.
-- Create a pull request only with explicit user intent. Run `agency pr create`
-  from its execution unit, then use `agency sync --apply` to reconcile PR state.
+- Create a pull request only with explicit user intent. Run
+  `agency pr create <task> [phase]` so the URL is recorded durably.
 
 ## Execution