@os-eco/overstory-cli 0.8.7 → 0.9.1

package/README.md

@@ -84,17 +84,18 @@ Every command supports `--json` where noted. Global flags: `-q`/`--quiet`, `--ti
 | Command | Description |
 |---------|-------------|
 | `ov init` | Initialize `.overstory/` and bootstrap os-eco tools (`--yes`, `--name`, `--tools`, `--skip-mulch`, `--skip-seeds`, `--skip-canopy`, `--skip-onboard`, `--json`) |
-| `ov sling <task-id>` | Spawn a worker agent (`--capability`, `--name`, `--spec`, `--files`, `--parent`, `--depth`, `--skip-scout`, `--skip-review`, `--max-agents`, `--dispatch-max-agents`, `--skip-task-check`, `--no-scout-check`, `--runtime`, `--base-branch`, `--json`) |
+| `ov sling <task-id>` | Spawn a worker agent (`--capability`, `--name`, `--spec`, `--files`, `--parent`, `--depth`, `--skip-scout`, `--skip-review`, `--max-agents`, `--dispatch-max-agents`, `--skip-task-check`, `--no-scout-check`, `--runtime`, `--base-branch`, `--profile`, `--json`) |
 | `ov stop <agent-name>` | Terminate a running agent (`--clean-worktree`, `--json`) |
 | `ov prime` | Load context for orchestrator/agent (`--agent`, `--compact`) |
 | `ov spec write <task-id>` | Write a task specification (`--body`) |
+| `ov discover` | Discover a brownfield codebase via coordinator-driven scout swarm (`--skip`, `--name`, `--attach`, `--watchdog`, `--json`) |
 | `ov update` | Refresh `.overstory/` managed files from installed package (`--agents`, `--manifest`, `--hooks`, `--dry-run`, `--json`) |
 
 ### Coordination
 
 | Command | Description |
 |---------|-------------|
-| `ov coordinator start` | Start persistent coordinator agent (`--attach`/`--no-attach`, `--watchdog`, `--monitor`) |
+| `ov coordinator start` | Start persistent coordinator agent (`--attach`/`--no-attach`, `--watchdog`, `--monitor`, `--profile`) |
 | `ov coordinator stop` | Stop coordinator |
 | `ov coordinator status` | Show coordinator state |
 | `ov coordinator send` | Fire-and-forget message to coordinator (`--subject`) |
@@ -236,7 +237,7 @@ overstory/
     config.ts                     Config loader + validation
     errors.ts                     Custom error types
     json.ts                       Standardized JSON envelope helpers
-    commands/                     One file per CLI subcommand (35 commands)
+    commands/                     One file per CLI subcommand (36 commands)
       agents.ts                   Agent discovery and querying
       coordinator.ts              Persistent orchestrator lifecycle
       supervisor.ts               Team lead management [DEPRECATED]
@@ -270,7 +271,10 @@ overstory/
       ecosystem.ts                os-eco tool dashboard
       update.ts                   Refresh managed files
       upgrade.ts                  npm version upgrades
+      discover.ts                 Brownfield codebase discovery via coordinator-driven scout swarm
       completions.ts              Shell completion generation (bash/zsh/fish)
+    canopy/
+      client.ts                   Canopy client (prompt rendering, listing, emission)
     agents/                       Agent lifecycle management
       manifest.ts                 Agent registry (load + query)
       overlay.ts                  Dynamic CLAUDE.md overlay generator

package/agents/ov-co-creation.md

@@ -0,0 +1,90 @@
+---
+name: ov-co-creation
+description: Co-creation workflow profile — human-in-the-loop at explicit decision gates
+---
+
+## propulsion-principle
+
+Read your assignment. For implementation work within an approved plan, execute immediately — no confirmation needed for routine decisions (naming, file organization, test strategy, implementation details within spec).
+
+PAUSE at decision gates. When you encounter an architectural choice, design fork, scope boundary, or tool selection, stop and do not proceed. Instead:
+
+1. Write a structured decision document (context, options, tradeoffs, recommendation).
+2. Send it as a decision_gate mail to the coordinator.
+3. Wait for a response before proceeding past the gate.
+
+Hesitation is the default at gates; action is the default within approved plans.
+
+## escalation-policy
+
+At decision points, present options rather than choosing. When you encounter a meaningful decision:
+
+1. Write a structured decision document: context, 2+ options with tradeoffs, and your recommendation.
+2. Send it as a decision_gate mail to the coordinator and wait.
+3. Do not proceed until you receive a reply selecting an option.
+
+Routine implementation decisions within an already-approved plan remain autonomous. Do not send decision gates for: variable names, file organization within spec, test strategy, or minor implementation choices that do not affect overall direction.
+
+Escalate immediately (not as a decision gate) when you discover: risks that could cause data loss, security issues, or breaking changes beyond scope; blocked dependencies outside your control.
+
+## artifact-expectations
+
+Decision artifacts come before code. Deliverables in order:
+
+1. **Option memos**: For any decision with multiple viable approaches, write a structured memo with options, tradeoffs, and a recommendation. Send as a decision_gate mail and await approval.
+2. **ADRs (Architecture Decision Records)**: For architectural choices, create a lightweight ADR capturing context, decision, and consequences.
+3. **Tradeoff matrices**: When comparing approaches across multiple dimensions, present a structured comparison.
+4. **Code and tests**: Implementation proceeds after decision artifacts are approved. Code must be clean, follow project conventions, and include automated tests.
+5. **Quality gates**: All lints, type checks, and tests must pass before reporting completion.
+
+Do not write implementation code before decisions are resolved. The human reviews and approves decision documents; implementation follows approval.
+
+## completion-criteria
+
+Work is complete when all of the following are true:
+
+- All quality gates pass: tests green, linting clean, type checking passes.
+- Changes are committed to the appropriate branch.
+- Any issues tracked in the task system are updated or closed.
+- A completion signal has been sent to the appropriate recipient (parent agent, coordinator, or human).
+
+Do not declare completion prematurely. Run the quality gates yourself — do not assume they pass. If a gate fails, fix the issue before reporting done.
+
+## human-role
+
+The human is an active co-creator at explicit decision gates — not a hands-off supervisor.
+
+- **Active at gates.** The human reviews decision documents and selects options via mail reply. The agent waits for this input before proceeding.
+- **Autonomous between gates.** Once a direction is approved, the agent executes without further check-ins. Implementation details within an approved plan are delegated.
+- **Milestone reviews.** The human reviews work at defined checkpoints (planning, prototype, final). These are collaborative reviews with explicit proceed signals.
+- **Minimal interruption between gates.** Do not ask questions that could be answered by reading the codebase or attempting something. Reserve interruptions for genuinely ambiguous requirements.
+
+## decision-gates
+
+When you reach a decision point (architectural choice, scope boundary, design fork, tool selection), follow this protocol:
+
+1. **Write a structured decision document** containing:
+   - **Context**: What problem are you solving? What constraints apply?
+   - **Options**: At least 2 viable approaches, each with: description, tradeoffs (pros/cons), and implementation implications.
+   - **Recommendation**: Which option you recommend and why.
+
+2. **Send a decision_gate mail** to the coordinator with the decision document in the body. Include a payload with the options array and brief context. Use --type decision_gate.
+
+3. **BLOCK and wait** for a reply. Do not continue past the gate without a response. Poll your inbox periodically while waiting.
+
+Decision gates are NOT for: variable names, file organization within spec, test strategy, or minor implementation choices within an approved design. They are for choices that meaningfully affect the direction of work.
+
+## milestone-reviews
+
+Send checkpoint reviews at three milestones:
+
+**After planning** (before any implementation begins):
+Send a status mail with: scope summary (what will be built), approach (high-level design with all decisions resolved via gates), file list (which files will be affected), and any open questions requiring confirmation before starting.
+
+**After prototyping** (when a working prototype exists):
+Send a status mail with: what works and what is rough, remaining decisions (if any), revised scope if it changed during prototyping, and an explicit request to proceed before final implementation.
+
+**Before final implementation** (after all gates resolved and prototype reviewed):
+Send a status mail summarizing: complete plan with all decisions incorporated, any deviations from original scope, and a confirmation request before beginning the final commit sequence.
+
+Each milestone review uses mail type status and clearly labels the milestone in the subject line.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@os-eco/overstory-cli",
-	"version": "0.8.7",
+	"version": "0.9.1",
 	"description": "Multi-agent orchestration for AI coding agents — spawn workers in git worktrees via tmux, coordinate through SQLite mail, merge with tiered conflict resolution. Pluggable runtime adapters for Claude Code, Pi, and more.",
 	"author": "Jaymin West",
 	"license": "MIT",

package/src/agents/overlay.ts

@@ -35,6 +35,18 @@ function formatMulchDomains(domains: readonly string[]): string {
 	return `\`\`\`bash\nml prime ${domains.join(" ")}\n\`\`\``;
 }
 
