feat(core): add workflow orchestration module for multi-agent execution by Pedrovaleriolopez · Pull Request #39 · SynkraAI/aiox-core

Pedrovaleriolopez · 2026-01-13T21:19:23Z

Summary

Add comprehensive workflow orchestration system that enables:

Real subagent dispatch with persona transformation
Task-based execution (loads real .md task files, not generic prompts)
Deterministic code operations (mkdir, file validation via JavaScript)
Checklist-based quality validation
Parallel phase execution for independent workflow phases
Context persistence between workflow phases

New Files

File	Purpose
`workflow-orchestrator.js`	Main orchestrator with phase execution
`subagent-prompt-builder.js`	Loads agent definitions, tasks, checklists, templates
`context-manager.js`	Persists workflow state between phases
`checklist-runner.js`	Programmatic checklist validation
`parallel-executor.js`	Concurrent phase execution
`index.js`	Module exports

CodeRabbit Fixes Applied

All critical issues from CodeRabbit review have been addressed:

Round 1 (commit `63639d9`)

Add passedCount/failedCount tracking in checklist-runner
Fix validation to fail on missing files
Unknown validation rules now fail with warning
Fix loadState() to persist initial state
Implement deep copy in exportState/importState
Add block scoping to switch cases
Convert _projectHasDatabase to async

Round 2 (commit `b408dec`)

Fix directory-exists validation consistency
Add null guard to exportState()
Unknown pre/post action types now fail-fast
resumeFrom() honors parallel_phases config

Round 3 (commit `2300a13`)

Guard reset() against undefined metadata
Fix race condition in parallel execution (thread-safe checklist handling)

Test Plan

ESLint: 0 errors
Orchestration tests: 19/19 passed
Full test suite: 2676 passed

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

New Features

Workflow execution system supporting multi-phase processes with persistent state tracking
Automated validation checklist framework for quality verification
Parallel task execution to improve workflow efficiency
Intelligent task orchestration with contextual guidance

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Add comprehensive workflow orchestration system that enables: - Real subagent dispatch with persona transformation - Task-based execution (loads real .md task files, not generic prompts) - Deterministic code operations (mkdir, file validation via JavaScript) - Checklist-based quality validation - Parallel phase execution for independent workflow phases - Context persistence between workflow phases New files: - workflow-orchestrator.js: Main orchestrator with phase execution - subagent-prompt-builder.js: Loads agent definitions, tasks, checklists, templates - context-manager.js: Persists workflow state between phases - checklist-runner.js: Programmatic checklist validation - parallel-executor.js: Concurrent phase execution - index.js: Module exports This module improves the brownfield-discovery workflow by: 1. Using REAL task files instead of generating generic prompts 2. Running pre/post actions via deterministic JavaScript code 3. Validating outputs with existing checklists 4. Supporting parallel execution of independent phases (1-3) Co-Authored-By: Claude <noreply@anthropic.com>

## Checklist Runner (checklist-runner.js) - Add passedCount/failedCount tracking for visibility - Fix validation to fail on missing files (not empty, contains, min-size) - Change unknown validation rules to fail with warning instead of passing - Improve duplicate detection to use full string comparison - Add YAML parse error warnings ## Context Manager (context-manager.js) - Fix loadState() to persist initial state to disk - Implement deep copy in exportState() and importState() ## Workflow Orchestrator (workflow-orchestrator.js) - Add block scoping to switch cases in _executePreAction - Add block scoping to switch cases in _executePostAction - Convert _projectHasDatabase to async with fs.pathExists/readFile - Make _evaluateCondition async to support file system checks - Remove unused ParallelExecutor instantiation - Fix linting warnings (quotes, trailing commas, unused params) ## Subagent Prompt Builder (subagent-prompt-builder.js) - Add console.warn for YAML parse errors in checklist extraction - Add console.warn for YAML parse errors in template extraction - Document asterisk stripping convention in task references Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

