create-workflow-command - Claude MCP Skill

# 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

```text
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:

```markdown
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

```bash
# 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:

```markdown
# 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:

```markdown
---
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:

```markdown
### 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:

```markdown
### 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}/tasks/step-1c-quality.md

**Wait for all**, then consolidate results.

### Synthesis Phase
Launch agent with all analysis results...
```

### Pattern C: Stateful Multi-Step (Resume)

When steps need shared context:

```markdown
### Step 1: Initialize
Launch agent, **capture agent_id**

### Step 2: Continue (same context)
Resume agent using agent_id:
- **resume**: <agent_id from Step 1>
- **prompt**: "Proceed to phase 2: <additional instructions>"
```

## Example: Feature Implementation Workflow

### Orchestrator Command

```markdown
---
description: Execute feature implementation through research, planning, and coding phases
argument-hint: [feature-description]
allowed-tools: Task, Read, TodoWrite
model: sonnet
---

# Implement Feature

## User Input
\`\`\`text
$ARGUMENTS
\`\`\`

Create TodoWrite with workflow steps.

## Phase 1: Research

Launch general-purpose agent:
- **Description**: "Research feature requirements"
- **Prompt**:
  \`\`\`
  Read ${CLAUDE_PLUGIN_ROOT}/tasks/step-1-feature-impl-research.md

  Feature: $ARGUMENTS
  \`\`\`

**Extract**: Key findings, constraints, existing patterns

## Phase 2: Architecture

Launch general-purpose agent:
- **Description**: "Design feature architecture"
- **Prompt**:
  \`\`\`
  Read ${CLAUDE_PLUGIN_ROOT}/tasks/step-2-feature-impl-architecture.md

  Feature: $ARGUMENTS
  Research findings: <summary from Phase 1>
  \`\`\`

**Extract**: File structure, components, interfaces

## Phase 3: Implementation

Launch developer agent:
- **Description**: "Implement feature code"
- **Prompt**:
  \`\`\`
  Read ${CLAUDE_PLUGIN_ROOT}/tasks/step-3-feature-impl-implement.md

  Architecture: <summary from Phase 2>
  \`\`\`

## Completion

Mark todos complete. Report:
1. Files created/modified
2. Tests added
3. Remaining work
```

### Task File Example (step-1-feature-impl-research.md)

```markdown
# Step 1: Feature Research

## Context
You are the research phase of a feature implementation workflow.

## Goal
Thoroughly understand the feature requirements and existing codebase context before any implementation begins.

## Instructions

1. **Parse Feature Request**
   - Extract core requirements
   - Identify acceptance criteria
   - Note any constraints mentioned

2. **Codebase Analysis**
   - Search for similar existing features
   - Identify relevant patterns and conventions
   - Find reusable components/utilities

3. **Dependency Check**
   - What existing code will this feature interact with?
   - Are there breaking change risks?
   - What tests exist for related functionality?

4. **Gap Analysis**
   - What's missing from the request?
   - What clarifications might be needed?
   - What edge cases should be considered?

## Constraints
- Do NOT write any implementation code
- Do NOT modify any files
- Focus purely on research and analysis

## Expected Output

Return a structured research summary:

\`\`\`markdown
## Feature Understanding
- Core requirement: <summary>
- Acceptance criteria: <list>

## Codebase Context
- Similar features: <list with file paths>
- Patterns to follow: <list>
- Reusable code: <list with file paths>

## Dependencies
- Files affected: <list>
- Tests to consider: <list>

## Open Questions
- <Question 1>
- <Question 2>

## Recommendation
<Brief recommendation for architecture phase>
\`\`\`

## Success Criteria
- [ ] Feature requirements clearly articulated
- [ ] Relevant existing code identified
- [ ] No implementation attempted
- [ ] Clear handoff to architecture phase
```

## Known Limitations

| Limitation | Impact | Workaround |
|------------|--------|------------|
| No nested sub-agents | Sub-agents can't spawn Task tool | Keep all orchestration in main command |
| No skill auto-loading | Sub-agents don't trigger skills | Pass explicit file paths or inline context |
| Fresh context per agent | Each dispatch starts empty | Use resume pattern OR pass summaries |
| File read latency | Extra tool call per step | Acceptable trade-off for context savings |

## Validation Checklist

Before finalizing workflow command:

- [ ] Each step has clear, specific goal
- [ ] Task files are self-contained (sub-agent doesn't need external context)
- [ ] File paths use `${CLAUDE_PLUGIN_ROOT}` for portability
- [ ] Context passed between steps is minimal (summaries, not full data)
- [ ] Orchestrator command stays lean (<100 tokens per step dispatch)
- [ ] Error handling defined for step failures
- [ ] Success criteria measurable for each step

## Create the Workflow

Based on user input, create:

1. **Directories**:
   - `${CLAUDE_PLUGIN_ROOT}/tasks/` - All task files directly here
   - `${CLAUDE_PLUGIN_ROOT}/agents/` - (Optional) Custom agent definitions

2. **Task files**: Create in `tasks/` directory with naming pattern `step-N-<workflow>-<name>.md`
   - Example: `step-1-feature-impl-research.md`
   - Example: `step-2-feature-impl-architecture.md`
   - Shared context: `common-context.md` directly in `tasks/`

3. **Orchestrator command**: Lean dispatch logic in `commands/<workflow-name>.md`

4. **Custom agents** (Optional): If workflow needs specialized agent behavior in `agents/`

5. **Update plugin.json**: Add command to plugin manifest if needed

After creation, suggest testing with `/customaize-agent:test-prompt` command.