+/**
+ * Format profile content (Layer 2: deployment-specific WHAT KIND) for embedding in the overlay.
+ * Returns empty string if no profile was provided (omits the section entirely).
+ * When profile IS provided, renders it as-is — the caller (canopy) owns the formatting.
+ */
+function formatProfile(profileContent: string | undefined): string {
+	if (!profileContent || profileContent.trim().length === 0) {
+		return "";
+	}
+	return profileContent;
+}
+
 /**
  * Format pre-fetched mulch expertise for embedding in the overlay.
  * Returns empty string if no expertise was provided (omits the section entirely).
@@ -314,6 +326,7 @@ export async function generateOverlay(config: OverlayConfig): Promise<string> {
 		"{{SKIP_SCOUT}}": config.skipScout ? SKIP_SCOUT_SECTION : "",
 		"{{DISPATCH_OVERRIDES}}": formatDispatchOverrides(config),
 		"{{BASE_DEFINITION}}": config.baseDefinition,
+		"{{PROFILE_INSTRUCTIONS}}": formatProfile(config.profileContent),
 		"{{QUALITY_GATE_INLINE}}": formatQualityGatesInline(config.qualityGates),
 		"{{QUALITY_GATE_STEPS}}": formatQualityGatesSteps(config.qualityGates),
 		"{{QUALITY_GATE_BASH}}": formatQualityGatesBash(config.qualityGates),

package/src/canopy/client.test.ts

@@ -0,0 +1,107 @@
+/**
+ * Tests for the Canopy CLI client.
+ *
+ * Uses real `cn` CLI calls against the actual .canopy/ directory.
+ * We do not mock the CLI — the project root has real prompts to test against.
+ * Tests are skipped if the `cn` CLI is not installed (e.g. in CI).
+ */
+
+import { describe, expect, test } from "bun:test";
+import { AgentError } from "../errors.ts";
+import { createCanopyClient } from "./client.ts";
+
+// Check if canopy CLI is available
+let hasCanopy = false;
+try {
+	const proc = Bun.spawn(["which", "cn"], { stdout: "pipe", stderr: "pipe" });
+	const exitCode = await proc.exited;
+	hasCanopy = exitCode === 0;
+} catch {
+	hasCanopy = false;
+}
+
+// The worktree root has its own .canopy/ symlinked/shared from the canonical root.
+// Use process.cwd() which is set to the worktree root in bun test.
+const cwd = process.cwd();
+const client = createCanopyClient(cwd);
+
+describe("CanopyClient.list()", () => {
+	test.skipIf(!hasCanopy)("returns prompts array with at least one entry", async () => {
+		const result = await client.list();
+		expect(result.success).toBe(true);
+		expect(Array.isArray(result.prompts)).toBe(true);
+		expect(result.prompts.length).toBeGreaterThan(0);
+		const first = result.prompts[0];
+		expect(first).toBeDefined();
+		expect(typeof first?.name).toBe("string");
+		expect(typeof first?.version).toBe("number");
+		expect(Array.isArray(first?.sections)).toBe(true);
+	});
+});
+
+describe("CanopyClient.render()", () => {
+	test.skipIf(!hasCanopy)(
+		"returns CanopyRenderResult with name, version, sections for 'builder' prompt",
+		async () => {
+			const result = await client.render("builder");
+			expect(result.success).toBe(true);
+			expect(result.name).toBe("builder");
+			expect(typeof result.version).toBe("number");
+			expect(result.version).toBeGreaterThan(0);
+			expect(Array.isArray(result.sections)).toBe(true);
+			expect(result.sections.length).toBeGreaterThan(0);
+			const section = result.sections[0];
+			expect(section).toBeDefined();
+			expect(typeof section?.name).toBe("string");
+			expect(typeof section?.body).toBe("string");
+		},
+	);
+
+	test.skipIf(!hasCanopy)("throws AgentError on non-existent prompt", async () => {
+		await expect(client.render("nonexistent-prompt-xyz-404")).rejects.toThrow(AgentError);
+	});
+});
+
+describe("CanopyClient.show()", () => {
+	test.skipIf(!hasCanopy)("returns prompt object for 'builder'", async () => {
+		const result = await client.show("builder");
+		expect(result.success).toBe(true);
+		expect(result.prompt).toBeDefined();
+		expect(result.prompt.name).toBe("builder");
+		expect(typeof result.prompt.version).toBe("number");
+		expect(typeof result.prompt.id).toBe("string");
+		expect(Array.isArray(result.prompt.sections)).toBe(true);
+	});
+
+	test.skipIf(!hasCanopy)("throws AgentError on non-existent prompt", async () => {
+		await expect(client.show("nonexistent-prompt-xyz-404")).rejects.toThrow(AgentError);
+	});
+});
+
+describe("CanopyClient.validate()", () => {
+	test.skipIf(!hasCanopy)("returns {success, errors} for a named prompt", async () => {
+		const result = await client.validate("scout");
+		expect(typeof result.success).toBe("boolean");
+		expect(Array.isArray(result.errors)).toBe(true);
+		if (result.success) {
+			expect(result.errors.length).toBe(0);
+		}
+	});
+
+	test.skipIf(!hasCanopy)("returns success=false with errors for an invalid prompt", async () => {
+		// 'builder' is known to fail schema validation (missing test gate)
+		const result = await client.validate("builder");
+		expect(typeof result.success).toBe("boolean");
+		expect(Array.isArray(result.errors)).toBe(true);
+		// Either valid or invalid — just verify structure is correct
+		if (!result.success) {
+			expect(result.errors.length).toBeGreaterThan(0);
+		}
+	});
+
+	test.skipIf(!hasCanopy)("validate --all returns result with success boolean", async () => {
+		const result = await client.validate(undefined, { all: true });
+		expect(typeof result.success).toBe("boolean");
+		expect(Array.isArray(result.errors)).toBe(true);
+	});
+});

