feat: add first-class workflow profiles

Author: RogerNavelsaker

README.md

@@ -84,18 +84,19 @@ 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`, `--profile`, `--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`, `--workflow`, `--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 spec write <task-id>` | Write a task specification (`--body`, `--workflow`, `--openspec`) |
 | `ov discover` | Discover a brownfield codebase via coordinator-driven scout swarm (`--skip`, `--name`, `--attach`, `--watchdog`, `--json`) |
+| `ov workflow start <workflow>` | Start the coordinator in `delivery` or `co-creation` mode |
 | `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`, `--profile`) |
+| `ov coordinator start` | Start persistent coordinator agent (`--attach`/`--no-attach`, `--watchdog`, `--monitor`, `--profile`, `--workflow`) |
 | `ov coordinator stop` | Stop coordinator |
 | `ov coordinator status` | Show coordinator state |
 | `ov coordinator send` | Fire-and-forget message to coordinator (`--subject`) |

agents/ov-co-creation.md

@@ -37,6 +37,8 @@ Decision artifacts come before code. Deliverables in order:
 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.
 
+When the project uses OpenSpec, place durable co-creation artifacts under `openspec/changes/<task-id>/`. Overstory's co-creation workflow writes task specs to `openspec/changes/<task-id>/tasks.md` by default; keep option memos, ADRs, and milestone notes alongside that change set.
+
 Do not write implementation code before decisions are resolved. The human reviews and approves decision documents; implementation follows approval.
 
 ## completion-criteria

agents/ov-delivery.md

@@ -0,0 +1,49 @@
+---
+name: ov-delivery
+description: Default delivery workflow profile — autonomous, hands-off execution
+---
+
+## propulsion-principle
+
+Read your assignment. Execute immediately. Do not ask for confirmation, do not propose a plan and wait for approval, do not summarize back what you were told. Start working within your first tool calls. The human gave you work because they want it done, not discussed. Assess the task, choose the right approach, and begin. If you need to explore first, explore. If you can implement directly, implement. Action is the default — hesitation is the exception.
+
+## escalation-policy
+
+Handle routine decisions autonomously. You have the context, the tools, and the expertise to make implementation choices without checking in. Escalate only when:
+
+- The task is genuinely ambiguous and multiple valid interpretations would lead to significantly different outcomes.
+- You discover a risk that could cause data loss, security issues, or breaking changes beyond your scope.
+- You are blocked by a dependency outside your control.
+- The scope of work has grown significantly beyond what was originally described.
+
+Do not escalate for: naming choices, implementation approach within spec, test strategy, file organization, or any decision you can make and verify yourself. When you do escalate, be specific: state what you found, what the options are, and what you recommend.
+
+## artifact-expectations
+
+Your primary deliverable is working software. Every task completion should include:
+
+- **Code**: Clean, tested implementation that follows project conventions.
+- **Tests**: Automated tests that verify the new behavior.
+- **Quality gates**: All lints, type checks, and tests must pass before you report completion.
+
+Documentation updates are expected only when the change affects public APIs, configuration, or user-facing behavior.
+
+## completion-criteria
+
+Work is complete when all of the following are true:
+
+- All quality gates pass.
+- 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.
+
+Do not declare completion prematurely. Run the quality gates yourself — do not assume they pass.
+
+## human-role
+
+The human operates in a hands-off mode. They provide objectives and review results — they do not micromanage execution.
+
+- **No real-time supervision.** Make decisions and proceed.
+- **Post-completion review.** The human reviews diffs, test results, and summaries after you report done.
+- **Minimal interaction.** Questions to the human should be rare and high-signal.
+- **Trust in autonomy.** The human chose automated delivery because they trust the system to execute.

src/commands/completions.test.ts

@@ -12,8 +12,8 @@ import {
 } from "./completions.ts";
 
 describe("COMMANDS array", () => {
-	it("should have exactly 33 commands", () => {
-		expect(COMMANDS).toHaveLength(33);
+	it("should have exactly 34 commands", () => {
+		expect(COMMANDS).toHaveLength(34);
 	});
 
 	it("should include all expected command names", () => {
@@ -38,6 +38,7 @@ describe("COMMANDS array", () => {
 		expect(names).toContain("metrics");
 		expect(names).toContain("spec");
 		expect(names).toContain("coordinator");
+		expect(names).toContain("workflow");
 		expect(names).toContain("supervisor");
 		expect(names).toContain("hooks");
 		expect(names).toContain("monitor");
@@ -62,7 +63,7 @@ describe("generateBash", () => {
 		expect(script).toContain("_init_completion");
 	});
 
-	it("should include all 33 command names", () => {
+	it("should include all 34 command names", () => {
 		const script = generateBash();
 		for (const cmd of COMMANDS) {
 			expect(script).toContain(cmd.name);
@@ -96,7 +97,7 @@ describe("generateZsh", () => {
 		expect(script).toContain("_arguments");
 	});
 
-	it("should include all 33 command names", () => {
+	it("should include all 34 command names", () => {
 		const script = generateZsh();
 		for (const cmd of COMMANDS) {
 			expect(script).toContain(cmd.name);
@@ -126,7 +127,7 @@ describe("generateFish", () => {
 		expect(script).toContain("__fish_use_subcommand");
 	});
 
-	it("should include all 33 command names", () => {
+	it("should include all 34 command names", () => {
 		const script = generateFish();
 		for (const cmd of COMMANDS) {
 			expect(script).toContain(cmd.name);

src/commands/completions.ts

@@ -92,6 +92,12 @@ export const COMMANDS: readonly CommandDef[] = [
 			{ name: "--max-agents", desc: "Max children per lead", takesValue: true },
 			{ name: "--dispatch-max-agents", desc: "Per-lead max agents ceiling", takesValue: true },
 			{ name: "--runtime", desc: "Runtime adapter", takesValue: true },
+			{
+				name: "--workflow",
+				desc: "Workflow profile alias",
+				takesValue: true,
+				values: ["delivery", "co-creation"],
+			},
 			{ name: "--json", desc: "JSON output" },
 			{ name: "--help", desc: "Show help" },
 		],
@@ -338,6 +344,13 @@ export const COMMANDS: readonly CommandDef[] = [
 				flags: [
 					{ name: "--body", desc: "Spec content", takesValue: true },
 					{ name: "--agent", desc: "Agent attribution", takesValue: true },
+					{
+						name: "--workflow",
+						desc: "Workflow profile alias",
+						takesValue: true,
+						values: ["delivery", "co-creation"],
+					},
+					{ name: "--openspec", desc: "Write to openspec tasks.md" },
 					{ name: "--help", desc: "Show help" },
 				],
 			},
@@ -358,6 +371,13 @@ export const COMMANDS: readonly CommandDef[] = [
 					{ name: "--attach", desc: "Attach to tmux session" },
 					{ name: "--no-attach", desc: "Do not attach to tmux session" },
 					{ name: "--watchdog", desc: "Auto-start watchdog daemon" },
+					{ name: "--monitor", desc: "Auto-start Tier 2 monitor agent" },
+					{
+						name: "--workflow",
+						desc: "Workflow profile alias",
+						takesValue: true,
+						values: ["delivery", "co-creation"],
+					},
 					{ name: "--json", desc: "JSON output" },
 				],
 			},
@@ -373,6 +393,24 @@ export const COMMANDS: readonly CommandDef[] = [
 			},
 		],
 	},
+	{
+		name: "workflow",
+		desc: "Start a coordinator in a workflow mode",
+		flags: [{ name: "--help", desc: "Show help" }],
+		subcommands: [
+			{
+				name: "start",
+				desc: "Start workflow-mode coordination",
+				flags: [
+					{ name: "--attach", desc: "Attach to tmux session" },
+					{ name: "--no-attach", desc: "Do not attach to tmux session" },
+					{ name: "--watchdog", desc: "Auto-start watchdog daemon" },
+					{ name: "--monitor", desc: "Auto-start Tier 2 monitor agent" },
+					{ name: "--json", desc: "JSON output" },
+				],
+			},
+		],
+	},
 	{
 		name: "supervisor",
 		desc: "[DEPRECATED] Per-project supervisor agent",

src/commands/coordinator.test.ts

@@ -534,6 +534,22 @@ describe("startCoordinator", () => {
 		expect(session?.runId).toBe(fileRunId);
 	});
 
+	test("maps --workflow co-creation to OVERSTORY_PROFILE env", async () => {
+		const { deps, calls } = makeDeps();
+		const originalSleep = Bun.sleep;
+		Bun.sleep = (() => Promise.resolve()) as typeof Bun.sleep;
+
+		try {
+			await captureStdout(() =>
+				coordinatorCommand(["start", "--workflow", "co-creation", "--no-attach"], deps),
+			);
+		} finally {
+			Bun.sleep = originalSleep;
+		}
+
+		expect(calls.createSession[0]?.env?.OVERSTORY_PROFILE).toBe("ov-co-creation");
+	});
+
 	test("deploys hooks to project root .claude/settings.local.json", async () => {
 		const { deps } = makeDeps();
 		const originalSleep = Bun.sleep;
@@ -1527,6 +1543,18 @@ describe("watchdog integration", () => {
 			expect(output).toContain("--watchdog");
 			expect(output).toContain("watchdog");
 		});
+
+		test("start help text includes --workflow flag", async () => {
+			const cmd = createCoordinatorCommand({});
+			for (const sub of cmd.commands) {
+				sub.exitOverride();
+			}
+			const output = await captureStdout(async () => {
+				await cmd.parseAsync(["start", "--help"], { from: "user" }).catch(() => {});
+			});
+			expect(output).toContain("--workflow");
+			expect(output).toContain("co-creation");
+		});
 	});
 });
 

src/commands/coordinator.ts

@@ -29,6 +29,7 @@ import { createRunStore, createSessionStore } from "../sessions/store.ts";
 import { resolveBackend, trackerCliName } from "../tracker/factory.ts";
 import type { AgentSession } from "../types.ts";
 import { isProcessRunning } from "../watchdog/health.ts";
+import { resolveProfileName } from "../workflow.ts";
 import type { SessionState } from "../worktree/tmux.ts";
 import {
 	capturePaneContent,
@@ -300,6 +301,7 @@ export interface CoordinatorSessionOptions {
 	watchdog: boolean;
 	monitor: boolean;
 	profile?: string;
+	workflow?: string;
 	/** Override coordinator name (default: "coordinator"). */
 	coordinatorName?: string;
 	/** Custom beacon builder. Receives tracker CLI name, returns beacon string. */
@@ -331,12 +333,14 @@ export async function startCoordinatorSession(
 		watchdog: watchdogFlag,
 		monitor: monitorFlag,
 		profile: profileFlag,
+		workflow: workflowFlag,
 		coordinatorName: coordinatorNameOpt,
 		beaconBuilder: beaconBuilderOpt,
 	} = opts;
 
 	const coordinatorName = coordinatorNameOpt ?? COORDINATOR_NAME;
 	const beaconBuilder = beaconBuilderOpt ?? buildCoordinatorBeacon;
+	const effectiveProfile = resolveProfileName(profileFlag ?? workflowFlag);
 
 	if (isRunningAsRoot()) {
 		throw new AgentError(
@@ -449,13 +453,13 @@ export async function startCoordinatorSession(
 			env: {
 				...runtime.buildEnv(resolvedModel),
 				OVERSTORY_AGENT_NAME: coordinatorName,
-				...(profileFlag ? { OVERSTORY_PROFILE: profileFlag } : {}),
+				...(effectiveProfile ? { OVERSTORY_PROFILE: effectiveProfile } : {}),
 			},
 		});
 		const pid = await tmux.createSession(tmuxSession, projectRoot, spawnCmd, {
 			...runtime.buildEnv(resolvedModel),
 			OVERSTORY_AGENT_NAME: coordinatorName,
-			...(profileFlag ? { OVERSTORY_PROFILE: profileFlag } : {}),
+			...(effectiveProfile ? { OVERSTORY_PROFILE: effectiveProfile } : {}),
 		});
 
 		// Create a run for this coordinator session BEFORE recording the session,
@@ -606,8 +610,15 @@ export async function startCoordinatorSession(
 	}
 }
 
-async function startCoordinator(
-	opts: { json: boolean; attach: boolean; watchdog: boolean; monitor: boolean; profile?: string },
+export async function startCoordinator(
+	opts: {
+		json: boolean;
+		attach: boolean;
+		watchdog: boolean;
+		monitor: boolean;
+		profile?: string;
+		workflow?: string;
+	},
 	deps: CoordinatorDeps = {},
 ): Promise<void> {
 	await startCoordinatorSession(
@@ -1304,6 +1315,7 @@ export function createCoordinatorCommand(deps: CoordinatorDeps = {}): Command {
 		.option("--watchdog", "Auto-start watchdog daemon with coordinator")
 		.option("--monitor", "Auto-start Tier 2 monitor agent with coordinator")
 		.option("--profile <name>", "Canopy profile to apply to spawned agents")
+		.option("--workflow <name>", "Workflow profile alias: delivery or co-creation")
 		.option("--json", "Output as JSON")
 		.action(
 			async (opts: {
@@ -1312,6 +1324,7 @@ export function createCoordinatorCommand(deps: CoordinatorDeps = {}): Command {
 				monitor?: boolean;
 				json?: boolean;
 				profile?: string;
+				workflow?: string;
 			}) => {
 				// opts.attach = true if --attach, false if --no-attach, undefined if neither
 				const shouldAttach = opts.attach !== undefined ? opts.attach : !!process.stdout.isTTY;
@@ -1322,6 +1335,7 @@ export function createCoordinatorCommand(deps: CoordinatorDeps = {}): Command {
 						watchdog: opts.watchdog ?? false,
 						monitor: opts.monitor ?? false,
 						profile: opts.profile,
+						workflow: opts.workflow,
 					},
 					deps,
 				);

src/commands/discover.ts

@@ -165,6 +165,7 @@ export async function discoverCommand(
 			watchdog: opts.watchdog ?? false,
 			monitor: false,
 			profile: "ov-discovery",
+			workflow: undefined,
 			coordinatorName,
 			beaconBuilder: (_trackerCli) => buildDiscoveryBeacon(categories, coordinatorName),
 		},

src/commands/sling.ts

@@ -39,6 +39,12 @@ import { createRunStore } from "../sessions/store.ts";
 import type { TrackerIssue } from "../tracker/factory.ts";
 import { createTrackerClient, resolveBackend, trackerCliName } from "../tracker/factory.ts";
 import type { AgentSession, OverlayConfig } from "../types.ts";
+import {
+	normalizeWorkflowName,
+	repoRootFromCommandDir,
+	resolveProfileName,
+	workflowPromptPath,
+} from "../workflow.ts";
 import { createWorktree, rollbackWorktree } from "../worktree/manager.ts";
 import { spawnHeadlessAgent } from "../worktree/process.ts";
 import {
@@ -155,6 +161,7 @@ export interface SlingOptions {
 	noScoutCheck?: boolean;
 	baseBranch?: string;
 	profile?: string;
+	workflow?: string;
 }
 
 export interface AutoDispatchOptions {
@@ -471,6 +478,7 @@ export async function getCurrentBranch(repoRoot: string): Promise<string | null>
  * @param opts - Command options
  */
 export async function slingCommand(taskId: string, opts: SlingOptions): Promise<void> {
+	const overstoryRepoRoot = repoRootFromCommandDir(import.meta.dir);
 	if (!taskId) {
 		throw new ValidationError("Task ID is required: ov sling <task-id>", {
 			field: "taskId",
@@ -787,8 +795,12 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 			}
 
 			// 8b. Resolve canopy profile if specified
-			const profileName =
-				opts.profile ?? process.env.OVERSTORY_PROFILE ?? config.project.defaultProfile;
+			const profileName = resolveProfileName(
+				opts.profile ??
+					opts.workflow ??
+					process.env.OVERSTORY_PROFILE ??
+					config.project.defaultProfile,
+			);
 			let profileContent: string | undefined;
 			if (profileName) {
 				try {
@@ -798,8 +810,16 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 						profileContent = rendered.sections.map((s) => s.body).join("\n\n");
 					}
 				} catch {
-					// Non-fatal: canopy may not be installed or profile may not exist
-					profileContent = undefined;
+					// Fallback to emitted prompt files so first-class workflows still work
+					// when cn is unavailable locally.
+					const workflow = normalizeWorkflowName(profileName);
+					if (workflow) {
+						const fallbackPath = workflowPromptPath(overstoryRepoRoot, workflow);
+						const fallbackFile = Bun.file(fallbackPath);
+						if (await fallbackFile.exists()) {
+							profileContent = await fallbackFile.text();
+						}
+					}
 				}
 			}