@markjaquith/agency 2.4.0 → 2.6.0

package/src/utils/progress.ts

@@ -0,0 +1,36 @@
+interface ProgressOptions {
+	readonly silent?: boolean
+}
+
+interface ProgressOutput {
+	readonly isTTY: boolean
+	readonly write: (text: string) => void
+}
+
+export interface Progress {
+	readonly start: (message: string) => void
+	readonly succeed: (message: string) => void
+	readonly fail: (message: string) => void
+}
+
+const terminalOutput: ProgressOutput = {
+	isTTY: Boolean(process.stderr.isTTY),
+	write: (text) => process.stderr.write(text),
+}
+
+export const createProgress = (
+	options: ProgressOptions,
+	output: ProgressOutput = terminalOutput,
+): Progress => {
+	const enabled = !options.silent && output.isTTY
+	const write = (symbol: string, message: string, complete: boolean) => {
+		if (!enabled) return
+		output.write(`\r\x1b[2K${symbol} ${message}${complete ? "\n" : ""}`)
+	}
+
+	return {
+		start: (message) => write("\x1b[2m○\x1b[0m", message, false),
+		succeed: (message) => write("\x1b[32m✓\x1b[0m", message, true),
+		fail: (message) => write("\x1b[31m✗\x1b[0m", message, true),
+	}
+}

package/src/workbase/AGENTS.md

@@ -24,7 +24,10 @@ field. Repositories listed in plural `repos` are read-only references.
 
 - Keep task-level decisions in `TASK.md` and phase-specific delivery context in
   `PHASE.md`.
+- Keep execution-unit `status` current with `agency task status` or
+  `agency phase status`; `agency work` marks launched work as `working`.
 - Do not manually create, move, or remove worktrees under `code/`.
+- Use `agency archive`, rather than moving work item folders manually.
 - Do not edit bare repositories or repository symlinks under `repos/`.
 - Do not run `agency work` from an active agent session unless the user
   explicitly asks to launch another agent.

package/src/workbase/opencode-file.ts

@@ -0,0 +1,37 @@
+import { createHash } from "node:crypto"
+
+const managedHeaderPattern =
+	/^\/\/ agency-managed: sha256=([a-f0-9]{64})\r?\n\r?\n/
+
+const checksum = (content: string) =>
+	createHash("sha256").update(content).digest("hex")
+
+const body = `${JSON.stringify(
+	{
+		$schema: "https://opencode.ai/config.json",
+		references: {
+			tasks: {
+				path: "../tasks",
+				description: "Agency task definitions and execution context",
+			},
+			epics: {
+				path: "../epics",
+				description: "Agency epic definitions and orchestration context",
+			},
+		},
+	},
+	null,
+	2,
+)}\n`
+
+const renderManagedWorkbaseOpencode = (content: string = body) =>
+	`// agency-managed: sha256=${checksum(content)}\n\n${content}`
+
+export const managedWorkbaseOpencode = renderManagedWorkbaseOpencode()
+
+export const canUpdateManagedWorkbaseOpencode = (content: string) => {
+	const match = content.match(managedHeaderPattern)
+	if (!match?.[1]) return false
+
+	return checksum(content.slice(match[0].length)) === match[1]
+}

package/src/workbase/schemas.test.ts

