mbruhler/claude-orchestration/designing-syntax

Designing Custom Workflow Syntax

I design custom syntax elements following a reuse-first approach. Only create new syntax when existing patterns don't fit.

When I Activate

I activate when you:

• Need custom workflow operators
• Want specialized checkpoints
• Ask about extending syntax
• Need domain-specific patterns
• Say "I need a custom syntax for..."

Reuse-First Process

Before creating new syntax, I check:

1. Built-in syntax - ->, ||, ~>, @, [...]
2. Global syntax library - library/syntax/
3. Template definitions - Existing workflow definitions
4. Similar patterns - Adaptable existing syntax

Only create new if no match exists.

Syntax Types

Operators

Custom flow control operators.

Example: => (merge with dedup)

---
symbol: =>
description: Merge with deduplication
---
Executes left then right, removes duplicates from combined output.

Actions

Reusable sub-workflows.

Example: @deep-review

---
name: @deep-review
type: action
---
Expansion: [code-reviewer:"security" || code-reviewer:"style"] -> merge

Checkpoints

Manual approval gates with prompts.

Example: @security-gate

---
name: @security-gate
type: checkpoint
---
Prompt: Review security findings. Verify no critical vulnerabilities.

Conditions

Custom conditional logic.

Example: if security-critical

---
name: if security-critical
description: Check if changes affect security code
evaluation: Modified files in: auth/, crypto/, permissions/
---

Loops

Reusable loop patterns.

Example: retry-with-backoff(n)

---
name: retry-with-backoff
type: loop
params: [attempts]
---
Pattern: @try -> operation -> (if failed)~> wait -> @try

Design Principles

1. Intuitive - Names/symbols hint at behavior
2. Composable - Works with existing syntax
3. Self-documenting - Clear from context
4. Minimal - Only when truly needed

Best Practices

✅ DO:

• Use descriptive names (@security-gate not @check)
• Document behavior clearly
• Provide examples
• Keep composable

❌ DON'T:

• Create for one-time use
• Make too specific
• Hide too much complexity
• Duplicate existing syntax

Library Structure

library/syntax/
├── operators/          # Flow control operators
├── actions/            # Reusable sub-workflows
├── checkpoints/        # Approval gates
├── conditions/         # Custom conditionals
├── loops/              # Loop patterns
├── aggregators/        # Result combination
└── guards/             # Pre-execution checks

Related Skills

• creating-workflows: Use custom syntax in workflows
• executing-workflows: Execute workflows with custom syntax

Need custom syntax? Describe the pattern you keep repeating!