@os-eco/overstory-cli 0.6.7 → 0.6.8

package/README.md

@@ -273,13 +273,13 @@ Global Flags:
 - **Dependencies**: Minimal runtime — `chalk` (color output), `commander` (CLI framework), core I/O via Bun built-in APIs
 - **Database**: SQLite via `bun:sqlite` (WAL mode for concurrent access)
 - **Linting**: Biome (formatter + linter)
-- **Testing**: `bun test` (2151 tests across 76 files, colocated with source)
+- **Testing**: `bun test` (2167 tests across 77 files, colocated with source)
 - **External CLIs**: `bd` (beads) or `sd` (seeds), `mulch`, `git`, `tmux` — invoked as subprocesses
 
 ## Development
 
 ```bash
-# Run tests (2151 tests across 76 files)
+# Run tests (2167 tests across 77 files)
 bun test
 
 # Run a single test
@@ -319,6 +319,7 @@ overstory/
     types.ts                      Shared types and interfaces
     config.ts                     Config loader + validation
     errors.ts                     Custom error types
+    json.ts                       Standardized JSON envelope helpers
     commands/                     One file per CLI subcommand (30 commands)
       agents.ts                   Agent discovery and querying
       coordinator.ts              Persistent orchestrator lifecycle

package/agents/coordinator.md

@@ -128,15 +128,15 @@ Coordinator (you, depth 0)
 - **Your agent name** is `coordinator` (or as set by `$OVERSTORY_AGENT_NAME`)
 
 #### Mail Types You Send
-- `dispatch` -- assign a work stream to a lead (includes taskId, objective, file area)
+- `dispatch` -- assign a work stream to a lead (includes beadId, objective, file area)
 - `status` -- progress updates, clarifications, answers to questions
 - `error` -- report unrecoverable failures to the human operator
 
 #### Mail Types You Receive
-- `merge_ready` -- lead confirms all builders are done, branch verified and ready to merge (branch, taskId, agentName, filesModified)
-- `merged` -- merger confirms successful merge (branch, taskId, tier)
-- `merge_failed` -- merger reports merge failure (branch, taskId, conflictFiles, errorMessage)
-- `escalation` -- any agent escalates an issue (severity: warning|error|critical, taskId, context)
+- `merge_ready` -- lead confirms all builders are done, branch verified and ready to merge (branch, beadId, agentName, filesModified)
+- `merged` -- merger confirms successful merge (branch, beadId, tier)
+- `merge_failed` -- merger reports merge failure (branch, beadId, conflictFiles, errorMessage)
+- `escalation` -- any agent escalates an issue (severity: warning|error|critical, beadId, context)
 - `health_check` -- watchdog probes liveness (agentName, checkType)
 - `status` -- leads report progress
 - `result` -- leads report completed work streams

package/agents/lead.md

@@ -81,7 +81,6 @@ You are primarily a coordinator, but you can also be a doer for simple tasks. Yo
   - `{{TRACKER_CLI}} sync` (sync {{TRACKER_NAME}} with git)
   - `ml prime`, `ml record`, `ml query`, `ml search` (expertise)
   - `ov sling` (spawn sub-workers)
-  - `ov spec write <id> --body "..." --agent $OVERSTORY_AGENT_NAME` (write spec files)
   - `ov status` (monitor active agents)
   - `ov mail send`, `ov mail check`, `ov mail list`, `ov mail read`, `ov mail reply` (communication)
   - `ov nudge <agent> [message]` (poke stalled workers)
@@ -192,11 +191,7 @@ Delegate exploration to scouts so you can focus on decomposition and planning.
 
 Write specs from scout findings and dispatch builders.
 
-6. **Write spec files** for each subtask based on scout findings using `ov spec write`:
-   ```bash
-   ov spec write <subtask-id> --body "<spec content>" --agent $OVERSTORY_AGENT_NAME
-   ```
-   Specs are written to `.overstory/specs/<subtask-id>.md` at the canonical root. Each spec should include:
+6. **Write spec files** for each subtask based on scout findings. Each spec goes to `.overstory/specs/<bead-id>.md` and should include:
    - Objective (what to build)
    - Acceptance criteria (how to know it is done)
    - File scope (which files the builder owns -- non-overlapping)

package/agents/merger.md

@@ -19,7 +19,7 @@ These are named failures. If you catch yourself doing any of these, stop and cor
 
 ## overlay
 
-Your task-specific context (task ID, branches to merge, target branch, merge order, parent agent) is in `.claude/CLAUDE.md` in your worktree. That file is generated by `ov sling` and tells you WHAT to merge. This file tells you HOW to merge.
+Your task-specific context (task ID, branches to merge, target branch, merge order, parent agent) is in `.claude/CLAUDE.md` in your worktree. That file is generated by `overstory sling` and tells you WHAT to merge. This file tells you HOW to merge.
 
 ## constraints
 
@@ -85,7 +85,7 @@ You are a branch integration specialist. When workers complete their tasks on se
   - `bun run typecheck` (verify no TypeScript errors)
   - `{{TRACKER_CLI}} show`, `{{TRACKER_CLI}} close` ({{TRACKER_NAME}} task management)
   - `ml prime`, `ml query` (load expertise for conflict understanding)
-  - `ov merge` (use ov merge infrastructure)
+  - `ov merge` (use overstory merge infrastructure)
   - `ov mail send`, `ov mail check` (communication)
   - `ov status` (check which branches are ready to merge)
 
@@ -146,7 +146,7 @@ If AI-resolve fails or produces broken code:
    ```
 7. **Send detailed merge report** via mail:
    ```bash
-   ov mail send --to <parent-or-coordinator> \
+   ov mail send --to <parent-or-orchestrator> \
      --subject "Merge complete: <branch>" \
      --body "Tier: <tier-used>. Conflicts: <list or none>. Tests: passing." \
      --type result

package/agents/reviewer.md

@@ -16,7 +16,7 @@ These are named failures. If you catch yourself doing any of these, stop and cor
 
 ## overlay
 
-Your task-specific context (task ID, code to review, branch name, parent agent) is in `.claude/CLAUDE.md` in your worktree. That file is generated by `ov sling` and tells you WHAT to review. This file tells you HOW to review.
+Your task-specific context (task ID, code to review, branch name, parent agent) is in `.claude/CLAUDE.md` in your worktree. That file is generated by `overstory sling` and tells you WHAT to review. This file tells you HOW to review.
 
 ## constraints
 
@@ -53,7 +53,7 @@ The only write exception is `ov spec write` for persisting spec files (scout onl
 
 1. Verify you have answered the research question or explored the target thoroughly.
 2. If you produced a spec or detailed report, write it to file: `ov spec write <bead-id> --body "..." --agent <your-name>`.
-3. **Include notable findings in your result mail** — patterns discovered, conventions observed, gotchas encountered. Your parent may record these via ml.
+3. **Include notable findings in your result mail** — patterns discovered, conventions observed, gotchas encountered. Your parent may record these via mulch.
 4. Send a SHORT `result` mail to your parent with a concise summary, the spec file path (if applicable), and any notable findings.
 5. Run `{{TRACKER_CLI}} close <task-id> --reason "<summary of findings>"`.
 6. Stop. Do not continue exploring after closing.

package/agents/scout.md

@@ -16,7 +16,7 @@ These are named failures. If you catch yourself doing any of these, stop and cor
 
 ## overlay
 
-Your task-specific context (what to explore, who spawned you, your agent name) is in `.claude/CLAUDE.md` in your worktree. That file is generated by `ov sling` and tells you WHAT to work on. This file tells you HOW to work.
+Your task-specific context (what to explore, who spawned you, your agent name) is in `.claude/CLAUDE.md` in your worktree. That file is generated by `overstory sling` and tells you WHAT to work on. This file tells you HOW to work.
 
 ## constraints
 
@@ -53,7 +53,7 @@ The only write exception is `ov spec write` for persisting spec files (scout onl
 
 1. Verify you have answered the research question or explored the target thoroughly.
 2. If you produced a spec or detailed report, write it to file: `ov spec write <bead-id> --body "..." --agent <your-name>`.
-3. **Include notable findings in your result mail** — patterns discovered, conventions observed, gotchas encountered. Your parent may record these via ml.
+3. **Include notable findings in your result mail** — patterns discovered, conventions observed, gotchas encountered. Your parent may record these via mulch.
 4. Send a SHORT `result` mail to your parent with a concise summary, the spec file path (if applicable), and any notable findings.
 5. Run `{{TRACKER_CLI}} close <task-id> --reason "<summary of findings>"`.
 6. Stop. Do not continue exploring after closing.
@@ -110,7 +110,7 @@ You perform reconnaissance. Given a research question, exploration target, or an
    This writes the spec to `.overstory/specs/<bead-id>.md`. Do NOT send full specs via mail.
 6. **Notify via short mail** after writing a spec file:
    ```bash
