@markjaquith/agency 2.4.0 → 2.6.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
@@ -241,11 +240,15 @@ agency pr create refresh-copy
 
 ```text
 agency init [path] [--json]
+agency workbase add <path> [--json]
+agency workbase list [--json]
 agency repo add <alias> <remote> [--json]
 agency repo link <alias> <path> [--json]
 agency repo list [--json]
 ```
 
+Registered workbases are stored in
+`$XDG_CONFIG_HOME/agency/workbases.json` (or `~/.config/agency/workbases.json`).
 `repo add` creates a bare clone. `repo link` creates a symlink to an existing Git
 repository. Alias names are then used by all documents and commands.
 
@@ -266,19 +269,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 +298,7 @@ Inspect tasks:
 ```text
 agency task list [--json]
 agency task show <id> [--json]
+agency task status <id> <open|working|delegated|done|dropped> [--json]
 ```
 
 To add a phase to an existing single-phase task, name the phase that will own
@@ -312,8 +325,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|delegated|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 `delegated`, `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
@@ -322,8 +355,10 @@ agency pr create <task-id> [phase-id] [--draft] [--json]
 ```
 
 `agency work` infers an epic, task, or phase from the current directory. From
-elsewhere in the workbase, it presents the full hierarchy in `fzf`. If `fzf` is
-not installed, Agency prints the hierarchy and asks for an explicit target.
+elsewhere in the workbase, it presents the full hierarchy in `fzf`. Outside a
+workbase, it first presents the registered workbases, then the selected
+workbase's hierarchy. If `fzf` is not installed, Agency prints the available
+choices and asks for an explicit target.
 
 Epic and multi-phase task targets launch orchestration agents beside their
 documents. Single-phase tasks and phases fetch repositories, create or reuse
@@ -351,13 +386,14 @@ the owning `TASK.md` or `PHASE.md`.
 
 ```text
 agency status [--json]
-agency validate [--json]
+agency validate [path] [--json]
 ```
 
 Validation checks JSON and YAML parsing, Effect Schema conformance, repository
 aliases, parent/child backlinks, phase directories, duplicate references,
 unknown dependencies, and dependency cycles. YAML duplicate keys, anchors,
-aliases, and custom tags are rejected.
+aliases, and custom tags are rejected. When path is omitted outside a workbase,
+Agency prompts for a registered workbase.
 
 ## Agent Skill
 

package/cli.ts

@@ -11,6 +11,8 @@ 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 { workbase, help as workbaseHelp } from "./src/commands/workbase"
 import type { Command } from "./src/types"
 import { FileSystemService } from "./src/services/FileSystemService"
 import { WorkbaseService } from "./src/services/WorkbaseService"
