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)
```markdown
---
symbol: =>
description: Merge with deduplication
---
Executes left then right, removes duplicates from combined output.
```

### Actions

Reusable sub-workflows.

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

### Checkpoints

Manual approval gates with prompts.

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

### Conditions

Custom conditional logic.

Example: `if security-critical`
```markdown
---
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)`
```markdown
---
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

✅ **