-   ov mail send --to <parent-or-coordinator> \
+   ov mail send --to <parent-or-orchestrator> \
      --subject "Spec ready: <bead-id>" \
      --body "Spec written to .overstory/specs/<bead-id>.md — <one-line summary>" \
      --type result

package/agents/supervisor.md

@@ -133,18 +133,18 @@ Before spawning, check `ov status` to ensure non-overlapping file scope across a
 - **Read message:** `ov mail read <id> --agent $OVERSTORY_AGENT_NAME`
 
 #### Mail Types You Send
-- `assign` -- assign work to a specific worker (taskId, specPath, workerName, branch)
-- `merge_ready` -- signal to coordinator that a branch is verified and ready for merge (branch, taskId, agentName, filesModified)
+- `assign` -- assign work to a specific worker (beadId, specPath, workerName, branch)
+- `merge_ready` -- signal to coordinator that a branch is verified and ready for merge (branch, beadId, agentName, filesModified)
 - `status` -- progress updates to coordinator
-- `escalation` -- report unresolvable issues to coordinator (severity: warning|error|critical, taskId, context)
+- `escalation` -- report unresolvable issues to coordinator (severity: warning|error|critical, beadId, context)
 - `question` -- ask coordinator for clarification
 - `result` -- report completed batch results to coordinator
 
 #### Mail Types You Receive
