@markjaquith/agency 1.11.1 → 2.1.0

package/src/commands/work.ts

@@ -1,193 +1,193 @@
-import { join } from "node:path"
 import { Effect } from "effect"
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path"
 import type { BaseCommandOptions } from "../utils/command"
+import { WorktreeService } from "../services/WorktreeService"
 import { FileSystemService } from "../services/FileSystemService"
-import { createLoggers, ensureGitRepo } from "../utils/effect"
-import { spawnProcess } from "../utils/process"
+import { WorkbaseService } from "../services/WorkbaseService"
+import { EpicService } from "../services/EpicService"
+import { TaskService } from "../services/TaskService"
+import { PhaseService } from "../services/PhaseService"
+import { createLoggers } from "../utils/effect"
 import { execvp } from "../utils/exec"
+import {
+	buildWorkTargetChoices,
+	pickWorkTarget,
+	type PickWorkTarget,
+	type WorkTarget,
+} from "../workbase/work-target"
 
 interface WorkOptions extends BaseCommandOptions {
-	/**
-	 * Force use of OpenCode CLI
-	 */
-	opencode?: boolean
-	/**
-	 * Force use of Claude Code CLI
-	 */
-	claude?: boolean
-	/**
-	 * Additional arguments to pass to the CLI tool
-	 */
-	extraArgs?: string[]
-	/**
-	 * Internal option to disable exec for testing.
-	 * When true, uses spawn instead of exec so tests can complete.
-	 */
-	_noExec?: boolean
+	readonly taskId?: string
+	readonly phaseId?: string
+	readonly epicId?: string
+	readonly opencode?: boolean
+	readonly claude?: boolean
 }
 
