@markjaquith/agency 0.5.0

package/src/commands/work.ts

@@ -0,0 +1,193 @@
+import { join } from "node:path"
+import { Effect } from "effect"
+import type { BaseCommandOptions } from "../utils/command"
+import { FileSystemService } from "../services/FileSystemService"
+import { createLoggers, ensureGitRepo } from "../utils/effect"
+import { spawnProcess } from "../utils/process"
+import { execvp } from "../utils/exec"
+
+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
+}
+
+export const work = (options: WorkOptions = {}) =>
+	Effect.gen(function* () {
+		const { verboseLog } = createLoggers(options)
+
+		const fs = yield* FileSystemService
+
+		const gitRoot = yield* ensureGitRepo()
+
+		// Check if TASK.md exists
+		const taskPath = join(gitRoot, "TASK.md")
+		const taskExists = yield* fs.exists(taskPath)
+		if (!taskExists) {
+			return yield* Effect.fail(
+				new Error("TASK.md not found. Run 'agency task' first to create it."),
+			)
+		}
+
+		verboseLog(`Found TASK.md at: ${taskPath}`)
+
+		// Change to git root before executing
+		process.chdir(gitRoot)
+
+		// Check for conflicting flags
+		if (options.opencode && options.claude) {
+			return yield* Effect.fail(
+				new Error(
+					"Cannot use both --opencode and --claude flags together. Choose one.",
+				),
+			)
+		}
+
+		// 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,
+		})
+
+		// 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.",
+					),
+				)
+			}
+			useOpencode = true
+			verboseLog("Using opencode (explicitly requested)")
+		} else if (options.claude) {
+			if (!hasClaude) {
+				return yield* Effect.fail(
+					new Error(
+						"claude CLI tool not found. Please install Claude Code or remove the --claude flag.",
+					),
+				)
+			}
+			useOpencode = false
+			verboseLog("Using claude (explicitly requested)")
+		} else {
+			// Auto-detect
+			if (!hasOpencode && !hasClaude) {
+				return yield* Effect.fail(
+					new Error(
+						"Neither opencode nor claude CLI tool found. Please install OpenCode or Claude Code.",
+					),
+				)
+			}
+			useOpencode = hasOpencode
+			verboseLog(`Using ${useOpencode ? "opencode" : "claude"} (auto-detected)`)
+		}
+
+		const cliName = useOpencode ? "opencode" : "claude"
+		const baseArgs = useOpencode
+			? [cliName, "-p", "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(" ")}`,
+			)
+		} else {
+			verboseLog(`Running ${cliName} with task prompt...`)
+		}
+
+		// 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)
+		}
+	})
+
+export const help = `
+Usage: agency work [options] [-- extra-args...]
+
+Start working on the task described in TASK.md using OpenCode or Claude Code.
+
+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.
+
+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)
+`

package/src/errors.ts

@@ -0,0 +1,17 @@
+import { Data } from "effect"
+
+/**
+ * Error thrown when a command requires the repository to be initialized
+ * but agency.template is not set in git config
+ */
+export class RepositoryNotInitializedError extends Data.TaggedError(
+	"RepositoryNotInitializedError",
+)<{
+	readonly message: string
+}> {
+	constructor(
+		message: string = "Repository not initialized. Run 'agency init' first to select a template.",
+	) {
+		super({ message })
+	}
+}

package/src/schemas.ts

@@ -0,0 +1,33 @@
+import { Schema } from "@effect/schema"
+
+/**
+ * Schema for managed files in the agency system
+ */
+export class ManagedFile extends Schema.Class<ManagedFile>("ManagedFile")({
+	name: Schema.String,
+	defaultContent: Schema.optional(Schema.String),
+}) {}
+
+/**
+ * Schema for agency metadata stored in agency.json
+ */
+export class AgencyMetadata extends Schema.Class<AgencyMetadata>(
+	"AgencyMetadata",
+)({
+	version: Schema.Literal(1),
+	injectedFiles: Schema.Array(Schema.String),
+	baseBranch: Schema.optional(Schema.String),
+	template: Schema.String,
+	createdAt: Schema.DateTimeUtc,
+	emitBranch: Schema.optional(Schema.String),
+}) {}
+
+/**
+ * Schema for agency configuration stored in ~/.config/agency/agency.json
+ */
+export class AgencyConfig extends Schema.Class<AgencyConfig>("AgencyConfig")({
+	sourceBranchPattern: Schema.String.pipe(
+		Schema.annotations({ default: "agency/%branch%" }),
+	),
+	emitBranch: Schema.String.pipe(Schema.annotations({ default: "%branch%" })),
+}) {}

package/src/services/AgencyMetadataService.ts

