feat(workflows): add conditional chained prompts support

- Introduce `selectedConditions` parameter to filter chained prompt paths
- Support conditional path entries in agent configuration
- Refactor chained prompt loading to handle conditional paths

Author: moazbuilds

config/main.agents.js

@@ -81,7 +81,9 @@ module.exports = [
       path.join(promptsDir, 'bmad', '01-analyst', 'workflow.md'),
       path.join(promptsDir, 'bmad', '01-analyst', 'chained', 'step-01-vision.md'),
     ],
-    chainedPromptsPath: path.join(promptsDir, 'bmad', '01-analyst', 'chained'),
+    chainedPromptsPath: [
+      path.join(promptsDir, 'bmad', '01-analyst', 'chained'),
+    ],
   },
 
   // Test agents

src/agents/runner/chained.ts

@@ -2,6 +2,7 @@ import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
 
 import { debug } from '../../shared/logging/logger.js';
+import type { ChainedPathEntry, ConditionalChainedPath } from '../../shared/agents/config/types.js';
 
 /**
  * Represents a chained prompt loaded from a .md file
@@ -87,21 +88,16 @@ function filenameToName(filename: string): string {
 }
 
 /**
- * Load chained prompts from a folder
- * Files are sorted by filename (01-first.md, 02-second.md, etc.)
- *
- * @param chainedPromptsPath - Absolute or relative path to folder containing .md files
- * @param projectRoot - Project root for resolving relative paths
- * @returns Array of ChainedPrompt objects sorted by filename
+ * Load chained prompts from a single folder
  */