-export const work = (options: WorkOptions = {}) =>
-	Effect.gen(function* () {
-		const { verboseLog } = createLoggers(options)
-
-		const fs = yield* FileSystemService
+type LaunchAgent = (cli: string, args: readonly string[], cwd: string) => void
 
-		const gitRoot = yield* ensureGitRepo()
+const launchAgent: LaunchAgent = (cli, args, cwd) => {
+	process.chdir(cwd)
+	execvp(cli, [...args])
+}
 
-		// Check if TASK.md exists
-		const taskPath = join(gitRoot, "TASK.md")
-		const taskExists = yield* fs.exists(taskPath)
-		if (!taskExists) {
+export const work = (
+	options: WorkOptions = {},
+	launch: LaunchAgent = launchAgent,
+	pick: PickWorkTarget = pickWorkTarget,
+) =>
+	Effect.gen(function* () {
+		if (options.opencode && options.claude) {
 			return yield* Effect.fail(
-				new Error("TASK.md not found. Run 'agency task' first to create it."),
+				new Error("Cannot use both --opencode and --claude"),
 			)
 		}
-
-		verboseLog(`Found TASK.md at: ${taskPath}`)
-
-		// Change to git root before executing
-		process.chdir(gitRoot)
-
-		// Check for conflicting flags
-		if (options.opencode && options.claude) {
+		if (options.epicId && (options.taskId || options.phaseId)) {
 			return yield* Effect.fail(
-				new Error(
-					"Cannot use both --opencode and --claude flags together. Choose one.",
-				),
+				new Error("Cannot combine --epic with a task or phase ID"),
 			)
 		}
 
-		// Check which CLI tool is available
-		const hasOpencode = yield* Effect.tryPromise({
-			try: async () => {
-				const result = Bun.spawnSync(["which", "opencode"], {
-					stdout: "ignore",
-					stderr: "ignore",
-				})
-				return result.exitCode === 0
-			},
-			catch: () => false,
-		})
-
-		const hasClaude = yield* Effect.tryPromise({
-			try: async () => {
-				const result = Bun.spawnSync(["which", "claude"], {
-					stdout: "ignore",
-					stderr: "ignore",
-				})
-				return result.exitCode === 0
-			},
-			catch: () => false,
-		})
+		const worktrees = yield* WorktreeService
+		const fs = yield* FileSystemService
+		const workbase = yield* WorkbaseService
+		const epics = yield* EpicService
+		const tasks = yield* TaskService
+		const phases = yield* PhaseService
+		const { log, verboseLog } = createLoggers(options)
+		const cwd = options.cwd ?? process.cwd()
+		const root = yield* workbase.discover(cwd)
+
+		let target: WorkTarget | null = null
+		if (options.epicId) {
+			const epic = yield* epics.show(options.epicId, root)
+			target = { kind: "epic", epicId: epic.id, path: epic.path }
+		} else if (options.taskId) {
+			const task = yield* tasks.show(options.taskId, root)
+			if (options.phaseId) {
+				const phase = yield* phases.show(task.id, options.phaseId, root)
+				target = {
+					kind: "phase",
+					taskId: task.id,
+					phaseId: phase.id,
+					path: phase.path,
+				}
+			} else {
+				target = {
+					kind: "task",
+					taskId: task.id,
+					path: task.path,
+					multiPhase: "phases" in task.data,
+				}
+			}
+		} else {
+			const path = relative(root, resolve(cwd))
+			const parts =
+				!path || isAbsolute(path) || path.startsWith(`..${sep}`)
+					? []
+					: path.split(sep)
+			if (parts[0] === "epics" && parts[1]) {
+				const epic = yield* epics.show(parts[1], root)
+				target = { kind: "epic", epicId: epic.id, path: epic.path }
+			} else if (parts[0] === "tasks" && parts[1]) {
+				const task = yield* tasks.show(parts[1], root)
+				if (parts[2] === "phases" && parts[3]) {
+					const phase = yield* phases.show(task.id, parts[3], root)
+					target = {
+						kind: "phase",
+						taskId: task.id,
+						phaseId: phase.id,
+						path: phase.path,
+					}
+				} else {
+					target = {
+						kind: "task",
+						taskId: task.id,
+						path: task.path,
+						multiPhase: "phases" in task.data,
+					}
+				}
+			}
+		}
 
-		// Determine which CLI to use based on flags or auto-detection
-		let useOpencode: boolean
-		if (options.opencode) {
-			if (!hasOpencode) {
-				return yield* Effect.fail(
-					new Error(
-						"opencode CLI tool not found. Please install OpenCode or remove the --opencode flag.",
-					),
-				)
+		if (!target) {
+			const epicRecords = yield* epics.list(root)
+			const taskRecords = yield* tasks.list(root)
+			const phaseRecords = []
+			for (const task of taskRecords) {
+				if ("phases" in task.data) {
+					phaseRecords.push(...(yield* phases.list(task.id, root)))
+				}
 			}
-			useOpencode = true
-			verboseLog("Using opencode (explicitly requested)")
-		} else if (options.claude) {
-			if (!hasClaude) {
+			const choices = buildWorkTargetChoices(
+				epicRecords,
+				taskRecords,
+				phaseRecords,
+			)
+			if (choices.length === 0) {
 				return yield* Effect.fail(
-					new Error(
-						"claude CLI tool not found. Please install Claude Code or remove the --claude flag.",
-					),
+					new Error("No epics, tasks, or phases found in this workbase"),
 				)
 			}
-			useOpencode = false
-			verboseLog("Using claude (explicitly requested)")
-		} else {
-			// Auto-detect
-			if (!hasOpencode && !hasClaude) {
+			const fzf = yield* fs.runCommand(["which", "fzf"], {
+				captureOutput: true,
+			})
+			if (fzf.exitCode !== 0) {
+				for (const choice of choices) log(choice.label)
 				return yield* Effect.fail(
 					new Error(
-						"Neither opencode nor claude CLI tool found. Please install OpenCode or Claude Code.",
+						"fzf is required to select a work target; install fzf or provide a target explicitly",
 					),
 				)
 			}
-			useOpencode = hasOpencode
-			verboseLog(`Using ${useOpencode ? "opencode" : "claude"} (auto-detected)`)
+			target = yield* pick(choices)
+			if (!target) return
 		}
 
-		const cliName = useOpencode ? "opencode" : "claude"
-		const baseArgs = useOpencode
-			? [cliName, "--prompt", "Start the task"]
-			: [cliName, "Start the task"]
-
-		// Append extra args if provided
-		const cliArgs =
-			options.extraArgs && options.extraArgs.length > 0
-				? [...baseArgs, ...options.extraArgs]
-				: baseArgs
-
-		if (options.extraArgs && options.extraArgs.length > 0) {
-			verboseLog(
-				`Running ${cliName} with extra args: ${options.extraArgs.join(" ")}`,
-			)
+		let prompt: string
+		let launchPath: string
+		if (target.kind === "epic") {
+			prompt = `Work on the epic. Read ${target.path}.`
+			launchPath = dirname(target.path)
+		} else if (target.kind === "task" && target.multiPhase) {
+			prompt = `Work on the task. Read ${target.path}.`
+			launchPath = dirname(target.path)
 		} else {
-			verboseLog(`Running ${cliName} with task prompt...`)
+			const taskId = target.taskId
+			const phaseId = target.kind === "phase" ? target.phaseId : undefined
+			const workspace = yield* worktrees.materialize(taskId, phaseId, root)
+			prompt = workspace.phasePath
+				? `Start the task. Read ${workspace.taskPath} and ${workspace.phasePath}.`
+				: `Start the task. Read ${workspace.taskPath}.`
+			launchPath = workspace.writablePath
 		}
 
-		// For testing, we need to use spawn instead of exec since exec never returns
-		if (options._noExec) {
-			const result = yield* spawnProcess(cliArgs, {
-				cwd: gitRoot,
-				stdout: "inherit",
-				stderr: "inherit",
-			}).pipe(
-				Effect.catchAll((error) =>
-					Effect.fail(
-						new Error(`${cliName} exited with code ${error.exitCode}`),
-					),
-				),
-			)
-
-			if (result.exitCode !== 0) {
-				return yield* Effect.fail(
-					new Error(`${cliName} exited with code ${result.exitCode}`),
-				)
-			}
-		} else {
-			// Use execvp to replace the current process with the CLI tool
-			// This will never return - the process is completely replaced
-			execvp(cliName, cliArgs)
+		const requested = options.claude ? "claude" : "opencode"
+		let cli = requested
+		let available = yield* fs.runCommand(["which", cli], {
+			captureOutput: true,
+		})
+		if (available.exitCode !== 0 && !options.opencode && !options.claude) {
+			cli = "claude"
+			available = yield* fs.runCommand(["which", cli], { captureOutput: true })
+		}
+		if (available.exitCode !== 0) {
+			return yield* Effect.fail(new Error(`${cli} CLI tool not found`))
 		}
+
+		verboseLog(`Launching ${cli} in ${launchPath}`)
+		const args = cli === "opencode" ? ["--prompt", prompt] : [prompt]
+		launch(cli, [cli, ...args], launchPath)
 	})
 
 export const help = `
-Usage: agency work [options] [-- extra-args...]
-
-Start working on the task described in TASK.md using OpenCode or Claude Code.
+Usage: agency work [<task-id> [phase-id] | --epic <epic-id>]
 
-This command replaces the current process with OpenCode (if available) or
-Claude Code (if OpenCode is not available), launching it with a prompt to
-get started on the task described in your TASK.md file.
+Launch an agent for the current epic, task, or phase. Outside an entity
+directory, select one with fzf.
 
 Options:
-  --opencode            Force use of OpenCode CLI
-  --claude              Force use of Claude Code CLI
-
-Pass-through Arguments:
-  Use -- to pass additional arguments to the underlying CLI tool.
-  Everything after -- will be forwarded to opencode or claude.
-
-Examples:
-  agency work                                  # Auto-detect (prefers opencode)
-  agency work --opencode                       # Explicitly use OpenCode
-  agency work --claude                         # Explicitly use Claude Code
-  agency work -- --model claude-sonnet-4-20250514  # Pass custom args to CLI
-
-Notes:
-  - Requires TASK.md to exist (run 'agency task' first)
-  - Requires either opencode or claude to be installed and available in PATH
-  - By default, prefers opencode if both are available
-  - Use --opencode or --claude to override auto-detection
-  - Arguments after -- are passed directly to the underlying tool
-  - Replaces the current process (agency exits and the tool takes over)
+  --epic <id>         Work on an epic
+  --opencode           Require OpenCode
+  --claude             Require Claude Code
 `

package/src/services/EpicService.test.ts

@@ -0,0 +1,71 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { mkdir } from "node:fs/promises"
+import { join } from "node:path"
+import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
+import { Effect } from "effect"
+import { EpicService } from "./EpicService"
+
+describe("EpicService", () => {
+	let root: string
+
+	beforeEach(async () => {
+		root = await createTempDir()
+		await Bun.write(join(root, "agency.json"), '{"version":2}\n')
+		await mkdir(join(root, "repos/agency"), { recursive: true })
+	})
+
+	afterEach(async () => {
+		await cleanupTempDir(root)
+	})
+
+	test("creates, lists, and shows epics", async () => {
+		const created = await runTestEffect(
+			EpicService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						"workspace-orchestration",
+						"https://example.com/tickets/epic",
+						[{ repo: "agency", ref: "main" }],
+						root,
+					),
+				),
+			),
+		)
+
+		expect(created.content).toContain("ticketUrl:")
+		expect(created.content).toContain("tasks: []")
+
+		const records = await runTestEffect(
+			EpicService.pipe(Effect.flatMap((service) => service.list(root))),
+		)
+		expect(records.map((record) => record.id)).toEqual([
+			"workspace-orchestration",
+		])
+
+		const shown = await runTestEffect(
+			EpicService.pipe(
+				Effect.flatMap((service) =>
+					service.show("workspace-orchestration", root),
+				),
+			),
+		)
+		expect(shown.path).toBe(join(root, "epics/workspace-orchestration/EPIC.md"))
+	})
+
+	test("rejects unknown repository aliases", async () => {
+		await expect(
+			runTestEffect(
+				EpicService.pipe(
+					Effect.flatMap((service) =>
+						service.create(
+							"example",
+							"https://example.com/tickets/epic",
+							[{ repo: "missing", ref: "main" }],
+							root,
+						),
+					),
+				),
+			),
+		).rejects.toThrow("Unknown repository alias 'missing'")
+	})
+})

package/src/services/EpicService.ts

@@ -0,0 +1,135 @@
+import { Schema, TreeFormatter } from "@effect/schema"
+import { Data, Effect, Either } from "effect"
+import { join } from "node:path"
+import { FileSystemService } from "./FileSystemService"
+import { WorkbaseService } from "./WorkbaseService"
+import {
+	EpicFrontmatter,
+	EntityId,
+	type RepositoryReference,
+} from "../workbase/schemas"
+import {
+	formatMarkdownDocument,
+	parseFrontmatter,
+} from "../workbase/frontmatter"
+
+class EpicError extends Data.TaggedError("EpicError")<{
+	readonly message: string
+}> {}
+
+export interface EpicRecord {
+	readonly id: string
+	readonly path: string
+	readonly content: string
+	readonly data: Schema.Schema.Type<typeof EpicFrontmatter>
+}
+
+const decodeEpic = (input: unknown) => {
+	const result = Schema.decodeUnknownEither(EpicFrontmatter, {
+		errors: "all",
+		onExcessProperty: "error",
+	})(input)
+	return Either.isLeft(result)
+		? Effect.fail(
+				new EpicError({ message: TreeFormatter.formatErrorSync(result.left) }),
+			)
+		: Effect.succeed(result.right)
+}
+
+const decodeId = (id: string) => {
+	const result = Schema.decodeUnknownEither(EntityId)(id)
+	return Either.isLeft(result)
+		? Effect.fail(new EpicError({ message: `Invalid epic ID '${id}'` }))
+		: Effect.succeed(result.right)
+}
+
+export class EpicService extends Effect.Service<EpicService>()("EpicService", {
+	sync: () => ({
+		create: (
+			id: string,
+			ticketUrl: string,
+			repos: readonly RepositoryReference[],
+			startPath: string = process.cwd(),
+			description?: string,
+		) =>
+			Effect.gen(function* () {
+				const fs = yield* FileSystemService
+				const workbase = yield* WorkbaseService
+				const root = yield* workbase.discover(startPath)
+				const validId = yield* decodeId(id)
+				const data = yield* decodeEpic({
+					ticketUrl,
+					...(description !== undefined ? { description } : {}),
+					repos,
+					tasks: [],
+				})
+				const directory = join(root, "epics", validId)
+				const path = join(directory, "EPIC.md")
+
+				if (yield* fs.exists(directory)) {
+					return yield* new EpicError({
+						message: `Epic '${validId}' already exists`,
+					})
+				}
+
+				for (const { repo: alias } of data.repos) {
+					if (!(yield* fs.exists(join(root, "repos", alias)))) {
+						return yield* new EpicError({
+							message: `Unknown repository alias '${alias}'`,
+						})
+					}
+				}
+
+				yield* fs.createDirectory(directory)
+				const title = validId
+					.split("-")
+					.map((part) => part[0]?.toUpperCase() + part.slice(1))
+					.join(" ")
+				const content = formatMarkdownDocument(
+					data,
+					`# ${title}\n\nDescribe the epic outcome.`,
+				)
+				yield* fs.writeFile(path, content)
+				return { id: validId, path, content, data } satisfies EpicRecord
+			}),
+
+		list: (startPath: string = process.cwd()) =>
+			Effect.gen(function* () {
+				const fs = yield* FileSystemService
+				const workbase = yield* WorkbaseService
+				const root = yield* workbase.discover(startPath)
+				const directory = join(root, "epics")
+				if (!(yield* fs.isDirectory(directory))) {
+					return [] as EpicRecord[]
+				}
+
+				const entries = (yield* fs.readDirectory(directory))
+					.filter((entry) => entry.isDirectory)
+					.sort((a, b) => a.name.localeCompare(b.name))
+				const records: EpicRecord[] = []
+				for (const entry of entries) {
+					const path = join(directory, entry.name, "EPIC.md")
+					if (!(yield* fs.exists(path))) continue
+					const content = yield* fs.readFile(path)
+					const parsed = yield* parseFrontmatter(content, path)
+					const data = yield* decodeEpic(parsed.data)
+					records.push({ id: entry.name, path, content, data })
+				}
+				return records
+			}),
+
+		show: (id: string, startPath: string = process.cwd()) =>
+			Effect.gen(function* () {
+				const service = yield* EpicService
+				const validId = yield* decodeId(id)
+				const records = yield* service.list(startPath)
+				const record = records.find((epic) => epic.id === validId)
+				if (!record) {
+					return yield* new EpicError({
+						message: `Epic '${validId}' does not exist`,
+					})
+				}
+				return record
+			}),
+	}),
+}) {}