-- `dispatch` -- coordinator assigns a task batch (taskId, specPath, capability, fileScope)
-- `worker_done` -- worker signals completion (taskId, branch, exitCode, filesModified)
-- `merged` -- merger confirms successful merge (branch, taskId, tier)
-- `merge_failed` -- merger reports merge failure (branch, taskId, conflictFiles, errorMessage)
+- `dispatch` -- coordinator assigns a task batch (beadId, specPath, capability, fileScope)
+- `worker_done` -- worker signals completion (beadId, branch, exitCode, filesModified)
+- `merged` -- merger confirms successful merge (branch, beadId, tier)
+- `merge_failed` -- merger reports merge failure (branch, beadId, conflictFiles, errorMessage)
 - `status` -- workers report progress
 - `question` -- workers ask for clarification
 - `error` -- workers report failures
@@ -218,7 +218,7 @@ This is your core responsibility. You manage the full worker lifecycle from spaw
 
 ### On `worker_done` Received
 
-When a worker sends `worker_done` mail (taskId, branch, exitCode, filesModified):
+When a worker sends `worker_done` mail (beadId, branch, exitCode, filesModified):
 
 1. **Verify the branch has commits:**
    ```bash
@@ -228,7 +228,7 @@ When a worker sends `worker_done` mail (taskId, branch, exitCode, filesModified)
 
 2. **Check if the worker closed its bead issue:**
    ```bash
-   {{TRACKER_CLI}} show <task-id>
+   {{TRACKER_CLI}} show <bead-id>
    ```
    Status should be `closed`. If still `open` or `in_progress`, send mail to worker to close it.
 
@@ -240,17 +240,17 @@ When a worker sends `worker_done` mail (taskId, branch, exitCode, filesModified)
      --body "Branch <branch> verified for bead <bead-id>. Worker <worker-name> completed successfully." \
      --type merge_ready --agent $OVERSTORY_AGENT_NAME
    ```