…H-1] ## Checklist Runner (checklist-runner.js) - Fix directory-exists validation to mirror file-exists logic - Use explicit continue for falsy targetPath - Use fs.pathExists() before fs.stat() for consistency ## Context Manager (context-manager.js) - Add null guard to exportState() - returns {} if state not loaded ## Workflow Orchestrator (workflow-orchestrator.js) - Unknown pre-action types now return { success: false } (fail-fast) - Unknown post-action types now return { success: false } (consistent) - resumeFrom() now honors parallel_phases configuration - resumeFrom() resets executionState.startTime for accurate timing Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Address final 2 CodeRabbit critical issues: - context-manager.js: Guard reset() against undefined metadata with fallback to empty object when state not yet loaded - workflow-orchestrator.js: Fix race condition by threading checklist through prepResult instead of shared instance field Also includes ESLint auto-fix for trailing commas. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

coderabbitai · 2026-01-13T21:19:34Z

Note

`.coderabbit.yaml` has unrecognized properties

CodeRabbit is using all valid settings from your configuration. Unrecognized properties (listed below) have been ignored and may indicate typos or deprecated fields that can be removed.

⚠️ Parsing warnings (1)

Validation error: Unrecognized key(s) in object: 'tools', 'abort_on_close'

⚙️ Configuration instructions

Please see the configuration documentation for more information.
You can also validate your configuration using the online YAML validator.
If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Walkthrough

Introduces a comprehensive orchestration framework for multi-agent workflows consisting of five new modules: WorkflowOrchestrator manages phase execution with subagent integration, ContextManager persists workflow state, ChecklistRunner validates outputs, SubagentPromptBuilder constructs task-specific prompts, and ParallelExecutor handles concurrent phase execution. An index module re-exports these components and provides factory functions.

Changes

Cohort / File(s)	Summary
Core Orchestration Engine `.aios-core/core/orchestration/workflow-orchestrator.js`, `.aios-core/core/orchestration/parallel-executor.js`	WorkflowOrchestrator (728 lines) loads YAML workflows, manages phase execution with pre/post-action hooks, integrates subagent dispatch callbacks, and tracks execution state. ParallelExecutor (225 lines) manages concurrent phase execution with configurable concurrency limits, task tracking, and status reporting.
State & Context Management `.aios-core/core/orchestration/context-manager.js`	ContextManager (294 lines) persists workflow execution state to `.aios/workflow-state/{workflowId}.json` with in-memory caching, provides phase output retrieval, lifecycle state updates (markCompleted, markFailed), and context assembly for subagent prompts.
Validation & Prompt Building `.aios-core/core/orchestration/checklist-runner.js`, `.aios-core/core/orchestration/subagent-prompt-builder.js`	ChecklistRunner (350 lines) executes validation checklists from Markdown/YAML, parses and normalizes items, evaluates against target paths using code-based rules, and handles blocker items. SubagentPromptBuilder (363 lines) assembles complete task-specific prompts by combining agent definitions, task definitions, loaded checklists/templates, and prior phase context.
Public API & Exports `.aios-core/core/orchestration/index.js`	Centralizes exports of WorkflowOrchestrator, ContextManager, ChecklistRunner, ParallelExecutor, and SubagentPromptBuilder; provides factory functions `createOrchestrator()`, `createContextManager()`, and `runChecklist()` for streamlined instantiation.

Sequence Diagram

