sea-workflow-orchestrate

name	sea-workflow-orchestrate
description	Orchestrate complex SEA-Forge workflows across multiple tools, services, and environments. Handles pipeline coordination, dependency management, and state tracking.

SEA Workflow Orchestration

Orchestrate complex SEA-Forge workflows across tools, services, and environments. Coordinate pipelines, manage dependencies, track state, and handle errors across the development lifecycle.

When to Use

Invoke when:

• Running complex multi-step workflows
• Coordinating across multiple contexts
• Managing release workflows
• Running distributed pipelines
• Handling multi-environment deployments

Usage

User invokes with:

• "Orchestrate release workflow"
• "Run full validation pipeline"
• "Coordinate multi-context deployment"
• "Execute feature workflow"

Workflow Definition

Workflows are defined in YAML:

# workflows/feature-development.yaml
name: Feature Development
description: Complete feature development workflow

variables:
  context_name: ${CONTEXT}
  branch: ${BRANCH:-feature/*}
  target_env: development

steps:
  - name: Validate preconditions
    run: |
      # Check we're on feature branch
      if ! git branch --show-current | grep -q "^feature/"; then
        echo "❌ Must be on feature branch"
        exit 1
      fi

      # Check task state
      if ! grep -q "^phase: implement" docs/task_state.md; then
        echo "❌ Task state must be in 'implement' phase"
        exit 1
      fi

      echo "✅ Preconditions validated"

  - name: Run Nx impact analysis
    run: |
      pnpm exec nx affected --graph=output.json
      # Save affected projects for later steps
      pnpm exec nx show projects --affected > tmp/affected.txt

  - name: Validate specs
    run: |
      # Find all affected specs
      for spec in $(git diff --name-only dev...HEAD | grep "docs/specs/"); do
        calm validate "$spec"
      done

  - name: Run unit tests
    run: |
      # Run tests for affected projects only
      pnpm exec nx affected -t test --base=dev

  - name: Generate handlers
    run: |
      # Regenerate handlers for affected contexts
      for context in $(cat tmp/affected.txt); do
        just pipeline "$context"
      done

  - name: Run integration tests
    run: |
      pnpm exec nx affected -t e2e --base=dev

  - name: Run security review
    delegate: security-reviewer
    config:
      scope: affected

  - name: Update task state
    run: |
      # Update task_state.md with completion status
      yq e '.last_test_status = "pass"' -i docs/task_state.md

  - name: Create PR
    run: |
      # Create PR with checklist
      gh pr create \
        --title "Feature: ${CONTEXT}" \
        --body "$(cat .github/templates/pr-template.md)" \
        --base dev

on_error:
  - name: Log failure
    run: |
      echo "Workflow failed at step ${FAILED_STEP}"
      echo "Error: ${ERROR}"
      tee tmp/workflow-error.log

  - name: Notify
    run: |
      # Send notification (via Slack, email, etc.)
      echo "Workflow ${WORKFLOW} failed" | notify-on-error

on_success:
  - name: Update state
    run: |
      yq e '.phase = "pr_review"' -i docs/task_state.md

Orchestration Process

Step 1: Load Workflow

WORKFLOW_FILE="$1"

# Validate workflow file exists
if [ ! -f "$WORKFLOW_FILE" ]; then
  echo "❌ Workflow not found: $WORKFLOW_FILE"
  exit 1
fi

# Parse workflow
WORKFLOW_NAME=$(yq e '.name' "$WORKFLOW_FILE")
STEPS_COUNT=$(yq e '.steps | length' "$WORKFLOW_FILE")

echo "🔄 Workflow: $WORKFLOW_NAME"
echo "📋 Steps: $STEPS_COUNT"

Step 2: Initialize State

# Create workflow state file
cat > tmp/workflow-state.yaml <<EOF
workflow:
  name: $WORKFLOW_NAME
  file: $WORKFLOW_FILE
  started_at: $(date -u +%Y-%m-%dT%H:%M:%SZ)
  status: running

steps:
  total: $STEPS_COUNT
  completed: 0
  failed: 0
  current: 0

variables:
  $(yq e '.variables // {}' "$WORKFLOW_FILE")

results:
  {}
EOF

Step 3: Execute Steps

# Execute each step
for i in $(seq 0 $((STEPS_COUNT - 1))); do
  STEP_NAME=$(yq e ".steps[$i].name" "$WORKFLOW_FILE")
  STEP_TYPE=$(yq e ".steps[$i].type // \"run\"" "$WORKFLOW_FILE")

  echo ""
  echo "▶️  Step $((i+1))/$STEPS_COUNT: $STEP_NAME"

  # Update state
  yq e ".steps.current = $i" -i tmp/workflow-state.yaml

  case "$STEP_TYPE" in
    run)
      # Execute shell command
      COMMAND=$(yq e ".steps[$i].run" "$WORKFLOW_FILE")

      # Substitute variables
      COMMAND=$(eval "echo \"$COMMAND\"")

      if eval "$COMMAND" >> tmp/workflow.log 2>&1; then
        echo "✅ $STEP_NAME completed"
        yq e ".results.$STEP_NAME = \"success\"" -i tmp/workflow-state.yaml
        yq e ".steps.completed += 1" -i tmp/workflow-state.yaml
      else
        echo "❌ $STEP_NAME failed"
        yq e ".results.$STEP_NAME = \"failed\"" -i tmp/workflow-state.yaml
        yq e ".steps.failed += 1" -i tmp/workflow-state.yaml

        # Handle error
        handle_error "$WORKFLOW_FILE" "$i"
        exit 1
      fi
      ;;

    delegate)
      # Delegate to subagent
      AGENT=$(yq e ".steps[$i].delegate" "$WORKFLOW_FILE")
      CONFIG=$(yq e ".steps[$i].config // {}" "$WORKFLOW_FILE")

      echo "🤖 Delegating to $AGENT..."

      # Invoke subagent via Task tool
      if claude-code --agent "$AGENT" --config "$CONFIG"; then
        echo "✅ $STEP_NAME completed"
      else
        echo "❌ $STEP_NAME failed"
        handle_error "$WORKFLOW_FILE" "$i"
        exit 1
      fi
      ;;

    parallel)
      # Execute sub-steps in parallel
      SUBSTEPS=$(yq e ".steps[$i].steps | length" "$WORKFLOW_FILE")

      for j in $(seq 0 $((SUBSTEPS - 1))); do
        SUBSTEP_CMD=$(yq e ".steps[$i].steps[$j].run" "$WORKFLOW_FILE")
        eval "($SUBSTEP_CMD) &"
      done

      # Wait for all background jobs
      wait
      ;;

    conditional)
      # Conditional execution
      CONDITION=$(yq e ".steps[$i].if" "$WORKFLOW_FILE")

      if eval "$CONDITION"; then
        # Execute then branch
        yq e ".steps[$i].then.run" "$WORKFLOW_FILE" | bash
      else
        # Execute else branch
        yq e ".steps[$i].else.run // \"\"" "$WORKFLOW_FILE" | bash
      fi
      ;;
  esac
done

Step 4: Handle Completion

# Check if workflow completed successfully
FAILED=$(yq e '.steps.failed' tmp/workflow-state.yaml)

if [ "$FAILED" -eq 0 ]; then
  echo ""
  echo "✅ Workflow completed successfully"

  # Run success handlers
  run_success_handlers "$WORKFLOW_FILE"

  # Update final state
  yq e ".status = \"completed\"" -i tmp/workflow-state.yaml
  yq e ".completed_at = \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"" -i tmp/workflow-state.yaml
else
  echo ""
  echo "❌ Workflow failed"

  # Run error handlers
  run_error_handlers "$WORKFLOW_FILE"

  yq e ".status = \"failed\"" -i tmp/workflow-state.yaml
fi

# Save workflow state
mv tmp/workflow-state.yaml "workflows/history/$(date +%Y%m%d-%H%M%S)-${WORKFLOW_NAME}.yaml"

Built-in Workflows

Feature Development

sea-workflow-orchestrate workflows/feature-development.yaml

Release Preparation

sea-workflow-orchestrate workflows/release-prep.yaml

Multi-Context Deployment

sea-workflow-orchestrate workflows/deploy-all.yaml

CI Pipeline

sea-workflow-orchestrate workflows/ci-pipeline.yaml

Workflow Features

Variables

variables:
  context_name: user-management
  environment: development
  parallel: true

Conditional Execution

steps:
  - name: Conditional step
    if: ${{ variables.parallel == true }}
    run: echo "Running in parallel"
    else:
      run: echo "Running sequentially"

Parallel Execution

steps:
  - name: Run tests in parallel
    type: parallel
    steps:
      - run: pnpm test:unit
      - run: pnpm test:integration
      - run: pnpm test:e2e

Subagent Delegation

steps:
  - name: Security review
    type: delegate
    delegate: security-reviewer
    config:
      scope: affected
      severity: high

Error Handling

on_error:
  - name: Log error
    run: echo "Error: ${ERROR}" >> error.log
  - name: Rollback
    run: just rollback

on_success:
  - name: Celebrate
    run: echo "🎉 Success!"

Workflow State

workflow:
  name: Feature Development
  started_at: 2026-03-04T10:00:00Z
  completed_at: 2026-03-04T10:30:00Z
  status: completed
  duration: 30m

steps:
  total: 10
  completed: 10
  failed: 0
  skipped: 0

variables:
  context_name: user-management
  environment: development

results:
  validate_preconditions: success
  nx_impact_analysis: success
  validate_specs: success
  unit_tests: success
  generate_handlers: success
  integration_tests: success
  security_review: success
  update_task_state: success
  create_pr: success

artifacts:
  - tmp/affected.txt
  - tmp/workflow.log
  - pr-url: https://github.com/...

Integration

• Integrates with all SEA subagents for delegation
• Integrates with nx-run-tasks for Nx operations
• Integrates with state-clerk for state tracking
• Integrates with Goose for long-running workflows

Output

After workflow execution:

## Workflow Complete

**Workflow**: {name}
**Status**: {success|failed}
**Duration**: {duration}
**Steps**: {completed}/{total}

### Results
| Step | Status | Duration |
|------|--------|----------|
| {step1} | ✅ | {duration} |
| {step2} | ✅ | {duration} |
| {step3} | ❌ | {duration} |

### Artifacts
- {artifact1}
- {artifact2}

### Next Steps
{next actions}

### State File
workflows/history/{timestamp}-{name}.yaml