-   Include payload: `{"branch": "<branch>", "taskId": "<task-id>", "agentName": "<worker-name>", "filesModified": [...]}`
+   Include payload: `{"branch": "<branch>", "beadId": "<bead-id>", "agentName": "<worker-name>", "filesModified": [...]}`
 
 5. **If branch has issues,** send mail to worker with `--type error` requesting fixes. Track retry count. After 2 failed attempts, escalate to coordinator.
 
 ### On `merged` Received
 
-When coordinator or merger sends `merged` mail (branch, taskId, tier):
+When coordinator or merger sends `merged` mail (branch, beadId, tier):
 
 1. **Mark the corresponding bead issue as closed** (if not already):
    ```bash
-   {{TRACKER_CLI}} close <task-id> --reason "Merged to main via tier <tier>"
+   {{TRACKER_CLI}} close <bead-id> --reason "Merged to main via tier <tier>"
    ```
 
 2. **Clean up worktree:**
@@ -266,7 +266,7 @@ When coordinator or merger sends `merged` mail (branch, taskId, tier):
 
 ### On `merge_failed` Received
 
-When merger sends `merge_failed` mail (branch, taskId, conflictFiles, errorMessage):
+When merger sends `merge_failed` mail (branch, beadId, conflictFiles, errorMessage):
 
 1. **Assess the failure.** Read `conflictFiles` and `errorMessage` to understand root cause.
 
@@ -354,7 +354,7 @@ ov mail send --to coordinator --subject "Warning: <brief-description>" \
   --body "<context and current state>" \
   --type escalation --priority normal --agent $OVERSTORY_AGENT_NAME
 ```
-Payload: `{"severity": "warning", "taskId": "<task-id>", "context": "<details>"}`
+Payload: `{"severity": "warning", "beadId": "<bead-id>", "context": "<details>"}`
 
 #### Error
 Use when the issue is blocking but recoverable with coordinator intervention:
@@ -368,7 +368,7 @@ ov mail send --to coordinator --subject "Error: <brief-description>" \
   --body "<what failed, what was tried, what is needed>" \
   --type escalation --priority high --agent $OVERSTORY_AGENT_NAME
 ```
-Payload: `{"severity": "error", "taskId": "<task-id>", "context": "<detailed-context>"}`
+Payload: `{"severity": "error", "beadId": "<bead-id>", "context": "<detailed-context>"}`
 
 #### Critical
 Use when the automated system cannot self-heal and human intervention is required:
