feat(workflows): add specification requirement check and pre-flight validation

moazbuilds · moazbuilds · commit fab7dc5f00a2 · 2026-01-06T19:18:48.000+02:00
- Add `specification` flag to workflow templates to mark workflows requiring specs
- Implement pre-flight checks for specification validation and onboarding needs
- Move specification validation logic to dedicated preflight module
- Update CLI and TUI to use new pre-flight validation flow
diff --git a/src/cli/tui/app-shell.tsx b/src/cli/tui/app-shell.tsx
@@ -24,9 +24,8 @@ import { MonitoringCleanup } from "../../agents/monitoring/index.js"
 import path from "path"
 import { createRequire } from "node:module"
 import { resolvePackageJson } from "../../shared/runtime/root.js"
-import { getSelectedTrack, setSelectedTrack, hasSelectedConditions, setSelectedConditions, getProjectName, setProjectName, getControllerAgents, loadControllerConfig } from "../../shared/workflows/index.js"
-import { loadTemplate } from "../../workflows/templates/loader.js"
-import { getTemplatePathFromTracking } from "../../shared/workflows/template.js"
+import { setSelectedTrack, setSelectedConditions, setProjectName } from "../../shared/workflows/index.js"
+import { checkOnboardingRequired, needsOnboarding } from "../../workflows/preflight.js"
 import type { TracksConfig, ConditionGroup } from "../../workflows/templates/types"
 import type { AgentDefinition } from "../../shared/agents/config/types"
 import type { InitialToast } from "./app"
@@ -168,39 +167,23 @@ export function App(props: { initialToast?: InitialToast }) {
       setDebugLogFile(debugLogPath)
     }
 
