/execute-workflow - Execute Declarative Workflow Definitions

Execute YAML/JSON workflow definitions as state-machine orchestrated multi-agent tasks with checkpoint/resume capability.

Usage

# Execute workflow by name (searches workflows/ directory)
/execute-workflow security-audit

# Execute workflow from specific file
/execute-workflow --file workflows/parallel-task-isolation.yaml

# Execute with input parameters
/execute-workflow security-audit --input target_dir=src --input depth=3

# Dry run (preview execution plan without running)
/execute-workflow security-audit --dry-run

# Resume from checkpoint
/execute-workflow --resume .coditect/workflow-checkpoints/abc123-SCAN.json

# Execute n8n-format workflow (auto-converted)
/execute-workflow --n8n workflows/devops/ci-pipeline.json

# List available workflows
/execute-workflow --list

# Show workflow details
/execute-workflow security-audit --info

System Prompt

⚠️ EXECUTION DIRECTIVE: When the user invokes this command, you MUST:

IMMEDIATELY execute - no questions, no explanations first
ALWAYS show full output from script/tool execution
ALWAYS provide summary after execution completes

DO NOT:

Say "I don't need to take action" - you ALWAYS execute when invoked
Ask for confirmation unless requires_confirmation: true in frontmatter
Skip execution even if it seems redundant - run it anyway

The user invoking the command IS the confirmation.

You are executing the CODITECT workflow executor. This command runs declarative workflow definitions as state-machine orchestrated multi-agent tasks.

Workflow Locations:

Native workflows: workflows/*.yaml, workflows/*.yml
n8n workflows: workflows/**/*.json (auto-converted via adapter)
Checkpoints: .coditect/workflow-checkpoints/

Execution Model:

The workflow executor uses a state-machine pattern where:

States define workflow progress (INITIATE → STEP_1 → ... → COMPLETE/FAILED)
Nodes are execution units (agents, functions, skills)
Edges define transitions between states with optional node execution

Execution Steps:

Load Workflow: Read YAML/JSON definition or convert n8n format
Validate: Check required fields and structure
Initialize: Set current_state to initial_state
Execute Loop:
- Find edge from current_state
- If edge has node, execute it (dispatch agent/function/skill)
- Transition to edge.to_state
- If state is checkpoint, save state
Complete: When terminal state reached

Agent Dispatch Pattern:

For nodes with type: agent, dispatch using Task tool:

Task(subagent_type="{node.agent}", prompt="""
Execute workflow node: {node.description}

Context from previous steps:
{workflow_context}

Required output: Complete the task and return results.
""")

Checkpoint/Resume:

Checkpoints save workflow state to .coditect/workflow-checkpoints/:

{
  "workflow_id": "abc123",
  "workflow_name": "security-audit",
  "current_state": "SCAN_DEPS",
  "completed_nodes": ["init", "setup"],
  "context": {...},
  "saved_at": "2025-12-18T08:00:00Z"
}

Resume by loading checkpoint and continuing from saved state.

Implementation

For --list mode:

