@markjaquith/agency 2.3.0 → 2.5.0

package/README.md

@@ -43,6 +43,8 @@ frontmatter; prose below it supplies human and agent context.
 ```text
 workbase/
   AGENTS.md                # managed workbase instructions
+  .opencode/
+    opencode.jsonc         # managed task and epic references
   agency.json
   repos/
     frontend/              # bare Git repository or symlink
@@ -69,10 +71,11 @@ workbase/
             backend/
 ```
 
-Agency creates `AGENTS.md` during initialization and ensures it exists whenever
-the workbase is discovered. A checksum in the generated file lets newer Agency
-versions refresh unmodified instructions while preserving custom or edited
-files.
+Agency creates `AGENTS.md` and `.opencode/opencode.jsonc` during initialization
+and ensures they exist whenever the workbase is discovered. The OpenCode config
+grants external-directory access to task and epic references. Checksums in the
+generated files let newer Agency versions refresh unmodified content while
+preserving custom or edited files.
 
 Repository metadata comes directly from Git under `repos/{alias}`. Workbase
 configuration may provide a custom writable-worktree creation command.
@@ -177,6 +180,7 @@ repos:
 branch: task/refresh-copy
 base: main
 pr: null
+status: open
 ---
 ```
 
@@ -207,6 +211,7 @@ repos:
 branch: task/checkout-ui
 base: task/checkout-api
 pr: null
+status: open
 ---
 ```
 
@@ -222,13 +227,7 @@ cd ~/work
 agency repo add frontend git@github.com:example/frontend.git
 agency repo link backend ~/Dev/backend
 
-agency task create refresh-copy \
-  --ticket-url https://example.com/tickets/refresh-copy \
-  --description "Refresh user-facing checkout copy" \
-  --repo frontend \
-  --reference backend:main \
-  --branch task/refresh-copy \
-  --base main
+agency task new
 
 agency validate
 agency work refresh-copy
@@ -266,19 +265,28 @@ back-reference.
 
 ### Tasks
 
+Create a task interactively. Text prompts identify optional values, and known
+choices use fzf:
+
+```text
+agency task new [id]
+```
+
 Create a single-phase task:
 
 ```text
-agency task create <id> --ticket-url <url> --repo <alias>
-  --branch <name> --base <name>
-  [--description <text>] [--epic <id>] [--reference <alias>:<ref>...] [--json]
+agency task create <id> --repo <alias>
+  [--ticket-url <url>] [--description <text>] [--epic <id>]
+  [--reference <alias>:<ref>...] [--branch <name>] [--base <name>] [--json]
 ```
 
+The branch defaults to `task/<id>` and the base defaults to `main`.
+
 Create a multi-phase task container:
 
 ```text
-agency task create <id> --ticket-url <url> --multi-phase
-  [--description <text>] [--epic <id>] [--json]
+agency task create <id> --multi-phase
+  [--ticket-url <url>] [--description <text>] [--epic <id>] [--json]
 ```
 
 Inspect tasks:
@@ -286,6 +294,7 @@ Inspect tasks:
 ```text
 agency task list [--json]
 agency task show <id> [--json]
+agency task status <id> <open|working|done|dropped> [--json]
 ```
 
 To add a phase to an existing single-phase task, name the phase that will own
@@ -312,8 +321,28 @@ agency phase create <task-id> <phase-id>
 
 agency phase list <task-id> [--json]
 agency phase show <task-id> <phase-id> [--json]
+agency phase status <task-id> <phase-id> <open|working|done|dropped> [--json]
 ```
 
+Single-phase tasks and phases store status in YAML. New execution units start
+`open`, and `agency work` marks the selected execution unit `working` immediately
+before launch. Use the status subcommands to mark work `done`, `dropped`, or open
+it again. The interactive work selector displays status markers before execution
+units.
+
+### Archive
+
+```text
+agency archive epic <epic-id> [--json]
+agency archive task <task-id> [--json]
+agency archive phase <task-id> <phase-id> [--json]
+```
+
+Archived work keeps its hierarchy under `archive/`. Epic archiving includes its
+listed tasks. Task and phase archiving update the active parent document and
+reject items that active siblings depend on. Agency removes registered worktrees
+before moving files, refuses dirty worktrees, and preserves branches.
+
 ### Work and Pull Requests
 
 ```text