-export async function loadChainedPrompts(
-  chainedPromptsPath: string,
+async function loadPromptsFromFolder(
+  folderPath: string,
   projectRoot: string
 ): Promise<ChainedPrompt[]> {
   // Resolve path
-  const absolutePath = path.isAbsolute(chainedPromptsPath)
-    ? chainedPromptsPath
-    : path.resolve(projectRoot, chainedPromptsPath);
+  const absolutePath = path.isAbsolute(folderPath)
+    ? folderPath
+    : path.resolve(projectRoot, folderPath);
 
   // Check if directory exists
   try {
@@ -147,3 +143,60 @@ export async function loadChainedPrompts(
   debug(`Loaded ${prompts.length} chained prompts from ${absolutePath}`);
   return prompts;
 }
+
+/**
+ * Type guard for conditional path entry
+ */
+function isConditionalPath(entry: ChainedPathEntry): entry is ConditionalChainedPath {
+  return typeof entry === 'object' && entry !== null && 'path' in entry;
+}
+
+/**
+ * Check if all conditions are met (AND logic)
+ */
+function meetsConditions(entry: ChainedPathEntry, selectedConditions: string[]): boolean {
+  if (typeof entry === 'string') return true;
+  if (!entry.conditions?.length) return true;
+  return entry.conditions.every(c => selectedConditions.includes(c));
+}
+
+/**
+ * Extract path string from entry
+ */
+function getPath(entry: ChainedPathEntry): string {
+  return typeof entry === 'string' ? entry : entry.path;
+}
+
+/**
+ * Load chained prompts from one or more folders
+ * Files are sorted by filename within each folder (01-first.md, 02-second.md, etc.)
+ * When multiple folders are provided, prompts are loaded in folder order
+ *
+ * @param chainedPromptsPath - Path or array of paths to folder(s) containing .md files
+ * @param projectRoot - Project root for resolving relative paths
+ * @param selectedConditions - User-selected conditions for filtering conditional paths
+ * @returns Array of ChainedPrompt objects sorted by filename within each folder
+ */
+export async function loadChainedPrompts(
+  chainedPromptsPath: ChainedPathEntry | ChainedPathEntry[],
+  projectRoot: string,
+  selectedConditions: string[] = []
+): Promise<ChainedPrompt[]> {
+  const entries = Array.isArray(chainedPromptsPath) ? chainedPromptsPath : [chainedPromptsPath];
+  const allPrompts: ChainedPrompt[] = [];
+
+  for (const entry of entries) {
+    if (!meetsConditions(entry, selectedConditions)) {
+      const pathStr = getPath(entry);
+      const conditions = isConditionalPath(entry) ? entry.conditions : [];
+      debug(`Skipped chained path: ${pathStr} (unmet conditions: ${conditions?.join(', ')})`);
+      continue;
+    }
+
+    const folderPath = getPath(entry);
+    const prompts = await loadPromptsFromFolder(folderPath, projectRoot);
+    allPrompts.push(...prompts);
+  }
+
+  return allPrompts;
+}

src/agents/runner/runner.ts

@@ -135,6 +135,11 @@ export interface ExecuteAgentOptions {
    * Custom prompt for resume (instead of "Continue from where you left off")
    */
   resumePrompt?: string;
+
+  /**
+   * Selected conditions for filtering conditional chained prompt paths
+   */
+  selectedConditions?: string[];
 }
 
 /**
@@ -195,7 +200,7 @@ export async function executeAgent(
   prompt: string,
   options: ExecuteAgentOptions,
 ): Promise<AgentExecutionOutput> {
-  const { workingDir, projectRoot, engine: engineOverride, model: modelOverride, logger, stderrLogger, onTelemetry, abortSignal, timeout, parentId, disableMonitoring, ui, uniqueAgentId, displayPrompt, resumeMonitoringId, resumePrompt } = options;
+  const { workingDir, projectRoot, engine: engineOverride, model: modelOverride, logger, stderrLogger, onTelemetry, abortSignal, timeout, parentId, disableMonitoring, ui, uniqueAgentId, displayPrompt, resumeMonitoringId, resumePrompt, selectedConditions } = options;
 
   // If resuming, look up session info from monitor
   let resumeSessionId: string | undefined;
@@ -416,7 +421,8 @@ export async function executeAgent(
     if (agentConfig.chainedPromptsPath) {
       chainedPrompts = await loadChainedPrompts(
         agentConfig.chainedPromptsPath,
-        projectRoot ?? workingDir
+        projectRoot ?? workingDir,
+        selectedConditions ?? []
       );
       if (chainedPrompts.length > 0) {
         debug(`Loaded ${chainedPrompts.length} chained prompts for agent '${agentId}'`);

src/shared/agents/config/types.ts

@@ -1,10 +1,23 @@
+/**
+ * Conditional chained prompt path entry
+ */
+export type ConditionalChainedPath = {
+  path: string;
+  conditions?: string[];
+};
+
+/**
+ * Single chained prompt path entry - string or conditional object
+ */
+export type ChainedPathEntry = string | ConditionalChainedPath;
+
 export type AgentDefinition = {
   id: string;
   model?: unknown;
   modelReasoningEffort?: unknown;
   model_reasoning_effort?: unknown;
   engine?: string; // Engine to use for this agent (dynamically determined from registry)
-  chainedPromptsPath?: string; // Path to folder containing chained prompt .md files
+  chainedPromptsPath?: ChainedPathEntry | ChainedPathEntry[]; // Path(s) to folder(s) containing chained prompt .md files
   [key: string]: unknown;
 };
 

src/workflows/execution/resume.ts

@@ -41,6 +41,7 @@ interface ExecWithResumeOptions {
   shouldResumeFromPause: boolean;
   stepResumeMonitoringId: number | undefined;
   stepResumePrompt: string | undefined;
+  selectedConditions: string[];
 }
 
 interface ExecWithResumeResult {
@@ -68,6 +69,7 @@ export async function execWithResume(options: ExecWithResumeOptions): Promise<Ex
     shouldResumeFromPause,
     stepResumeMonitoringId,
     stepResumePrompt,
+    selectedConditions,
   } = options;
 
   debug(`[DEBUG workflow] Checking if fallback should execute... notCompletedSteps=${JSON.stringify(notCompletedSteps)}`);
@@ -114,7 +116,8 @@ export async function execWithResume(options: ExecWithResumeOptions): Promise<Ex
     if (agentConfig?.chainedPromptsPath) {
       stepOutput.chainedPrompts = await loadChainedPrompts(
         agentConfig.chainedPromptsPath,
-        cwd
+        cwd,
+        selectedConditions
       );
     }
   } else if (shouldResumeFromSavedSession && stepDataForResume?.monitoringId) {
@@ -139,7 +142,7 @@ export async function execWithResume(options: ExecWithResumeOptions): Promise<Ex
       stepOutput = {
         output: '',
         monitoringId: stepDataForResume.monitoringId,
-        chainedPrompts: await loadChainedPrompts(agentConfig.chainedPromptsPath!, cwd),
+        chainedPrompts: await loadChainedPrompts(agentConfig.chainedPromptsPath!, cwd, selectedConditions),
       };
     } else {
       // No chained prompts - normal resume with re-execution
@@ -154,6 +157,7 @@ export async function execWithResume(options: ExecWithResumeOptions): Promise<Ex
         uniqueAgentId,
         resumeMonitoringId: stepResumeMonitoringId,
         resumePrompt: stepResumePrompt,
+        selectedConditions,
       });
 
       debug(`[DEBUG workflow] executeStep completed. monitoringId=${stepOutput.monitoringId}`);
@@ -184,6 +188,7 @@ export async function execWithResume(options: ExecWithResumeOptions): Promise<Ex
       uniqueAgentId,
       resumeMonitoringId: stepResumeMonitoringId,
       resumePrompt: stepResumePrompt,
+      selectedConditions,
     });
 
     debug(`[DEBUG workflow] executeStep completed. monitoringId=${stepOutput.monitoringId}`);

src/workflows/execution/run.ts

@@ -385,6 +385,7 @@ export async function runWorkflow(options: RunWorkflowOptions = {}): Promise<voi
         shouldResumeFromPause,
         stepResumeMonitoringId,
         stepResumePrompt,
+        selectedConditions,
       });
 
       debug(`[DEBUG workflow] Checking for chained prompts...`);

src/workflows/execution/step.ts

@@ -35,6 +35,8 @@ export interface StepExecutorOptions {
   resumeMonitoringId?: number;
   /** Custom prompt for resume (instead of "Continue from where you left off") */
   resumePrompt?: string;
+  /** Selected conditions for filtering conditional chained prompt paths */
+  selectedConditions?: string[];
 }
 
 async function ensureProjectScaffold(cwd: string): Promise<void> {
@@ -133,6 +135,7 @@ export async function executeStep(
     uniqueAgentId: options.uniqueAgentId,
     resumeMonitoringId: options.resumeMonitoringId,
     resumePrompt: options.resumePrompt,
+    selectedConditions: options.selectedConditions,
     // Pass emitter as UI so runner can register monitoring ID immediately
     ui: options.emitter,
   });