sequenceDiagram
    actor User
    participant WO as WorkflowOrchestrator
    participant PE as ParallelExecutor
    participant CM as ContextManager
    participant SPB as SubagentPromptBuilder
    participant Subagent as Subagent<br/>(via callback)
    participant CR as ChecklistRunner

    User->>WO: run(workflow)
    WO->>WO: loadWorkflow()
    WO->>CM: initialize()
    CM-->>WO: state
    WO->>WO: groupPhases()
    loop For each phase group
        WO->>WO: _executePreAction()
        alt Parallel phases
            WO->>PE: executeParallel(phases)
            PE->>PE: _executeWithConcurrencyLimit()
            loop For each phase
                PE->>SPB: buildPrompt()
                SPB-->>PE: prompt
                PE->>Subagent: dispatchSubagent(prompt)
                Subagent-->>PE: result
                PE->>CM: savePhaseOutput()
            end
            PE-->>WO: results
        else Sequential phases
            WO->>SPB: buildPrompt()
            SPB-->>WO: prompt
            WO->>Subagent: dispatchSubagent(prompt)
            Subagent-->>WO: result
            WO->>CM: savePhaseOutput()
        end
        WO->>WO: _executePostAction()
        WO->>CR: run(checklist)
        CR-->>WO: validation result
    end
    WO->>CM: markCompleted()
    WO-->>User: workflow result

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Suggested labels

core, workflows, agents, tools

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(core): add workflow orchestration module for multi-agent execution' clearly and specifically describes the main addition—a workflow orchestration module for multi-agent execution—which aligns with the primary changeset introducing WorkflowOrchestrator and supporting classes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

📝 Generate docstrings

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

github-actions · 2026-01-13T21:20:26Z

📊 Coverage Report

Coverage report not available

📈 Full coverage report available in Codecov

Generated by PR Automation (Story 6.1)

coderabbitai

Actionable comments posted: 4

🤖 Fix all issues with AI agents

In @.aios-core/core/orchestration/context-manager.js:
- Around line 1-294: Add unit tests for the ContextManager class to raise
.aios-core/core/ coverage above 60% by exercising lifecycle and edge cases: test
initialize() and loadState() create and return the initial state and persist it
to disk, savePhaseOutput(phaseNum, output) persists phase outputs and updates
currentPhase/status and isPhaseCompleted(phaseNum) reflects completion,
getContextForPhase(phaseNum) returns previousPhases correctly,
updateMetadata(metadata) merges metadata, markCompleted() and markFailed(error,
failedPhase) set status/completedAt/failedAt and error fields,
reset(keepMetadata) resets state while preserving or clearing metadata as
expected, and importState()/exportState() perform deep copy behavior; use
temporary filesystem fixtures (mock or tmp dirs) to avoid touching real
projectRoot and assert on file contents and JSON read/write to cover persistence
code paths.
- Around line 28-38: The constructor currently uses the raw workflowId to build
this.stateDir and this.statePath, allowing path traversal; in the constructor of
context-manager.js sanitize workflowId before using it by (a) normalizing to a
safe token: take only a validated basename (e.g., safeId =
path.basename(workflowId || '')) and enforce a whitelist regex like
/^[A-Za-z0-9._-]+$/; (b) if the whitelist check fails or result is empty,
replace with a deterministic safe fallback such as a hash (e.g.,
crypto.createHash('sha256').update(workflowId || '').digest('hex')); then use
that sanitized token when setting this.statePath and this.stateDir to ensure no
directory traversal (update references to workflowId -> safeId in the
constructor and any code that builds paths).

In @.aios-core/core/orchestration/parallel-executor.js:
- Around line 37-60: The concurrency limiter is broken because phases.map(async
...) starts all executions immediately; instead change the mapping to produce
thunks (functions) like () => executePhaseThunk(phase) that when invoked will
set this.runningTasks (use phaseId and startTime inside the thunk), call
executePhase(phase), and resolve/reject with the same result shape, and pass
that array of thunks to _executeWithConcurrencyLimit; then update
_executeWithConcurrencyLimit to expect and invoke each thunk (e.g., await
thunk()) rather than awaiting already-started promises so the maxConcurrency
limit is honored.

In @.aios-core/core/orchestration/workflow-orchestrator.js:
- Around line 268-271: The catch block that logs checklistRunner.run() errors
currently swallows failures; update the catch to record the error into the
validation object (e.g., push a descriptive error into validation.errors) or
rethrow the error so validation fails; specifically modify the try/catch around
checklistRunner.run() in the workflow-orchestrator to either add
validation.errors.push({ message: `Checklist error: ${error.message}`, error })
or throw error after logging so upstream validation observes the failure.

