---
name: lilflow-workflow-driver
description: Drive a lilflow session-mode workflow from inside this agent session (Claude Code natively, or OpenCode via the oh-my-opencode Claude Code compatibility layer). Use this skill whenever the FLOW_RUN_ID environment variable is set — it means lilflow has started a workflow and expects you to advance it via the `flow session-bridge` CLI. Call `flow session-bridge next` to get the next step, execute it, then call `flow session-bridge update <step> completed|failed` to advance. For conversational agent steps, work with the user iteratively before marking complete.
---

# lilflow Workflow Driver

You are driving a **lilflow** workflow. Each step in the workflow must be fetched, executed, and reported back through the `flow session-bridge` CLI. Do not try to guess the workflow — always ask the bridge what's next.

This skill works identically in Claude Code and in OpenCode (via [oh-my-opencode](https://github.com/opensoft/oh-my-opencode)'s Claude Code compatibility layer). The bridge CLI is the same in both environments.

## When this skill activates

You can tell this skill applies when:

- The environment variable `FLOW_RUN_ID` is set (always check `echo $FLOW_RUN_ID` first).
- The user's initial prompt references a workflow, a "run", or explicitly mentions lilflow.

If `FLOW_RUN_ID` is not set, stop and tell the user — the workflow runner did not start this session.

## Core loop

Follow this loop until `flow session-bridge next` reports `workflow_status: "completed"`:

1. **Get the next step:**
   ```bash
   flow session-bridge next
   ```
   Returns JSON: `{ step, steps, remaining, workflow_status }`. `step` is non-null for a single eligible step; `steps` is a list for a parallel batch.

2. **Execute the step** based on its `type`:

   - **`run`** — execute `step.command` via the `Bash` tool. Capture stdout/exit code.
   - **`agent`** with `mode: autonomous` — execute `step.agent.prompt` yourself. You are the agent.
   - **`agent`** with `mode: conversational` — see [Conversational steps](#conversational-steps) below.
   - **`agent`** with a different provider (e.g. `opencode`) — mark the step `deferred`; the runner handles foreign providers.
   - **`gate`** — call `flow session-bridge gate <name>`. It evaluates the condition and returns `{ passed, workflow_should_stop }`.
   - **`interactive`** — call `flow session-bridge ask <prompt>` to get user input, then run the command with the input.
   - **`wait`** — call `flow session-bridge wait <name>`. Blocks until the trigger fires.
   - **`subflow`** — not yet supported in session mode. Mark the step `deferred`.

3. **Report the result:**
   ```bash
   flow session-bridge update <step-name> completed --output "..." --exit-code 0
   flow session-bridge update <step-name> failed --reason "..."
   ```

4. **On failure:** call `flow session-bridge update <name> failed` and stop the loop unless the user instructs otherwise.

5. **Repeat** until `workflow_status === "completed"`.

## Conversational steps

When `step.agent.mode === "conversational"`:

1. Present the step's prompt and your proposed approach to the user.
2. Work iteratively — implement, show results, gather feedback, adjust.
3. Do NOT call `flow session-bridge update` until the user has confirmed satisfaction OR you have completed the task to its written specification.
4. Explicitly tell the user when you consider the step complete before advancing.
5. If the user says "skip", "abort", or similar, call `flow session-bridge update <name> failed --reason "user aborted"`.

Example:
```
User: (workflow starts)
Agent: The workflow says: "Create React components for the dashboard.
       Iterate with the user until they approve." Here's my plan: ...
User: Add a sidebar too.
Agent: [revises, implements, shows output]. Anything else?
User: Looks good.
Agent: Marking "implement" complete, advancing to the next step.
  [runs: flow session-bridge update implement completed]
```

## Parallel batches

If `flow session-bridge next` returns multiple `steps`, they are eligible in parallel. You may execute them sequentially, or use sub-agents (the `Agent` tool) to run them concurrently. Call `flow session-bridge update` once per step.

## User-initiated questions

If you need user input in the middle of an autonomous step (an ambiguity the workflow didn't cover), call `flow session-bridge ask "<question>"` — the bridge prompts the user and returns their response on stdout.

## Context management

After long workflows, your context may accumulate noise from completed steps. Call:
```bash
flow session-bridge compact
```
This returns a condensed summary of completed steps. Use the summary to anchor your memory and treat earlier tool results as droppable.

## Reporting notes and decisions

To record observations that don't change workflow state:
```bash
flow session-bridge log "observation or decision"
```

## Inspecting state

To see the full workflow state (what's done, what's pending):
```bash
flow session-bridge status
```

## Rules

1. **Always** call `flow session-bridge next` before executing anything. Do not infer the workflow.
2. **Always** call `flow session-bridge update` after finishing a step, even on failure. The bridge is the source of truth.
3. **Never** invent step names or pretend a step succeeded. The event log is authoritative.
4. When a gate fails with `workflow_should_stop: true`, stop the loop and report the failure to the user.
5. Respect `mode: conversational` — do not advance these steps without user interaction.