/create-workflow-command

name: create-workflow-command
description: Create a workflow command that orchestrates multi-step execution through sub-agents with file-based task prompts

Create Workflow Command

Create a command that orchestrates multi-step workflows by dispatching sub-agents with task-specific instructions stored in separate files.

User Input

Workflow Name: $1
Description: $2

Architecture Overview

Workflow commands solve the **context bloat problem**: instead of embedding detailed step instructions in the main command (polluting orchestrator context), store them in separate task files that sub-agents read on-demand.

plugins/<plugin-name>/
├── commands/
│   └── <workflow>.md          # Lean orchestrator (~50-100 tokens per step)
├── agents/                     # Optional: reusable executor agents
│   └── step-executor.md       # Custom agent with specific tools/behavior
└── tasks/                      # All task instructions directly here
    ├── step-1-<name>.md       # Full instructions (~500+ tokens each)
    ├── step-2-<name>.md
    ├── step-3-<name>.md
    └── common-context.md      # Shared context across workflows

Key Principles

1. Context Isolation

Each sub-agent gets its own isolated context window. The main orchestrator stays lean while sub-agents load detailed instructions from files.

| Component | Context Cost | Purpose | |-----------|--------------|---------| | Orchestrator command | ~50-100 tokens/step | Dispatch and coordinate | | Task file | ~500+ tokens | Detailed step instructions | | Sub-agent base | ~294 tokens | System prompt overhead |

2. Sub-Agent Capabilities

Sub-agents spawned via Task tool:

| Capability | Available | Notes | |------------|-----------|-------| | Read tool | ✅ Yes | Can read any file | | Write tool | ✅ Yes | If not restricted | | Grep/Glob | ✅ Yes | For code search | | Skills loading | ❌ No | Skills don't auto-load in sub-agents | | Spawn sub-agents | ❌ No | Cannot nest Task tool | | Resume context | ✅ Yes | Via `resume` parameter |

3. File Reference Pattern

Use `${CLAUDE_PLUGIN_ROOT}` for portable paths within plugin:

Read ${CLAUDE_PLUGIN_ROOT}/tasks/step-1-workflow-name.md and execute.

Sub-agent will use Read tool to fetch the file content.

Implementation Process

Step 1: Gather Requirements

Ask user (if not provided):

1. **Workflow name**: kebab-case identifier (e.g., `feature-implementation`) 2. **Description**: What the workflow accomplishes 3. **Steps**: List of discrete steps with:

• Step name
• Step goal
• Required tools
• Expected output

4. **Execution mode**: Sequential or parallel steps 5. **Agent type**: `general-purpose` or custom agent

Step 2: Create Directory Structure

# Create tasks directory (if it doesn't exist)
mkdir -p ${CLAUDE_PLUGIN_ROOT}/tasks

# Optional: Create agents directory (if using custom agents)
mkdir -p ${CLAUDE_PLUGIN_ROOT}/agents

**Note**: All task files (both workflow-specific steps and shared context) are placed directly in `tasks/` without subdirectories.

Step 3: Create Task Files

For each step, create a task file with this structure:

# Step N: <Step Name>

## Context
You are executing step N of the <workflow-name> workflow.

## Goal
<Clear, specific goal for this step>

## Input
<What this step receives from previous steps or user>

## Instructions
1. <Specific action>
2. <Specific action>
3. <Specific action>

## Constraints
- <Limitation or boundary>
- <What NOT to do>

## Expected Output
<What to return to orchestrator>

## Success Criteria
- [ ] <Measurable outcome>
- [ ] <Measurable outcome>

Step 4: Create Orchestrator Command

Create the main command file with this pattern:

---
description: <Workflow description>
argument-hint: <Required arguments>
allowed-tools: Task, Read
model: sonnet
---

# <Workflow Name>

## User Input

\`\`\`text
$ARGUMENTS
\`\`\`

## Workflow Execution

### Step 1: <Step Name>

Launch general-purpose agent:
- **Description**: "<3-5 word summary>"
- **Prompt**:
  \`\`\`
  Read ${CLAUDE_PLUGIN_ROOT}/tasks/step-1-<workflow>-<name>.md and execute.

  Context:
  - TARGET: $1
  - MODE: $2
  \`\`\`

**Capture**: <What to extract from result>

### Step 2: <Step Name>

Launch general-purpose agent:
- **Description**: "<3-5 word summary>"
- **Prompt**:
  \`\`\`
  Read ${CLAUDE_PLUGIN_ROOT}/tasks/step-2-<workflow>-<name>.md and execute.

  Context from Step 1:
  - <Key data from previous step>
  \`\`\`

### Step 3: <Step Name>

[Continue pattern...]

## Completion

Summarize workflow results:
1. <What was accomplished>
2. <Key outputs>
3. <Next steps if any>

Frontmatter Options

| Field | Purpose | Default | |-------|---------|---------| | `description` | Brief description of workflow purpose | Required | | `argument-hint` | Expected arguments description | None | | `allowed-tools` | Tools the command can use | Inherits from conversation | | `model` | Specific Claude model (sonnet, opus, haiku) | Inherits from conversation |

**Model selection**:

• `haiku` - Fast, efficient for simple workflows
• `sonnet` - Balanced performance (recommended default)
• `opus` - Maximum capability for complex orchestration

Execution Patterns

Pattern A: Sequential Steps (Default)

Each step depends on previous step's output:

### Step 1: Analyze
Launch agent → Get analysis result

### Step 2: Plan (uses Step 1 result)
Launch agent with Step 1 context → Get plan

### Step 3: Execute (uses Step 2 result)
Launch agent with Step 2 context → Complete

Pattern B: Parallel Independent Steps

Steps can run concurrently:

### Analysis Phase (Parallel)

Launch 3 agents simultaneously:
1. Agent 1: Security analysis → Read ${CLAUDE_PLUGIN_ROOT}/tasks/step-1a-security.md
2. Agent 2: Performance analysis → Read ${CLAUDE_PLUGIN_ROOT}/tasks/step-1b-performance.md
3. Agent 3: Code quality analysis → Read ${CLAUDE_PLUGIN_ROOT}/