🧹 Nitpick comments (8)

.aios-core/core/orchestration/parallel-executor.js (1)
192-222: getSummary does not count cancelled tasks.

The switch statement handles completed, failed, and running, but cancelled tasks (set by cancelAll()) are silently ignored. Consider adding a cancelled counter for completeness.
♻️ Suggested enhancement
  getSummary() {
    let completed = 0;
    let failed = 0;
    let running = 0;
+   let cancelled = 0;
    let totalDuration = 0;

    for (const [, status] of this.runningTasks) {
      switch (status.status) {
        case 'completed':
          completed++;
          if (status.startTime && status.endTime) {
            totalDuration += status.endTime - status.startTime;
          }
          break;
        case 'failed':
          failed++;
          break;
        case 'running':
          running++;
          break;
+       case 'cancelled':
+         cancelled++;
+         break;
      }
    }

    return {
      total: this.runningTasks.size,
      completed,
      failed,
      running,
+     cancelled,
      averageDuration: completed > 0 ? Math.round(totalDuration / completed) : 0,
    };
  }
.aios-core/core/orchestration/subagent-prompt-builder.js (1)
318-326: Template content is always wrapped in a YAML code block.

Templates loaded from .md files will still be wrapped in ```yaml fences (line 324), which could be misleading. Consider detecting the file extension and using appropriate formatting.
♻️ Suggested enhancement

Track the file type when loading templates and format accordingly:
  // In loadTemplate method, return object with content and type
  async loadTemplate(templateName) {
    const extensions = ['.yaml', '.yml', '.md'];
    const baseName = templateName.replace(/\.(yaml|yml|md)$/, '');

    for (const ext of extensions) {
      const filePath = path.join(this.paths.templates, `${baseName}${ext}`);
      if (await fs.pathExists(filePath)) {
-       return await fs.readFile(filePath, 'utf8');
+       return {
+         content: await fs.readFile(filePath, 'utf8'),
+         type: ext === '.md' ? 'markdown' : 'yaml',
+       };
      }
    }

    return null;
  }
Then adjust the assembly:
  for (const template of templates) {
    prompt += `### ${template.name}\n\n`;
-   prompt += `\`\`\`yaml\n${template.content}\n\`\`\`\n\n`;
+   const fence = template.type === 'markdown' ? '' : 'yaml';
+   prompt += `\`\`\`${fence}\n${template.content}\n\`\`\`\n\n`;
  }
.aios-core/core/orchestration/checklist-runner.js (2)
60-75: Non-blocker failures don't affect overall passed status.

Currently, result.passed only becomes false when a blocker item fails (line 71). Non-blocker failures are counted in failedCount but don't mark the overall result as failed. This appears intentional, but consider documenting this behavior in the JSDoc or adding a passedWithWarnings status.

216-322: Validation rule matching relies on substring checks, which can be fragile.

Rules like validationLower.includes('file') && validationLower.includes('exist') could match unintended strings (e.g., "profile exists in database"). Consider using more structured rule definitions or stricter regex patterns for reliability.
♻️ Suggested approach

Consider a more explicit rule format:
// Instead of free-form strings, define structured rules:
// validation: { rule: 'file_exists' }
// validation: { rule: 'contains', value: 'some text' }
// validation: { rule: 'min_size', bytes: 1024 }

async executeValidation(validation, targetPaths) {
  // Support both string (legacy) and object (structured) formats
  if (typeof validation === 'object') {
    return this._executeStructuredValidation(validation, targetPaths);
  }
  // Fall back to current string-based matching
  return this._executeStringValidation(validation, targetPaths);
}
This provides a migration path while maintaining backward compatibility.
.aios-core/core/orchestration/workflow-orchestrator.js (1)
94-115: Directory list is hardcoded.

