workflow-executor

What this skill does

# Workflow Executor Skill (v0.6.9)

Execute looplia workflows defined in `workflows/*.md` files using the skills-first architecture.

## When to Use

Use this skill when:
- Handling `/run` commands
- Executing workflow-as-markdown definitions
- Orchestrating multi-step skill workflows

---

## ⚠️ CRITICAL EXECUTION MODEL - READ FIRST

**YOU (the model reading this skill) must execute the step loop directly. DO NOT delegate.**

```
┌─────────────────────────────────────────────────────────────────────┐
│  YOU (main agent) iterate through steps, making ONE Task call each  │
│                                                                     │
│  FOR step IN workflow.steps:                                        │
│      1. Call Task(general-purpose) for THIS STEP ONLY               │
│      2. WAIT for Task to complete                                   │
│      3. Validate output                                             │
│      4. THEN move to next step                                      │
│                                                                     │
│  ❌ WRONG: Task("Execute all workflow steps...")                    │
│  ✅ RIGHT: Task("Execute step: summary"), Task("Execute step: ideas")│
└─────────────────────────────────────────────────────────────────────┘
```

**3 steps = 3 Task calls. You MUST make 3 separate Task tool invocations.**

---

## CRITICAL: Task Invocation with general-purpose Subagent

**v0.6.9:** Using built-in `general-purpose` subagent for ALL workflow steps (all providers).

When executing a step with `skill: {name}` and `mission:`:

```json
{
  "subagent_type": "general-purpose",
  "description": "Execute step: {step.id}",
  "prompt": "Execute skill '{step.skill}' for step '{step.id}'.\n\n## Mission\n{step.mission}\n\n## Execution Protocol\n1. Read input files (if provided)\n2. Invoke the skill using Skill tool\n3. Execute the mission with skill context\n4. Write JSON output to the specified path using Write tool\n\n## CRITICAL: Output Writing is MANDATORY\nYOU MUST CALL THE WRITE TOOL before completing. If you don't write the file, the workflow fails.\n\n## Rules\n- ALWAYS invoke the specified skill using Skill tool\n- ALWAYS write output to the exact path using Write tool\n- NEVER return results as text - always write JSON to output file\n- NEVER spawn Task subagents - execute skills directly\n- ALWAYS include contentId in JSON outputs\n\nInput: {resolved input path}\nOutput: {step.output}\nValidation: {step.validate JSON}"
}
```

**Example:**
```yaml
- id: analyze-content
  skill: media-reviewer
  mission: |
    Deep analysis of video transcript. Extract key themes,
    important quotes, and narrative structure.
  input: ${{ sandbox }}/inputs/content.md
  output: ${{ sandbox }}/outputs/analysis.json
```

**Task tool call:**
```json
{
  "subagent_type": "general-purpose",
  "description": "Execute step: analyze-content",
  "prompt": "Execute skill 'media-reviewer' for step 'analyze-content'.\n\n## Mission\nDeep analysis of video transcript. Extract key themes, important quotes, and narrative structure.\n\n## Execution Protocol\n1. Read input files (if provided)\n2. Invoke the skill using Skill tool\n3. Execute the mission with skill context\n4. Write JSON output to the specified path using Write tool\n\n## CRITICAL: Output Writing is MANDATORY\nYOU MUST CALL THE WRITE TOOL before completing. If you don't write the file, the workflow fails.\n\n## Rules\n- ALWAYS invoke the specified skill using Skill tool\n- ALWAYS write output to the exact path using Write tool\n- NEVER return results as text - always write JSON to output file\n- NEVER spawn Task subagents - execute skills directly\n- ALWAYS include contentId in JSON outputs\n\nInput: sandbox/video-2025-01-15-abc123/inputs/content.md\nOutput: sandbox/video-2025-01-15-abc123/outputs/analysis.json\nValidation: {\"required_fields\":[\"contentId\",\"headline\",\"keyThemes\"]}"
}
```

### Rules

- **ALWAYS** use `subagent_type: "general-purpose"` for ALL workflow steps
- **NEVER** use custom subagent_type per step (removed in v0.6.1)
- **VALIDATE** that step has both `skill:` and `mission:` fields
- **REJECT** steps using deprecated `run:` syntax

