@oisincoveney/pipeline 1.10.2 → 1.10.3

package/README.md

@@ -72,10 +72,17 @@ Inspect the execution plan before running:
 pipe explain-plan
 ```
 
-Run the default workflow:
+Generate the default schedule artifact:
 
 ```shell
-pipe run "Implement PIPE-123 user-facing behavior"
+pipe "Implement PIPE-123 user-facing behavior"
+```
+
+This writes `.pipeline/runs/<runId>/schedule.yaml` and stops for approval. Run
+the approved artifact explicitly:
+
+```shell
+pipe run --schedule .pipeline/runs/<runId>/schedule.yaml "Implement PIPE-123 user-facing behavior"
 ```
 
 Run a read-only repository inspection:
@@ -96,9 +103,9 @@ Run an epic drain workflow:
 pipe epic PIPE-31
 ```
 
-The `epic` entrypoint routes an epic's child tickets into fixed specialist
-tracks, runs those tracks in parallel, merges passing branches, and then runs a
-thermo-nuclear code quality review.
+The `epic` entrypoint generates a specialized schedule for the epic, writes the
+schedule artifact, and stops. Execution uses the same `pipe run --schedule`
+approval boundary as `pipe`.
 
 The `pipe` binary also accepts the task directly:
 
@@ -201,8 +208,9 @@ workflows:
 ```
 
 Projects can also declare `entrypoints` in `.pipeline/pipeline.yaml` to expose
-stable app or CLI names that resolve to workflows. Direct `--workflow` selection
-remains available and takes precedence over `--entrypoint` when both are set.
+stable app or CLI names that resolve to workflows or schedule policies. Direct
+`--workflow` selection remains available and takes precedence over `--entrypoint`
+when both are set.
 
 The default scaffold includes a full research, red, green, verify, learn
 workflow. See `docs/config-architecture.md` for a complete example and the host
@@ -347,7 +355,7 @@ runners:
 
 ## App-Facing API
 
-External apps can import the stable config, planner, and runtime surfaces
+External apps can import the stable config, planner, schedule, and runtime surfaces
 without deep-importing private source paths:
 
 ```ts
@@ -356,6 +364,10 @@ import {
   parsePipelineConfigParts,
 } from "@oisincoveney/pipeline/config";
 import { compileWorkflowPlan } from "@oisincoveney/pipeline/planner";
+import {
+  compileScheduleArtifact,
+  parseScheduleArtifact,
+} from "@oisincoveney/pipeline/schedule";
 import {
   runPipelineFromConfig,
   type PipelineRuntimeResult,

package/dist/config.d.ts

@@ -8,6 +8,7 @@ declare const RUNNER_TYPES: readonly ["codex", "opencode", "command"];
 declare const NODE_KINDS: readonly ["agent", "command", "builtin", "group", "parallel", "workflow"];
 declare const HOOK_EVENTS: readonly ["workflow.start", "workflow.success", "workflow.failure", "workflow.complete", "node.start", "node.success", "node.error", "gate.failure"];
 declare const GATE_KINDS: readonly ["acceptance", "artifact", "builtin", "changed_files", "command", "json_schema", "verdict"];
+declare const SCHEDULE_BASELINES: readonly ["epic", "pipe"];
 type PipelineConfigErrorCode = "PIPELINE_CONFIG_LEGACY_UNSUPPORTED" | "PIPELINE_CONFIG_MISSING" | "PIPELINE_CONFIG_PARSE_ERROR" | "PIPELINE_CONFIG_VALIDATION_ERROR";
 interface PipelineConfigIssue {
   message: string;
@@ -129,15 +130,31 @@ type ChildWorkflowNode = WorkflowNodeBase & {
   worktree_root?: string;
 };
 type WorkflowNode = AgentWorkflowNode | CommandWorkflowNode | BuiltinWorkflowNode | GroupWorkflowNode | ParallelWorkflowNode | ChildWorkflowNode;
+declare const workflowSchema: z.ZodObject<{
+  description: z.ZodOptional<z.ZodString>;
+  execution: z.ZodOptional<z.ZodObject<{
+    fail_fast: z.ZodOptional<z.ZodBoolean>;
+    max_parallel_nodes: z.ZodOptional<z.ZodNumber>;
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+  }, z.core.$strict>>;
+  hooks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  nodes: z.ZodArray<z.ZodType<WorkflowNode, unknown, z.core.$ZodTypeInternals<WorkflowNode, unknown>>>;
+}, z.core.$strict>;
 declare const configSchema: z.ZodObject<{
   default_workflow: z.ZodString;
-  entrypoints: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+  entrypoints: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
     description: z.ZodOptional<z.ZodString>;
     task_context: z.ZodOptional<z.ZodObject<{
       type: z.ZodString;
     }, z.core.$loose>>;
     workflow: z.ZodString;
-  }, z.core.$strict>>>;
+  }, z.core.$strict>, z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    task_context: z.ZodOptional<z.ZodObject<{
+      type: z.ZodString;
+    }, z.core.$loose>>;
+    schedule: z.ZodString;
+  }, z.core.$strict>]>>>;
   hooks: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
     builtin: z.ZodOptional<z.ZodString>;
     command: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -205,10 +222,10 @@ declare const configSchema: z.ZodObject<{
     }, z.core.$strict>>;
     output: z.ZodOptional<z.ZodObject<{
       format: z.ZodEnum<{
+        json_schema: "json_schema";
         text: "text";
         json: "json";
         jsonl: "jsonl";
-        json_schema: "json_schema";
       }>;
       repair: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodOptional<z.ZodBoolean>;
@@ -221,6 +238,7 @@ declare const configSchema: z.ZodObject<{
     runner: z.ZodString;
     skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
     tools: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+      task: "task";
       read: "read";
       list: "list";
       grep: "grep";
@@ -228,7 +246,6 @@ declare const configSchema: z.ZodObject<{
       bash: "bash";
       edit: "edit";
       write: "write";
-      task: "task";
     }>>>;
   }, z.core.$strict>>>;
   rules: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
@@ -248,14 +265,15 @@ declare const configSchema: z.ZodObject<{
         disabled: "disabled";
       }>>>;
       output_formats: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        json_schema: "json_schema";
         text: "text";
         json: "json";
         jsonl: "jsonl";
-        json_schema: "json_schema";
       }>>>;
       rules: z.ZodOptional<z.ZodBoolean>;
       skills: z.ZodOptional<z.ZodBoolean>;
       tools: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        task: "task";
         read: "read";
         list: "list";
         grep: "grep";
