/craft-workflow-design

name: workflow-design
description: "Design a workflow - create new definitions, edit existing ones, or archive workflows you no longer need."
argument-hint: "[create | edit <name> | archive <name>]"
when_to_use: "Use when the user wants to author or organize workflow definitions: 'create a new workflow', 'edit the workflow', 'refine this workflow', 'archive a workflow'. NOT for running or prepping sessions (use craft:workflow-run)."

Workflow Design

Author and manage workflow definitions. Owns the definition lifecycle: creating new workflows from scratch or by importing process documents, editing existing definitions (stage prose, prompts, checklists, variables), and archiving workflows no longer in use.

For executing sessions of an existing workflow, use `/craft:workflow-run`. This command does not run anything - it just shapes the definitions that workflow-run executes against.

---

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

Every workflow definition uses stages-v1 format: a `definition.md` routing table plus per-stage files in `stages/NN-slug.md`. For the definitive specification of the routing-table schema, stage file frontmatter (execution, agent, produces, consumes, human_gate), and session frontmatter, see `${CLAUDE_PLUGIN_ROOT}/commands/references/workflow-formats.md`. That file is a cold-path schema lookup; all create/edit/archive procedure lives in this file.

---

Step 0: Determine Verb

Parse args to determine which verb to execute:

• **`create`** -> Step 1 (define a new workflow from scratch or by importing a process document)
• **`edit {name}`** -> Step 2 (refine an existing workflow's stages, prompts, checklist items, or variables)
• **`archive {name}`** -> Step 3 (move an existing workflow to `.archived/`)
• **No args** -> AskUserQuestion:

question: "What would you like to do?"
header: "Workflow design"
options:
  - label: "Create a new workflow"
    description: "Define stages, variables, and execution modes from scratch or import"
  - label: "Edit an existing workflow"
    description: "Refine stage prose, prompts, checklists, or variables"
  - label: "Archive a workflow"
    description: "Move to .archived/ - sessions and definition preserved, hidden from dashboard"

Route based on selection.

---

Step 1: Create New Workflow (`create` verb)

1.1: Determine Source

Use **AskUserQuestion**:

question: "How do you want to create this workflow?"
header: "Source"
options:
  - label: "From scratch"
    description: "Define stages interactively"
  - label: "Import from file"
    description: "Parse an existing process document (Markdown, any project)"
  - label: "Import from URL"
    description: "Fetch and parse a remote process document"

• **"From scratch"** -> Jump to **Step 1.3** (Define Stages).
• **"Import from file"** -> Ask for file path. Jump to **Step 1.2**.
• **"Import from URL"** -> Fetch URL via WebFetch. Jump to **Step 1.2**.

1.2: Parse Source Document

Read the source. Identify stages by looking for:

• `### Stage N:` or `## Stage N:` headings
• `### Step N:` or `## Step N:` headings
• Numbered headings (`### 1. Title`, `## 1: Title`)
• Any `##` or `###` level heading pattern that repeats with incrementing numbers

For each stage found, extract:

• **Name** from the heading
• **Description** from the first paragraph
• **Produces** from "Artifacts:" or "What it produces:" sections
• **Key principles** from "Key principle:" sections
• **Sub-steps** from bullet lists or sub-headings within the stage

Present the parsed structure:

> Found **{N} stages** in "{source file}": > 1. {Stage 1 name} - {first line of description} > 2. {Stage 2 name} - {first line} > ... > > Does this look right?

Use **AskUserQuestion**:

question: "Does the parsed structure look correct?"
header: "Parse review"
options:
  - label: "Looks good"
    description: "Continue to configure execution modes"
  - label: "Needs adjustment"
    description: "I'll tell you what to fix"

• **"Looks good"** -> Jump to **Step 1.3**.
• **"Needs adjustment"** -> Let the user describe changes, re-parse. Loop.

1.3: Define Workflow Metadata

Ask for:

• **Workflow name** (slugified for the folder name)
• **Description** (one line - this becomes the workflow's frontmatter `description`)
• **Variables** - "What variables does this workflow need? (e.g., topic, domain, project)"

For each variable, capture:

• Name
• Description (what it represents)
• Optional default value

1.4: Configure Execution Modes

Walk through each stage. For each one, suggest an execution mode based on the stage description:

• Stages mentioning "research", "investigate", "analyze" with a named agent -> suggest `agent`
• Stages mentioning "verify" with a named agent -> suggest `agent`
• Stages mentioning "synthesize", "combine", "integrate", "review", "decide" -> suggest `inline` (needs prior stage context)
• Stages mentioning "build", "write", "create", "implement" -> suggest `inline` (needs workflow context)
• Stages mentioning "apply", "fix", "update" -> suggest `inline`
• Stages with sub-passes or multiple agents -> suggest `agent`
• Default -> suggest `inline`

Use **AskUserQuestion** per stage:

question: "Stage {N}: {name} - How should this execute?"
header: "Execution"
options:
  - label: "{suggested mode} (Recommended)"
    description: "{description of what this mode does}"
  - label: "{alternative 1}"
    description: "{description}"
  - label: "{alternative 2}"
    description: "{description}"
  - label: "{alternative 3}"
    description: "{description}"

**Execution modes:**

| Mode | Behavior | |------|----------| | `agent` | Spawn isolated sub-agent, auto-advance on success. Use when the work is self-contained and doesn't need p