@@ -382,7 +382,7 @@ ov mail send --to coordinator --subject "CRITICAL: <brief-description>" \
   --body "<what broke, impact scope, manual intervention needed>" \
   --type escalation --priority urgent --agent $OVERSTORY_AGENT_NAME
 ```
-Payload: `{"severity": "critical", "taskId": null, "context": "<full-details>"}`
+Payload: `{"severity": "critical", "beadId": null, "context": "<full-details>"}`
 
 After sending a critical escalation, **stop dispatching new work** for the affected area until the coordinator responds.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@os-eco/overstory-cli",
-	"version": "0.6.7",
+	"version": "0.6.8",
 	"description": "Multi-agent orchestration for Claude Code — spawn worker agents in git worktrees via tmux, coordinate through SQLite mail, merge with tiered conflict resolution",
 	"author": "Jaymin West",
 	"license": "MIT",

package/src/commands/clean.ts

@@ -25,6 +25,7 @@ import { join } from "node:path";
 import { loadConfig } from "../config.ts";
 import { ValidationError } from "../errors.ts";
 import { createEventStore } from "../events/store.ts";
+import { printHint, printSuccess } from "../logging/color.ts";
 import { createMulchClient } from "../mulch/client.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import type { AgentSession, MulchDoctorResult, MulchPruneResult, MulchStatus } from "../types.ts";
@@ -584,7 +585,7 @@ export async function cleanCommand(opts: CleanOptions): Promise<void> {
 	}
 
 	if (lines.length === 0) {
-		process.stdout.write("Nothing to clean.\n");
+		printHint("Nothing to clean");
 	} else {
 		if (result.mulchHealth?.checked) {
 			process.stdout.write("\n--- Cleanup Results ---\n");
@@ -592,6 +593,6 @@ export async function cleanCommand(opts: CleanOptions): Promise<void> {
 		for (const line of lines) {
 			process.stdout.write(`${line}\n`);
 		}
-		process.stdout.write("\nClean complete.\n");
+		printSuccess("Clean complete");
 	}
 }

package/src/commands/coordinator.test.ts

@@ -1185,7 +1185,7 @@ describe("watchdog integration", () => {
 				Bun.sleep = originalSleep;
 			}
 
-			expect(output).toContain("Watchdog: started (PID 88888)");
+			expect(output).toContain("Watchdog started");
 		});
 	});
 
@@ -1414,7 +1414,7 @@ describe("monitor integration", () => {
 				Bun.sleep = originalSleep;
 			}
 
-			expect(output).toContain("Monitor:  started (PID 77777)");
+			expect(output).toContain("Monitor started");
 		});
 
 		test("does NOT call monitor.start() when tier2Enabled is false", async () => {
@@ -1460,21 +1460,16 @@ describe("monitor integration", () => {
 			const originalSleep = Bun.sleep;
 			Bun.sleep = (() => Promise.resolve()) as typeof Bun.sleep;
 
-			let stderrOutput = "";
-			const origStderrWrite = process.stderr.write.bind(process.stderr);
-			process.stderr.write = (chunk: string | Uint8Array) => {
-				stderrOutput += typeof chunk === "string" ? chunk : new TextDecoder().decode(chunk);
-				return true;
-			};
-
+			let output: string;
 			try {
-				await captureStdout(() => coordinatorCommand(["start", "--monitor", "--no-attach"], deps));
+				output = await captureStdout(() =>
+					coordinatorCommand(["start", "--monitor", "--no-attach"], deps),
+				);
 			} finally {
 				Bun.sleep = originalSleep;
-				process.stderr.write = origStderrWrite;
 			}
 
-			expect(stderrOutput).toContain("skipped");
+			expect(output).toContain("skipped");
 		});
 	});
 

package/src/commands/coordinator.ts

@@ -20,6 +20,7 @@ import { createIdentity, loadIdentity } from "../agents/identity.ts";
 import { createManifestLoader, resolveModel } from "../agents/manifest.ts";
 import { loadConfig } from "../config.ts";
 import { AgentError, ValidationError } from "../errors.ts";
+import { printHint, printSuccess, printWarning } from "../logging/color.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import { createRunStore } from "../sessions/store.ts";
 import { resolveBackend, trackerCliName } from "../tracker/factory.ts";
@@ -428,9 +429,9 @@ async function startCoordinator(
 			const watchdogResult = await watchdog.start();
 			if (watchdogResult) {
 				watchdogPid = watchdogResult.pid;
-				if (!json) process.stdout.write(`  Watchdog: started (PID ${watchdogResult.pid})\n`);
+				if (!json) printHint("Watchdog started");
 			} else {
-				if (!json) process.stderr.write("  Watchdog: failed to start or already running\n");
+				if (!json) printWarning("Watchdog failed to start");
 			}
 		}
 
@@ -438,15 +439,14 @@ async function startCoordinator(
 		let monitorPid: number | undefined;
 		if (monitorFlag) {
 			if (!config.watchdog.tier2Enabled) {
-				if (!json)
-					process.stderr.write("  Monitor:  skipped (watchdog.tier2Enabled is false in config)\n");
+				if (!json) printWarning("Monitor skipped", "watchdog.tier2Enabled is false");
 			} else {
 				const monitorResult = await monitor.start([]);
 				if (monitorResult) {
 					monitorPid = monitorResult.pid;
-					if (!json) process.stdout.write(`  Monitor:  started (PID ${monitorResult.pid})\n`);
+					if (!json) printHint("Monitor started");
 				} else {
-					if (!json) process.stderr.write("  Monitor:  failed to start or already running\n");
+					if (!json) printWarning("Monitor failed to start");
 				}
 			}
 		}
@@ -464,7 +464,7 @@ async function startCoordinator(
 		if (json) {
 			process.stdout.write(`${JSON.stringify(output)}\n`);
 		} else {
-			process.stdout.write("Coordinator started\n");
+			printSuccess("Coordinator started");
 			process.stdout.write(`  Tmux:    ${tmuxSession}\n`);
 			process.stdout.write(`  Root:    ${projectRoot}\n`);
 			process.stdout.write(`  PID:     ${pid}\n`);
@@ -568,21 +568,21 @@ async function stopCoordinator(opts: { json: boolean }, deps: CoordinatorDeps =
 				`${JSON.stringify({ stopped: true, sessionId: session.id, watchdogStopped, monitorStopped, runCompleted })}\n`,
 			);
 		} else {
-			process.stdout.write(`Coordinator stopped (session: ${session.id})\n`);
+			printSuccess("Coordinator stopped", session.id);
 			if (watchdogStopped) {
-				process.stdout.write("Watchdog stopped\n");
+				printHint("Watchdog stopped");
 			} else {
-				process.stdout.write("No watchdog running\n");
+				printHint("No watchdog running");
 			}
 			if (monitorStopped) {
-				process.stdout.write("Monitor stopped\n");
+				printHint("Monitor stopped");
 			} else {
-				process.stdout.write("No monitor running\n");
+				printHint("No monitor running");
 			}
 			if (runCompleted) {
-				process.stdout.write("Run completed\n");
+				printHint("Run completed");
 			} else {
-				process.stdout.write("No active run\n");
+				printHint("No active run");
 			}
 		}
 	} finally {
@@ -633,12 +633,12 @@ async function statusCoordinator(
 					`${JSON.stringify({ running: false, watchdogRunning, monitorRunning })}\n`,
 				);
 			} else {
-				process.stdout.write("Coordinator is not running\n");
+				printHint("Coordinator is not running");
 				if (watchdogRunning) {
-					process.stdout.write("Watchdog: running\n");
+					printHint("Watchdog: running");
 				}
 				if (monitorRunning) {
-					process.stdout.write("Monitor: running\n");
+					printHint("Monitor: running");
 				}
 			}
 			return;

package/src/commands/group.ts

@@ -11,6 +11,7 @@ import { join } from "node:path";
 import { Command } from "commander";
 import { loadConfig } from "../config.ts";
 import { GroupError, ValidationError } from "../errors.ts";
+import { printHint, printSuccess } from "../logging/color.ts";
 import { createTrackerClient, resolveBackend, type TrackerClient } from "../tracker/factory.ts";
 import type { TaskGroup, TaskGroupProgress } from "../types.ts";
 
@@ -326,7 +327,7 @@ export function createGroupCommand(): Command {
 				if (opts.json) {
 					process.stdout.write(`${JSON.stringify(group, null, "\t")}\n`);
 				} else {
-					process.stdout.write(`Created group "${group.name}" (${group.id})\n`);
+					printSuccess("Created group", group.name);
 					process.stdout.write(`  Members: ${group.memberIssueIds.join(", ")}\n`);
 				}
 			},
@@ -365,7 +366,7 @@ export function createGroupCommand(): Command {
 						if (json) {
 							process.stdout.write("[]\n");
 						} else {
-							process.stdout.write("No active groups\n");
+							printHint("No active groups");
 						}
 						return;
 					}
@@ -414,7 +415,7 @@ export function createGroupCommand(): Command {
 				if (opts.json) {
 					process.stdout.write(`${JSON.stringify(group, null, "\t")}\n`);
 				} else {
-					process.stdout.write(`Added ${ids.length} issue(s) to "${group.name}"\n`);
+					printSuccess("Added to group", group.name);
 					process.stdout.write(`  Members: ${group.memberIssueIds.join(", ")}\n`);
 				}
 			},
@@ -434,7 +435,7 @@ export function createGroupCommand(): Command {
 			if (opts.json) {
 				process.stdout.write(`${JSON.stringify(group, null, "\t")}\n`);
 			} else {
-				process.stdout.write(`Removed ${ids.length} issue(s) from "${group.name}"\n`);
+				printSuccess("Removed from group", group.name);
 				process.stdout.write(`  Members: ${group.memberIssueIds.join(", ")}\n`);
 			}
 		});
@@ -452,7 +453,7 @@ export function createGroupCommand(): Command {
 				if (opts.json) {
 					process.stdout.write("[]\n");
 				} else {
-					process.stdout.write("No groups\n");
+					printHint("No groups");
 				}
 				return;
 			}

package/src/commands/hooks.test.ts

@@ -227,7 +227,7 @@ describe("hooks uninstall", () => {
 		);
 
 		const output = await captureStdout(() => hooksCommand(["uninstall"]));
-		expect(output).toContain("preserved other settings");
+		expect(output).toContain("Removed");
 
 		const content = await Bun.file(join(claudeDir, "settings.local.json")).text();
 		const parsed = JSON.parse(content) as Record<string, unknown>;

package/src/commands/hooks.ts

@@ -15,6 +15,7 @@ import { join } from "node:path";
 import { Command } from "commander";
 import { loadConfig } from "../config.ts";
 import { ValidationError } from "../errors.ts";
+import { printHint, printSuccess, printWarning } from "../logging/color.ts";
 
 interface HookEntry {
 	matcher: string;
@@ -120,8 +121,8 @@ async function installHooks(force: boolean): Promise<void> {
 	await mkdir(targetDir, { recursive: true });
 	await Bun.write(targetPath, `${JSON.stringify(targetConfig, null, "\t")}\n`);
 
-	process.stdout.write("\u2713 Installed orchestrator hooks to .claude/settings.local.json\n");
-	process.stdout.write("  Source: .overstory/hooks.json\n");
+	printSuccess("Installed orchestrator hooks");
+	printHint("Source: .overstory/hooks.json");
 }
 
 /**
@@ -139,7 +140,7 @@ async function uninstallHooks(): Promise<void> {
 	const targetFile = Bun.file(targetPath);
 
 	if (!(await targetFile.exists())) {
-		process.stdout.write("No .claude/settings.local.json found \u2014 nothing to uninstall.\n");
+		printWarning("No .claude/settings.local.json found", "nothing to uninstall");
 		return;
 	}
 
@@ -159,12 +160,10 @@ async function uninstallHooks(): Promise<void> {
 	const remainingKeys = Object.keys(rest);
 	if (remainingKeys.length === 0) {
 		await unlink(targetPath);
-		process.stdout.write("\u2713 Removed .claude/settings.local.json (was hooks-only)\n");
+		printSuccess("Removed hooks from settings.local.json");
 	} else {
 		await Bun.write(targetPath, `${JSON.stringify(rest, null, "\t")}\n`);
-		process.stdout.write(
-			"\u2713 Removed hooks from .claude/settings.local.json (preserved other settings)\n",
-		);
+		printSuccess("Removed hooks from settings.local.json");
 	}
 }
 
@@ -199,7 +198,7 @@ async function statusHooks(json: boolean): Promise<void> {
 			`Hooks installed (.claude/settings.local.json): ${installed ? "yes" : "no"}\n`,
 		);
 		if (!installed && sourceExists) {
-			process.stdout.write(`\nRun 'ov hooks install' to install.\n`);
+			printHint("Run ov hooks install to install");
 		}
 	}
 }

package/src/commands/init.test.ts

@@ -20,10 +20,6 @@ const AGENT_DEF_FILES = [
 	"supervisor.md",
 	"coordinator.md",
 	"monitor.md",
-	"issue-reviews.md",
-	"pr-reviews.md",
-	"prioritize.md",
-	"release.md",
 ];
 
 /** Resolve the source agents directory (same logic as init.ts). */
@@ -50,7 +46,7 @@ describe("initCommand: agent-defs deployment", () => {
 		await cleanupTempDir(tempDir);
 	});
 
-	test("creates .overstory/agent-defs/ with all 12 agent definition files", async () => {
+	test("creates .overstory/agent-defs/ with all 8 agent definition files", async () => {
 		await initCommand({});
 
 		const agentDefsDir = join(tempDir, ".overstory", "agent-defs");

package/src/commands/init.ts

@@ -14,6 +14,7 @@ import { mkdir, readdir } from "node:fs/promises";
 import { basename, join } from "node:path";
 import { DEFAULT_CONFIG } from "../config.ts";
 import { ValidationError } from "../errors.ts";
+import { printHint, printSuccess } from "../logging/color.ts";
 import type { AgentManifest, OverstoryConfig } from "../types.ts";
 
 const OVERSTORY_DIR = ".overstory";
@@ -522,7 +523,7 @@ export interface InitOptions {
  * Print a success status line.
  */
 function printCreated(relativePath: string): void {
-	process.stdout.write(`  \u2713 Created ${relativePath}\n`);
+	printSuccess("Created", relativePath);
 }
 
 /**
@@ -631,11 +632,11 @@ export async function initCommand(opts: InitOptions): Promise<void> {
 	if (force) {
 		const migrated = await migrateExistingDatabases(overstoryPath);
 		for (const dbName of migrated) {
-			process.stdout.write(`  \u2713 Migrated ${OVERSTORY_DIR}/${dbName} (schema validated)\n`);
+			printSuccess("Migrated", dbName);
 		}
 	}
 
-	process.stdout.write("\nDone.\n");
-	process.stdout.write("  Next: run `ov hooks install` to enable Claude Code hooks.\n");
-	process.stdout.write("  Then: run `ov status` to see the current state.\n");
+	printSuccess("Initialized");
+	printHint("Next: run `ov hooks install` to enable Claude Code hooks.");
+	printHint("Then: run `ov status` to see the current state.");
 }

package/src/commands/mail.test.ts

@@ -100,7 +100,7 @@ describe("mailCommand", () => {
 			client.close();
 
 			await mailCommand(["list", "--agent", "builder-1", "--unread"]);
-			expect(output).toContain("No messages found.");
+			expect(output).toContain("No messages found");
 		});
 
 		test("--to takes precedence over --agent when both provided", async () => {
@@ -134,7 +134,7 @@ describe("mailCommand", () => {
 			output = "";
 			await mailCommand(["reply", originalId, "--body", "Actually also do Y"]);
 
-			expect(output).toContain("Reply sent:");
+			expect(output).toContain("Reply sent");
 
 			// Verify the reply went to builder-1, not back to orchestrator
 			const store2 = createMailStore(join(tempDir, ".overstory", "mail.db"));
@@ -162,7 +162,7 @@ describe("mailCommand", () => {
 			output = "";
 			await mailCommand(["reply", originalId, "--body", "Done", "--agent", "builder-1"]);
 
-			expect(output).toContain("Reply sent:");
+			expect(output).toContain("Reply sent");
 
 			// Verify the reply went to orchestrator (original sender)
 			const store2 = createMailStore(join(tempDir, ".overstory", "mail.db"));
@@ -193,7 +193,7 @@ describe("mailCommand", () => {
 			output = "";
 			await mailCommand(["reply", "--agent", "scout-1", "--body", "Got it", originalId]);
 
-			expect(output).toContain("Reply sent:");
+			expect(output).toContain("Reply sent");
 
 			// Verify the reply used the correct message ID (not 'scout-1' or 'Got it')
 			const store2 = createMailStore(join(tempDir, ".overstory", "mail.db"));
@@ -223,7 +223,7 @@ describe("mailCommand", () => {
 			output = "";
 			await mailCommand(["read", originalId]);
 
-			expect(output).toContain(`Marked ${originalId} as read.`);
+			expect(output).toContain("Marked as read");
 		});
 
 		test("read marks message as read", async () => {
@@ -238,7 +238,7 @@ describe("mailCommand", () => {
 
 			output = "";
 			await mailCommand(["read", originalId]);
-			expect(output).toContain(`Marked ${originalId} as read.`);
+			expect(output).toContain("Marked as read");
 
 			// Reading again should show already read
 			output = "";