@@ -263,7 +281,6 @@ declare const configSchema: z.ZodObject<{
         bash: "bash";
         edit: "edit";
         write: "write";
-        task: "task";
       }>>>;
     }, z.core.$strict>;
     command: z.ZodOptional<z.ZodString>;
@@ -275,6 +292,15 @@ declare const configSchema: z.ZodObject<{
       opencode: "opencode";
     }>;
   }, z.core.$strict>>>;
+  schedules: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    baseline: z.ZodEnum<{
+      pipe: "pipe";
+      epic: "epic";
+    }>;
+    max_parallel_nodes: z.ZodOptional<z.ZodNumber>;
+    planner_profile: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>>>;
   skills: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
     path: z.ZodString;
   }, z.core.$strict>>>;
@@ -298,6 +324,7 @@ type RunnerType = (typeof RUNNER_TYPES)[number];
 type WorkflowNodeKind = (typeof NODE_KINDS)[number];
 type HookEvent = (typeof HOOK_EVENTS)[number];
 type GateKind = (typeof GATE_KINDS)[number];
+type ScheduleBaseline = (typeof SCHEDULE_BASELINES)[number];
 interface PipelineConfigParts {
   pipeline: string;
   profiles: string;
@@ -310,6 +337,6 @@ declare function loadPipelineConfig(projectRoot: string, options?: PipelineConfi
 declare function tryLoadPipelineConfig(projectRoot: string, options?: PipelineConfigValidationOptions): PipelineConfig | null;
 declare function parsePipelineConfigYaml(source: string, sourcePath?: string, projectRoot?: string): PipelineConfig;
 declare function parsePipelineConfigParts(sources: PipelineConfigParts, projectRoot?: string, sourcePaths?: PipelineConfigParts, options?: PipelineConfigValidationOptions): PipelineConfig;
-declare function validatePipelineConfig(config: PipelineConfig, projectRoot?: string, options?: PipelineConfigValidationOptions): PipelineConfig;
+declare function validatePipelineConfig(rawConfig: PipelineConfig, projectRoot?: string, options?: PipelineConfigValidationOptions): PipelineConfig;
 //#endregion
-export { GateKind, HookEvent, PIPELINE_CONFIG_PATH, PROFILES_CONFIG_PATH, PipelineConfig, PipelineConfigError, PipelineConfigErrorCode, PipelineConfigIssue, PipelineConfigParts, PipelineConfigValidationOptions, RUNNERS_CONFIG_PATH, RunnerType, WorkflowNodeKind, loadPipelineConfig, parsePipelineConfigParts, parsePipelineConfigYaml, tryLoadPipelineConfig, validatePipelineConfig };
+export { GateKind, HookEvent, PIPELINE_CONFIG_PATH, PROFILES_CONFIG_PATH, PipelineConfig, PipelineConfigError, PipelineConfigErrorCode, PipelineConfigIssue, PipelineConfigParts, PipelineConfigValidationOptions, RUNNERS_CONFIG_PATH, RunnerType, ScheduleBaseline, WorkflowNodeKind, loadPipelineConfig, parsePipelineConfigParts, parsePipelineConfigYaml, tryLoadPipelineConfig, validatePipelineConfig, workflowSchema };

package/dist/config.js

@@ -54,6 +54,7 @@ const RETRY_REASONS = [
 	"gate_failure",
 	"timeout"
 ];
+const SCHEDULE_BASELINES = ["epic", "pipe"];
 var PipelineConfigError = class extends Error {
 	code;
 	issues;
@@ -258,10 +259,16 @@ const hookSchema = z.object({
 	trusted: z.boolean().optional()
 }).strict();
 const taskContextResolverSchema = z.object({ type: z.string().min(1) }).passthrough();
-const entrypointSchema = z.object({
+const entrypointBaseSchema = z.object({
 	description: z.string().optional(),
-	task_context: taskContextResolverSchema.optional(),
-	workflow: z.string()
+	task_context: taskContextResolverSchema.optional()
+});
+const entrypointSchema = z.union([entrypointBaseSchema.extend({ workflow: z.string() }).strict(), entrypointBaseSchema.extend({ schedule: z.string() }).strict()]);
+const schedulePolicySchema = z.object({
+	description: z.string().optional(),
+	baseline: z.enum(SCHEDULE_BASELINES),
+	max_parallel_nodes: z.number().int().positive().optional(),
+	planner_profile: z.string().optional()
 }).strict();
 const workflowNodeBaseSchema = z.object({
 	artifacts: z.array(artifactSchema).optional(),
@@ -321,11 +328,12 @@ const pipelineFileSchema = z.object({
 	entrypoints: strictRecord(entrypointSchema).default({}),
 	hooks: strictRecord(hookSchema).default({}),
 	orchestrator: orchestratorSchema,
+	schedules: strictRecord(schedulePolicySchema).default({}),
 	task_context: taskContextResolverSchema.optional(),
 	workflows: strictRecord(workflowSchema).default({}),
 	version: z.literal(1)
 }).strict();
-z.object({
+const configSchema = z.object({
 	default_workflow: z.string(),
 	entrypoints: strictRecord(entrypointSchema).default({}),
 	hooks: strictRecord(hookSchema).default({}),
@@ -334,11 +342,70 @@ z.object({
 	profiles: strictRecord(profileSchema).default({}),
 	rules: strictRecord(pathRefSchema).default({}),
 	runners: strictRecord(runnerSchema).default({}),
+	schedules: strictRecord(schedulePolicySchema).default({}),
 	skills: strictRecord(pathRefSchema).default({}),
 	task_context: taskContextResolverSchema.optional(),
 	version: z.literal(1),
 	workflows: strictRecord(workflowSchema).default({})
-}).strict();
+}).strict().superRefine(validateConfigReferences);
+function validateConfigReferences(config, ctx) {
+	addConfigSchemaIssues(ctx, configReferenceIssues(config));
+}
+function configReferenceIssues(config) {
+	return [
+		...missingRegistryReferenceIssue({
+			message: (_field, value) => `default workflow '${value}' is not declared`,
+			path: ["default_workflow"],
+			registry: config.workflows,
+			value: config.default_workflow
+		}),
+		...registryReferenceIssues("entrypoints", config.entrypoints, [{
+			field: "workflow",
+			message: (entrypointId, value) => `entrypoint '${entrypointId}' references missing workflow '${value}'`,
+			read: (entrypoint) => "workflow" in entrypoint ? entrypoint.workflow : void 0,
+			registry: config.workflows
+		}, {
+			field: "schedule",
+			message: (entrypointId, value) => `entrypoint '${entrypointId}' references missing schedule '${value}'`,
+			read: (entrypoint) => "schedule" in entrypoint ? entrypoint.schedule : void 0,
+			registry: config.schedules
+		}]),
+		...registryReferenceIssues("schedules", config.schedules, [{
+			field: "planner_profile",
+			message: (scheduleId, value) => `schedule '${scheduleId}' references missing planner profile '${value}'`,
+			read: (schedule) => schedule.planner_profile,
+			registry: config.profiles
+		}])
+	];
+}
+function registryReferenceIssues(registryPath, records, rules) {
+	return Object.entries(records).flatMap(([recordId, record]) => rules.flatMap((rule) => missingRegistryReferenceIssue({
+		message: (_field, value) => rule.message(recordId, value),
+		path: [
+			registryPath,
+			recordId,
+			rule.field
+		],
+		registry: rule.registry,
+		value: rule.read(record)
+	})));
+}
+function missingRegistryReferenceIssue({ message, path, registry, value }) {
+	return value && !Object.hasOwn(registry, value) ? [{
+		message: message(String(path.at(-1)), value),
+		path
+	}] : [];
+}
+function addConfigSchemaIssues(ctx, issues) {
+	for (const issue of issues) addConfigSchemaIssue(ctx, issue.path, issue.message);
+}
+function addConfigSchemaIssue(ctx, path, message) {
+	ctx.addIssue({
+		code: "custom",
+		path,
+		message
+	});
+}
 function loadPipelineConfig(projectRoot, options = {}) {
 	const missing = [
 		PIPELINE_CONFIG_PATH,
@@ -397,6 +464,7 @@ function parsePipelineConfigParts(sources, projectRoot, sourcePaths = {
 		profiles: profiles.profiles,
 		rules: profiles.rules,
 		runners: runners.runners,
+		schedules: pipeline.schedules,
 		skills: profiles.skills,
 		...pipeline.task_context ? { task_context: pipeline.task_context } : {},
 		version: 1,
@@ -474,7 +542,13 @@ function normalizeMcpJsonServer(server) {
 		...server.bearer_token_env_var ? { bearer_token_env_var: server.bearer_token_env_var } : {}
 	};
 }
-function validatePipelineConfig(config, projectRoot, options = {}) {
+function validatePipelineConfig(rawConfig, projectRoot, options = {}) {
+	const parsed = configSchema.safeParse(rawConfig);
+	if (!parsed.success) throw validationError(parsed.error.issues.map((issue) => ({
+		path: issue.path.join("."),
+		message: issue.message
+	})));
+	const config = parsed.data;
 	const issues = [];
 	validateRegistryIds("runners", config.runners, issues);
 	validateRegistryIds("profiles", config.profiles, issues);
@@ -484,14 +558,6 @@ function validatePipelineConfig(config, projectRoot, options = {}) {
 	validateRegistryIds("hooks", config.hooks, issues);
 	validateRegistryIds("workflows", config.workflows, issues);
 	validateRegistryIds("entrypoints", config.entrypoints, issues);
-	if (!config.workflows[config.default_workflow]) issues.push({
-		path: "default_workflow",
-		message: `default workflow '${config.default_workflow}' is not declared`
-	});
-	for (const [entrypointId, entrypoint] of Object.entries(config.entrypoints)) if (!config.workflows[entrypoint.workflow]) issues.push({
-		path: `entrypoints.${entrypointId}.workflow`,
-		message: `entrypoint '${entrypointId}' references missing workflow '${entrypoint.workflow}'`
-	});
 	if (config.profiles[config.orchestrator.profile]) validateReferences("orchestrator.hooks", config.orchestrator.hooks, config.hooks, "hook", issues);
 	else issues.push({
 		path: "orchestrator.profile",
@@ -672,4 +738,4 @@ function validationError(issues) {
 	return new PipelineConfigError("PIPELINE_CONFIG_VALIDATION_ERROR", ["Invalid pipeline config:", ...issues.map((issue) => issue.path ? `- ${issue.path}: ${issue.message}` : `- ${issue.message}`)].join("\n"), issues);
 }
 //#endregion
-export { PIPELINE_CONFIG_PATH, PROFILES_CONFIG_PATH, PipelineConfigError, RUNNERS_CONFIG_PATH, loadPipelineConfig, parsePipelineConfigParts, parsePipelineConfigYaml, tryLoadPipelineConfig, validatePipelineConfig };
+export { PIPELINE_CONFIG_PATH, PROFILES_CONFIG_PATH, PipelineConfigError, RUNNERS_CONFIG_PATH, loadPipelineConfig, parsePipelineConfigParts, parsePipelineConfigYaml, tryLoadPipelineConfig, validatePipelineConfig, workflowSchema };

package/dist/index.d.ts

@@ -5,6 +5,7 @@ import { Command } from "commander";
 interface PipeOptions {
   entrypoint?: string;
   pipelineRunner?: typeof runPipelineFromConfig;
+  schedule?: string;
   workflow?: string;
 }
 /**

package/dist/index.js

@@ -7,7 +7,8 @@ import { formatConfigError, runPipelineFromConfig } from "./pipeline-runtime.js"
 import { runKubernetesRunnerJob } from "./kubernetes-runner.js";
 import { DEFAULT_MCPM_ARGS } from "./mcp/bootstrap.js";
 import { formatPipelineInitResult, initPipelineProject } from "./pipeline-init.js";
-import { existsSync, realpathSync } from "node:fs";
+import { compileScheduleArtifact, generateScheduleArtifact, parseScheduleArtifact } from "./schedule-planner.js";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command, CommanderError, Help, Option } from "commander";
@@ -26,6 +27,7 @@ function pipe(description, options = {}) {
 		return runConfiguredPipeline({
 			pipelineRunner: options.pipelineRunner ?? runPipelineFromConfig,
 			entrypoint: options.entrypoint,
+			schedule: options.schedule,
 			task: description,
 			workflow: options.workflow,
 			worktreePath
@@ -35,7 +37,35 @@ function pipe(description, options = {}) {
 	}
 }
 async function runConfiguredPipeline(inputs) {
+	const config = loadPipelineConfig(inputs.worktreePath, { allowMissingLintFileReferences: true });
+	if (inputs.schedule) {
+		const compiled = compileScheduleArtifact(config, parseScheduleArtifact(readFileSync(inputs.schedule, "utf8"), inputs.schedule), inputs.worktreePath);
+		await runAndPrintPipeline({
+			...inputs,
+			config: compiled.config,
+			workflow: compiled.workflowId
+		});
+		return;
+	}
+	const scheduledEntrypoint = scheduledEntrypointId(config, inputs.workflow, inputs.entrypoint);
+	if (scheduledEntrypoint) {
+		const result = await generateScheduleArtifact({
+			config,
+			entrypointId: scheduledEntrypoint,
+			task: inputs.task,
+			worktreePath: inputs.worktreePath
+		});
+		console.log([`Schedule generated: ${result.path}`, `Run after approval: pipe run --schedule ${result.path}`].join("\n"));
+		return;
+	}
+	await runAndPrintPipeline({
+		...inputs,
+		config
+	});
+}
+async function runAndPrintPipeline(inputs) {
 	const result = await (inputs.pipelineRunner ?? runPipelineFromConfig)({
+		config: inputs.config,
 		reporter: formatRuntimeProgress,
 		entrypoint: inputs.entrypoint,
 		task: inputs.task,
@@ -45,6 +75,12 @@ async function runConfiguredPipeline(inputs) {
 	console.log(formatRuntimeResult(result));
 	if (result.outcome !== "PASS") throw new Error(formatRuntimeFailure(result));
 }
+function scheduledEntrypointId(config, workflowId, entrypointId) {
+	if (workflowId) return null;
+	const id = entrypointId ?? "pipe";
+	const entrypoint = config.entrypoints[id];
+	return entrypoint && "schedule" in entrypoint ? id : null;
+}
 function formatRuntimeProgress(event) {
 	const message = formatRuntimeProgressMessage(event);
 	console.error(message);
@@ -164,24 +200,25 @@ function createCliProgram() {
 	const runAction = async (descriptionParts, flags) => {
 		await pipe(descriptionParts.join(" "), {
 			entrypoint: flags.entrypoint,
+			schedule: flags.schedule,
 			workflow: flags.workflow
 		});
 	};
-	program.command("run").description("Run a workflow from .pipeline/pipeline.yaml").argument("<description...>", "task description").option("--entrypoint <entrypoint>", "entrypoint alias from pipeline.yaml").option("--workflow <workflow>", "workflow id from pipeline.yaml").action(runAction);
-	program.command("pipe").description("Alias for run").argument("<description...>", "task description").option("--entrypoint <entrypoint>", "entrypoint alias from pipeline.yaml").option("--workflow <workflow>", "workflow id from pipeline.yaml").action(runAction);
-	program.command("validate").description("Validate .pipeline/pipeline.yaml and compile the workflow plan").option("--entrypoint <entrypoint>", "entrypoint alias from pipeline.yaml").option("--strict", "fail when validation lint warnings are emitted").option("--no-lint", "skip validation lint warnings").option("--workflow <workflow>", "workflow id from pipeline.yaml").action((flags) => {
+	program.command("run").description("Run a workflow from .pipeline/pipeline.yaml").argument("<description...>", "task description").option("--entrypoint <entrypoint>", "entrypoint alias from pipeline.yaml").option("--schedule <schedule>", "approved schedule YAML to execute").option("--workflow <workflow>", "workflow id from pipeline.yaml").action(runAction);
+	program.command("pipe").description("Alias for run").argument("<description...>", "task description").option("--entrypoint <entrypoint>", "entrypoint alias from pipeline.yaml").option("--schedule <schedule>", "approved schedule YAML to execute").option("--workflow <workflow>", "workflow id from pipeline.yaml").action(runAction);
+	program.command("validate").description("Validate .pipeline/pipeline.yaml and compile the workflow plan").option("--entrypoint <entrypoint>", "entrypoint alias from pipeline.yaml").option("--schedule <schedule>", "approved schedule YAML to validate").option("--strict", "fail when validation lint warnings are emitted").option("--no-lint", "skip validation lint warnings").option("--workflow <workflow>", "workflow id from pipeline.yaml").action((flags) => {
 		const cwd = process.env.PIPELINE_TARGET_PATH ?? process.cwd();
 		const config = loadPipelineConfig(cwd, { allowMissingLintFileReferences: true });
-		const plan = compileWorkflowPlan(config, resolveWorkflowSelection(config, flags.workflow, flags.entrypoint));
+		const plan = flags.schedule ? compileScheduleArtifact(config, parseScheduleArtifact(readFileSync(flags.schedule, "utf8"), flags.schedule), cwd).plan : compileWorkflowPlan(config, resolveWorkflowSelection(config, flags.workflow, flags.entrypoint));
 		const warnings = flags.lint === false ? [] : lintPipelineConfig(config, cwd);
 		for (const warning of warnings) console.error(formatConfigLintWarning(warning));
 		if (flags.strict && warnings.length > 0) throw new Error(`Validation failed with ${warnings.length} warning${warnings.length === 1 ? "" : "s"}.`);
 		console.log(`OK: ${plan.workflowId} (${plan.topologicalOrder.length} nodes)`);
 	});
-	program.command("explain-plan").description("Explain workflow nodes, runners, gates, hooks, and artifacts").option("--entrypoint <entrypoint>", "entrypoint alias from pipeline.yaml").option("--workflow <workflow>", "workflow id from pipeline.yaml").action((flags) => {
+	program.command("explain-plan").description("Explain workflow nodes, runners, gates, hooks, and artifacts").option("--entrypoint <entrypoint>", "entrypoint alias from pipeline.yaml").option("--schedule <schedule>", "approved schedule YAML to explain").option("--workflow <workflow>", "workflow id from pipeline.yaml").action((flags) => {
 		const cwd = process.env.PIPELINE_TARGET_PATH ?? process.cwd();
 		const config = loadPipelineConfig(cwd, { allowMissingLintFileReferences: true });
-		console.log(formatWorkflowPlan(config, cwd, resolveWorkflowSelection(config, flags.workflow, flags.entrypoint)));
+		console.log(formatSelectedWorkflowPlan(config, cwd, flags));
 	});
 	program.command("doctor").description("Check local prerequisites for pipeline init and execution").action(async () => {
 		const result = await runDoctor(process.env.PIPELINE_TARGET_PATH ?? process.cwd());
@@ -414,7 +451,16 @@ function hasExitCode(err) {
 	return err instanceof Error && "exitCode" in err && typeof err.exitCode === "number";
 }
 function formatWorkflowPlan(config, worktreePath, workflowId) {
-	const plan = compileWorkflowPlan(config, workflowId);
+	return formatCompiledWorkflowPlan(config, worktreePath, compileWorkflowPlan(config, workflowId));
+}
+function formatSelectedWorkflowPlan(config, worktreePath, flags) {
+	if (flags.schedule) {
+		const compiled = compileScheduleArtifact(config, parseScheduleArtifact(readFileSync(flags.schedule, "utf8"), flags.schedule), worktreePath);
+		return formatCompiledWorkflowPlan(compiled.config, worktreePath, compiled.plan);
+	}
+	return formatWorkflowPlan(config, worktreePath, resolveWorkflowSelection(config, flags.workflow, flags.entrypoint));
+}
+function formatCompiledWorkflowPlan(config, worktreePath, plan) {
 	const workflow = config.workflows[plan.workflowId];
 	const lines = [`Workflow: ${plan.workflowId}`];
 	lines.push(formatOrchestratorPlan(config, worktreePath));
@@ -449,6 +495,7 @@ function resolveWorkflowSelection(config, workflowId, entrypointId) {
 	if (!entrypointId) return;
 	const entrypoint = config.entrypoints[entrypointId];
 	if (!entrypoint) throw new Error(`Unknown pipeline entrypoint '${entrypointId}'`);
+	if ("schedule" in entrypoint) throw new Error(`Pipeline entrypoint '${entrypointId}' generates schedule '${entrypoint.schedule}'; use the entrypoint to create a schedule, then run with --schedule.`);
 	return entrypoint.workflow;
 }
 function formatOrchestratorPlan(config, worktreePath) {

package/dist/install-commands.js

@@ -169,6 +169,15 @@ function dispatchBlock(host, config, workflowId = config.default_workflow) {
 		hostSpecificDispatchGuard(host, nativeRoutes, cliRoutes)
 	].filter((line) => Boolean(line)).join("\n");
 }
+function entrypointDispatchBlock(host, config, id, entrypoint) {
+	if ("workflow" in entrypoint) return dispatchBlock(host, config, entrypoint.workflow);
+	return [
+		`Generate a schedule for entrypoint \`${id}\` and the user task.`,
+		`The schedule policy is \`${entrypoint.schedule}\`.`,
+		`Run \`pipe run --entrypoint ${id} <task description>\` to write the schedule artifact, then stop for approval.`,
+		"Do not execute workflow nodes until the user runs `pipe run --schedule <schedule.yaml>`."
+	].join("\n");
+}
 function nativeDispatchBlock(host, routes) {
 	if (routes.length === 0) return;
 	return [
@@ -265,7 +274,7 @@ function opencodeDefinitions(config) {
 				"",
 				orchestratorBlock(config),
 				"",
-				dispatchBlock("opencode", config, entrypoint.workflow)
+				entrypointDispatchBlock("opencode", config, id, entrypoint)
 			]).join("\n")),
 			host: "opencode",
 			invocation: invocationForHost("opencode", id),
@@ -323,7 +332,7 @@ function codexDefinitions(config, cwd) {
 				"",
 				orchestratorBlock(config),
 				"",
-				dispatchBlock("codex", config, entrypoint.workflow)
+				entrypointDispatchBlock("codex", config, id, entrypoint)
 			]).join("\n")),
 			host: "codex",
 			invocation: invocationForHost("codex", id),
@@ -342,7 +351,7 @@ function codexDefinitions(config, cwd) {
 				"",
 				orchestratorBlock(config),
 				"",
-				dispatchBlock("codex", config, entrypoint.workflow)
+				entrypointDispatchBlock("codex", config, id, entrypoint)
 			]).join("\n")),
 			host: "codex",
 			invocation: codexPluginInvocation(id),

package/dist/mcp/launch-plan.js

@@ -1,4 +1,4 @@
-import { mkdtempSync, writeFileSync } from "node:fs";
+import { mkdtempSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 //#region src/mcp/launch-plan.ts
@@ -23,14 +23,22 @@ function mcpArgsFor(runnerType, servers, hasPipelineConfig) {
 	return [];
 }
 function mcpEnvFor(input, servers) {
-	const declaredServers = input.config?.mcp_servers ?? {};
-	if (input.runnerType !== "opencode" || Object.keys(servers).length === 0 && Object.keys(declaredServers).length === 0) return {};
-	const config = toOpenCodeMcpConfig(servers, declaredServers);
-	const path = join(mkdtempSync(join(tmpdir(), "pipeline-opencode-mcp-")), `${input.nodeId}.json`);
-	writeFileSync(path, JSON.stringify(config));
+	if (input.runnerType !== "opencode" || !input.config) return {};
+	const config = toOpenCodeMcpConfig(servers);
+	const dir = mkdtempSync(join(tmpdir(), "pipeline-opencode-runtime-"));
 	return {
-		OPENCODE_CONFIG: path,
-		PIPELINE_WORKTREE: input.worktreePath
+		OPENCODE_AUTH_CONTENT: void 0,
+		OPENCODE_CONFIG: void 0,
+		OPENCODE_CONFIG_CONTENT: JSON.stringify(config),
+		OPENCODE_CONFIG_DIR: void 0,
+		OPENCODE_DISABLE_PROJECT_CONFIG: "1",
+		OPENCODE_TEST_HOME: join(dir, "home"),
+		PIPELINE_OPENCODE_RUNTIME_DIR: dir,
+		PIPELINE_WORKTREE: input.worktreePath,
+		XDG_CACHE_HOME: join(dir, "cache"),
+		XDG_CONFIG_HOME: join(dir, "config"),
+		XDG_DATA_HOME: join(dir, "data"),
+		XDG_STATE_HOME: join(dir, "state")
 	};
 }
 function isRemoteMcpServer(server) {
@@ -41,10 +49,10 @@ function headersWithBearerTokenEnv(server, renderTokenRef) {
 	if (server.bearer_token_env_var) headers.Authorization = `Bearer ${renderTokenRef(server.bearer_token_env_var)}`;
 	return Object.keys(headers).length > 0 ? headers : void 0;
 }
-function toOpenCodeMcpConfig(selectedServers, declaredServers) {
-	return { mcp: {
-		...Object.fromEntries(Object.keys(declaredServers).filter((id) => !selectedServers[id]).map((id) => [id, { enabled: false }])),
-		...Object.fromEntries(Object.entries(selectedServers).map(([id, server]) => {
+function toOpenCodeMcpConfig(selectedServers) {
+	return {
+		$schema: "https://opencode.ai/config.json",
+		mcp: { ...Object.fromEntries(Object.entries(selectedServers).map(([id, server]) => {
 			if (isRemoteMcpServer(server)) {
 				const headers = headersWithBearerTokenEnv(server, (envVar) => `{env:${envVar}}`);
 				return [id, {
@@ -60,8 +68,8 @@ function toOpenCodeMcpConfig(selectedServers, declaredServers) {
 				...server.env ? { environment: server.env } : {},
 				type: "local"
 			}];
-		}))
-	} };
+		})) }
+	};
 }
 function codexMcpArgs(servers) {
 	return Object.entries(servers).flatMap(([id, server]) => {

package/dist/pipeline-init.js

@@ -23,13 +23,13 @@ default_workflow: default
 
 entrypoints:
   pipe:
-    workflow: default
+    schedule: pipe-schedule
     description: Full pipeline
   inspect:
     workflow: inspect
     description: Read-only repository inspection
   epic:
-    workflow: epic-drain
+    schedule: epic-schedule
     description: Route an epic's tickets into specialist tracks, run them in parallel, then thermo-nuclear review.
 
 orchestrator:
@@ -60,6 +60,14 @@ hooks:
     timeout_ms: 5000
     output_limit_bytes: 4096
 
+schedules:
+  pipe-schedule:
+    baseline: pipe
+    planner_profile: pipeline-schedule-planner
+  epic-schedule:
+    baseline: epic
+    planner_profile: pipeline-schedule-planner
+
 workflows:
   inspect:
     description: Read-only repository inspection workflow.
@@ -410,6 +418,22 @@ profiles:
       mode: inherit
     output:
       format: text
+  pipeline-schedule-planner:
+    runner: codex
+    description: Refine a baseline schedule into a specialized approved-plan artifact.
+    instructions:
+      path: .pipeline/prompts/schedule-planner.md
+    skills: [research, scope]
+    mcp_servers: [serena, context7, backlog, qdrant, github-readonly]
+    tools: [read, list, grep, glob, bash]
+    filesystem:
+      mode: read-only
+      allow: ["**/*"]
+      deny: ["node_modules/**", "dist/**", ".git/**"]
+    network:
+      mode: inherit
+    output:
+      format: text
   pipeline-test-writer:
     runner: codex
     description: Add focused failing tests for the requested behavior.
@@ -638,6 +662,18 @@ const SCAFFOLD_FILES = {
 		"Do not modify files.",
 		""
 	].join("\n"),
+	".pipeline/prompts/schedule-planner.md": [
+		"# Schedule planner",
+		"",
+		"Refine the provided baseline into a specialized `pipeline-schedule` YAML artifact for the user task.",
+		"",
+		"Keep the graph auditable: every workflow must be embedded in the artifact, every `kind: workflow` reference must point to an embedded workflow, and execution must include research, implementation, and verification.",
+		"",
+		"Use parallel branches only when they reduce coordination risk. Preserve configured profile ids, gates, hooks, retries, artifacts, and worktree policy unless the task clearly needs a different valid graph.",
+		"",
+		"Return only YAML. Do not wrap it in Markdown fences. Do not modify files. Do not invoke other agents.",
+		""
+	].join("\n"),
 	".pipeline/prompts/test-writer.md": [
 		"You are the RED/test-write phase for the pipeline.",
 		"Add focused failing tests for the requested behavior only.",

package/dist/pipeline-runtime.js

@@ -293,6 +293,7 @@ function resolveWorkflowSelection(config, workflowId, entrypointId) {
 	if (!entrypointId) return;
 	const entrypoint = config.entrypoints[entrypointId];
 	if (!entrypoint) throw new Error(`Unknown pipeline entrypoint '${entrypointId}'`);
+	if ("schedule" in entrypoint) throw new Error(`Pipeline entrypoint '${entrypointId}' generates schedule '${entrypoint.schedule}'; run an approved schedule artifact instead.`);
 	return entrypoint.workflow;
 }
 function failedRuntimeResult(context, nodes, failure) {