7.3 KiB

Raw Blame History

Role-Workflow-Subagent Pattern

A pattern for building plugins where a Role skill orchestrates multiple Workflows through subagent dispatch.

When to Use

Good fit:

Plugin has 2+ distinct workflows that produce structured findings
Workflows execute in subagent context (multi-file analysis, long-running evaluations)
Synthesis across workflow outputs is needed
Context bloat is a concern in the orchestrating thread

Not a fit:

Single workflow with no synthesis step
Workflows that need to share live state (not just task file)
Simple tools that don't need orchestration
Tight coupling between workflows requiring shared context

Components

Component	Responsibility	State
Thread	User conversation	Persistent
Role Skill	Orchestration, synthesis	Reads/writes task file Summary
Workflow Document	Framework, rubrics, templates	Static (read-only)
Task File	Shared state	Written by role (Context) and subagents (their sections)
Subagent	Execution	Ephemeral (discarded after completion)

Flow

┌─────────────────────────────────────────────────────────┐
│  THREAD (Main Conversation)                             │
│  ┌───────────────────────────────────────────────────┐  │
│  │  ROLE SKILL                                       │  │
│  │  1. Understand request                            │  │
│  │  2. Create task file with Context section         │  │
│  │  3. Dispatch subagents ───────────────────────────┼──┼──┐
│  │  4. Wait for completion                           │  │  │
│  │  5. Read task file                                │  │  │
│  │  6. Synthesize & present                          │  │  │
│  └───────────────────────────────────────────────────┘  │  │
└─────────────────────────────────────────────────────────┘  │
                                                             │
     ┌───────────────────────────────────────────────────────┘
     ▼
┌─────────────────────────────────────────────────────────┐
│  SUBAGENT (Fresh Context)                               │
│  1. Read workflow document                              │
│  2. Read task file Context section                      │
│  3. Execute evaluation using workflow's framework       │
│  4. Write findings to workflow's section in task file   │
│  5. Return summary to role                              │
│  [Context discarded after completion]                   │
└─────────────────────────────────────────────────────────┘

File Structure

plugin/
├── skills/
│   └── <role>/
│       └── SKILL.md           # Role orchestration logic
├── workflows/
│   ├── <workflow-1>.md        # Workflow document
│   └── <workflow-2>.md        # Workflow document
└── .claude/<plugin>/tasks/    # Task files (runtime, gitignored)
    └── <date>-<role>-<subject>.md

Task File Template

# Task: [Workflow Name] - [Subject]

## Context
[Role writes: input parameters, files, goals, concerns]

## [Workflow 1 Name]
Status: Pending
[Subagent writes findings here]

## [Workflow 2 Name]
Status: Pending
[Subagent writes findings here]

## Summary
[Role synthesizes after all workflows complete]

Dispatch Instructions

Keep dispatch prompts brief (6-8 lines), pointing to documents:

Execute the [workflow-name] workflow.

Task file: [path]
Workflow: [path]

Read the workflow document for process and templates.
Read task file Context for scope.
Write findings to your section in the task file.
Return a brief summary.

Design Principles

Subagent Containerization - Fresh context per workflow. Prevents context bloat.
Workflow Documents Over Inline Prompts - Dispatch instructions reference documents, not duplicate content.
Task File as Shared State - Only communication channel between role and subagents.
Trust AI Training - Workflow docs contain rubrics and templates, not explanations of known frameworks.
Role Owns Synthesis - Role reads full task file, synthesizes across all workflows.
No Concurrent Writes - One subagent per section. Role owns Summary.
User Drives Iteration - No automatic retry. User provides feedback, role re-dispatches.

Anti-Patterns

Wrong	Right
25-line dispatch prompts duplicating workflow steps	6-8 line dispatch pointing to workflow document
Multiple workflows in same subagent	Fresh subagent per workflow
Workflow documents as separate skills	Workflows are `.md` documents read by subagents
Explaining frameworks in workflow docs	Listing frameworks with severity scale and output template
Role returns raw findings	Role synthesizes, prioritizes, presents top issues
Subagent manages cross-workflow state	Role manages state, subagent executes one workflow

Model Guidance

Align model selection with workflow phases (typically 2-3 subagents maximum):

Phase	Model	Use case
Phase 1: Research	Haiku	Data gathering, file scanning, extracting information
Phase 2: Processing	Sonnet	Pattern application, filtering research output, applying frameworks, moderate judgment
Phase 3: Synthesis	Opus	Role orchestration, cross-workflow synthesis, high-stakes decisions

Sonnet tier characteristics:

Intermediate processing between research and synthesis
Apply established rubrics/frameworks to gathered data
Filter and structure findings for final synthesis
Lower-stakes decisions (e.g., severity classification, pattern matching)

Note: Most workflows use 2-3 subagents. Avoid over-segmentation.

Implementation Checklist

Role skill created at skills/<role>/SKILL.md
Workflow documents created at workflows/<workflow>.md
Task file template includes Context section
Dispatch instructions are 6-8 lines referencing workflow docs
Workflow docs have: framework/checklist, output template, severity scale
Role synthesizes findings after all workflows complete
No inline duplication of workflow content in skill
Task file location gitignored

Subagent Pattern - General subagent guidance
Audit Pattern - Single audit workflow (simpler than role-workflow)
Brainstorming Pattern - Design refinement before building

7.3 KiB Raw Blame History