| name | repo-defining-workflows |
| description | Workflow pattern standards for creating multi-agent orchestrations including YAML frontmatter (name, goal, termination, inputs, outputs), execution phases (sequential/parallel/conditional), agent coordination patterns, and Gherkin success criteria. Essential for defining reusable, validated workflow processes. |
Defining Workflows
Purpose
This Skill provides comprehensive guidance for defining workflows - multi-agent orchestrations that coordinate multiple agents in sequence, parallel, or conditionally to accomplish complex tasks. Workflows enable reusable, validated processes.
When to use this Skill:
- Creating new workflow documents
- Defining multi-agent coordination patterns
- Structuring sequential or parallel agent execution
- Writing workflow acceptance criteria
- Documenting workflow parameters and inputs
Workflow Structure
YAML Frontmatter (Required)
---
name: workflow-identifier
goal: What this workflow achieves
termination: Success/failure criteria
inputs:
- name: input-name
type: string | number | boolean | file | file-list | enum
description: What this input is for
required: true | false
default: value (if not required)
- name: max-concurrency
type: number
description: Background agents run concurrently — the N in the N+1 model (1 main thread + N background agents = N+1 total)
required: false
default: 3
outputs:
- name: output-name
type: string | number | boolean | file | file-list | enum
description: What this output contains
pattern: file-pattern (for file/file-list types)
---
Critical YAML Syntax: Values containing colons (:) must be quoted.
✅ Good:
description: "Workflow name: detailed description here"
parameter: "key: value pairs"
❌ Bad (breaks YAML parsing):
description: Workflow name: detailed description
Workflow Content
# Workflow Name
## Purpose
What this workflow accomplishes and when to use it.
## Agents Involved
- **agent-name-1**: Role and responsibility
- **agent-name-2**: Role and responsibility
## Input Parameters
| Parameter | Type | Required | Default | Description |
| --------- | ------ | -------- | ------- | ----------- |
| param1 | string | Yes | - | Purpose |
| param2 | number | No | 5 | Purpose |
## Execution Phases
### Phase 1: Name (Sequential)
1. Run agent-name-1 with parameters
2. Wait for completion
3. Run agent-name-2 with results from agent-name-1
### Phase 2: Name (Parallel)
Run in parallel:
- agent-name-3
- agent-name-4
Wait for all to complete before proceeding.
### Phase 3: Name (Conditional)
If condition A:
- Run agent-name-5
Else:
- Run agent-name-6
## Success Criteria
```gherkin
Given [precondition]
When [workflow executed]
Then [expected outcome]
And [additional verification]
```
Example Usage
Concrete example showing how to invoke workflow.
Related Workflows
- workflow-name-1 - When to use together
- workflow-name-2 - Alternative approach
## Execution Patterns
### Sequential Execution
**When**: Steps depend on previous results.
```markdown
1. maker creates content
2. checker validates content (uses maker output)
3. fixer applies fixes (uses checker findings)
Parallel Execution
When: Steps are independent and can run simultaneously.
Run in parallel:
- checker-1 validates docs
- checker-2 validates code
- checker-3 validates configs
Combine results after all complete.
Conditional Execution
When: Different paths based on conditions.
If validation passes:
- Deploy to production
Else:
- Create issue with findings
- Notify team
Mixed Patterns
Combine sequential, parallel, and conditional:
1. Run maker (sequential)
2. Run checkers in parallel:
- checker-1
- checker-2
3. Wait for all checkers
4. Conditional:
If critical issues found:
- STOP
- Report to user
Else:
- Run fixer (sequential)
- Deploy
Standard Input Parameters
Most workflows support:
- max-concurrency (number, default: 3): Background agents run concurrently — the N in the N+1 model (
1 main thread + N background agents = N+1 total). The DAG governs the actual fan-out; N only caps it. Never self-promoted beyond the declared value
- dry-run (boolean, default: false): Preview without executing
- verbose (boolean, default: false): Detailed logging
Common Mistakes
❌ Mistake 1: Unquoted colons in YAML
Wrong:
description: Workflow name: detailed description
Right:
description: "Workflow name: detailed description"
❌ Mistake 2: Missing agent dependencies
Wrong: Parallel execution when agent-2 needs agent-1 output
Right: Sequential execution with explicit dependency
❌ Mistake 3: No success criteria
Wrong: Workflow without Gherkin validation criteria
Right: Clear Gherkin scenarios for success validation
❌ Mistake 4: Missing parameters documentation
Wrong: Undocumented parameters that users must guess
Right: Table with all parameters, types, defaults, descriptions
Workflow File Naming
Convention: [workflow-name].md
Examples:
quality-gate.md - Plan quality gate workflowquality-gate.md - Docs quality gate workflowrepo-rules-quality-gate.md - Repo rules quality gate workflow
Quality Checklist
Before publishing workflow:
References
Primary Convention: Workflow Pattern Convention
Related Conventions:
Related Skills:
repo-applying-maker-checker-fixer - MCF workflow patternplan-writing-gherkin-criteria - Success criteria format
This Skill packages workflow definition standards for creating reusable multi-agent orchestrations with clear coordination patterns. For comprehensive details, consult the primary convention document.
