@markjaquith/agency 2.2.0 → 2.4.0

package/README.md

@@ -42,6 +42,7 @@ frontmatter; prose below it supplies human and agent context.
 
 ```text
 workbase/
+  AGENTS.md                # managed workbase instructions
   agency.json
   repos/
     frontend/              # bare Git repository or symlink
@@ -68,6 +69,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.
+
 Repository metadata comes directly from Git under `repos/{alias}`. Workbase
 configuration may provide a custom writable-worktree creation command.
 

package/package.json

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

package/src/commands/init.test.ts

@@ -33,6 +33,9 @@ describe("init command", () => {
 		expect(await Bun.file(join(root, ".gitignore")).text()).toBe(
 			"/repos/\n/tasks/*/code/\n/tasks/*/phases/*/code/\n",
 		)
+		expect(await Bun.file(join(root, "AGENTS.md")).text()).toContain(
+			"# Agency Workbase",
+		)
 	})
 
 	test("preserves existing gitignore entries", async () => {

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/work.test.ts

@@ -52,9 +52,18 @@ const createHarness = (options: HarnessOptions = {}) => {
 		args: readonly string[]
 		cwd: string
 	}> = []
+	const materializeOptions: Array<
+		Parameters<WorktreeService["materialize"]>[3]
+	> = []
 	const worktrees = {
-		materialize: () => {
+		materialize: (
+			_taskId: string,
+			_phaseId?: string,
+			_root?: string,
+			commandOptions?: Parameters<WorktreeService["materialize"]>[3],
+		) => {
 			events.push("materialize")
+			materializeOptions.push(commandOptions)
 			return options.materializeError
 				? Effect.fail(options.materializeError)
 				: Effect.succeed(options.workspace ?? singlePhaseWorkspace)
@@ -125,7 +134,7 @@ const createHarness = (options: HarnessOptions = {}) => {
 			) as Effect.Effect<void, unknown, never>,
 		)
 
-	return { events, probes, launches, run }
+	return { events, probes, launches, materializeOptions, run }
 }
 
 describe("work command", () => {
@@ -375,6 +384,7 @@ describe("work command", () => {
 		expect(verboseLogs).toEqual([
 			"Launching opencode in /workbase/tasks/example/code/agency",
 		])
+		expect(verboseHarness.materializeOptions[0]?.verbose).toBe(true)
 
 		const silentHarness = createHarness()
 		const silentLogs = await captureLogs(() =>

package/src/commands/work.ts

@@ -155,7 +155,12 @@ export const work = (
 		} else {
 			const taskId = target.taskId
 			const phaseId = target.kind === "phase" ? target.phaseId : undefined
-			const workspace = yield* worktrees.materialize(taskId, phaseId, root)
+			const workspace = yield* worktrees.materialize(
+				taskId,
+				phaseId,
+				root,
+				options,
+			)
 			prompt = workspace.phasePath
 				? `Start the task. Read ${workspace.taskPath} and ${workspace.phasePath}.`
 				: `Start the task. Read ${workspace.taskPath}.`

package/src/markdown.d.ts

@@ -0,0 +1,4 @@
+declare module "*.md" {
+	const content: string
+	export default content
+}

package/src/services/FileSystemService.ts

@@ -180,6 +180,7 @@ export class FileSystemService extends Effect.Service<FileSystemService>()(
 				options?: {
 					readonly cwd?: string
 					readonly captureOutput?: boolean
+					readonly forwardOutput?: boolean
 					readonly env?: Record<string, string>
 				},
 			) =>
@@ -187,8 +188,12 @@ export class FileSystemService extends Effect.Service<FileSystemService>()(
 					spawnProcess(args, {
 						cwd: options?.cwd,
 						stdin: "pipe",
-						stdout: options?.captureOutput ? "pipe" : "inherit",
-						stderr: "pipe",
+						stdout: options?.forwardOutput
+							? "tee"
+							: options?.captureOutput
+								? "pipe"
+								: "inherit",
+						stderr: options?.forwardOutput ? "tee" : "pipe",
 						env: options?.env,
 					}),
 					Effect.mapError(

package/src/services/PullRequestService.ts

@@ -2,6 +2,7 @@ import { Data, Effect } from "effect"
 import { FileSystemService } from "./FileSystemService"
 import { WorkbaseService } from "./WorkbaseService"
 import { WorktreeService } from "./WorktreeService"
+import type { BaseCommandOptions } from "../utils/command"
 import { TaskService } from "./TaskService"
 import { PhaseService } from "./PhaseService"
 import {
@@ -59,6 +60,7 @@ export class PullRequestService extends Effect.Service<PullRequestService>()(
 				phaseId?: string,
 				draft = false,
 				startPath: string = process.cwd(),
+				options: BaseCommandOptions = {},
 			) =>
 				Effect.gen(function* () {
 					const service = yield* PullRequestService
@@ -70,6 +72,7 @@ export class PullRequestService extends Effect.Service<PullRequestService>()(
 						taskId,
 						phaseId,
 						startPath,
+						options,
 					)
 					const task = yield* tasks.show(taskId, workspace.root)
 					const execution =

package/src/services/WorkbaseService.test.ts

@@ -1,8 +1,10 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test"
 import { Effect } from "effect"
+import { createHash } from "node:crypto"
 import { mkdir } from "node:fs/promises"
 import { dirname, join } from "node:path"
 import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
+import { managedWorkbaseAgents } from "../workbase/agents-file"
 import { WorkbaseService } from "./WorkbaseService"
 
 const write = async (root: string, path: string, content: string) => {
@@ -11,6 +13,11 @@ const write = async (root: string, path: string, content: string) => {
 	await Bun.write(fullPath, content)
 }
 
+const managedAgents = (body: string) => {
+	const checksum = createHash("sha256").update(body).digest("hex")
+	return `<!-- agency-managed: sha256=${checksum} -->\n\n${body}`
+}
+
 describe("WorkbaseService", () => {
 	let root: string
 
@@ -35,6 +42,51 @@ describe("WorkbaseService", () => {
 		)
 
 		expect(discovered).toBe(root)
+		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(
+			managedWorkbaseAgents,
+		)
+	})
+
+	test("preserves an unmanaged workbase AGENTS.md", async () => {
+		await write(root, "agency.json", '{"version":2}\n')
+		await write(root, "AGENTS.md", "# Custom instructions\n")
+
+		await runTestEffect(
+			WorkbaseService.pipe(Effect.flatMap((service) => service.discover(root))),
+		)
+
+		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(
+			"# Custom instructions\n",
+		)
+	})
+
+	test("updates an unmodified managed workbase AGENTS.md", async () => {
+		await write(root, "agency.json", '{"version":2}\n')
+		await write(
+			root,
+			"AGENTS.md",
+			managedAgents("# Previous Agency instructions\n"),
+		)
+
+		await runTestEffect(
+			WorkbaseService.pipe(Effect.flatMap((service) => service.discover(root))),
+		)
+
+		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(
+			managedWorkbaseAgents,
+		)
+	})
+
+	test("preserves a modified managed workbase AGENTS.md", async () => {
+		await write(root, "agency.json", '{"version":2}\n')
+		const content = `${managedAgents("# Previous Agency instructions\n")}\nUser edit\n`
+		await write(root, "AGENTS.md", content)
+
+		await runTestEffect(
+			WorkbaseService.pipe(Effect.flatMap((service) => service.discover(root))),
+		)
+
+		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(content)
 	})
 
 	test("rejects an invalid worktree command template", async () => {

package/src/services/WorkbaseService.ts

@@ -15,6 +15,10 @@ import {
 	type TaskFrontmatter as TaskData,
 } from "../workbase/schemas"
 import { validateWorktreeCreateCommand } from "../workbase/worktree-command"
+import {
+	canUpdateManagedWorkbaseAgents,
+	managedWorkbaseAgents,
+} from "../workbase/agents-file"
 
 class WorkbaseNotFoundError extends Data.TaggedError("WorkbaseNotFoundError")<{
 	readonly message: string
@@ -64,6 +68,24 @@ const decode = <S extends Schema.Schema.AnyNoContext>(
 		: { success: true, value: result.right }
 }
 
+const ensureWorkbaseAgents = (root: string) =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystemService
+		const path = join(root, "AGENTS.md")
+		if (!(yield* fs.exists(path))) {
+			yield* fs.writeFile(path, managedWorkbaseAgents)
+			return
+		}
+
+		const content = yield* fs.readFile(path)
+		if (
+			content !== managedWorkbaseAgents &&
+			canUpdateManagedWorkbaseAgents(content)
+		) {
+			yield* fs.writeFile(path, managedWorkbaseAgents)
+		}
+	})
+
 const findCycles = (nodes: readonly Dependency[]): readonly string[] => {
 	const dependencies = new Map(
 		nodes.map((node) => [node.id, [...(node.dependsOn ?? [])]]),
@@ -142,6 +164,7 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 							`${existing}${prefix}${missing.join("\n")}\n`,
 						)
 					}
+					yield* ensureWorkbaseAgents(root)
 
 					return root
 				}),
@@ -198,6 +221,7 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 										})
 									}
 								}
+								yield* ensureWorkbaseAgents(current)
 								return current
 							}
 						}

package/src/services/WorktreeService.test.ts

@@ -2,7 +2,12 @@ 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 {
+	captureLogs,
+	cleanupTempDir,
+	createTempDir,
+	runTestEffect,
+} from "../test-utils"
 import { TaskService } from "./TaskService"
 import { PhaseService } from "./PhaseService"
 import { WorktreeService } from "./WorktreeService"
@@ -127,6 +132,60 @@ describe("WorktreeService", () => {
 		).toBe("example\n")
 	})
 
+	test("logs the expanded configured command in verbose mode", async () => {
+		await Bun.write(
+			join(root, "agency.json"),
+			JSON.stringify({
+				version: 2,
+				worktreeCreateCommand: [
+					"sh",
+					"-c",
+					'git -C "$1" worktree add -b "$3" "$2" "$4" >/dev/null 2>&1',
+					"agency-worktree",
+					"{repo}",
+					"{worktree}",
+					"{branch}",
+					"{base}",
+				],
+			}),
+		)
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "verbose-command",
+							ticketUrl: "https://example.com/task",
+							repo: "agency",
+							branch: "task/verbose-command",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+
+		const logs = await captureLogs(() =>
+			runTestEffect(
+				WorktreeService.pipe(
+					Effect.flatMap((service) =>
+						service.materialize("verbose-command", undefined, root, {
+							verbose: true,
+						}),
+					),
+				),
+			),
+		)
+
+		expect(logs).toHaveLength(1)
+		expect(logs[0]).toStartWith("Running worktree command: sh -c ")
+		expect(logs[0]).toContain(join(root, "repos", "agency"))
+		expect(logs[0]).toContain(
+			join(root, "tasks", "verbose-command", "code", "agency"),
+		)
+	})
+
 	test("selects phases and rejects missing or unexpected phase IDs", async () => {
 		await runTestEffect(
 			TaskService.pipe(

package/src/services/WorktreeService.ts

@@ -9,6 +9,8 @@ import {
 	worktreeCommandEnvironment,
 } from "../workbase/worktree-command"
 import type { RepositoryReference } from "../workbase/schemas"
+import type { BaseCommandOptions } from "../utils/command"
+import { createLoggers } from "../utils/effect"
 
 class WorktreeError extends Data.TaggedError("WorktreeError")<{
 	readonly message: string
@@ -49,6 +51,15 @@ const parseWorktreeList = (output: string): readonly GitWorktree[] => {
 	return worktrees
 }
 
+const formatCommand = (args: readonly string[]) =>
+	args
+		.map((argument) =>
+			/^[A-Za-z0-9_./:=+@%-]+$/.test(argument)
+				? argument
+				: `'${argument.replaceAll("'", `'\\''`)}'`,
+		)
+		.join(" ")
+
 export class WorktreeService extends Effect.Service<WorktreeService>()(
 	"WorktreeService",
 	{
@@ -57,12 +68,16 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 				taskId: string,
 				phaseId?: string,
 				startPath: string = process.cwd(),
+				options: BaseCommandOptions = {},
 			) =>
 				Effect.gen(function* () {
 					const fs = yield* FileSystemService
 					const workbase = yield* WorkbaseService
 					const tasks = yield* TaskService
 					const phases = yield* PhaseService
+					const { verboseLog } = createLoggers(options)
+					const forwardCommandOutput =
+						options.verbose === true && !options.silent && !options.json
 					const { root, config } = yield* workbase.loadConfig(startPath)
 					const report = yield* workbase.validate(root)
 					const ownershipIssue = report.issues.find((issue) =>
@@ -258,9 +273,14 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 								]
 							}
 
+							if (config.worktreeCreateCommand) {
+								verboseLog(`Running worktree command: ${formatCommand(args)}`)
+							}
 							const result = yield* fs.runCommand(args, {
 								cwd: repositoryPath,
 								captureOutput: true,
+								forwardOutput:
+									config.worktreeCreateCommand && forwardCommandOutput,
 								env,
 							})
 							if (result.exitCode !== 0) {

package/src/utils/process.test.ts

@@ -1,8 +1,45 @@
-import { describe, expect, test } from "bun:test"
+import { describe, expect, spyOn, test } from "bun:test"
 import { Effect } from "effect"
 import { spawnProcess } from "./process"
 
 describe("spawnProcess", () => {
+	test("forwards and captures output in tee mode", async () => {
+		const forwardedStdout: Uint8Array[] = []
+		const forwardedStderr: Uint8Array[] = []
+		const stdout = spyOn(process.stdout, "write").mockImplementation(((
+			chunk: Uint8Array,
+		) => {
+			forwardedStdout.push(chunk)
+			return true
+		}) as never)
+		const stderr = spyOn(process.stderr, "write").mockImplementation(((
+			chunk: Uint8Array,
+		) => {
+			forwardedStderr.push(chunk)
+			return true
+		}) as never)
+
+		try {
+			const result = await Effect.runPromise(
+				spawnProcess(
+					["sh", "-c", "printf 'standard output'; printf 'standard error' >&2"],
+					{ stdout: "tee", stderr: "tee" },
+				),
+			)
+
+			expect(result).toEqual({
+				stdout: "standard output",
+				stderr: "standard error",
+				exitCode: 0,
+			})
+			expect(Buffer.concat(forwardedStdout).toString()).toBe("standard output")
+			expect(Buffer.concat(forwardedStderr).toString()).toBe("standard error")
+		} finally {
+			stdout.mockRestore()
+			stderr.mockRestore()
+		}
+	})
+
 	test("captures large stdout and stderr without hanging", async () => {
 		const line = "x".repeat(4096)
 		const script = [

package/src/utils/process.ts

@@ -15,11 +15,29 @@ interface ProcessResult {
 interface SpawnOptions {
 	readonly cwd?: string
 	readonly stdin?: "pipe" | "inherit"
-	readonly stdout?: "pipe" | "inherit"
-	readonly stderr?: "pipe" | "inherit"
+	readonly stdout?: "pipe" | "inherit" | "tee"
+	readonly stderr?: "pipe" | "inherit" | "tee"
 	readonly env?: Record<string, string>
 }
 
+const readOutput = async (
+	stream: ReadableStream<Uint8Array> | null | undefined,
+	target?: { write(chunk: Uint8Array): unknown },
+) => {
+	if (!stream) return ""
+
+	const reader = stream.getReader()
+	const decoder = new TextDecoder()
+	let output = ""
+	while (true) {
+		const { done, value } = await reader.read()
+		if (done) break
+		target?.write(value)
+		output += decoder.decode(value, { stream: true })
+	}
+	return output + decoder.decode()
+}
+
 /**
  * Generic error for process execution failures
  */
@@ -50,8 +68,8 @@ export const spawnProcess = (
 			const proc = Bun.spawn([...args], {
 				cwd: options?.cwd ?? process.cwd(),
 				stdin: options?.stdin ?? "pipe",
-				stdout: options?.stdout ?? "pipe",
-				stderr: options?.stderr ?? "pipe",
+				stdout: options?.stdout === "inherit" ? "inherit" : "pipe",
+				stderr: options?.stderr === "inherit" ? "inherit" : "pipe",
 				env: options?.env ? { ...process.env, ...options.env } : process.env,
 			})
 			// Start draining stdout/stderr immediately so verbose subprocesses
@@ -59,11 +77,17 @@ export const spawnProcess = (
 			const stdoutPromise =
 				options?.stdout === "inherit"
 					? Promise.resolve("")
-					: new Response(proc.stdout ?? "").text()
+					: readOutput(
+							proc.stdout,
+							options?.stdout === "tee" ? process.stdout : undefined,
+						)
 			const stderrPromise =
 				options?.stderr === "inherit"
 					? Promise.resolve("")
-					: new Response(proc.stderr ?? "").text()
+					: readOutput(
+							proc.stderr,
+							options?.stderr === "tee" ? process.stderr : undefined,
+						)
 
 			const [exitCode, stdout, stderr] = await Promise.all([
 				proc.exited,

package/src/workbase/AGENTS.md

@@ -0,0 +1,32 @@
+# Agency Workbase
+
+This directory is an Agency workbase. Epics, tasks, and phases are durable
+Markdown documents; repository aliases and generated Git worktrees provide code
+access.
+
+## Session Context
+
+Before doing work, identify the current entity from the working directory and
+read its context:
+
+- In `epics/<epic>/`, read `EPIC.md`. Coordinate the epic's tasks without
+  writing implementation code.
+- In `tasks/<task>/`, read `TASK.md`. A task with `phases` is an orchestration
+  session; a task without `phases` is a single execution unit.
+- In `tasks/<task>/phases/<phase>/`, read both `../../TASK.md` and `PHASE.md`.
+  The phase is the execution unit.
+
+For execution units, writable and reference checkouts live under `code/` when
+materialized. Write only through the checkout named by the singular `repo`
+field. Repositories listed in plural `repos` are read-only references.
+
+## Safety
+
+- Keep task-level decisions in `TASK.md` and phase-specific delivery context in
+  `PHASE.md`.
+- Do not manually create, move, or remove worktrees under `code/`.
+- 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.
+- Run `agency validate` before worktree or pull-request operations.
+- Create a pull request only when the user explicitly requests it.

package/src/workbase/agents-file.ts

@@ -0,0 +1,24 @@
+import { createHash } from "node:crypto"
+import agentsTemplate from "./AGENTS.md" with { type: "text" }
+
+const managedHeaderPattern =
+	/^<!-- agency-managed: sha256=([a-f0-9]{64}) -->\r?\n\r?\n/
+
+const checksum = (content: string) =>
+	createHash("sha256").update(content).digest("hex")
+
+const canonicalBody = agentsTemplate.endsWith("\n")
+	? agentsTemplate
+	: `${agentsTemplate}\n`
+
+const renderManagedWorkbaseAgents = (body: string = canonicalBody) =>
+	`<!-- agency-managed: sha256=${checksum(body)} -->\n\n${body}`
+
+export const managedWorkbaseAgents = renderManagedWorkbaseAgents()
+
+export const canUpdateManagedWorkbaseAgents = (content: string) => {
+	const match = content.match(managedHeaderPattern)
+	if (!match?.[1]) return false
+
+	return checksum(content.slice(match[0].length)) === match[1]
+}