echo "Available Workflows:"
echo "===================="
for f in workflows/*.yaml workflows/*.yml 2>/dev/null; do
  [ -f "$f" ] && echo "  - $(basename "$f" .yaml | sed 's/.yml$//')"
done

For --dry-run mode: Read workflow file and display execution plan:

States to traverse
Nodes to execute per transition
Agents that will be dispatched
Estimated duration and token budget
Checkpoint states

For --info mode: Display workflow metadata:

Name, version, description
Category and tags
Node count and types
State count
Estimated duration

For execution mode:

Load workflow definition
Parse input parameters into context
Execute state machine:
- For each transition, if node specified:
  - type: agent → Task tool dispatch
  - type: function → Log function execution
  - type: skill → Skill invocation
- Track completed nodes and states
- Save checkpoints at configured states
Report final status and outputs

Options

Option	Description
`WORKFLOW`	Workflow name (searches workflows/ directory)
`--file PATH`	Execute specific workflow file
`--dry-run`	Preview execution plan without running
`--resume PATH`	Resume from checkpoint file
`--n8n`	Treat input as n8n-format workflow
`--input KEY=VALUE`	Pass input parameter to workflow (repeatable)
`--list`	List available workflows
`--info`	Show workflow details without executing
`--verbose`	Show detailed execution progress

Examples

Execute Security Audit Workflow

/execute-workflow security-audit --input target=./src

Result: Executes security-audit.yaml with target parameter

Dry Run Preview

/execute-workflow parallel-task-isolation --dry-run

Output:

Workflow: parallel-task-isolation
Version: 1.0.0

Execution Plan:
  Step 1: INITIATE → SETUP_WORKTREES (node: setup)
          Agent: git-workflow-orchestrator
  Step 2: SETUP_WORKTREES → DISPATCH_AGENTS (node: dispatch)
          Agent: orchestrator
  Step 3: DISPATCH_AGENTS → MERGE_RESULTS (node: merge)
          Function: merge_worktree_results
  Step 4: MERGE_RESULTS → COMPLETE

Checkpoints: SETUP_WORKTREES, DISPATCH_AGENTS
Estimated Duration: 15-30 minutes
Token Budget: 60000

Resume Failed Workflow

/execute-workflow --resume .coditect/workflow-checkpoints/sec-audit-SCAN_DEPS.json

Result: Continues from SCAN_DEPS checkpoint state

Execute n8n Workflow

/execute-workflow --n8n --file workflows/devops/deploy-pipeline.json

Result: Converts n8n format via adapter and executes

Show Workflow Info

/execute-workflow security-audit --info

Output:

Workflow: security-audit
Version: 1.0.0
Description: Comprehensive security audit pipeline

States: INITIATE, SCAN_DEPS, STATIC_ANALYSIS, SECRET_DETECTION, REPORT, COMPLETE, FAILED
Initial: INITIATE
Terminal: COMPLETE, FAILED

Nodes (4):
  - dep_scan (agent: security-specialist)
  - sast (agent: security-auditor)
  - secrets (function: detect_secrets)
  - report (agent: documentation-generation)

Metadata:
  Category: security
  Tags: security, audit, compliance
  Duration: 15-30 minutes
  Token Budget: 50000

Workflow Definition Format

Native CODITECT (YAML):

name: example-workflow
version: "1.0.0"
description: "Example workflow description"

states:
  - INITIATE
  - PROCESS
  - COMPLETE
  - FAILED

initial_state: INITIATE
terminal_states: [COMPLETE, FAILED]

nodes:
  - id: process_node
    type: agent
    agent: general-purpose
    description: "Process the input data"
    timeout: 300

edges:
  - from_state: INITIATE
    to_state: PROCESS
    node: process_node
    on_failure: FAILED

  - from_state: PROCESS
    to_state: COMPLETE

metadata:
  category: general
  estimated_duration: "5-10 minutes"
  token_budget: 20000
  tags: [example]

checkpoints:
  - PROCESS

n8n Format (Auto-Converted):

{
  "name": "Example n8n Workflow",
  "nodes": [
    {
      "id": "1",
      "type": "n8n-nodes-base.function",
      "name": "Process Data",
      "notes": "Agent: general-purpose"
    }
  ],
  "connections": {}
}

Integration

Core Components:

skills/workflow-executor/core/executor.py - State machine engine
skills/workflow-executor/core/schema.py - Data classes
skills/workflow-executor/core/loader.py - File loading
skills/workflow-executor/core/n8n_adapter.py - n8n conversion

Related Commands:

/parallel-tasks - Git worktree parallel execution
/create-worktree - Create isolated worktree

Agent Integration:

All 119 CODITECT agents available for dispatch
Use subagent_type matching agent file name (without .md)

Success Output

When workflow execution completes:

✅ COMMAND COMPLETE: /execute-workflow
Workflow: <workflow-name>
Version: <version>
Status: <COMPLETE|FAILED>
States: N traversed
Nodes: N executed
Duration: <time>
Checkpoints: N saved

Completion Checklist

Before marking complete:

Failure Indicators

This command has FAILED if:

❌ Workflow file not found
❌ Invalid workflow definition
❌ Node execution failed
❌ Terminal state not reached

When NOT to Use

Do NOT use when:

Simple single task (use direct agent)
Manual steps required
Workflow not defined yet (use /create-workflow)

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Skip checkpoints	Lost progress	Enable checkpoints
No dry-run	Unexpected changes	Preview first
Ignore failures	Silent errors	Check terminal state

Principles

This command embodies:

#3 Complete Execution - Full workflow lifecycle
#6 Clear, Understandable - Clear execution progress
#9 Based on Facts - State-machine verified

Full Standard: CODITECT-STANDARD-AUTOMATION.md

Version: 1.0.0 Last Updated: 2025-12-18 ADR: ADR-WORKFLOW-EXECUTOR

Usage​

System Prompt​

System Prompt​

Implementation​

Options​

Examples​

Execute Security Audit Workflow​

Dry Run Preview​

Resume Failed Workflow​

Execute n8n Workflow​

Show Workflow Info​

Workflow Definition Format​

Integration​

Success Output​

Completion Checklist​

Failure Indicators​

When NOT to Use​

Anti-Patterns (Avoid)​

Principles​

Usage

System Prompt

System Prompt

Implementation

Options

Examples

Execute Security Audit Workflow

Dry Run Preview

Resume Failed Workflow

Execute n8n Workflow

Show Workflow Info

Workflow Definition Format

Integration

Success Output

Completion Checklist

Failure Indicators

When NOT to Use

Anti-Patterns (Avoid)

Principles