/craft-workflow-run

name: workflow-run
description: "Run a session of an existing workflow - start, continue, advance stages, run-all, batch-create sessions, mark ready."
argument-hint: "[run <name> | continue | next <name> | run-all <name> | batch <name> | ready <name>]"
when_to_use: "Use when the user wants to execute workflow work: 'run the workflow', 'continue the workflow', 'next session', 'run all remaining sessions', 'batch create sessions', or 'mark sessions ready'. NOT for authoring or archiving workflow definitions (use craft:workflow-design)."

Workflow Run

Execute a session of an existing workflow. Owns the full session lifecycle: starting new sessions, continuing active ones, advancing through stages, batch-creating drafts, marking drafts ready, and chaining all runnable sessions.

---

⛔ **CRITICAL: ALWAYS USE TASKCREATE FOR STAGE PROGRESS**

When executing a session, you MUST call **TaskCreate** for every stage in the workflow before starting Stage 1. This produces the live progress checklist that you and the user both see in the terminal UI. Narrating stage advances in prose without TaskCreate is NOT acceptable - the user has no progress signal, you have no compaction-recoverable state, and the system has no record of where you are.

---

⛔ **CRITICAL: ALWAYS CALL THE TRANSITION SCRIPTS**

For every state transition, invoke the appropriate script via the Bash tool. Never use Edit/Write/sed to modify `session.md` frontmatter or stage status tags directly:

• `start-workflow-session.sh <session-dir>` - activate a new session
• `complete-workflow-stage.sh <session-dir> <stage-num> [notes]` - mark a stage complete and advance
• `complete-workflow-session.sh <session-dir>` - finalize a session with validation

The scripts contain guards (sibling-active check, format integrity, sentinel updates) that direct edits bypass. Bypassing the scripts is how parallel sessions and corrupt state happen.

---

⛔ **CRITICAL: NEVER RUN TWO SESSIONS IN PARALLEL**

The `start-workflow-session.sh` script enforces a per-workflow sibling-active guard. If you try to start a session while a sibling session is already active in the same workflow, the script exits 1 with an error naming the blocking session. Respect it.

---

⛔ **IF THE SIBLING-ACTIVE GUARD EXITS 1, STOP**

When `start-workflow-session.sh` exits 1 with the sibling-active error, surface the error verbatim to the user and STOP. Do NOT bypass it. Do NOT manually clear sibling state. Do NOT suggest workarounds. The sibling session must be completed or paused by the user before another can start. This is the single most important safeguard against state corruption.

---

⛔ **FORMAT IS STAGES-V1 ONLY**

Every workflow definition in this version uses stages-v1 format: a `definition.md` routing table plus per-stage files in `stages/NN-slug.md`. Do NOT add format-detection branches or fallback code paths for legacy definition layouts. If you encounter a workflow without a `stages/` directory, surface the issue to the user; do not try to handle it.

---

Project Root

Use `$CRAFT_PROJECT_ROOT` (set at session start) as the base path for all `.craft/` references. If not set, resolve by walking up from PWD to find the nearest `.craft/.global-state`.

Set `PROJECT` to `${CRAFT_PROJECT_ROOT:-.}`.

Format Reference

For the definitive specification of workflow definition frontmatter, stage file structure, session frontmatter, and Progress table format, see `${CLAUDE_PLUGIN_ROOT}/commands/references/workflow-formats.md`. That file is a cold-path schema lookup - read it when you need to verify the shape of a frontmatter field or the exact format of the Progress table. All procedural steps for executing a session live in this file, not the schema reference.

---

Step 0: Determine Verb

Parse args to determine which verb to execute:

• **`run {name}`** -> Step 1 (create new session, then execute)
• **`continue`** -> Step 1g (resume active session, then execute from current stage)
• **`next {name}`** -> Step 1d (find next runnable session, activate it, execute)
• **`run-all {name}`** -> Step 1e (chain through all runnable sessions in order)
• **`batch {name}`** -> Step 1b (create multiple draft sessions, no execution)
• **`ready {name}`** -> Step 1f (transition selected draft sessions to ready)
• **No args** -> AskUserQuestion: "What would you like to do?" with options mapping to the verbs above

---

Step 1: Create New Session (`run` verb)

1.1: Select Workflow

If workflow name provided in args, use it. Otherwise, list available workflows and let the user pick via AskUserQuestion.

Read the workflow's `definition.md` to get variables and stage list.

1.2: Name and Configure Session

Ask for a session name (e.g., "MCP Course", "Auth Service Audit").

For each variable in the workflow's definition, ask for the value:

> **Fill in workflow variables:** > - `{var1}` ({description}): > - `{var2}` ({description}):

1.3: Choose Run Mode

Use **AskUserQuestion**:

question: "How do you want to run this session?"
header: "Run mode"
options:
  - label: "Interactive (Recommended)"
    description: "Step through each stage, confirm before advancing"
  - label: "Auto"
    description: "Run all stages automatically, pause only at manual gates"
  - label: "Draft only"
    description: "Create the session file but don't start yet"

1.4: Write Session File

Create the session and artifacts directories using Bash:

mkdir -p "$PROJECT/.craft/workflows/{workflow-slug}/sessions/{date}-{session-slug}"
mkdir -p "$PROJECT/.craft/workflows/{workflow-slug}/sessions/{date}-{session-slug}/artifacts"

Write `session.md` with the hybrid format (see `${CLAUDE_PLUGIN_ROOT}/commands/references/workflow-formats.md` New Session Format Reference for the exact schema). The session contains:

• **Frontmatter:** workflow, name, status, mode, started, completed, current_stage, variables (including system variable `session_dir` set to the full session