/create-workflow

description: Scaffold a custom workflow — generates a mode skill and shortcut command
argument-hint: <workflow name> [description]
disable-model-invocation: true

/swarm:create-workflow

You are scaffolding a custom swarm workflow. This generates two files in the user's project: 1. A **mode skill** (`.claude/skills/<name>-mode/SKILL.md`) — the domain-specific operational spec 2. A **shortcut command** (`.claude/commands/<name>.md`) — the entry point users invoke

The interaction model is **generate first, edit after**. Ask the minimum needed to infer the full spec, generate everything, then let the user adjust.

Step 0: Gather

$ARGUMENTS

**If $ARGUMENTS contains a name and description** (has sentence structure, verbs, or a separator like `write-article — takes raw thoughts and produces a polished blog post`): extract both and proceed directly to Step 1.

**If $ARGUMENTS appears to be a name only** (kebab-case identifier, no verb or sentence structure — e.g., `write-article`): use it as the workflow name. Ask one question (plain text): "What does this workflow do? What does the user get at the end?" Wait for their response. Then proceed to Step 1.

**If $ARGUMENTS is empty**: ask one question (plain text): "What's this workflow called, and what does it do? (e.g., `write-article — takes raw dictated thoughts and produces a polished blog post`)" Wait for their response. Parse the name and purpose. Then proceed to Step 1.

Validate: the name should be kebab-case. If not, convert it silently.

---

Step 0.5: Determine Workflow Type

Before inferring the spec, decide whether this workflow should be a **thin wrapper** (extension of a built-in mode) or a **full custom mode**.

**Infer the closest built-in mode** from the purpose:

• Writing / editing / documentation / narrative → `swarm:writing-mode`
• Code / engineering / building / debugging → `swarm:code-mode`
• Anything else (research, synthesis, evaluation) → `swarm:general-mode`

Use **AskUserQuestion**:

• question: "How should this workflow be structured?"
• header: "Type"
• options:
• label: "Thin wrapper over [inferred base] (Recommended)"

description: "Inherits phase arc, lead identity, and facilitator from the base. You add intake (Pre-flight actions), an outcomes question, and additive Mode-Specific Rules + Suggest-Members Guidance. Stays in sync with swarm updates."

• label: "Full custom mode"

description: "Use when the workflow needs custom phase semantics, a distinct lead identity, or substantial domain governance. More surface to maintain; runs /swarm:update-workflow to stay current on wiring."

• label: "Wrapper — pick a different base"

description: "Create a thin wrapper but choose the base mode explicitly."

**If "Thin wrapper over [inferred base]"**: store `type = wrapper`, `base_mode = <inferred>`. Proceed to Step 1.

**If "Full custom mode"**: store `type = full_mode`. Proceed to Step 1.

**If "Wrapper — pick a different base"**: use **AskUserQuestion**:

• question: "Which base mode should this wrapper extend?"
• header: "Base mode"
• options:
• label: "swarm:code-mode"

description: "Engineering work — building, fixing, refactoring software"

• label: "swarm:writing-mode"

description: "Prose work — articles, essays, documentation, narrative"

• label: "swarm:general-mode"

description: "Work that doesn't fit a specific mode"

Store `type = wrapper` and `base_mode = <selected>`. Proceed to Step 1.

**Hard contract for wrappers.** Wrappers cannot override the base's phase arc, lead identity, or facilitator. Wrapper Mode-Specific Rules are additive-only. If the purpose statement implies the workflow needs to change phase semantics or replace the lead identity, prefer the full custom mode path — tell the user why when presenting the spec.

---

Step 1: Generate Spec

From the **name** and **purpose statement**, infer the workflow spec. Do not ask the user any questions in this step — generate using smart defaults and present for review. If the purpose statement is too thin to infer confidently, make your best guess and note it in the spec presentation. Do not stop to ask.

What you infer depends on the `type` chosen in Step 0.5:

Inference rules — wrapper workflows

For a wrapper, the base mode provides Lead Identity, Facilitator, Phase Arc, and base Mode-Specific Rules. Do not re-infer those. Infer only:

**Outcomes Question.** Infer from the purpose. Lives in the shortcut's `## Settings` section, not in the mode skill. Examples: "What's the GitHub issue number?" (intake-driven), "What are you building?" (code), "What do you want to write about?" (writing).

**Pre-flight intake** (for the shortcut command — optional). Only include if the purpose implies setup actions: fetching external data (e.g., `gh issue view`), parsing structured arguments, creating branches before work, reading project-specific files. If the workflow is pure "mode + outcomes question," omit Pre-flight.

**Mode-Specific Rules (additive).** Draft ONLY rules genuinely domain-specific to this workflow that don't exist in the base mode. Do NOT duplicate base mode rules or swarm's universal hard rules. Additive-only — cannot remove or contradict base rules. If the workflow has no domain-specific rules beyond the base, omit this section.

**Lead Allowlist additions** (optional). Only include if the workflow needs domain-specific `Permitted` or `Forbidden` bullets beyond the base mode's allowlist. Additive-only — cannot remove base-mode forbidden items. If no additions are needed, omit this subsection.

**Suggest-Members Guidance (supplement).** Domain-specific voices this workflow should favor, in addition to the base mode's guidance. Short, actionable. If the base's guidance is sufficient, omit this section.

Do not infer Lead Identity, Facilitator, Phase Arc, Information Flow, or Pre-flight Reads for wrappers — they come from the base mode or don't apply.

**Hard contract reminder.** If the inferred spec