-    // Check if tracks/conditions exist and no selection yet
+    // Run pre-flight checks
     try {
-      const templatePath = await getTemplatePathFromTracking(cmRoot)
-      const template = await loadTemplate(cwd, templatePath)
-      const selectedTrack = await getSelectedTrack(cmRoot)
-      const conditionsSelected = await hasSelectedConditions(cmRoot)
-      const existingProjectName = await getProjectName(cmRoot)
-
-      const hasTracks = template.tracks && Object.keys(template.tracks.options).length > 0
-      const hasConditionGroups = template.conditionGroups && template.conditionGroups.length > 0
-      const needsTrackSelection = hasTracks && !selectedTrack
-      const needsConditionsSelection = hasConditionGroups && !conditionsSelected
-      const needsProjectName = !existingProjectName
-
-      // Check if workflow requires controller selection
-      // Skip if controller session already exists
-      let controllers: AgentDefinition[] = []
-      const existingControllerConfig = await loadControllerConfig(cmRoot)
-      const hasExistingControllerSession = existingControllerConfig?.controllerConfig?.sessionId
-      if (template.controller === true && !hasExistingControllerSession) {
-        controllers = await getControllerAgents(cwd)
-      }
-      const needsControllerSelection = controllers.length > 0
+      const onboardingNeeds = await checkOnboardingRequired({ cwd })
+      const { template, controllerAgents } = onboardingNeeds
 
-      // If project name, tracks, conditions, or controller need selection, show onboard view
-      if (needsProjectName || needsTrackSelection || needsConditionsSelection || needsControllerSelection) {
+      // If any onboarding is needed, show onboard view
+      if (needsOnboarding(onboardingNeeds)) {
         debug('[AppShell] Starting onboarding flow')
 
-        // Store config for Onboard component (backward compatibility)
+        const hasTracks = template.tracks && Object.keys(template.tracks.options).length > 0
+        const hasConditionGroups = template.conditionGroups && template.conditionGroups.length > 0
+
+        // Store config for Onboard component
         if (hasTracks) setTemplateTracks(template.tracks!)
         if (hasConditionGroups) setTemplateConditionGroups(template.conditionGroups!)
-        if (needsControllerSelection) setControllerAgents(controllers)
-        setInitialProjectName(existingProjectName)
+        if (onboardingNeeds.needsControllerSelection) setControllerAgents(controllerAgents)
+        setInitialProjectName(null)
 
         // Create event bus and service for onboarding
         const eventBus = new WorkflowEventBus()
@@ -209,8 +192,8 @@ export function App(props: { initialToast?: InitialToast }) {
         const service = new OnboardingService(eventBus, {
           tracks: hasTracks ? template.tracks : undefined,
           conditionGroups: hasConditionGroups ? template.conditionGroups : undefined,
-          controllerAgents: needsControllerSelection ? controllers : undefined,
-          initialProjectName: existingProjectName,
+          controllerAgents: onboardingNeeds.needsControllerSelection ? controllerAgents : undefined,
+          initialProjectName: onboardingNeeds.needsProjectName ? undefined : undefined,
           cwd,
           cmRoot,
         })
@@ -233,12 +216,12 @@ export function App(props: { initialToast?: InitialToast }) {
         return
       }
     } catch (error) {
-      // If template loading fails, proceed to workflow anyway
-      appDebug('[AppShell] Failed to check tracks/conditions: %s', error)
-      console.error("Failed to check tracks/conditions:", error)
+      // If pre-flight check fails, proceed to workflow anyway
+      appDebug('[AppShell] Failed pre-flight check: %s', error)
+      console.error("Failed pre-flight check:", error)
     }
 
-    // No tracks/conditions or already selected - start workflow directly
+    // No onboarding needed - start workflow directly
     appDebug('[AppShell] Starting workflow execution directly')
     startWorkflowExecution()
   }
@@ -257,7 +240,7 @@ export function App(props: { initialToast?: InitialToast }) {
     pendingWorkflowStart = () => {
       appDebug('[AppShell] Importing and running workflow')
       import("../../workflows/run.js").then(({ runWorkflow }) => {
-        runWorkflow({ cwd, specificationPath: specPath }).catch((error) => {
+        runWorkflow({ cwd }).catch((error) => {
           // Emit error event to show toast with actual error message
           const errorMsg = error instanceof Error ? error.message : String(error)
           appDebug('[AppShell] Workflow error: %s', errorMsg)
diff --git a/src/cli/tui/routes/home/hooks/use-home-commands.tsx b/src/cli/tui/routes/home/hooks/use-home-commands.tsx
@@ -11,7 +11,7 @@ import { useDialog } from "@tui/shared/context/dialog"
 import { useSession } from "@tui/shared/context/session"
 import { SelectMenu } from "@tui/shared/components/select-menu"
 import * as path from "node:path"
-import { getAbsoluteSpecPath, HOME_COMMANDS } from "../config/commands"
+import { HOME_COMMANDS } from "../config/commands"
 
 export interface UseHomeCommandsOptions {
   onStartWorkflow?: () => void
@@ -60,11 +60,10 @@ export function useHomeCommands(options: UseHomeCommandsOptions) {
   }
 
   const handleStartCommand = async () => {
-    const specPath = getAbsoluteSpecPath()
-
     try {
-      const { validateSpecification } = await import("../../../../../workflows/run.js")
-      await validateSpecification(specPath)
+      // Pre-flight check - validates specification if required by template
+      const { checkSpecificationRequired } = await import("../../../../../workflows/preflight.js")
+      await checkSpecificationRequired()
     } catch (error) {
       if (error instanceof Error) {
         toast.show({
@@ -78,7 +77,6 @@ export function useHomeCommands(options: UseHomeCommandsOptions) {
 
     if (options.onStartWorkflow) {
       options.onStartWorkflow()
-      return
     }
   }
 
diff --git a/src/runtime/cli-setup.ts b/src/runtime/cli-setup.ts
@@ -120,6 +120,9 @@ export async function runCodemachineCli(argv: string[] = process.argv): Promise<
       // Set CWD immediately (lightweight, no I/O)
       const cwd = options.dir || process.cwd();
       process.env.CODEMACHINE_CWD = cwd;
+      if (options.spec && options.spec !== DEFAULT_SPEC_PATH) {
+        process.env.CODEMACHINE_SPEC_PATH = path.resolve(cwd, options.spec);
+      }
       appDebug('[CLI] CWD set to %s', cwd);
 
       // Start background initialization (non-blocking, fire-and-forget)
diff --git a/src/runtime/services/validation.ts b/src/runtime/services/validation.ts
@@ -1,5 +1,5 @@
 import * as path from 'node:path';
-import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { readFile, writeFile, mkdir, stat } from 'node:fs/promises';
 
 const DEFAULT_SPEC_TEMPLATE = `# Project Specifications
 
@@ -28,24 +28,37 @@ export class ValidationError extends Error {
 
 export async function validateSpecification(specificationPath: string): Promise<void> {
   const absolute = path.resolve(specificationPath);
-  let specificationContents: string;
 
+  // Check if path exists and what type it is
   try {
-    specificationContents = await readFile(absolute, { encoding: 'utf8' });
-  } catch (_error) {
-    // File doesn't exist - create it with default template
-    await mkdir(path.dirname(absolute), { recursive: true });
-    await writeFile(absolute, DEFAULT_SPEC_TEMPLATE, { encoding: 'utf8' });
-
-    const message = `Spec file created. Please write your specs at: ${absolute}`;
-    throw new ValidationError(message, absolute);
+    const stats = await stat(absolute);
+    if (stats.isDirectory()) {
+      throw new ValidationError(`Spec path should be a file, not a directory: ${absolute}`, absolute);
+    }
+  } catch (error) {
+    // Re-throw ValidationError
+    if (error instanceof ValidationError) {
+      throw error;
+    }
+
+    const nodeError = error as NodeJS.ErrnoException;
+    if (nodeError.code === 'ENOENT') {
+      // File doesn't exist - create it with default template
+      await mkdir(path.dirname(absolute), { recursive: true });
+      await writeFile(absolute, DEFAULT_SPEC_TEMPLATE, { encoding: 'utf8' });
+      throw new ValidationError(`Spec file created. Please write your specs at: ${absolute}`, absolute);
+    }
+
+    // Unexpected error - wrap it
+    throw new ValidationError(`Failed to access spec file: ${nodeError.message}`, absolute);
   }
 
+  // File exists and is not a directory - read it
+  const specificationContents = await readFile(absolute, { encoding: 'utf8' });
   const trimmed = specificationContents.trim();
 
   // Check if empty or still has default template content
   if (trimmed.length === 0 || trimmed === DEFAULT_SPEC_TEMPLATE.trim()) {
-    const message = `Spec file is empty. Please write your specs at: ${absolute}`;
-    throw new ValidationError(message, absolute);
+    throw new ValidationError(`Spec file is empty. Please write your specs at: ${absolute}`, absolute);
   }
 }
diff --git a/src/workflows/preflight.ts b/src/workflows/preflight.ts
@@ -0,0 +1,131 @@
+/**
+ * Workflow Pre-flight Checks
+ *
+ * Consolidates all checks that must pass before a workflow can start.
+ * Single source of truth for workflow startup validation.
+ */
+
+import * as path from 'node:path';
+import type { WorkflowTemplate } from './templates/types.js';
+import { loadTemplateWithPath } from './templates/loader.js';
+import { getTemplatePathFromTracking, getSelectedTrack, hasSelectedConditions, getProjectName, loadControllerConfig, getControllerAgents } from '../shared/workflows/index.js';
+import { validateSpecification } from '../runtime/services/index.js';
+import { ensureWorkspaceStructure } from '../runtime/services/workspace/index.js';
+import type { AgentDefinition } from '../shared/agents/config/types.js';
+
+export { ValidationError } from '../runtime/services/index.js';
+
+/**
+ * Onboarding requirements - what the user needs to configure before workflow can start
+ */
+export interface OnboardingNeeds {
+  needsProjectName: boolean;
+  needsTrackSelection: boolean;
+  needsConditionsSelection: boolean;
+  needsControllerSelection: boolean;
+  /** Controller agents available for selection (only populated if needsControllerSelection is true) */
+  controllerAgents: AgentDefinition[];
+  /** The loaded template for reference */
+  template: WorkflowTemplate;
+}
+
+/**
+ * Check what onboarding steps are needed before workflow can start
+ * Does NOT throw - returns the requirements for the UI to handle
+ */
+export async function checkOnboardingRequired(options: { cwd?: string } = {}): Promise<OnboardingNeeds> {
+  const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd();
+  const cmRoot = path.join(cwd, '.codemachine');
+
+  // Ensure workspace structure exists
+  await ensureWorkspaceStructure({ cwd });
+
+  // Load template
+  const templatePath = await getTemplatePathFromTracking(cmRoot);
+  const { template } = await loadTemplateWithPath(cwd, templatePath);
+
+  // Check existing selections
+  const selectedTrack = await getSelectedTrack(cmRoot);
+  const conditionsSelected = await hasSelectedConditions(cmRoot);
+  const existingProjectName = await getProjectName(cmRoot);
+
+  // Determine what's needed
+  const hasTracks = !!(template.tracks && Object.keys(template.tracks.options).length > 0);
+  const hasConditionGroups = !!(template.conditionGroups && template.conditionGroups.length > 0);
+  const needsTrackSelection = hasTracks && !selectedTrack;
+  const needsConditionsSelection = hasConditionGroups && !conditionsSelected;
+  const needsProjectName = !existingProjectName;
+
+  // Check controller requirement
+  let controllerAgents: AgentDefinition[] = [];
+  const existingControllerConfig = await loadControllerConfig(cmRoot);
+  const hasExistingControllerSession = existingControllerConfig?.controllerConfig?.sessionId;
+  if (template.controller === true && !hasExistingControllerSession) {
+    controllerAgents = await getControllerAgents(cwd);
+  }
+  const needsControllerSelection = controllerAgents.length > 0;
+
+  return {
+    needsProjectName,
+    needsTrackSelection,
+    needsConditionsSelection,
+    needsControllerSelection,
+    controllerAgents,
+    template,
+  };
+}
+
+/**
+ * Check if specification file is required and valid
+ * Throws ValidationError if template requires specification but it's missing/empty
+ *
+ * Path can be overridden via:
+ * - CLI: --spec <path>
+ * - Env: CODEMACHINE_SPEC_PATH
+ */
+export async function checkSpecificationRequired(options: { cwd?: string } = {}): Promise<void> {
+  const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd();
+  const cmRoot = path.join(cwd, '.codemachine');
+  const specificationPath = process.env.CODEMACHINE_SPEC_PATH
+    || path.resolve(cwd, '.codemachine', 'inputs', 'specifications.md');
+
+  // Ensure workspace structure exists
+  await ensureWorkspaceStructure({ cwd });
+
+  // Load template to check specification requirement
+  const templatePath = await getTemplatePathFromTracking(cmRoot);
+  const { template } = await loadTemplateWithPath(cwd, templatePath);
+
+  // Validate specification only if template requires it
+  if (template.specification === true) {
+    await validateSpecification(specificationPath);
+  }
+}
+
+/**
+ * Main pre-flight check - verifies workflow can start
+ * Throws ValidationError if workflow cannot start due to missing specification
+ * Returns onboarding needs if user configuration is required
+ */
+export async function checkWorkflowCanStart(options: { cwd?: string } = {}): Promise<OnboardingNeeds> {
+  const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd();
+
+  // First check specification requirement (throws if invalid)
+  await checkSpecificationRequired({ cwd });
+
+  // Then check onboarding requirements (returns needs, doesn't throw)
+  return checkOnboardingRequired({ cwd });
+}
+
+/**
+ * Quick check if any onboarding is needed
+ * Useful for UI to decide whether to show onboarding flow
+ */
+export function needsOnboarding(needs: OnboardingNeeds): boolean {
+  return (
+    needs.needsProjectName ||
+    needs.needsTrackSelection ||
+    needs.needsConditionsSelection ||
+    needs.needsControllerSelection
+  );
+}
diff --git a/src/workflows/run.ts b/src/workflows/run.ts
@@ -21,27 +21,29 @@ import { StepIndexManager } from './indexing/index.js';
 import { registry } from '../infra/engines/index.js';
 import { MonitoringCleanup, AgentMonitorService, StatusService } from '../agents/monitoring/index.js';
 import { WorkflowEventBus, WorkflowEventEmitter } from './events/index.js';
-import { validateSpecification } from '../runtime/services/index.js';
 import { ensureWorkspaceStructure, mirrorSubAgents } from '../runtime/services/workspace/index.js';
 import { WorkflowRunner } from './runner/index.js';
 import { getUniqueAgentId } from './context/index.js';
 import { setupWorkflowMCP, cleanupWorkflowMCP } from './mcp.js';
 
-export { validateSpecification, ValidationError } from '../runtime/services/index.js';
+// Re-export from preflight for backward compatibility
+export { ValidationError, checkWorkflowCanStart, checkSpecificationRequired, checkOnboardingRequired, needsOnboarding } from './preflight.js';
 export type { WorkflowStep, WorkflowTemplate };
 
 /**
- * Run a workflow with validation
+ * Run a workflow
+ * Note: Pre-flight checks (specification validation) should be done via preflight.ts before calling this
  */
 export async function runWorkflow(options: RunWorkflowOptions = {}): Promise<void> {
   const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd();
-  const specificationPath = options.specificationPath || path.resolve(cwd, '.codemachine', 'inputs', 'specifications.md');
 
   // Ensure workspace structure exists (creates .codemachine folder tree)
   await ensureWorkspaceStructure({ cwd });
 
-  // Validate specification
-  await validateSpecification(specificationPath);
+  // Load template
+  const cmRoot = path.join(cwd, '.codemachine');
+  const templatePath = options.templatePath || (await getTemplatePathFromTracking(cmRoot));
+  const { template } = await loadTemplateWithPath(cwd, templatePath);
 
   // Clear screen for TUI
   if (process.stdout.isTTY) {
@@ -58,8 +60,7 @@ export async function runWorkflow(options: RunWorkflowOptions = {}): Promise<voi
   // Set up cleanup handlers
   MonitoringCleanup.setup();
 
-  // Load template (needed before we can set up the before-cleanup handler)
-  const cmRoot = path.join(cwd, '.codemachine');
+  // Initialize index manager for step tracking
   const indexManager = new StepIndexManager(cmRoot);
 
   // Register callback to save session state before cleanup on Ctrl+C
@@ -84,10 +85,6 @@ export async function runWorkflow(options: RunWorkflowOptions = {}): Promise<voi
     },
   });
 
-  // Load template
-  const templatePath = options.templatePath || (await getTemplatePathFromTracking(cmRoot));
-  const { template } = await loadTemplateWithPath(cwd, templatePath);
-
   debug('[Workflow] Using template: %s', template.name);
 
   // Mirror sub-agents if template has subAgentIds
diff --git a/src/workflows/templates/types.ts b/src/workflows/templates/types.ts
diff --git a/templates/workflows/bmad.workflow.js b/templates/workflows/bmad.workflow.js
diff --git a/templates/workflows/codemachine-one.workflow.js b/templates/workflows/codemachine-one.workflow.js