### Why Per-Step Task Calls (Context Isolation)

Each `Task(general-purpose)` creates a **separate context window**:
- Isolates step processing from main agent context
- Prevents context pollution across steps
- Enables focused execution with only relevant inputs

**NEVER batch multiple steps** - this defeats context isolation.

### Anti-Patterns (VIOLATIONS = TEST FAILURE)

❌ **FATAL ERROR - Delegating entire workflow to one Task:**
```json
{
  "description": "Execute workflow: writing-kit",
  "prompt": "Run all workflow steps..."
}
```
**This is WRONG.** You made 1 Task call. Tests expect 3. TEST WILL FAIL.

❌ **FATAL ERROR - Executing skills inline without Task:**
```
Skill("media-reviewer")  // NO! You must use Task wrapper
Skill("idea-synthesis")  // NO! You must use Task wrapper
```
**This is WRONG.** Each step MUST be wrapped in a Task call.

✅ **CORRECT - One Task call per step (3 steps = 3 Task calls):**
```
Task("Execute step: summary")    // Task #1
  → Subagent invokes Skill("media-reviewer")

Task("Execute step: ideas")      // Task #2
  → Subagent invokes Skill("idea-synthesis")

Task("Execute step: writing-kit") // Task #3
  → Subagent invokes Skill("writing-kit-assembler")
```

**Verification**: Count your Task tool calls. If workflow has 3 steps, you MUST have 3 Task calls.

---

## Step Field Validation (v0.6.3)

Before executing a step, validate:

| Field | Required | Error if Missing |
|-------|----------|------------------|
| `skill` | **Yes** | "Step '{id}' missing required 'skill' field" |
| `mission` | **Yes** | "Step '{id}' missing required 'mission' field" |
| `input` | **Conditional** | Required unless skill is input-less capable (e.g., `search`) |
| `output` | **Yes** | "Step '{id}' missing required 'output' field" |
| `run` | **FORBIDDEN** | "Step '{id}' uses deprecated 'run:' syntax. Migrate to 'skill:' + 'mission:'" |

### Input-less Capable Skills

These skills can operate without an `input` field:
- `browser-research` - Executes research missions autonomously (from looplia-skills)

Example input-less step:
```yaml
- id: find-news
  skill: browser-research
  mission: |
    Search Hacker News for today's top 3 AI stories.
    Extract title, URL, points, and brief summary.
  output: ${{ sandbox }}/outputs/news.json
  # No input field - browser-research operates autonomously
```

---

## Execution Protocol

### Phase 1: Sandbox Setup

**New Sandbox with Named Inputs** (v0.6.3 - when `--input` provided):

1. Generate sandbox ID:
   ```
   {first-input-name}-{YYYY-MM-DD}-{random4chars}
   Example: video-transcript-2025-12-18-xk7m
   ```

2. Create folder structure:
   ```
   sandbox/{sandbox-id}/
   ├── inputs/
   │   ├── video-transcript.md  # Named input files
   │   └── user-notes.md
   ├── outputs/             # Step outputs go here
   ├── logs/                # Session logs
   └── validation.json      # Validation state
   ```

3. Copy each input file to `inputs/{name}.md`

**New Sandbox with Single File** (legacy - when `--file` provided):

1. Generate sandbox ID:
   ```
   {content-slug}-{YYYY-MM-DD}-{random4chars}
   Example: my-article-2025-12-18-xk7m
   ```

2. Create folder structure and copy to `inputs/content.md`

**Input-less Sandbox** (v0.6.3 - no inputs required):

For workflows using only input-less capable skills (e.g., `search`):

1. Generate sandbox ID from workflow name:
   ```
   {workflow-slug}-{YYYY-MM-DD}-{random4chars}
   Example: hn-reporter-2025-12-18-xk7m
   ```

2. Create folder structure with empty `inputs/` directory

**Resume Sandbox** (when `--sandbox-id` provided):

1. Verify sandbox exists
2. Load `validation.json` to see completed steps
3. Continue from first incomplete step

### Phase 2: Workflow Parsing

1. Read workflow file: `workflows/{workflow-id}.