@@ -5,7 +5,9 @@ import {
 	EpicFrontmatter,
 	PhaseFrontmatter,
 	TaskFrontmatter,
+	WorkStatus,
 	WorkbaseConfig,
+	WorkbaseRegistry,
 } from "./schemas"
 
 describe("body-of-work descriptions", () => {
@@ -53,6 +55,15 @@ describe("body-of-work descriptions", () => {
 		expect(epic.description).toBeUndefined()
 	})
 
+	test("allows tasks without an external ticket", () => {
+		const task = Schema.decodeUnknownSync(TaskFrontmatter)({
+			ticketUrl: null,
+			phases: [],
+		})
+
+		expect(task.ticketUrl).toBeNull()
+	})
+
 	test("rejects an empty description when present", () => {
 		expect(() =>
 			Schema.decodeUnknownSync(PhaseFrontmatter)({
@@ -66,6 +77,109 @@ describe("body-of-work descriptions", () => {
 	})
 })
 
+describe("work status", () => {
+	const supportedStatuses: Record<WorkStatus, true> = {
+		open: true,
+		working: true,
+		delegated: true,
+		done: true,
+		dropped: true,
+	}
+
+	test("defaults execution units to open", () => {
+		const task = Schema.decodeUnknownSync(TaskFrontmatter)({
+			ticketUrl: "https://example.com/task",
+			repo: "agency",
+			branch: "task/default-status",
+			base: "main",
+			pr: null,
+		})
+		const phase = Schema.decodeUnknownSync(PhaseFrontmatter)({
+			repo: "agency",
+			branch: "task/default-phase-status",
+			base: "main",
+			pr: null,
+		})
+
+		expect("status" in task && task.status).toBe("open")
+		expect(phase.status).toBe("open")
+	})
+
+	test("accepts every supported status on tasks and phases", () => {
+		for (const status of Object.keys(supportedStatuses) as WorkStatus[]) {
+			expect(Schema.decodeUnknownSync(WorkStatus)(status)).toBe(status)
+
+			const task = Schema.decodeUnknownSync(TaskFrontmatter)({
+				ticketUrl: null,
+				repo: "agency",
+				branch: `task/${status}`,
+				base: "main",
+				pr: null,
+				status,
+			})
+			const phase = Schema.decodeUnknownSync(PhaseFrontmatter)({
+				repo: "agency",
+				branch: `phase/${status}`,
+				base: "main",
+				pr: null,
+				status,
+			})
+
+			expect("status" in task && task.status).toBe(status)
+			expect(phase.status).toBe(status)
+		}
+	})
+
+	test("rejects unsupported statuses on tasks and phases", () => {
+		expect(() => Schema.decodeUnknownSync(WorkStatus)("blocked")).toThrow()
+		expect(() =>
+			Schema.decodeUnknownSync(TaskFrontmatter)({
+				ticketUrl: null,
+				repo: "agency",
+				branch: "task/invalid",
+				base: "main",
+				pr: null,
+				status: "blocked",
+			}),
+		).toThrow()
+		expect(() =>
+			Schema.decodeUnknownSync(PhaseFrontmatter)({
+				repo: "agency",
+				branch: "phase/invalid",
+				base: "main",
+				pr: null,
+				status: "blocked",
+			}),
+		).toThrow()
+	})
+})
+
+describe("workbase registry", () => {
+	test("accepts registered paths", () => {
+		expect(
+			Schema.decodeUnknownSync(WorkbaseRegistry)({
+				version: 1,
+				workbases: ["/work/one", "/work/two"],
+			}),
+		).toEqual({ version: 1, workbases: ["/work/one", "/work/two"] })
+	})
+
+	test("rejects invalid versions and empty paths", () => {
+		expect(() =>
+			Schema.decodeUnknownSync(WorkbaseRegistry)({
+				version: 2,
+				workbases: [],
+			}),
+		).toThrow()
+		expect(() =>
+			Schema.decodeUnknownSync(WorkbaseRegistry)({
+				version: 1,
+				workbases: [""],
+			}),
+		).toThrow()
+	})
+})
+
 describe("schema boundaries", () => {
 	const rejects = <S extends Schema.Schema.AnyNoContext>(
 		schema: S,

package/src/workbase/schemas.ts

@@ -15,6 +15,14 @@ export const RepositoryReference = Schema.Struct({
 	ref: NonEmptyString,
 })
 
+export const WorkStatus = Schema.Literal(
+	"open",
+	"working",
+	"delegated",
+	"done",
+	"dropped",
+)
+
 const Url = NonEmptyString.pipe(Schema.pattern(/^[a-zA-Z][a-zA-Z0-9+.-]*:/))
 
 const GitHubPullRequestUrl = NonEmptyString.pipe(
@@ -26,6 +34,11 @@ export const WorkbaseConfig = Schema.Struct({
 	worktreeCreateCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
 })
 
+export const WorkbaseRegistry = Schema.Struct({
+	version: Schema.Literal(1),
+	workbases: Schema.Array(NonEmptyString),
+})
+
 export const Dependency = Schema.Struct({
 	id: EntityId,
 	dependsOn: Schema.optional(Schema.Array(EntityId)),
@@ -37,6 +50,7 @@ const ExecutionUnit = {
 	branch: NonEmptyString,
 	base: NonEmptyString,
 	pr: Schema.NullOr(GitHubPullRequestUrl),
+	status: Schema.optionalWith(WorkStatus, { default: () => "open" as const }),
 }
 
 export const EpicFrontmatter = Schema.Struct({
@@ -47,14 +61,14 @@ export const EpicFrontmatter = Schema.Struct({
 })
 
 const SinglePhaseTaskFrontmatter = Schema.Struct({
-	ticketUrl: Url,
+	ticketUrl: Schema.NullOr(Url),
 	description: Description,
 	epic: Schema.optional(EntityId),
 	...ExecutionUnit,
 })
 
 const MultiPhaseTaskFrontmatter = Schema.Struct({
-	ticketUrl: Url,
+	ticketUrl: Schema.NullOr(Url),
 	description: Description,
 	epic: Schema.optional(EntityId),
 	phases: Schema.Array(Dependency),
@@ -71,8 +85,10 @@ export const PhaseFrontmatter = Schema.Struct({
 })
 
 export type WorkbaseConfig = Schema.Schema.Type<typeof WorkbaseConfig>
+export type WorkbaseRegistry = Schema.Schema.Type<typeof WorkbaseRegistry>
 export type Dependency = Schema.Schema.Type<typeof Dependency>
 export type RepositoryReference = Schema.Schema.Type<typeof RepositoryReference>
+export type WorkStatus = Schema.Schema.Type<typeof WorkStatus>
 export type EpicFrontmatter = Schema.Schema.Type<typeof EpicFrontmatter>
 export type TaskFrontmatter = Schema.Schema.Type<typeof TaskFrontmatter>
 export type PhaseFrontmatter = Schema.Schema.Type<typeof PhaseFrontmatter>

package/src/workbase/work-target.test.ts

@@ -25,32 +25,37 @@ describe("work target choices", () => {
 				{
 					id: "single",
 					path: "/workbase/tasks/single/TASK.md",
-					data: {},
+					data: { status: "done" },
 				},
 				{
 					id: "standalone",
 					path: "/workbase/tasks/standalone/TASK.md",
 					data: { description: "Independent work" },
 				},
+				{
+					id: "delegated",
+					path: "/workbase/tasks/delegated/TASK.md",
+					data: { status: "delegated" },
+				},
 			],
 			[
 				{
 					taskId: "multi",
 					id: "verify",
 					path: "/workbase/tasks/multi/phases/verify/PHASE.md",
-					data: {},
+					data: { status: "done" },
 				},
 				{
 					taskId: "multi",
 					id: "build",
 					path: "/workbase/tasks/multi/phases/build/PHASE.md",
-					data: {},
+					data: { status: "working" },
 				},
 				{
 					taskId: "multi",
 					id: "unlisted",
 					path: "/workbase/tasks/multi/phases/unlisted/PHASE.md",
-					data: {},
+					data: { status: "dropped" },
 				},
 			],
 		)
@@ -58,11 +63,12 @@ describe("work target choices", () => {
 		expect(choices.map((choice) => choice.label)).toEqual([
 			"\x1b[35m\x1b[0m delivery\x1b[2m - Ship the release\x1b[0m",
 			"  \x1b[36m󰗡\x1b[0m multi",
-			"    \x1b[33m󰔚\x1b[0m build",
-			"    \x1b[33m󰔚\x1b[0m verify",
-			"    \x1b[33m󰔚\x1b[0m unlisted",
-			"  \x1b[36m󰗡\x1b[0m single",
-			"\x1b[36m󰗡\x1b[0m standalone\x1b[2m - Independent work\x1b[0m",
+			"    \x1b[34m◐\x1b[0m \x1b[33m󰔚\x1b[0m build",
+			"    \x1b[32m✓\x1b[0m \x1b[33m󰔚\x1b[0m verify",
+			"    \x1b[31m⊘\x1b[0m \x1b[33m󰔚\x1b[0m unlisted",
+			"  \x1b[32m✓\x1b[0m \x1b[36m󰗡\x1b[0m single",
+			"\x1b[2m○\x1b[0m \x1b[36m󰗡\x1b[0m standalone\x1b[2m - Independent work\x1b[0m",
+			"\x1b[35m↗\x1b[0m \x1b[36m󰗡\x1b[0m delegated",
 		])
 		expect(choices.map((choice) => choice.target.kind)).toEqual([
 			"epic",
@@ -72,6 +78,7 @@ describe("work target choices", () => {
 			"phase",
 			"task",
 			"task",
+			"task",
 		])
 	})
 })

package/src/workbase/work-target.ts

@@ -1,4 +1,5 @@
 import { Effect } from "effect"
+import type { WorkStatus } from "./schemas"
 
 export type WorkTarget =
 	| {
@@ -36,14 +37,17 @@ interface TaskRecord {
 				readonly description?: string
 				readonly phases: readonly { readonly id: string }[]
 		  }
-		| { readonly description?: string }
+		| { readonly description?: string; readonly status?: WorkStatus }
 }
 
 interface PhaseRecord {
 	readonly taskId: string
 	readonly id: string
 	readonly path: string
-	readonly data: { readonly description?: string }
+	readonly data: {
+		readonly description?: string
+		readonly status?: WorkStatus
+	}
 }
 
 export interface WorkTargetChoice {
@@ -51,13 +55,22 @@ export interface WorkTargetChoice {
 	readonly target: WorkTarget
 }
 
+const statusIcons: Record<WorkStatus, string> = {
+	open: "\x1b[2m○\x1b[0m",
+	working: "\x1b[34m◐\x1b[0m",
+	delegated: "\x1b[35m↗\x1b[0m",
+	done: "\x1b[32m✓\x1b[0m",
+	dropped: "\x1b[31m⊘\x1b[0m",
+}
+
 const label = (
 	indent: string,
 	kind: WorkTarget["kind"],
 	id: string,
 	description?: string,
+	status?: WorkStatus,
 ) =>
-	`${indent}${
+	`${indent}${status === undefined ? "" : `${statusIcons[status]} `}${
 		{
 			epic: "\x1b[35m\x1b[0m",
 			task: "\x1b[36m󰗡\x1b[0m",
@@ -73,7 +86,13 @@ const taskChoices = (
 	const multiPhase = "phases" in task.data
 	const choices: WorkTargetChoice[] = [
 		{
-			label: label(indent, "task", task.id, task.data.description),
+			label: label(
+				indent,
+				"task",
+				task.id,
+				task.data.description,
+				multiPhase ? undefined : (task.data.status ?? "open"),
+			),
 			target: {
 				kind: "task",
 				taskId: task.id,
@@ -91,7 +110,13 @@ const taskChoices = (
 		if (!record) continue
 		renderedPhases.add(record.id)
 		choices.push({
-			label: label(`${indent}  `, "phase", record.id, record.data.description),
+			label: label(
+				`${indent}  `,
+				"phase",
+				record.id,
+				record.data.description,
+				record.data.status ?? "open",
+			),
 			target: {
 				kind: "phase",
 				taskId: task.id,
@@ -103,7 +128,13 @@ const taskChoices = (
 	for (const record of phaseRecords) {
 		if (renderedPhases.has(record.id)) continue
 		choices.push({
-			label: label(`${indent}  `, "phase", record.id, record.data.description),
+			label: label(
+				`${indent}  `,
+				"phase",
+				record.id,
+				record.data.description,
+				record.data.status ?? "open",
+			),
 			target: {
 				kind: "phase",
 				taskId: task.id,

package/src/workbase/workbase-choice.ts

@@ -0,0 +1,71 @@
+import { Effect } from "effect"
+import { resolve } from "node:path"
+import { FileSystemService } from "../services/FileSystemService"
+import { WorkbaseService } from "../services/WorkbaseService"
+
+export type PickWorkbase = (
+	workbases: readonly string[],
+) => Effect.Effect<string | null, Error>
+
+export const pickWorkbase: PickWorkbase = (workbases) =>
+	Effect.tryPromise({
+		try: async () => {
+			const input = workbases
+				.map((workbase, index) => `${index}\t${workbase}`)
+				.join("\n")
+			const process = Bun.spawn(
+				["fzf", "--delimiter=\t", "--with-nth=2..", "--prompt=Workbase> "],
+				{ stdin: new Blob([input]), stdout: "pipe", stderr: "inherit" },
+			)
+			const [exitCode, output] = await Promise.all([
+				process.exited,
+				new Response(process.stdout).text(),
+			])
+			if (exitCode === 1 || exitCode === 130) return null
+			if (exitCode !== 0) throw new Error(`fzf exited with code ${exitCode}`)
+			const index = Number.parseInt(output.split("\t", 1)[0] ?? "", 10)
+			return workbases[index] ?? null
+		},
+		catch: (cause) =>
+			new Error("Failed to select a workbase with fzf", { cause }),
+	})
+
+export const resolveWorkbase = (
+	startPath: string,
+	log: (message: string) => void,
+	pick: PickWorkbase = pickWorkbase,
+) =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystemService
+		const workbase = yield* WorkbaseService
+
+		return yield* workbase.discover(startPath).pipe(
+			Effect.catchTag("WorkbaseNotFoundError", () =>
+				Effect.gen(function* () {
+					const registered = yield* workbase.listRegistered()
+					if (registered.length === 0) {
+						return yield* Effect.fail(
+							new Error(
+								`No Agency workbase found from ${resolve(startPath)}. Register one with 'agency workbase add <path>'.`,
+							),
+						)
+					}
+
+					const fzf = yield* fs.runCommand(["which", "fzf"], {
+						captureOutput: true,
+					})
+					if (fzf.exitCode !== 0) {
+						for (const path of registered) log(path)
+						return yield* Effect.fail(
+							new Error(
+								"fzf is required to select a workbase; install fzf or run Agency from a registered workbase",
+							),
+						)
+					}
+
+					const selected = yield* pick(registered)
+					return selected ? yield* workbase.discover(selected) : null
+				}),
+			),
+		)
+	})