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

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:

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

Implementation Process

Step 1: Gather Requirements

Ask user (if not provided):

Workflow name: kebab-case identifier (e.g., feature-implementation)
Description: What the workflow accomplishes
Steps: List of discrete steps with:
- Step name
- Step goal
- Required tools
- Expected output
Execution mode: Sequential or parallel steps
Agent type: general-purpose or custom agent

Step 2: Create Directory Structure

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 4: Create Orchestrator Command

Create the main command file with this pattern:

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:

Pattern B: Parallel Independent Steps

Steps can run concurrently:

Pattern C: Stateful Multi-Step (Resume)

When steps need shared context:

Example: Feature Implementation Workflow

Orchestrator Command

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

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:

Directories:
- ${CLAUDE_PLUGIN_ROOT}/tasks/ - All task files directly here
- ${CLAUDE_PLUGIN_ROOT}/agents/ - (Optional) Custom agent definitions
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/
Orchestrator command: Lean dispatch logic in commands/<workflow-name>.md
Custom agents (Optional): If workflow needs specialized agent behavior in agents/
Update plugin.json: Add command to plugin manifest if needed

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