cc-os/plugins/cc-architect/references/tool-patterns/role-workflow-pattern.md

# 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

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

1. **Subagent Containerization** - Fresh context per workflow. Prevents context bloat.

2. **Workflow Documents Over Inline Prompts** - Dispatch instructions reference documents, not duplicate content.

3. **Task File as Shared State** - Only communication channel between role and subagents.

4. **Trust AI Training** - Workflow docs contain rubrics and templates, not explanations of known frameworks.

5. **Role Owns Synthesis** - Role reads full task file, synthesizes across all workflows.

6. **No Concurrent Writes** - One subagent per section. Role owns Summary.

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

## Related Patterns

- **[Subagent Pattern](../subagent-pattern.md)** - General subagent guidance
- **[Audit Pattern](audit-pattern.md)** - Single audit workflow (simpler than role-workflow)
- **[Brainstorming Pattern](brainstorming-pattern.md)** - Design refinement before building