Repo Defining Workflows

Defining Workflows

Purpose

Guidance for defining workflows: reusable, validated multi-agent orchestrations with sequential, parallel, or conditional coordination.

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

See Workflow Structure for the required YAML frontmatter schema (name, goal, termination, inputs, outputs), YAML colon-quoting rule, and the full workflow content template (Purpose, Agents Involved, Input Parameters, Execution Phases, Success Criteria, Example Usage, Related Workflows).

Execution Patterns

See Execution Patterns for worked Sequential, Parallel, Conditional, and Mixed execution examples.

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. Shards are plain-named; a step keeps its own number — Ordinal Prefixes.

Examples:

• plan-quality-gate.md - Plan quality gate workflow
• rules-quality-gate.md - Repo rules quality gate workflow

Quality Checklist

Before publishing workflow:

• Valid YAML frontmatter (all colons quoted)
• name field matches filename
• goal is clear and concise
• termination criteria defined (success/failure)
• All inputs documented (type, required, default)
• All outputs documented (type, pattern for file outputs)
• Every *-quality-gate applies lifecycle ownership Step 0 and emits lifecycle-status
• Execution phases clearly defined
• Dependencies explicit (sequential vs parallel)
• Success criteria in Gherkin format
• Example usage provided
• Related workflows linked

References

Primary Convention: Workflow Pattern Convention

Related Conventions:

• Maker-Checker-Fixer Pattern - Three-stage workflow pattern
• Acceptance Criteria Convention - Gherkin format

Related Skills:

• repo-applying-maker-checker-fixer - MCF workflow pattern
• plan-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.