@markjaquith/agency 2.30.1 → 2.31.0

package/README.md

@@ -37,6 +37,12 @@ For development, run `bun link` from this repository.
 Entity IDs come from directory names. Structured metadata lives in YAML 1.2
 frontmatter; prose below it supplies human and agent context.
 
+New epic, task, and phase documents use the same core prose sections:
+`Outcome` states the intended result, `Plan` describes the current approach, and
+`Important Decisions` preserves consequential choices and their rationale. These
+sections are creation defaults rather than validation requirements, so existing
+and customized documents remain valid.
+
 ## Workbase Layout
 
 ```text

package/package.json

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

package/src/services/EpicService.test.ts

@@ -34,6 +34,9 @@ describe("EpicService", () => {
 
 		expect(created.content).toContain("ticketUrl:")
 		expect(created.content).toContain("tasks: []")
+		expect(created.content).toContain(
+			"# Workspace Orchestration\n\n## Outcome\n\nDescribe the epic outcome.\n\n## Plan\n\nDescribe the current approach.\n\n## Important Decisions\n\nRecord consequential decisions and their rationale.",
+		)
 
 		const records = await runTestEffect(
 			EpicService.pipe(Effect.flatMap((service) => service.list(root))),

package/src/services/EpicService.ts

@@ -10,6 +10,7 @@ import {
 } from "../workbase/schemas"
 import {
 	formatMarkdownDocument,
+	formatWorkDocumentBody,
 	parseFrontmatter,
 } from "../workbase/frontmatter"
 import { documentRevision } from "../workbase/document-revision"
@@ -95,7 +96,7 @@ export class EpicService extends Effect.Service<EpicService>()("EpicService", {
 					.join(" ")
 				const content = formatMarkdownDocument(
 					data,
-					`# ${title}\n\nDescribe the epic outcome.`,
+					formatWorkDocumentBody(title, "epic"),
 				)
 				yield* fs.writeFile(path, content)
 				return {

package/src/services/PhaseService.ts

@@ -14,6 +14,7 @@ import {
 } from "../workbase/schemas"
 import {
 	formatMarkdownDocument,
+	formatWorkDocumentBody,
 	parseFrontmatter,
 } from "../workbase/frontmatter"
 import { canTransitionStatus } from "../readiness"
@@ -196,7 +197,7 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 						.join(" ")
 					const content = formatMarkdownDocument(
 						data,
-						`# ${title}\n\nDescribe the phase outcome.`,
+						formatWorkDocumentBody(title, "phase"),
 					)
 
 					if (!isMultiPhase) {
@@ -246,7 +247,7 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 						const firstPhasePath = join(firstDirectory, "PHASE.md")
 						const firstContent = formatMarkdownDocument(
 							firstData,
-							`# ${firstTitle}\n\nDescribe the phase outcome.`,
+							formatWorkDocumentBody(firstTitle, "phase"),
 						)
 						const steps: TransactionStep[] = []
 						if (yield* fs.isDirectory(oldCodePath)) {

package/src/services/PullRequestService.test.ts

@@ -220,7 +220,10 @@ process.exit(${exitCode})
 		const original = await Bun.file(taskPath).text()
 		await Bun.write(
 			taskPath,
-			original.replace("# Example\n\nDescribe the task outcome.", body),
+			original.replace(
+				"# Example\n\n## Outcome\n\nDescribe the task outcome.\n\n## Plan\n\nDescribe the current approach.\n\n## Important Decisions\n\nRecord consequential decisions and their rationale.",
+				body,
+			),
 		)
 		const url = "https://github.com/example/agency/pull/42"
 		await writeFakeGh({ stdout: `${url}\n` })

package/src/services/TaskPhaseService.test.ts

@@ -33,7 +33,7 @@ describe("task and phase services", () => {
 				),
 			),
 		)
-		await runTestEffect(
+		const createdTask = await runTestEffect(
 			TaskService.pipe(
 				Effect.flatMap((service) =>
 					service.create(
@@ -51,6 +51,9 @@ describe("task and phase services", () => {
 				),
 			),
 		)
+		expect(createdTask.content).toContain(
+			"# Task One\n\n## Outcome\n\nDescribe the task outcome.\n\n## Plan\n\nDescribe the current approach.\n\n## Important Decisions\n\nRecord consequential decisions and their rationale.",
+		)
 
 		const epic = await runTestEffect(
 			EpicService.pipe(
@@ -159,6 +162,14 @@ describe("task and phase services", () => {
 			),
 		)
 		expect(phases.map((phase) => phase.id)).toEqual(["first", "second"])
+		const firstPhase = await runTestEffect(
+			PhaseService.pipe(
+				Effect.flatMap((service) => service.show("multi", "first", root)),
+			),
+		)
+		expect(firstPhase.content).toContain(
+			"# First\n\n## Outcome\n\nDescribe the phase outcome.\n\n## Plan\n\nDescribe the current approach.\n\n## Important Decisions\n\nRecord consequential decisions and their rationale.",
+		)
 	})
 
 	test("converts a single-phase task when the existing phase ID is provided", async () => {
@@ -243,7 +254,9 @@ describe("task and phase services", () => {
 				{ id: "extra", dependsOn: ["implementation"] },
 			],
 		})
-		expect(task.content).toContain("Describe the task outcome.")
+		expect(task.content).toContain(
+			"## Outcome\n\nDescribe the task outcome.\n\n## Plan\n\nDescribe the current approach.\n\n## Important Decisions",
+		)
 
 		const firstPhase = await runTestEffect(
 			PhaseService.pipe(

package/src/services/TaskService.ts

@@ -13,6 +13,7 @@ import {
 } from "../workbase/schemas"
 import {
 	formatMarkdownDocument,
+	formatWorkDocumentBody,
 	parseFrontmatter,
 } from "../workbase/frontmatter"
 import { canTransitionStatus } from "../readiness"
@@ -163,7 +164,7 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 					.join(" ")
 				const content = formatMarkdownDocument(
 					data,
-					`# ${title}\n\nDescribe the task outcome.`,
+					formatWorkDocumentBody(title, "task"),
 				)
 				const writes: {
 					path: string

package/src/workbase/frontmatter.ts

@@ -81,3 +81,20 @@ export const parseFrontmatter = (content: string, path: string) =>
 
 export const formatMarkdownDocument = (data: object, body: string) =>
 	`---\n${stringify(data, { lineWidth: 0 }).trimEnd()}\n---\n\n${body.trim()}\n`
+
+export const formatWorkDocumentBody = (
+	title: string,
+	kind: "epic" | "task" | "phase",
+) => `# ${title}
+
+## Outcome
+
+Describe the ${kind} outcome.
+
+## Plan
+
+Describe the current approach.
+
+## Important Decisions
+
+Record consequential decisions and their rationale.`