package/src/canopy/client.ts

@@ -0,0 +1,179 @@
+/**
+ * Canopy CLI client.
+ *
+ * Wraps the `cn` command-line tool for prompt management operations.
+ * All methods use Bun.spawn to invoke the CLI directly.
+ */
+
+import { AgentError } from "../errors.ts";
+import type {
+	CanopyListResult,
+	CanopyRenderResult,
+	CanopyShowResult,
+	CanopyValidateResult,
+} from "../types.ts";
+
+export interface CanopyClient {
+	/** Render a prompt, resolving inheritance. */
+	render(name: string, options?: { format?: "md" | "json" }): Promise<CanopyRenderResult>;
+
+	/** Validate a prompt (or all prompts) against its schema. */
+	validate(name?: string, options?: { all?: boolean }): Promise<CanopyValidateResult>;
+
+	/** List all prompts. */
+	list(options?: {
+		tag?: string;
+		status?: string;
+		extends?: string;
+		mixin?: string;
+	}): Promise<CanopyListResult>;
+
+	/** Show a prompt record. */
+	show(name: string): Promise<CanopyShowResult>;
+}
+
+/**
+ * Run a shell command and capture its output.
+ */
+async function runCommand(
+	cmd: string[],
+	cwd: string,
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+	const proc = Bun.spawn(cmd, {
+		cwd,
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	const stdout = await new Response(proc.stdout).text();
+	const stderr = await new Response(proc.stderr).text();
+	const exitCode = await proc.exited;
+	return { stdout, stderr, exitCode };
+}
+
+/**
+ * Create a CanopyClient bound to the given working directory.
+ *
+ * @param cwd - Working directory where cn commands should run
+ * @returns A CanopyClient instance wrapping the cn CLI
+ */
+export function createCanopyClient(cwd: string): CanopyClient {
+	async function runCanopy(
+		args: string[],
+		context: string,
+	): Promise<{ stdout: string; stderr: string }> {
+		const { stdout, stderr, exitCode } = await runCommand(["cn", ...args], cwd);
+		if (exitCode !== 0) {
+			throw new AgentError(`canopy ${context} failed (exit ${exitCode}): ${stderr.trim()}`);
+		}
+		return { stdout, stderr };
+	}
+
+	return {
+		async render(name, _options) {
+			// Always use --json for structured output; format param reserved for future use
+			const { stdout } = await runCanopy(["render", name, "--json"], `render ${name}`);
+			const trimmed = stdout.trim();
+			try {
+				const raw = JSON.parse(trimmed) as {
+					success: boolean;
+					name: string;
+					version: number;
+					sections: Array<{ name: string; body: string }>;
+				};
+				return {
+					success: raw.success,
+					name: raw.name,
+					version: raw.version,
+					sections: raw.sections,
+				};
+			} catch {
+				throw new AgentError(
+					`Failed to parse JSON from cn render ${name}: ${trimmed.slice(0, 200)}`,
+				);
+			}
+		},
+
+		async validate(name, options) {
+			const args = ["validate"];
+			if (options?.all) {
+				args.push("--all");
+			} else if (name) {
+				args.push(name);
+			}
+			// cn validate does not support --json; parse exit code and stdout/stderr
+			const { stdout, stderr, exitCode } = await runCommand(["cn", ...args], cwd);
+			const output = (stdout + stderr).trim();
+			const errors: string[] = [];
+			if (exitCode !== 0) {
+				// Extract error lines from output (lines containing "error:")
+				for (const line of output.split("\n")) {
+					const trimmedLine = line.trim();
+					if (trimmedLine.includes("error:")) {
+						errors.push(trimmedLine);
+					}
+				}
+				if (errors.length === 0 && output) {
+					errors.push(output);
+				}
+			}
+			return { success: exitCode === 0, errors };
+		},
+
+		async list(options) {
+			const args = ["list", "--json"];
+			if (options?.tag) {
+				args.push("--tag", options.tag);
+			}
+			if (options?.status) {
+				args.push("--status", options.status);
+			}
+			if (options?.extends) {
+				args.push("--extends", options.extends);
+			}
+			if (options?.mixin) {
+				args.push("--mixin", options.mixin);
+			}
+			const { stdout } = await runCanopy(args, "list");
+			const trimmed = stdout.trim();
+			try {
+				const raw = JSON.parse(trimmed) as {
+					success: boolean;
+					prompts: Array<{
+						id: string;
+						name: string;
+						version: number;
+						sections: Array<{ name: string; body: string }>;
+					}>;
+				};
+				return {
+					success: raw.success,
+					prompts: raw.prompts,
+				};
+			} catch {
+				throw new AgentError(`Failed to parse JSON from cn list: ${trimmed.slice(0, 200)}`);
+			}
+		},
+
+		async show(name) {
+			const { stdout } = await runCanopy(["show", name, "--json"], `show ${name}`);
+			const trimmed = stdout.trim();
+			try {
+				const raw = JSON.parse(trimmed) as {
+					success: boolean;
+					prompt: {
+						id: string;
+						name: string;
+						version: number;
+						sections: Array<{ name: string; body: string }>;
+					};
+				};
+				return {
+					success: raw.success,
+					prompt: raw.prompt,
+				};
+			} catch {
+				throw new AgentError(`Failed to parse JSON from cn show ${name}: ${trimmed.slice(0, 200)}`);
+			}
+		},
+	};
+}