The directory structure is specific to a particular workflow type. Consider making this configurable via the workflow YAML or constructor options for reusability.
♻️ Suggested enhancement
  async setupDirectories() {
-   const dirs = [
-     'docs/architecture',
-     'docs/frontend',
-     // ... hardcoded list
-   ];
+   // Allow workflow to define required directories, with sensible defaults
+   const defaultDirs = ['.aios/workflow-state'];
+   const workflowDirs = this.workflow?.setup?.directories || [];
+   const dirs = [...new Set([...defaultDirs, ...workflowDirs])];
.aios-core/core/orchestration/context-manager.js (3)
88-103: Duplicate state initialization logic.

The loadState method (lines 98-102) duplicates the "create initial state if not exists" pattern from initialize() (lines 57-59). This violates DRY and could lead to inconsistencies if one path is updated but not the other.
♻️ Proposed refactor: Delegate to initialize()
  async loadState() {
    if (this._stateCache) {
      return this._stateCache;
    }

-   if (await fs.pathExists(this.statePath)) {
-     this._stateCache = await fs.readJson(this.statePath);
-     return this._stateCache;
-   }
-
-   // No state file exists - create, cache, and persist initial state
-   await this.ensureStateDir();
-   this._stateCache = this._createInitialState();
-   await fs.writeJson(this.statePath, this._stateCache, { spaces: 2 });
-   return this._stateCache;
+   // Delegate to initialize() which handles both cases
+   return this.initialize();
  }
165-180: Synchronous accessors depend on cache being loaded.

getPreviousPhaseOutputs() and getPhaseOutput() return empty/null if called before initialize() or loadState(). This is handled gracefully with null guards, but callers should be aware of this precondition.

Consider adding a brief note to the JSDoc indicating the cache-dependent behavior, or alternatively making these async with automatic cache loading.

288-291: Consider validating imported state structure.

importState accepts any object without validating required fields (workflowId, status, phases, etc.). Importing malformed state could cause runtime errors in subsequent operations.
♻️ Proposed fix: Add basic validation
  async importState(state) {
+   if (!state || typeof state !== 'object') {
+     throw new Error('Invalid state: must be an object');
+   }
+   if (!state.workflowId || !state.status || !state.phases) {
+     throw new Error('Invalid state: missing required fields (workflowId, status, phases)');
+   }
    this._stateCache = JSON.parse(JSON.stringify(state));
    await this._saveState();
  }

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between feca895 and 2300a13.

📒 Files selected for processing (6)

.aios-core/core/orchestration/checklist-runner.js
.aios-core/core/orchestration/context-manager.js
.aios-core/core/orchestration/index.js
.aios-core/core/orchestration/parallel-executor.js
.aios-core/core/orchestration/subagent-prompt-builder.js
.aios-core/core/orchestration/workflow-orchestrator.js

🧰 Additional context used

🧬 Code graph analysis (4)

.aios-core/core/orchestration/parallel-executor.js (2)

.aios-core/core/orchestration/workflow-orchestrator.js (1)

chalk (15-15)

.aios-core/core/orchestration/index.js (1)

ParallelExecutor (18-18)

.aios-core/core/orchestration/index.js (2)

.aios-core/core/orchestration/workflow-orchestrator.js (3)

SubagentPromptBuilder (17-17)

ContextManager (18-18)

ChecklistRunner (19-19)

.aios-core/cli/commands/migrate/analyze.js (1)

module (193-193)

.aios-core/core/orchestration/checklist-runner.js (2)

.aios-core/core/orchestration/workflow-orchestrator.js (1)

ChecklistRunner (19-19)

.aios-core/core/orchestration/index.js (1)

ChecklistRunner (17-17)

.aios-core/core/orchestration/context-manager.js (2)

.aios-core/core/orchestration/workflow-orchestrator.js (1)

ContextManager (18-18)

.aios-core/core/orchestration/index.js (1)

ContextManager (16-16)

🪛 GitHub Actions: CI

.aios-core/core/orchestration/subagent-prompt-builder.js