creating-workflows

Creating Workflows

Guide for authoring sprint workflow definitions in .claude/workflows/.

What is a Workflow?

Workflow Location

.claude/workflows/
├── sprint-default.yaml     # Top-level sprint workflow
├── feature-standard.yaml   # Step-level implementation workflow
├── bugfix-workflow.yaml    # Quick bug fix workflow
└── custom-workflow.yaml    # Your custom workflows

Quick Start

1. Create Workflow File

# .claude/workflows/my-workflow.yaml
name: My Custom Workflow
description: Brief description of workflow purpose

phases:
  - id: first-phase
    prompt: |
      Instructions for first phase.
      {{step.prompt}}

  - id: second-phase
    prompt: |
      Instructions for second phase.

2. Reference in SPRINT.yaml

workflow: my-workflow
steps:
  - Implement feature X
  - Add tests for feature X

Phase Types Decision Tree

Do you need to process multiple sprint steps?
├── YES → Use for-each phase
│         └── for-each: step
│             workflow: step-workflow
│
└── NO → Use simple phase
         └── prompt: "Instructions here"

Workflow Patterns

Template Variables

Example Workflows

Minimal Workflow

name: Minimal Execute
phases:
  - id: execute
    prompt: "Execute the task: {{step.prompt}}"

Sprint Workflow with For-Each

name: Standard Sprint
phases:
  - id: prepare
    prompt: "Prepare sprint environment"

  - id: development
    for-each: step
    workflow: feature-standard

  - id: qa
    prompt: "Run tests and quality checks"

  - id: deploy
    prompt: "Create PR and finalize"

Ralph Mode Workflows

Ralph Mode enables autonomous goal-driven execution where Claude creates steps dynamically instead of following predefined phases.

Ralph Mode Structure

name: My Ralph Workflow
mode: ralph

goal-prompt: |
  Analyze goal and create steps...

reflection-prompt: |
  Evaluate if goal is complete...

per-iteration-hooks:
  - id: learning
    workflow: "m42-signs:learning-extraction"
    parallel: true
    enabled: false

Per-Iteration Hooks

Hooks are deterministic tasks that run every iteration:

See references/workflow-schema.md for full Ralph Mode schema.

References

• references/workflow-schema.md - Complete YAML schema (includes Ralph Mode)
• references/template-variables.md - All available variables
• references/phase-types.md - Simple vs for-each phases
• references/workflow-patterns.md - Common patterns

Assets

• assets/feature-workflow.yaml - Feature implementation template
• assets/bugfix-workflow.yaml - Bug fix template
• assets/validation-checklist.md - Pre-deployment checklist

Validation

Before using a workflow:

1. Check YAML syntax is valid
2. Verify all phase IDs are unique
3. Ensure for-each phases have workflow reference
4. Confirm referenced workflows exist in .claude/workflows/
5. Test template variables resolve correctly

Troubleshooting

Related

• orchestrating-sprints - Running and managing sprints
• creating-sprints - Creating SPRINT.yaml definitions