@markjaquith/agency 1.11.1 → 2.1.0

package/index.ts

@@ -1 +1 @@
-console.log("Hello via Bun!")
+export * from "./src/workbase/schemas"

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@markjaquith/agency",
-  "version": "1.11.1",
-  "description": "Manages personal agents files",
+  "version": "2.1.0",
+  "description": "Manage agentic work across repositories with durable workbases",
   "keywords": [
     "agents",
     "bun",
-    "personal-agents",
-    "typescript"
+    "typescript",
+    "worktrees"
   ],
   "license": "MIT",
   "author": "Mark Jaquith",
@@ -21,7 +21,7 @@
     "index.ts",
     "cli.ts",
     "src",
-    "templates",
+    "skills",
     "README.md",
     "LICENSE"
   ],
@@ -40,9 +40,7 @@
     "tag": "latest"
   },
   "scripts": {
-    "test": "find src -name '*.test.ts' ! -name '*.integration.test.ts' -print0 | xargs -0 -n 1 -P 4 bun test",
-    "test:integration": "find src -name '*.integration.test.ts' -print0 | xargs -0 -n 1 -P 4 bun test",
-    "test:all": "find src -name '*.test.ts' -print0 | xargs -0 -n 1 -P 4 bun test",
+    "test": "find src -name '*.test.ts' -print0 | xargs -0 -n 1 -P 4 bun test",
     "format": "oxfmt",
     "format:check": "oxfmt --check",
     "knip": "knip --production",
@@ -53,21 +51,18 @@
   "dependencies": {
     "@effect/schema": "^0.75.5",
     "effect": "^3.19.15",
-    "jsonc-parser": "^3.3.1",
-    "ora": "^8.2.0"
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@types/bun": "^1.3.6",
-    "knip": "^5.82.1",
-    "oxfmt": "^0.27.0"
+    "knip": "^6.27.0",
+    "oxfmt": "^0.27.0",
+    "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "typescript": "^5.9.3"
+    "typescript": "^7.0.2"
   },
   "engines": {
     "bun": ">=1.0.0"
-  },
-  "trustedDependencies": [
-    "@triggi/native-exec"
-  ]
+  }
 }