@@ -20,6 +22,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 +34,7 @@ const CliLayer = Layer.mergeAll(
 	PhaseService.Default,
 	WorktreeService.Default,
 	PullRequestService.Default,
+	ArchiveService.Default,
 )
 
 /**
@@ -153,6 +157,40 @@ 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,
+				}),
+			)
+		},
+	},
+	workbase: {
+		run: async (args: string[], options: Record<string, any>) => {
+			if (options.help) {
+				console.log(workbaseHelp)
+				return
+			}
+			await runCommand(
+				workbase({
+					subcommand: 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) {
@@ -231,13 +269,14 @@ const commands: Record<string, Command> = {
 		},
 	},
 	validate: {
-		run: async (_args: string[], options: Record<string, any>) => {
+		run: async (args: string[], options: Record<string, any>) => {
 			if (options.help) {
 				console.log(validateHelp)
 				return
 			}
 			await runCommand(
 				validate({
+					path: args[0],
 					silent: options.silent,
 					verbose: options.verbose,
 					json: options.json,
@@ -255,14 +294,16 @@ Usage: agency <command> [options]
 
 Commands:
   init [path]            Initialize an Agency workbase
+  workbase <subcommand>  Manage registered workbases
   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
   repo <subcommand>      Manage workbase repositories
   status                 Show status for the current workbase
-  validate               Validate the current workbase
+  validate [path]        Validate a workbase
 
 Global Options:
   -h, --help             Show help for a command

package/package.json

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

package/skills/agency/SKILL.md

@@ -58,6 +58,13 @@ If no workbase is found, do not initialize one without user intent. When asked:
 agency init [path]
 ```
 
+Register known workbases so `agency work` can select one when run elsewhere:
+
+```bash
+agency workbase add <path>
+agency workbase list
+```
+
 ## Repository Aliases
 
 Add a remote as an Agency-managed bare repository:
@@ -100,17 +107,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 +132,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 +182,7 @@ repos:
 branch: task/example
 base: main
 pr: null
+status: open
 ---
 ```
 
@@ -189,6 +202,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`, `delegated`, `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,16 +211,36 @@ 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|delegated|done|dropped>
+agency phase status <task-id> <phase-id> <open|working|delegated|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
-agency validate
+agency validate [path]
 ```
 
 Use `--json` when diagnostics will be consumed programmatically. Resolve all
 validation errors before materializing worktrees or creating PRs. Validation
 checks schemas, aliases, backlinks, phase directories, duplicate references,
 duplicate writable branch ownership, unknown dependencies, and dependency cycles.
+Outside a workbase, omitting path opens the registered-workbase picker.
 
 ## Worktrees And Agent Launch
 
@@ -220,6 +255,7 @@ repositories for execution targets, creates or reuses their worktrees, and
 replaces the current process with the selected agent. It infers the nearest
 epic, task, or phase from the current directory; otherwise it opens an `fzf`
 picker containing the workbase hierarchy.
+Outside a workbase, it first opens a picker containing registered workbases.
 
 Epic and multi-phase task targets are orchestration sessions launched beside
 their documents. Single-phase tasks and phases are execution sessions launched

package/src/cli.test.ts

@@ -12,9 +12,14 @@ interface CliResult {
 	stderr: string
 }
 
-async function runCli(args: string[], cwd = projectRoot): Promise<CliResult> {
+async function runCli(
+	args: string[],
+	cwd = projectRoot,
+	env?: Record<string, string>,
+): Promise<CliResult> {
 	const subprocess = Bun.spawn([process.execPath, cliPath, ...args], {
 		cwd,
+		env: env ? { ...process.env, ...env } : undefined,
 		stdout: "pipe",
 		stderr: "pipe",
 	})
@@ -76,10 +81,12 @@ describe("CLI", () => {
 	test("routes command help and global options on either side of commands", async () => {
 		for (const [command, usage] of [
 			["init", "Usage: agency init"],
+			["workbase", "Usage: agency workbase"],
 			["repo", "Usage: agency repo"],
 			["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"],
@@ -105,6 +112,25 @@ describe("CLI", () => {
 		expect(after).toEqual({ exitCode: 0, stdout: "", stderr: "" })
 	})
 
+	test("registers and lists workbases", async () => {
+		const parent = await createTempDir()
+		tempDirs.push(parent)
+		const root = join(parent, "workbase")
+		const env = { XDG_CONFIG_HOME: join(parent, "config") }
+
+		expect(
+			parseJson(await runCli(["init", root, "--json"], parent, env)),
+		).toEqual({
+			root,
+		})
+		expect(
+			parseJson(await runCli(["workbase", "add", root, "--json"], parent, env)),
+		).toEqual({ path: await realpath(root) })
+		expect(
+			parseJson(await runCli(["workbase", "list", "--json"], parent, env)),
+		).toEqual([await realpath(root)])
+	})
+
 	test("runs a multi-phase domain workflow through subprocesses", async () => {
 		const parent = await createTempDir()
 		tempDirs.push(parent)
@@ -277,9 +303,11 @@ describe("CLI", () => {
 			issues: [],
 		})
 
-		const validation = parseJson(await runCli(["validate", "--json"], root))
+		const validation = parseJson(
+			await runCli(["validate", root, "--json"], parent),
+		)
 		expect(validation).toEqual({
-			root: workbaseRoot,
+			root,
 			issues: [],
 			epicCount: 1,
 			taskCount: 1,

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, delegated, done, or dropped
 
 Create options:
   --description <text>  Short description of the phase