package/cli.ts

@@ -11,6 +11,7 @@ import { validate, help as validateHelp } from "./src/commands/validate"
 import { repo, help as repoHelp } from "./src/commands/repo"
 import { epic, help as epicHelp } from "./src/commands/epic"
 import { phase, help as phaseHelp } from "./src/commands/phase"
+import { archive, help as archiveHelp } from "./src/commands/archive"
 import type { Command } from "./src/types"
 import { FileSystemService } from "./src/services/FileSystemService"
 import { WorkbaseService } from "./src/services/WorkbaseService"
@@ -20,6 +21,7 @@ import { TaskService } from "./src/services/TaskService"
 import { PhaseService } from "./src/services/PhaseService"
 import { WorktreeService } from "./src/services/WorktreeService"
 import { PullRequestService } from "./src/services/PullRequestService"
+import { ArchiveService } from "./src/services/ArchiveService"
 
 // Create CLI layer with all services
 const CliLayer = Layer.mergeAll(
@@ -31,6 +33,7 @@ const CliLayer = Layer.mergeAll(
 	PhaseService.Default,
 	WorktreeService.Default,
 	PullRequestService.Default,
+	ArchiveService.Default,
 )
 
 /**
@@ -153,6 +156,23 @@ const commands: Record<string, Command> = {
 			)
 		},
 	},
+	archive: {
+		run: async (args: string[], options: Record<string, any>) => {
+			if (options.help) {
+				console.log(archiveHelp)
+				return
+			}
+			await runCommand(
+				archive({
+					type: args[0],
+					args: args.slice(1),
+					json: options.json,
+					silent: options.silent,
+					verbose: options.verbose,
+				}),
+			)
+		},
+	},
 	repo: {
 		run: async (args: string[], options: Record<string, any>) => {
 			if (options.help) {
@@ -257,6 +277,7 @@ Commands:
   init [path]            Initialize an Agency workbase
   epic <subcommand>      Manage epics
   phase <subcommand>     Manage task phases
+  archive <type>         Archive a work item
   task <subcommand>      Manage tasks
   work [task] [phase]    Work on an epic, task, or phase
   pr create              Create a pull request for an execution unit

package/package.json

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

package/skills/agency/SKILL.md

@@ -100,17 +100,22 @@ Epic task ordering and dependencies live in `EPIC.md`. Creating a task with
 
 ## Create Single-Phase Tasks
 
+For guided creation, run `agency task new`. It prompts for text input, uses fzf
+for known choices, and allows optional inputs to be skipped.
+
 ```bash
 agency task create <id> \
-  --ticket-url <url> \
+  [--ticket-url <url>] \
   [--description <text>] \
   [--epic <epic-id>] \
   --repo <writable-alias> \
   [--reference <read-only-alias>:<ref>] \
-  --branch <branch> \
-  --base <base>
+  [--branch <branch>] \
+  [--base <base>]
 ```
 
+The branch defaults to `task/<id>` and the base defaults to `main`.
+
 The task itself is the execution unit. Its worktrees live under
 `tasks/{id}/code/{alias}`.
 
@@ -120,7 +125,7 @@ Create the task container:
 
 ```bash
 agency task create <id> \
-  --ticket-url <url> \
+  [--ticket-url <url>] \
   [--description <text>] \
   [--epic <epic-id>] \
   --multi-phase
@@ -170,6 +175,7 @@ repos:
 branch: task/example
 base: main
 pr: null
+status: open
 ---
 ```
 
@@ -189,6 +195,8 @@ output, including mutations, entity inspection, status, validation, and PR creat
 - Multi-phase task frontmatter owns the phase dependency graph.
 - Epic frontmatter owns the child-task dependency graph.
 - `pr` is either a GitHub PR URL string or `null`.
+- Execution-unit `status` is `open`, `working`, `done`, or `dropped`. New work
+  starts open, and `agency work` marks it working before agent launch.
 - Keep directory IDs stable; encode sequencing with `dependsOn`, not numeric
   directory prefixes.
 - Do not use YAML duplicate keys, anchors, aliases, or custom tags.
@@ -196,6 +204,25 @@ output, including mutations, entity inspection, status, validation, and PR creat
 Prefer Agency commands for creation. When manually editing dependencies or
 prose, preserve backlinks and run validation immediately afterward.
 
+Update execution status with:
+
+```bash
+agency task status <task-id> <open|working|done|dropped>
+agency phase status <task-id> <phase-id> <open|working|done|dropped>
+```
+
+## Archive Completed Work
+
+```bash
+agency archive epic <epic-id>
+agency archive task <task-id>
+agency archive phase <task-id> <phase-id>
+```
+
+Use these commands instead of moving work item folders manually. Agency mirrors
+their hierarchy under `archive/`, removes registered worktrees first, and keeps
+branches. It refuses dirty worktrees and active sibling dependencies.
+
 ## Validate Every Structural Change
 
 ```bash

package/src/cli.test.ts

@@ -80,6 +80,7 @@ describe("CLI", () => {
 			["epic", "Usage: agency epic"],
 			["task", "Usage: agency task"],
 			["phase", "Usage: agency phase"],
+			["archive", "Usage: agency archive"],
 			["work", "Usage: agency work"],
 			["pr", "Usage: agency pr"],
 			["status", "Usage: agency status"],

package/src/commands/archive.test.ts

@@ -0,0 +1,69 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { join } from "node:path"
+import {
+	captureLogs,
+	cleanupTempDir,
+	createTempDir,
+	runTestEffect,
+} from "../test-utils"
+import { archive } from "./archive"
+import { task } from "./task"
+
+describe("archive command", () => {
+	let root: string
+
+	beforeEach(async () => {
+		root = await createTempDir()
+		await Bun.write(join(root, "agency.json"), '{"version":2}\n')
+		const initialized = Bun.spawnSync([
+			"git",
+			"init",
+			"--bare",
+			join(root, "repos/agency"),
+		])
+		if (initialized.exitCode !== 0) {
+			throw new Error(new TextDecoder().decode(initialized.stderr))
+		}
+		await runTestEffect(
+			task({
+				subcommand: "create",
+				args: ["example"],
+				ticketUrl: "https://example.com/task",
+				repo: "agency",
+				branch: "task/example",
+				base: "main",
+				cwd: root,
+				silent: true,
+			}),
+		)
+	})
+
+	afterEach(async () => cleanupTempDir(root))
+
+	test("archives a task and outputs the result as JSON", async () => {
+		const logs = await captureLogs(() =>
+			runTestEffect(
+				archive({
+					type: "task",
+					args: ["example"],
+					cwd: root,
+					json: true,
+				}),
+			),
+		)
+
+		expect(JSON.parse(logs[0]!)).toEqual({
+			kind: "task",
+			id: "example",
+			path: join(root, "archive/tasks/example"),
+			archivedPaths: [join(root, "archive/tasks/example")],
+			removedWorktrees: [],
+		})
+	})
+
+	test("requires a supported work item type", async () => {
+		await expect(
+			runTestEffect(archive({ args: [], cwd: root, silent: true })),
+		).rejects.toThrow("Available: epic, task, phase")
+	})
+})

package/src/commands/archive.ts

@@ -0,0 +1,70 @@
+import { Effect } from "effect"
+import { ArchiveService } from "../services/ArchiveService"
+import type { BaseCommandOptions } from "../utils/command"
+import { createLoggers } from "../utils/effect"
+
+interface ArchiveOptions extends BaseCommandOptions {
+	readonly type?: string
+	readonly args: readonly string[]
+	readonly json?: boolean
+}
+
+export const archive = (options: ArchiveOptions) =>
+	Effect.gen(function* () {
+		const archives = yield* ArchiveService
+		const { log } = createLoggers(options)
+		const cwd = options.cwd ?? process.cwd()
+		const [id, phaseId] = options.args
+
+		let result
+		switch (options.type) {
+			case "epic":
+				if (!id) {
+					return yield* Effect.fail(
+						new Error("Usage: agency archive epic <epic-id>"),
+					)
+				}
+				result = yield* archives.archiveEpic(id, cwd)
+				break
+			case "task":
+				if (!id) {
+					return yield* Effect.fail(
+						new Error("Usage: agency archive task <task-id>"),
+					)
+				}
+				result = yield* archives.archiveTask(id, cwd)
+				break
+			case "phase":
+				if (!id || !phaseId) {
+					return yield* Effect.fail(
+						new Error("Usage: agency archive phase <task-id> <phase-id>"),
+					)
+				}
+				result = yield* archives.archivePhase(id, phaseId, cwd)
+				break
+			default:
+				return yield* Effect.fail(
+					new Error("Work item type is required. Available: epic, task, phase"),
+				)
+		}
+
+		log(
+			options.json
+				? JSON.stringify(result, null, 2)
+				: `Archived ${result.kind} '${result.id}' to ${result.path}`,
+		)
+	})
+
+export const help = `
+Usage: agency archive <type> <id>
+
+Archive a work item after removing its worktrees. Branches are preserved.
+
+Types:
+  epic <epic-id>                Archive an epic and its tasks
+  task <task-id>                Archive a task
+  phase <task-id> <phase-id>    Archive a phase
+
+Options:
+  --json                        Output results as JSON
+`

package/src/commands/init.test.ts

@@ -36,6 +36,9 @@ describe("init command", () => {
 		expect(await Bun.file(join(root, "AGENTS.md")).text()).toContain(
 			"# Agency Workbase",
 		)
+		expect(
+			await Bun.file(join(root, ".opencode/opencode.jsonc")).text(),
+		).toContain('"path": "../tasks"')
 	})
 
 	test("preserves existing gitignore entries", async () => {

package/src/commands/phase.ts

@@ -90,9 +90,29 @@ export const phase = (options: PhaseOptions) =>
 				)
 				return
 			}
+			case "status": {
+				const status = options.args[2]
+				if (!taskId || !phaseId || !status) {
+					return yield* Effect.fail(
+						new Error(
+							"Usage: agency phase status <task-id> <phase-id> <status>",
+						),
+					)
+				}
+				const record = yield* phases.setStatus(taskId, phaseId, status, cwd)
+				const { content: _, ...output } = record
+				log(
+					options.json
+						? JSON.stringify(output, null, 2)
+						: `Marked phase '${phaseId}' as ${record.data.status}`,
+				)
+				return
+			}
 			default:
 				return yield* Effect.fail(
-					new Error("Subcommand is required. Available: create, list, show"),
+					new Error(
+						"Subcommand is required. Available: create, list, show, status",
+					),
 				)
 		}
 	})
@@ -104,6 +124,8 @@ Subcommands:
   create <task> <phase> Create a phase
   list <task>           List task phases
   show <task> <phase>   Show a phase
+  status <task> <phase> <status>
+                        Set open, working, done, or dropped
 
 Create options:
   --description <text>  Short description of the phase

package/src/commands/pr.ts

@@ -24,6 +24,7 @@ export const pr = (options: PrOptions) =>
 			options.phaseId,
 			options.draft,
 			options.cwd ?? process.cwd(),
+			options,
 		)
 		log(options.json ? JSON.stringify({ url }, null, 2) : url)
 	})

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

@@ -95,6 +95,7 @@ describe("task and phase command JSON output", () => {
 					branch: "task/first",
 					base: "main",
 					pr: null,
+					status: "open",
 				},
 			},
 		])
@@ -118,6 +119,7 @@ describe("task and phase command JSON output", () => {
 				branch: "task/first",
 				base: "main",
 				pr: null,
+				status: "open",
 			},
 		})
 	})
@@ -156,10 +158,53 @@ describe("task and phase command JSON output", () => {
 		expect(JSON.parse(phaseLogs[0]!)).toMatchObject({
 			taskId: "another",
 			id: "first",
-			data: { repo: "agency", branch: "task/another-first", base: "main" },
+			data: {
+				repo: "agency",
+				branch: "task/another-first",
+				base: "main",
+				status: "open",
+			},
 		})
 	})
 
+	test("sets task and phase status", async () => {
+		const phaseLogs = await captureLogs(() =>
+			runTestEffect(
+				phase({
+					subcommand: "status",
+					args: ["multi", "first", "done"],
+					cwd: root,
+					json: true,
+				}),
+			),
+		)
+		expect(JSON.parse(phaseLogs[0]!).data.status).toBe("done")
+
+		await runTestEffect(
+			task({
+				subcommand: "create",
+				args: ["single-status"],
+				ticketUrl: "https://example.com/task",
+				repo: "agency",
+				branch: "task/single-status",
+				base: "main",
+				cwd: root,
+				silent: true,
+			}),
+		)
+		const taskLogs = await captureLogs(() =>
+			runTestEffect(
+				task({
+					subcommand: "status",
+					args: ["single-status", "dropped"],
+					cwd: root,
+					json: true,
+				}),
+			),
+		)
+		expect(JSON.parse(taskLogs[0]!).data.status).toBe("dropped")
+	})
+
 	test("converts a single-phase task with an explicit first phase ID", async () => {
 		await runTestEffect(
 			task({

package/src/commands/task.test.ts

@@ -0,0 +1,94 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { mkdir } from "node:fs/promises"
+import { join } from "node:path"
+import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
+import { task, type TaskInteraction } from "./task"
+
+describe("task creation input", () => {
+	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 () => cleanupTempDir(root))
+
+	test("guides task creation and defaults branch metadata", async () => {
+		await mkdir(join(root, "epics/delivery"), { recursive: true })
+		await Bun.write(
+			join(root, "epics/delivery/EPIC.md"),
+			"---\nticketUrl: https://example.com/delivery\nrepos:\n  - repo: agency\n    ref: main\ntasks: []\n---\n\n# Delivery\n",
+		)
+		const textAnswers = ["guided-task", "", ""]
+		const prompts: string[] = []
+		const interaction: TaskInteraction = {
+			text: (prompt) => {
+				prompts.push(prompt)
+				return Effect.succeed(textAnswers.shift() ?? "")
+			},
+			select: (prompt, choices) => {
+				prompts.push(`${prompt}: ${choices.join(",")}`)
+				return Effect.succeed(
+					prompt === "Parent epic"
+						? "(none)"
+						: prompt === "Task type"
+							? "single-phase"
+							: "agency",
+				)
+			},
+		}
+
+		await runTestEffect(
+			task(
+				{ subcommand: "new", args: [], cwd: root, silent: true },
+				interaction,
+			),
+		)
+
+		const content = await Bun.file(
+			join(root, "tasks/guided-task/TASK.md"),
+		).text()
+		expect(content).toContain("ticketUrl: null")
+		expect(content).toContain("repo: agency")
+		expect(content).toContain("branch: task/guided-task")
+		expect(content).toContain("base: main")
+		expect(prompts).toEqual([
+			"Task ID: ",
+			"Ticket URL (optional): ",
+			"Description (optional): ",
+			"Parent epic: (none),delivery",
+			"Task type: single-phase,multi-phase",
+			"Writable repository: agency",
+		])
+	})
+
+	test("keeps scripted creation non-interactive and permits no ticket URL", async () => {
+		const interaction: TaskInteraction = {
+			text: () => Effect.fail(new Error("unexpected text prompt")),
+			select: () => Effect.fail(new Error("unexpected selection prompt")),
+		}
+
+		await runTestEffect(
+			task(
+				{
+					subcommand: "create",
+					args: ["scripted-task"],
+					repo: "agency",
+					cwd: root,
+					silent: true,
+				},
+				interaction,
+			),
+		)
+
+		const content = await Bun.file(
+			join(root, "tasks/scripted-task/TASK.md"),
+		).text()
+		expect(content).toContain("ticketUrl: null")
+		expect(content).toContain("branch: task/scripted-task")
+		expect(content).toContain("base: main")
+	})
+})