package/skills/agency/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: agency
+description: >
+  Use Agency to manage filesystem-backed workbases, repository aliases, epics,
+  tasks, phases, execution worktrees, and GitHub pull requests. Use when the
+  user asks to create, inspect, validate, or work on Agency epics/tasks/phases;
+  coordinate work across repositories; materialize task worktrees; or create a
+  PR through Agency.
+license: MIT
+compatibility: Requires the agency CLI and Git, plus OpenCode or Claude Code. Interactive work selection uses fzf; PR creation uses gh.
+---
+
+# Agency
+
+Use Agency to coordinate durable work across one or more Git repositories.
+Agency stores planning and orchestration as Markdown with YAML frontmatter while
+keeping repository checkouts as local workbase state.
+
+## Mental Model
+
+- A **workbase** is the root containing `agency.json`, `repos/`, `epics/`, and
+  `tasks/`.
+- A repository alias is a bare Git repository or symlink at `repos/{alias}`.
+- An **epic** orchestrates tasks and only reads repositories.
+- A **task** describes one durable outcome. It may be standalone or belong to an
+  epic.
+- A **phase** belongs to a multi-phase task and corresponds to one PR or intended
+  PR.
+- An **execution unit** is either a single-phase task or a phase. It has one
+  writable `repo`, optional read-only `repos`, one branch, one base, and one
+  `pr` value.
+
+IDs are directory names. Do not repeat IDs in document frontmatter.
+
+## Start By Inspecting
+
+From anywhere beneath a workbase, run:
+
+```bash
+agency status --json
+agency validate --json
+agency repo list --json
+agency epic list --json
+agency task list --json
+```
+
+Use `show` before changing an existing entity:
+
+```bash
+agency epic show <epic-id> --json
+agency task show <task-id> --json
+agency phase show <task-id> <phase-id> --json
+```
+
+If no workbase is found, do not initialize one without user intent. When asked:
+
+```bash
+agency init [path]
+```
+
+## Repository Aliases
+
+Add a remote as an Agency-managed bare repository:
+
+```bash
+agency repo add <alias> <git-remote>
+```
+
+Link an existing local Git repository:
+
+```bash
+agency repo link <alias> <path>
+```
+
+Use aliases, never absolute paths or Git URLs, in epic/task/phase frontmatter.
+
+## Choose The Correct Work Shape
+
+Use a single-phase task when one PR in one writable repository can deliver the
+outcome. Use a multi-phase task when the outcome requires multiple intended PRs,
+possibly across repositories or with sequencing dependencies. Use an epic when
+several independently meaningful tasks need orchestration.
+
+If phases are known up front, create a multi-phase task. To add a phase later,
+use `--first-phase <id>` to name the phase created from the task's existing
+execution fields and worktrees.
+
+## Create Epics
+
+```bash
+agency epic create <id> \
+  --ticket-url <url> \
+  [--description <text>] \
+  --repo <read-only-alias>:<ref> \
+  [--repo <another-alias>:<ref>]
+```
+
+Epic task ordering and dependencies live in `EPIC.md`. Creating a task with
+`--epic` automatically writes both sides of the epic/task relationship.
+
+## Create Single-Phase Tasks
+
+```bash
+agency task create <id> \
+  --ticket-url <url> \
+  [--description <text>] \
+  [--epic <epic-id>] \
+  --repo <writable-alias> \
+  [--reference <read-only-alias>:<ref>] \
+  --branch <branch> \
+  --base <base>
+```
+
+The task itself is the execution unit. Its worktrees live under
+`tasks/{id}/code/{alias}`.
+
+## Create Multi-Phase Tasks
+
+Create the task container:
+
+```bash
+agency task create <id> \
+  --ticket-url <url> \
+  [--description <text>] \
+  [--epic <epic-id>] \
+  --multi-phase
+```
+
+Then create each phase:
+
+```bash
+agency phase create <task-id> <phase-id> \
+  [--description <text>] \
+  --repo <writable-alias> \
+  [--reference <read-only-alias>:<ref>] \
+  --branch <branch> \
+  --base <base> \
+  [--depends-on <phase-id>]
+```
+
+Repeat `--reference` and `--depends-on` when needed. Phase worktrees live under
+`tasks/{task-id}/phases/{phase-id}/code/{alias}`.
+
+Convert an existing single-phase task while adding another phase:
+
+```bash
+agency phase create <task-id> <new-phase-id> \
+  --first-phase <existing-phase-id> \
+  --repo <writable-alias> \
+  --branch <new-branch> \
+  --base <base> \
+  [--depends-on <existing-phase-id>]
+```
+
+The conversion preserves task-level metadata and prose, moves execution metadata
+into the named existing phase, and relocates any materialized worktrees.
+
+## Frontmatter Rules
+
+Agency documents use YAML 1.2 frontmatter:
+
+```yaml
+---
+ticketUrl: https://example.com/tickets/example
+description: Deliver the example outcome.
+repo: application
+repos:
+  - repo: api
+    ref: main
+branch: task/example
+base: main
+pr: null
+---
+```
+
+Follow these invariants:
+
+- `ticketUrl` belongs to epics and tasks, not phases.
+- `description` is an optional non-empty summary on epics, tasks, and phases.
+- `repo` is the one writable repository for an execution unit.
+- `repos` contains `{ repo, ref }` read-only references and must not repeat `repo`.
+- Epics may declare `repos` but never `repo`.
+- A writable `(repo, branch)` pair belongs to exactly one task or phase.
+- Use a commit SHA for a read-only `ref` when reproducibility matters.
+
+Commands that print Agency-owned results accept `--json` for machine-readable
+output, including mutations, entity inspection, status, validation, and PR creation.
+
+- 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`.
+- Keep directory IDs stable; encode sequencing with `dependsOn`, not numeric
+  directory prefixes.
+- Do not use YAML duplicate keys, anchors, aliases, or custom tags.
+
+Prefer Agency commands for creation. When manually editing dependencies or
+prose, preserve backlinks and run validation immediately afterward.
+
+## Validate Every Structural Change
+
+```bash
+agency validate
+```
+
+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.
+
+## Worktrees And Agent Launch
+
+```bash
+agency work
+agency work <task-id> [phase-id]
+agency work --epic <epic-id>
+```
+
+Use `--opencode` or `--claude` to require a specific agent. This command fetches
+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.
+
+Epic and multi-phase task targets are orchestration sessions launched beside
+their documents. Single-phase tasks and phases are execution sessions launched
+in their writable checkout.
+
+The workbase may delegate writable checkout creation through
+`worktreeCreateCommand` in `agency.json`. Do not bypass that command or create a
+parallel worktree manually. Supplemental read-only checkouts are still detached
+Git worktrees managed directly by Agency at their declared refs.
+
+Agency inspects `git worktree list --porcelain` before materializing. It reuses a
+writable checkout only when both path and branch match, and reuses a reference
+checkout only when its commit matches the declared ref. If a branch is checked
+out elsewhere, choose a different branch or remove the conflicting worktree;
+never force a second checkout of the branch.
+
+Do not run `agency work` from inside an active agent session unless the user
+explicitly wants to launch a nested/replacement agent process. If already
+working in an Agency checkout, read the owning `TASK.md` and optional `PHASE.md`
+directly instead.
+
+## Create Pull Requests
+
+Only create a PR when the user explicitly requests it:
+
+```bash
+agency pr create <task-id> [phase-id] [--draft]
+```
+
+Agency requires a clean writable worktree, pushes the execution branch, runs
+`gh pr create --fill`, and records the returned URL in the owning document's
+`pr` field. If PR creation fails, do not invent or manually write a URL.
+
+## Safety Rules
+
+- Run `agency validate` before worktree or PR operations.
+- Inspect existing entities before editing them.
+- Never write through a repository listed in plural `repos`.
+- Do not manually move generated `code/` worktrees.
+- Do not manually edit bare repositories under `repos/`.
+- Do not create a PR, initialize a workbase, clone a remote, or add a symlink
+  without user intent.
+- Keep task-level decisions in `TASK.md` and delivery-specific context in
+  `PHASE.md`.

package/src/cli.test.ts

@@ -0,0 +1,290 @@
+import { afterEach, describe, expect, test } from "bun:test"
+import { realpath } from "node:fs/promises"
+import { join } from "node:path"
+import { cleanupTempDir, createTempDir } from "./test-utils"
+
+const projectRoot = join(import.meta.dir, "..")
+const cliPath = join(projectRoot, "cli.ts")
+
+interface CliResult {
+	exitCode: number
+	stdout: string
+	stderr: string
+}
+
+async function runCli(args: string[], cwd = projectRoot): Promise<CliResult> {
+	const subprocess = Bun.spawn([process.execPath, cliPath, ...args], {
+		cwd,
+		stdout: "pipe",
+		stderr: "pipe",
+	})
+	const [exitCode, stdout, stderr] = await Promise.all([
+		subprocess.exited,
+		new Response(subprocess.stdout).text(),
+		new Response(subprocess.stderr).text(),
+	])
+	return { exitCode, stdout, stderr }
+}
+
+function parseJson(result: CliResult) {
+	expect(result.exitCode).toBe(0)
+	expect(result.stderr).toBe("")
+	return JSON.parse(result.stdout)
+}
+
+describe("CLI", () => {
+	const tempDirs: string[] = []
+
+	afterEach(async () => {
+		await Promise.all(tempDirs.splice(0).map(cleanupTempDir))
+	})
+
+	test("reports version and routes top-level help with intentional statuses", async () => {
+		const version = await runCli(["--version"])
+		expect(version).toEqual({
+			exitCode: 0,
+			stdout: "v0.0.0-development\n",
+			stderr: "",
+		})
+
+		const noArgs = await runCli([])
+		expect(noArgs.exitCode).toBe(1)
+		expect(noArgs.stdout).toContain("Usage: agency <command> [options]")
+		expect(noArgs.stderr).toBe("")
+
+		const help = await runCli(["--help"])
+		expect(help.exitCode).toBe(0)
+		expect(help.stdout).toContain("Usage: agency <command> [options]")
+		expect(help.stderr).toBe("")
+	})
+
+	test("reports unknown commands and preserves tagged error messages", async () => {
+		const unknown = await runCli(["unknown"])
+		expect(unknown.exitCode).toBe(1)
+		expect(unknown.stdout).toBe("")
+		expect(unknown.stderr).toContain("Error: Unknown command 'unknown'")
+
+		const cwd = await createTempDir()
+		tempDirs.push(cwd)
+		const taggedError = await runCli(["repo", "list"], cwd)
+		expect(taggedError.exitCode).toBe(1)
+		expect(taggedError.stdout).toBe("")
+		expect(taggedError.stderr).toContain("ⓘ No Agency workbase found from")
+		expect(taggedError.stderr).not.toContain("An error has occurred")
+	})
+
+	test("routes command help and global options on either side of commands", async () => {
+		for (const [command, usage] of [
+			["init", "Usage: agency init"],
+			["repo", "Usage: agency repo"],
+			["epic", "Usage: agency epic"],
+			["task", "Usage: agency task"],
+			["phase", "Usage: agency phase"],
+			["work", "Usage: agency work"],
+			["pr", "Usage: agency pr"],
+			["status", "Usage: agency status"],
+			["validate", "Usage: agency validate"],
+		] as const) {
+			const result = await runCli([command, "--help"])
+			expect(result.exitCode).toBe(0)
+			expect(result.stdout).toContain(usage)
+			expect(result.stderr).toBe("")
+		}
+
+		const helpBefore = await runCli(["--help", "task"])
+		expect(helpBefore.exitCode).toBe(0)
+		expect(helpBefore.stdout).toContain("Usage: agency task <subcommand>")
+		expect(helpBefore.stderr).toBe("")
+
+		const root = await createTempDir()
+		tempDirs.push(root)
+		const before = await runCli(["--silent", "init", root])
+		expect(before).toEqual({ exitCode: 0, stdout: "", stderr: "" })
+
+		const after = await runCli(["status", "--silent"], root)
+		expect(after).toEqual({ exitCode: 0, stdout: "", stderr: "" })
+	})
+
+	test("runs a multi-phase domain workflow through subprocesses", async () => {
+		const parent = await createTempDir()
+		tempDirs.push(parent)
+		const root = join(parent, "workbase")
+		const source = join(parent, "source")
+
+		const git = Bun.spawn(["git", "init", "--initial-branch=main", source], {
+			stdout: "ignore",
+			stderr: "pipe",
+		})
+		expect(await git.exited).toBe(0)
+
+		expect(parseJson(await runCli(["init", root, "--json"]))).toEqual({
+			root,
+		})
+		const workbaseRoot = await realpath(root)
+		expect(
+			parseJson(
+				await runCli(["repo", "link", "agency", source, "--json"], root),
+			),
+		).toEqual({
+			alias: "agency",
+			path: join(workbaseRoot, "repos/agency"),
+		})
+		for (const alias of ["effect", "tooling"]) {
+			parseJson(await runCli(["repo", "link", alias, source, "--json"], root))
+		}
+
+		const epic = parseJson(
+			await runCli(
+				[
+					"epic",
+					"create",
+					"delivery",
+					"--ticket-url",
+					"https://example.com/epics/delivery",
+					"--repo",
+					"agency:main",
+					"--json",
+				],
+				root,
+			),
+		)
+		expect(epic).toMatchObject({
+			id: "delivery",
+			data: { repos: [{ repo: "agency", ref: "main" }], tasks: [] },
+		})
+
+		const task = parseJson(
+			await runCli(
+				[
+					"task",
+					"create",
+					"ship",
+					"--ticket-url",
+					"https://example.com/tasks/ship",
+					"--epic",
+					"delivery",
+					"--multi-phase",
+					"--json",
+				],
+				root,
+			),
+		)
+		expect(task).toMatchObject({
+			id: "ship",
+			data: { epic: "delivery", phases: [] },
+		})
+
+		for (const [id, branch] of [
+			["prepare", "task/ship-prepare"],
+			["implement", "task/ship-implement"],
+		] as const) {
+			const phase = parseJson(
+				await runCli(
+					[
+						"phase",
+						"create",
+						"ship",
+						id,
+						"--repo",
+						"agency",
+						"--branch",
+						branch,
+						"--base",
+						"main",
+						"--json",
+					],
+					root,
+				),
+			)
+			expect(phase).toMatchObject({ taskId: "ship", id })
+		}
+
+		const release = parseJson(
+			await runCli(
+				[
+					"phase",
+					"create",
+					"ship",
+					"release",
+					"--repo",
+					"agency",
+					"--branch",
+					"task/ship-release",
+					"--base",
+					"main",
+					"--depends-on",
+					"prepare",
+					"--depends-on",
+					"implement",
+					"--reference",
+					"effect:main",
+					"--reference",
+					"tooling:main",
+					"--json",
+				],
+				root,
+			),
+		)
+		expect(release.data).toMatchObject({
+			branch: "task/ship-release",
+			base: "main",
+			repos: [
+				{ repo: "effect", ref: "main" },
+				{ repo: "tooling", ref: "main" },
+			],
+		})
+
+		const epicList = parseJson(await runCli(["epic", "list", "--json"], root))
+		expect(epicList).toHaveLength(1)
+		expect(epicList[0].data.tasks).toEqual([{ id: "ship" }])
+
+		const taskShow = parseJson(
+			await runCli(["task", "show", "ship", "--json"], root),
+		)
+		expect(taskShow.data.phases).toEqual([
+			{ id: "prepare" },
+			{ id: "implement" },
+			{ id: "release", dependsOn: ["prepare", "implement"] },
+		])
+		const plainTaskShow = await runCli(["task", "show", "ship"], root)
+		expect(plainTaskShow.exitCode).toBe(0)
+		expect(plainTaskShow.stdout).toContain(
+			"ticketUrl: https://example.com/tasks/ship",
+		)
+		expect(plainTaskShow.stderr).toBe("")
+
+		const phaseList = parseJson(
+			await runCli(["phase", "list", "ship", "--json"], root),
+		)
+		expect(phaseList.map((phase: { id: string }) => phase.id)).toEqual([
+			"implement",
+			"prepare",
+			"release",
+		])
+
+		const phaseShow = parseJson(
+			await runCli(["phase", "show", "ship", "release", "--json"], root),
+		)
+		expect(phaseShow).toMatchObject({ taskId: "ship", id: "release" })
+
+		const status = parseJson(await runCli(["status", "--json"], root))
+		expect(status).toMatchObject({
+			root: workbaseRoot,
+			epicCount: 1,
+			taskCount: 1,
+			phaseCount: 3,
+			valid: true,
+			issues: [],
+		})
+
+		const validation = parseJson(await runCli(["validate", "--json"], root))
+		expect(validation).toEqual({
+			root: workbaseRoot,
+			issues: [],
+			epicCount: 1,
+			taskCount: 1,
+			phaseCount: 3,
+			valid: true,
+		})
+	}, 30_000)
+})