create-workflow-command

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}/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:

### 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

---
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)

# 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.