@markjaquith/agency 2.2.0 → 2.3.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.3.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/markdown.d.ts

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

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/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]
+}