@@ -0,0 +1,287 @@
+import { join } from "node:path"
+import { Context, Data, Effect, Layer } from "effect"
+import { Schema } from "@effect/schema"
+import { AgencyMetadata } from "../schemas"
+import { FileSystemService } from "./FileSystemService"
+import { GitService } from "./GitService"
+
+/**
+ * Error type for AgencyMetadata operations
+ */
+export class AgencyMetadataError extends Data.TaggedError(
+	"AgencyMetadataError",
+)<{
+	message: string
+	cause?: unknown
+}> {}
+
+/**
+ * Service for managing agency.json metadata operations
+ */
+export class AgencyMetadataService extends Context.Tag("AgencyMetadataService")<
+	AgencyMetadataService,
+	{
+		/**
+		 * Read agency.json from disk in the repository root.
+		 * Returns null if the file doesn't exist or is invalid.
+		 */
+		readonly readFromDisk: (
+			gitRoot: string,
+		) => Effect.Effect<AgencyMetadata | null, never, FileSystemService>
+
+		/**
+		 * Read agency.json from a specific git branch using git show.
+		 * Returns null if the file doesn't exist or is invalid.
+		 */
+		readonly readFromBranch: (
+			gitRoot: string,
+			branch: string,
+		) => Effect.Effect<AgencyMetadata | null, never, GitService>
+
+		/**
+		 * Write agency.json to disk in the repository root.
+		 */
+		readonly write: (
+			gitRoot: string,
+			metadata: AgencyMetadata,
+		) => Effect.Effect<void, AgencyMetadataError, FileSystemService>
+
+		/**
+		 * Get list of files to filter during PR/merge operations.
+		 * Always includes TASK.md, AGENCY.md, and agency.json, plus any injectedFiles from metadata.
+		 */
+		readonly getFilesToFilter: (
+			gitRoot: string,
+		) => Effect.Effect<string[], never, FileSystemService>
+
+		/**
+		 * Get the configured base branch from agency.json metadata.
+		 * Returns null if no metadata exists or no base branch is configured.
+		 */
+		readonly getBaseBranch: (
+			gitRoot: string,
+		) => Effect.Effect<string | null, never, FileSystemService>
+
+		/**
+		 * Set the base branch in agency.json metadata.
+		 */
+		readonly setBaseBranch: (
+			gitRoot: string,
+			baseBranch: string,
+		) => Effect.Effect<void, AgencyMetadataError, FileSystemService>
+
+		/**
+		 * Parse and validate agency.json content from a JSON string.
+		 * Returns null if the content is invalid.
+		 */
+		readonly parse: (content: string) => Effect.Effect<AgencyMetadata | null>
+	}
+>() {}
+
+/**
+ * Parse and validate agency.json content from a JSON string.
+ * Returns null if the content is invalid.
+ */
+const parseAgencyMetadata = (content: string) =>
+	Effect.gen(function* () {
+		const data = yield* Effect.try({
+			try: () => JSON.parse(content),
+			catch: () => new Error("Failed to parse agency.json"),
+		})
+
+		// Validate version
+		if (typeof data.version !== "number" || data.version !== 1) {
+			return null
+		}
+
+		// Parse and validate using Effect schema
+		const metadata = yield* Effect.try({
+			try: () => Schema.decodeUnknownSync(AgencyMetadata)(data),
+			catch: () => new Error("Invalid agency.json format"),
+		})
+
+		return metadata
+	}).pipe(Effect.catchAll(() => Effect.succeed(null)))
+
+/**
+ * Implementation of AgencyMetadataService
+ */
+export const AgencyMetadataServiceLive = Layer.succeed(
+	AgencyMetadataService,
+	AgencyMetadataService.of({
+		readFromDisk: (gitRoot: string) =>
+			Effect.gen(function* () {
+				const fs = yield* FileSystemService
+				const metadataPath = join(gitRoot, "agency.json")
+
+				const exists = yield* fs.exists(metadataPath)
+				if (!exists) {
+					return null
+				}
+
+				const content = yield* fs.readFile(metadataPath)
+				return yield* parseAgencyMetadata(content)
+			}).pipe(Effect.catchAll(() => Effect.succeed(null))),
+
+		readFromBranch: (gitRoot: string, branch: string) =>
+			Effect.gen(function* () {
+				const git = yield* GitService
+
+				// Try to read agency.json from the branch using git show
+				const result = yield* git.runGitCommand(
+					["git", "show", `${branch}:agency.json`],
+					gitRoot,
+					{ captureOutput: true },
+				)
+
+				if (result.exitCode !== 0 || !result.stdout) {
+					return null
+				}
+
+				return yield* parseAgencyMetadata(result.stdout)
+			}).pipe(Effect.catchAll(() => Effect.succeed(null))),
+
+		write: (gitRoot: string, metadata: AgencyMetadata) =>
+			Effect.gen(function* () {
+				const fs = yield* FileSystemService
+				const metadataPath = join(gitRoot, "agency.json")
+
+				const content = JSON.stringify(metadata, null, 2) + "\n"
+				yield* fs.writeFile(metadataPath, content).pipe(
+					Effect.mapError(
+						(error) =>
+							new AgencyMetadataError({
+								message: `Failed to write agency.json: ${error}`,
+								cause: error,
+							}),
+					),
+				)
+			}),
+
+		getFilesToFilter: (gitRoot: string) =>
+			Effect.gen(function* () {
+				const fs = yield* FileSystemService
+				const metadataPath = join(gitRoot, "agency.json")
+
+				const exists = yield* fs.exists(metadataPath)
+				const baseFiles = ["TASK.md", "AGENCY.md", "agency.json"]
+
+				if (!exists) {
+					return baseFiles
+				}
+
+				const content = yield* fs
+					.readFile(metadataPath)
+					.pipe(Effect.catchAll(() => Effect.succeed("")))
+
+				if (!content) {
+					return baseFiles
+				}
+
+				const metadata = yield* parseAgencyMetadata(content)
+
+				if (!metadata) {
+					return baseFiles
+				}
+
+				return [...baseFiles, ...metadata.injectedFiles]
+			}).pipe(
+				Effect.catchAll(() =>
+					Effect.succeed(["TASK.md", "AGENCY.md", "agency.json"]),
+				),
+			),
+
+		getBaseBranch: (gitRoot: string) =>
+			Effect.gen(function* () {
+				const fs = yield* FileSystemService
+				const metadataPath = join(gitRoot, "agency.json")
+
+				const exists = yield* fs.exists(metadataPath)
+				if (!exists) {
+					return null
+				}
+
+				const content = yield* fs
+					.readFile(metadataPath)
+					.pipe(Effect.catchAll(() => Effect.succeed("")))
+
+				if (!content) {
+					return null
+				}
+
+				const metadata = yield* parseAgencyMetadata(content)
+				return metadata?.baseBranch || null
+			}).pipe(Effect.catchAll(() => Effect.succeed(null))),
+
+		setBaseBranch: (gitRoot: string, baseBranch: string) =>
+			Effect.gen(function* () {
+				const fs = yield* FileSystemService
+				const metadataPath = join(gitRoot, "agency.json")
+
+				const exists = yield* fs.exists(metadataPath).pipe(
+					Effect.mapError(
+						(error) =>
+							new AgencyMetadataError({
+								message: `Failed to check agency.json: ${error}`,
+								cause: error,
+							}),
+					),
+				)
+
+				if (!exists) {
+					return yield* Effect.fail(
+						new AgencyMetadataError({
+							message:
+								"agency.json not found. Please run 'agency task' first to initialize backpack files.",
+						}),
+					)
+				}
+
+				const content = yield* fs.readFile(metadataPath).pipe(
+					Effect.mapError(
+						(error) =>
+							new AgencyMetadataError({
+								message: `Failed to read agency.json: ${error}`,
+								cause: error,
+							}),
+					),
+				)
+
+				const metadata = yield* parseAgencyMetadata(content).pipe(
+					Effect.flatMap((m) =>
+						m
+							? Effect.succeed(m)
+							: Effect.fail(
+									new AgencyMetadataError({
+										message:
+											"agency.json is invalid. Please run 'agency task' first to initialize backpack files.",
+									}),
+								),
+					),
+				)
+
+				// Create a new metadata instance with the updated baseBranch
+				const updatedMetadata = new AgencyMetadata({
+					version: metadata.version,
+					injectedFiles: metadata.injectedFiles,
+					template: metadata.template,
+					createdAt: metadata.createdAt,
+					baseBranch,
+					emitBranch: metadata.emitBranch,
+				})
+
+				const outputContent = JSON.stringify(updatedMetadata, null, 2) + "\n"
+				return yield* fs.writeFile(metadataPath, outputContent).pipe(
+					Effect.mapError(
+						(error) =>
+							new AgencyMetadataError({
+								message: `Failed to write agency.json: ${error}`,
+								cause: error,
+							}),
+					),
+				)
+			}),
+
+		parse: parseAgencyMetadata,
+	}),
+)

