SynkraAI
diff --git a/‎.aiox-core/development/scripts/workflow-validator.js‎
Lines changed: 92 additions & 18 deletions b/‎.aiox-core/development/scripts/workflow-validator.js‎
Lines changed: 92 additions & 18 deletions
diff --git a/‎.aiox-core/development/tasks/create-workflow.md‎
Lines changed: 44 additions & 42 deletions b/‎.aiox-core/development/tasks/create-workflow.md‎
Lines changed: 44 additions & 42 deletions
diff --git a/‎.aiox-core/development/tasks/validate-workflow.md‎
Lines changed: 2 additions & 2 deletions b/‎.aiox-core/development/tasks/validate-workflow.md‎
Lines changed: 2 additions & 2 deletions
@@ -101,36 +101,38 @@ class WorkflowValidator {
       return result; // Can't continue without parsed data
     }
 
-    const workflow = parseResult.data;
+    const workflow = this._normalizeWorkflowDocument(parseResult.data);
 
     // 3. Required fields
     const fieldsResult = this.validateRequiredFields(workflow, workflowPath);
     this._mergeResults(result, fieldsResult);
 
+    const phaseSequence = this._getPhaseSequence(workflow);
+
     // 4. Phase sequence
-    if (workflow.workflow && workflow.workflow.sequence) {
-      const sequenceResult = this.validatePhaseSequence(workflow.workflow.sequence);
+    if (phaseSequence.length > 0) {
+      const sequenceResult = this.validatePhaseSequence(phaseSequence);
       this._mergeResults(result, sequenceResult);
 
       // 5. Agent references
-      const agentResult = await this.validateAgentReferences(workflow.workflow.sequence);
+      const agentResult = await this.validateAgentReferences(phaseSequence);
       this._mergeResults(result, agentResult);
 
       // 6. Artifact flow
-      const artifactResult = this.validateArtifactFlow(workflow.workflow.sequence);
+      const artifactResult = this.validateArtifactFlow(phaseSequence);
       this._mergeResults(result, artifactResult);
 
       // 7. Circular dependencies
-      const circularResult = this.detectCircularDeps(workflow.workflow.sequence);
+      const circularResult = this.detectCircularDeps(phaseSequence);
       this._mergeResults(result, circularResult);
 
       // 8. Conditional logic
-      const conditionalResult = this.validateConditionalLogic(workflow.workflow.sequence);
+      const conditionalResult = this.validateConditionalLogic(phaseSequence);
       this._mergeResults(result, conditionalResult);
     }
 
     // 9. Handoff prompts
-    const handoffResult = this.validateHandoffPrompts(workflow);
+    const handoffResult = this.validateHandoffPrompts(workflow, phaseSequence);
     this._mergeResults(result, handoffResult);
 
     // 10. Mermaid diagram
@@ -191,18 +193,18 @@ class WorkflowValidator {
     const result = { valid: true, errors: [], warnings: [], suggestions: [] };
     const filename = path.basename(filePath);
 
-    if (!workflow.workflow) {
+    const wf = workflow.workflow;
+    if (!wf || typeof wf !== 'object') {
       result.valid = false;
       result.errors.push({
         code: WorkflowValidationErrorCodes.WF_MISSING_REQUIRED_FIELD,
-        message: 'Missing top-level "workflow:" key',
+        message: 'Missing workflow payload (expected workflow.id, workflow.name, and sequence/phases)',
         file: filename,
-        suggestion: 'Add workflow: as the root key containing id, name, and sequence',
+        suggestion: 'Add workflow: root key or canonical top-level id/name/sequence|phases',
       });
       return result;
     }
 
-    const wf = workflow.workflow;
     const requiredFields = ['id', 'name'];
 
     for (const field of requiredFields) {
@@ -217,13 +219,22 @@ class WorkflowValidator {
       }
     }
 
-    if (!wf.sequence || !Array.isArray(wf.sequence) || wf.sequence.length === 0) {
+    const hasSequence = Array.isArray(wf.sequence) && wf.sequence.length > 0;
+    const hasPhases = Array.isArray(wf.phases) && wf.phases.length > 0;
+    if (!hasSequence && !hasPhases) {
       result.valid = false;
       result.errors.push({
         code: WorkflowValidationErrorCodes.WF_MISSING_REQUIRED_FIELD,
-        message: 'Missing or empty "sequence:" array',
+        message: 'Missing or empty workflow execution array ("sequence" or "phases")',
+        file: filename,
+        suggestion: 'Add workflow.sequence (official) with at least one step; phases is compatibility only',
+      });
+    } else if (!hasSequence && hasPhases) {
+      result.warnings.push({
+        code: WorkflowValidationErrorCodes.WF_MISSING_REQUIRED_FIELD,
+        message: 'Workflow uses workflow.phases without workflow.sequence',
         file: filename,
-        suggestion: 'Add sequence: with at least one step entry containing agent and creates/action',
+        suggestion: 'Prefer workflow.sequence as canonical execution contract (keep phases only as supplemental metadata)',
       });
     }
 
@@ -539,18 +550,20 @@ class WorkflowValidator {
   /**
    * Validate handoff prompts exist for transitions
    * @param {Object} workflow - Full parsed workflow
+   * @param {Array|null} phaseSequence - Optional resolved phase sequence
    * @returns {Object} Validation result
    */
-  validateHandoffPrompts(workflow) {
+  validateHandoffPrompts(workflow, phaseSequence = null) {
     const result = { valid: true, errors: [], warnings: [], suggestions: [] };
 
     const wf = workflow.workflow;
-    if (!wf || !wf.sequence || !Array.isArray(wf.sequence)) return result;
+    const sequence = Array.isArray(phaseSequence) ? phaseSequence : this._getPhaseSequence(workflow);
+    if (!wf || !Array.isArray(sequence) || sequence.length === 0) return result;
 
     // Count agent transitions (where one agent hands off to another)
     let transitionCount = 0;
     let prevAgent = null;
-    for (const step of wf.sequence) {
+    for (const step of sequence) {
       if (step.agent && step.agent !== prevAgent) {
         if (prevAgent) transitionCount++;
         prevAgent = step.agent;
@@ -687,6 +700,67 @@ class WorkflowValidator {
       target.valid = false;
     }
   }
+
+  /**
+   * Normalize workflow payload to keep backward compatibility across
+   * workflow-wrapped and top-level workflow documents.
+   * @private
+   * @param {Object} data
+   * @returns {Object}
+   */
+  _normalizeWorkflowDocument(data) {
+    if (!data || typeof data !== 'object') {
+      return { workflow: null };
+    }
+
+    if (data.workflow && typeof data.workflow === 'object') {
+      const normalizedWorkflow = { ...data.workflow };
+      if (!normalizedWorkflow.phases && Array.isArray(data.phases)) {
+        normalizedWorkflow.phases = data.phases;
+      }
+      return { ...data, workflow: normalizedWorkflow };
+    }
+
+    const normalizedWorkflow = {
+      id: data.id,
+      name: data.name,
+      version: data.version,
+      description: data.description,
+      type: data.type,
+      orchestrator: data.orchestrator,
+      sequence: Array.isArray(data.sequence) ? data.sequence : undefined,
+      phases: Array.isArray(data.phases) ? data.phases : undefined,
+      handoff_prompts: data.handoff_prompts,
+      flow_diagram: data.flow_diagram,
+    };
+
+    return {
+      ...data,
+      workflow: normalizedWorkflow,
+    };
+  }
+
+  /**
+   * Resolve executable entries from canonical workflow.sequence[], with
+   * workflow.phases[] as compatibility fallback.
+   * @private
+   * @param {Object} workflow
+   * @returns {Array}
+   */
+  _getPhaseSequence(workflow) {
+    const wf = workflow && workflow.workflow ? workflow.workflow : null;
+    if (!wf) return [];
+
+    if (Array.isArray(wf.sequence) && wf.sequence.length > 0) {
+      return wf.sequence;
+    }
+
+    if (Array.isArray(wf.phases) && wf.phases.length > 0) {
+      return wf.phases;
+    }
+
+    return [];
+  }
 }
 
 module.exports = {
 
@@ -273,23 +273,23 @@ ELICIT: Workflow Basic Information
 4. What is the expected outcome?
 ```
 
-### Step 2: Workflow Stages
-```
-ELICIT: Workflow Stages and Flow
-1. What are the main stages/phases? (e.g., "planning", "implementation", "testing")
-2. What is the sequence of these stages?
+### Step 2: Workflow Sequence Design
+```text
+ELICIT: Workflow Sequence and Flow
+1. What are the main execution steps/phases? (e.g., "planning", "implementation", "testing")
+2. What is the exact step order (`workflow.sequence`)?
 3. Are there any parallel activities?
 4. Are there decision points or conditional flows?
-5. What are the exit criteria for each stage?
+5. What are the exit criteria for each step?
 ```
 
 ### Step 3: Agent Orchestration
-```
+```text
 ELICIT: Agent Participation
-For each stage:
+For each workflow step:
 1. Which agent(s) are involved?
 2. What are their specific responsibilities?
-3. How do agents hand off work between stages?
+3. How do agents hand off work between steps?
 4. Are there any approval requirements?
 ```
 
@@ -316,39 +316,41 @@ ELICIT: Resources and Dependencies
    workflow:
      id: {workflow-name}
      name: {Workflow Display Name}
+     version: {semver}
      description: {Purpose and overview}
      type: {greenfield|brownfield}
      scope: {ui|service|fullstack}
-     
-   stages:
-     - id: stage-1
-       name: {Stage Name}
-       agent: {agent-id}
-       tasks:
-         - {task-name}
-       outputs:
-         - {output-description}
-       next: stage-2
-       
-   transitions:
-     - from: stage-1
-       to: stage-2
-       condition: {optional condition}
-       
-   resources:
-     templates:
-       - {template-name}
-     data:
-       - {data-file}
-       
-   validation:
-     checkpoints:
-       - stage: {stage-id}
-         criteria: {validation-criteria}
+ 
+     # Optional compatibility metadata (non-executable)
+     phases:
+       - phase_1: {phase label}
+       - phase_2: {phase label}
+ 
+     # Canonical executable contract
+     sequence:
+       - step: {step-slug}
+         id: {step-id}
+         phase: {1..N}
+         phase_name: {Phase Display Name}
+         agent: {agent-id}
+         task: {task-name}
+         action: {what happens}
+         requires: {previous-step-id}
+         outputs:
+           - {artifact-name}
+         next: {next-step-id}
+         on_failure: {fallback-step-id}
+
+       - workflow_end:
+           id: complete
+           action: workflow_complete
+
+     handoff_prompts:
+       {from}_to_{to}: {handoff guidance}
    ```
 
 3. **Add Security Controls**
-   - Stage authorization requirements
+   - Step authorization requirements
    - Data access restrictions
    - Audit logging points
    - Approval workflows
@@ -378,21 +380,21 @@ ELICIT: Resources and Dependencies
      timestamp: new Date().toISOString(),
      metadata: {
        type: workflowType,
-       stages: stageList,
+       sequence_steps: stepList,
        agents: involvedAgents
      }
    });
    ```
 
 6. **Generate Documentation**
    - Create workflow diagram (text-based)
-   - Document each stage's purpose
+   - Document each step's purpose
    - List all handoff points
    - Include troubleshooting guide
 
 ## Validation Checklist
 - [ ] Workflow name is unique and valid
-- [ ] All stages have clear purposes
+- [ ] All sequence steps have clear purposes
 - [ ] Agent assignments are valid
 - [ ] No circular dependencies
 - [ ] All resources exist
@@ -415,14 +417,14 @@ ELICIT: Resources and Dependencies
    (hybrid → squads/{squad_name}/workflows/{workflow-name}.yaml)
 📊 Workflow Summary:
    - Context: {target_context} {squad_name if applicable}
-   - Stages: {stage-count}
+   - Steps: {step-count}
    - Agents: {agent-list}
    - Type: {workflow-type}
 🚀 To use: Select workflow when starting new project
 ```
 
 ## Workflow Execution Notes
 - Workflows are selected during project initialization
-- Each stage execution is logged in memory
+- Each step execution is logged in memory
 - Progress tracking available through memory queries
-- Agents automatically receive stage-specific context 
+- Agents automatically receive step-specific context
@@ -190,8 +190,8 @@ acceptance-criteria:
    - **Recovery:** Show line/column of syntax error
 
 3. **Error:** Missing Required Fields
-   - **Cause:** Workflow missing workflow.id, workflow.name, or sequence
-   - **Resolution:** Add missing fields to workflow YAML
+   - **Cause:** Workflow missing workflow.id, workflow.name, or execution array
+   - **Resolution:** Add `workflow.sequence` (official). `workflow.phases` is accepted for compatibility only.
    - **Recovery:** Show which fields are missing with examples
 
 ---