package/src/services/ClaudeService.test.ts

@@ -0,0 +1,184 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test"
+import { Effect } from "effect"
+import { join } from "path"
+import {
+	createTempDir,
+	cleanupTempDir,
+	initGitRepo,
+	runTestEffect,
+	fileExists,
+	readFile,
+	createFile,
+} from "../test-utils"
+import { ClaudeService } from "./ClaudeService"
+
+describe("ClaudeService", () => {
+	let tempDir: string
+
+	beforeEach(async () => {
+		tempDir = await createTempDir()
+		await initGitRepo(tempDir)
+	})
+
+	afterEach(async () => {
+		await cleanupTempDir(tempDir)
+	})
+
+	describe("claudeFileExists", () => {
+		test("returns false when CLAUDE.md does not exist", async () => {
+			const result = await runTestEffect(
+				Effect.gen(function* () {
+					const claudeService = yield* ClaudeService
+					return yield* claudeService.claudeFileExists(tempDir)
+				}),
+			)
+
+			expect(result).toBe(false)
+		})
+
+		test("returns true when CLAUDE.md exists", async () => {
+			await createFile(tempDir, "CLAUDE.md", "# Claude Code\n")
+
+			const result = await runTestEffect(
+				Effect.gen(function* () {
+					const claudeService = yield* ClaudeService
+					return yield* claudeService.claudeFileExists(tempDir)
+				}),
+			)
+
+			expect(result).toBe(true)
+		})
+	})
+
+	describe("hasAgencySection", () => {
+		test("returns false when content does not have agency section", async () => {
+			const content = "# Claude Code\n\nSome instructions\n"
+
+			const result = await runTestEffect(
+				Effect.gen(function* () {
+					const claudeService = yield* ClaudeService
+					return yield* claudeService.hasAgencySection(content)
+				}),
+			)
+
+			expect(result).toBe(false)
+		})
+
+		test("returns true when content has both @AGENCY.md and @TASK.md", async () => {
+			const content = `# Claude Code
+
+Some instructions
+
+## Agency
+
+@AGENCY.md
+@TASK.md
+`
+
+			const result = await runTestEffect(
+				Effect.gen(function* () {
+					const claudeService = yield* ClaudeService
+					return yield* claudeService.hasAgencySection(content)
+				}),
+			)
+
+			expect(result).toBe(true)
+		})
+	})
+
+	describe("injectAgencySection", () => {
+		test("creates CLAUDE.md with agency section when file does not exist", async () => {
+			const result = await runTestEffect(
+				Effect.gen(function* () {
+					const claudeService = yield* ClaudeService
+					return yield* claudeService.injectAgencySection(tempDir)
+				}),
+			)
+
+			expect(result.created).toBe(true)
+			expect(result.modified).toBe(true)
+
+			const claudePath = join(tempDir, "CLAUDE.md")
+			expect(await fileExists(claudePath)).toBe(true)
+
+			const content = await readFile(claudePath)
+			expect(content).toContain("@AGENCY.md")
+			expect(content).toContain("@TASK.md")
+			expect(content.indexOf("@AGENCY.md")).toBeLessThan(
+				content.indexOf("@TASK.md"),
+			)
+		})
+
+		test("appends agency section when file exists without references", async () => {
+			const initialContent = "# Claude Code\n\nSome existing instructions\n"
+			await createFile(tempDir, "CLAUDE.md", initialContent)
+
+			const result = await runTestEffect(
+				Effect.gen(function* () {
+					const claudeService = yield* ClaudeService
+					return yield* claudeService.injectAgencySection(tempDir)
+				}),
+			)
+
+			expect(result.created).toBe(false)
+			expect(result.modified).toBe(true)
+
+			const content = await readFile(join(tempDir, "CLAUDE.md"))
+			expect(content).toContain("Some existing instructions")
+			expect(content).toContain("@AGENCY.md")
+			expect(content).toContain("@TASK.md")
+		})
+
+		test("does not modify file when agency section already exists in correct order", async () => {
+			const contentWithSection = `# Claude Code
+
+Some instructions
+
+## Agency
+
+@AGENCY.md
+@TASK.md
+`
+			await createFile(tempDir, "CLAUDE.md", contentWithSection)
+
+			const result = await runTestEffect(
+				Effect.gen(function* () {
+					const claudeService = yield* ClaudeService
+					return yield* claudeService.injectAgencySection(tempDir)
+				}),
+			)
+
+			expect(result.created).toBe(false)
+			expect(result.modified).toBe(false)
+
+			const content = await readFile(join(tempDir, "CLAUDE.md"))
+			expect(content).toBe(contentWithSection)
+		})
+
+		test("re-adds references when they exist in wrong order", async () => {
+			const contentWithWrongOrder = `# Claude Code
+
+Some instructions
+
+@TASK.md
+@AGENCY.md
+`
+			await createFile(tempDir, "CLAUDE.md", contentWithWrongOrder)
+
+			const result = await runTestEffect(
+				Effect.gen(function* () {
+					const claudeService = yield* ClaudeService
+					return yield* claudeService.injectAgencySection(tempDir)
+				}),
+			)
+
+			expect(result.created).toBe(false)
+			expect(result.modified).toBe(true)
+
+			const content = await readFile(join(tempDir, "CLAUDE.md"))
+			// Should have the section appended with correct order
+			expect(content).toContain("@AGENCY.md")
+			expect(content).toContain("@TASK.md")
+		})
+	})
+})