# Workflow / Slash Command Definitions

> Encode complex multi-step processes as reusable workflows that any agent can execute consistently.

## When to Use

- A task involves 5+ steps that you repeat (releases, deployments, audits)
- Multiple team members (or agents) need to perform the same process
- You want to enforce a specific order of operations with quality gates
- You catch yourself typing the same sequence of commands across conversations

## The Pattern

A **workflow** is a markdown file that describes a multi-step process an AI agent can follow. In Windsurf, these live in `.windsurf/workflows/` and are triggered via `/slash-command`. In other editors, they're referenced documents.

### File Format

```markdown
---
description: Short description of what this workflow does
---

## Prerequisites

- List tools/access needed

## Steps

1. First step with exact command
2. Second step
   // turbo
3. This step is safe to auto-run (Windsurf-specific annotation)
4. Verification step
```

### Naming Conventions

Use prefixes to categorize:

| Prefix     | Scope                 | Examples                                                              |
| ---------- | --------------------- | --------------------------------------------------------------------- |
| `repo_`    | Cross-repo operations | `repo_sync-repos`, `repo_backup-main-branch`, `repo_commit-workspace` |
| `release-` | Release processes     | `release-testflight`, `release-desktop`                               |
| `test-`    | Testing workflows     | `test-ios-app`, `test-desktop-app`, `test-coverage`                   |
| (none)     | Product-specific      | `debug-service`, `docker-compose`, `start-all-services`               |

## Step-by-Step: Creating a Workflow

### 1. Identify the process

Watch for patterns in your conversations:

- "Every time I release, I forget to run tests first"
- "I always need to sync all repos before starting work"
- "The backup process has 7 steps and I mess up the order"

### 2. Write the workflow file

```markdown
---
description: Build and upload iOS app to TestFlight
---

## Pre-Flight Quality Gate

0a. Verify git working directory is clean:
git status --porcelain

0b. Compile ALL targets (catches missing files):
xcodebuild -workspace App.xcworkspace -scheme App -destination 'generic/platform=iOS' build

0c. Run pbxproj consistency check:
Compare filesystem Swift files against Xcode project references

## Build & Archive

1. Increment build number in Xcode
2. Archive: Product → Archive
3. Distribute: App Store Connect → Upload

## Post-Upload

4. Verify build appears in App Store Connect
5. Add changelog notes
6. Submit for TestFlight review
```

### 3. Add quality gates

**Key lesson from real experience:** A TestFlight workflow without a pre-flight compile check shipped a build where a Swift file was missing from the Xcode target. The bug was only discovered after upload.

**Always add quality gates before destructive/irreversible steps:**

```markdown
## Pre-Flight Quality Gate (MANDATORY)

0a. Check git is clean
0b. Compile all targets
0c. Run linter
0d. Run tests
0e. Check for secrets in staged files
```

### 4. Include troubleshooting

```markdown
## Troubleshooting

| Problem                       | Cause                      | Fix                             |
| ----------------------------- | -------------------------- | ------------------------------- |
| Build fails with missing file | File not in Xcode target   | Add to PBXSourcesBuildPhase     |
| Archive grayed out            | Wrong destination selected | Select "Any iOS Device"         |
| Upload fails                  | Expired certificate        | Renew in Apple Developer portal |
```

## Real-World Workflow Library

### Cross-Repo Workflows

**`/repo_sync-repos`** — Pull latest from all repos:

```markdown
For each repo in workspace:

1. cd <repo>
2. git stash (if dirty)
3. git pull origin main --rebase
4. git stash pop (if stashed)
5. Report status
```

**`/repo_backup-main-branch`** — Create backup branches:

```markdown
For each repo:

1. Check if backup/main-YYYY-MM-DD already exists (skip if so)
2. git branch backup/main-YYYY-MM-DD main
3. Report created branches
   NOTE: Does NOT push to remote or modify main
```

**`/repo_commit-workspace`** — Commit all repos with intelligent messages:

```markdown
For each repo with changes:

1. git diff --stat to understand changes
2. Generate commit message from diff
3. git add -A && git commit -m "<message>"
4. Report what was committed
```

### Quality Workflows

**`/production-readiness`** — Full pre-release check:

```markdown
For each repo:

1. Secret scan (scripts/secret-scan-repo.sh)
2. Lint (language-specific)
3. Type check (tsc --noEmit / mypy)
4. Tests (with coverage)
5. Build (production mode)
6. Docker build (if applicable)
7. Report pass/fail matrix
```

## Anti-Patterns

- **No quality gates** — Workflows that go straight to build/deploy without verification
- **Too granular** — A workflow for `git add && git commit` is overkill
- **Too monolithic** — A 50-step workflow should be split into composable sub-workflows
- **Hardcoded paths** — Use variables or conventions, not absolute paths
- **No troubleshooting section** — When a step fails, the agent needs recovery guidance

## Editor-Specific Notes

| Editor          | Workflow Support                                                          |
| --------------- | ------------------------------------------------------------------------- |
| **Windsurf**    | Native: `.windsurf/workflows/*.md`, triggered via `/slash-command`        |
| **Claude Code** | Reference docs: "Follow the workflow in docs/workflows/release.md"        |
| **Cursor**      | No native workflow. Use @-mentions: "@docs/workflows/release.md run this" |
| **Aider**       | Use `/read docs/workflows/release.md` then ask to follow it               |
| **Codex**       | Include workflow in task description                                      |

For non-Windsurf editors, keep workflows in `docs/workflows/` (committed, versioned) rather than `.windsurf/workflows/`.

## Related Skills

- [01 — AGENTS.md Pattern](./01-agents-md-pattern.md)
- [12 — Pre-Release Quality Gates](./12-quality-gates.md)
- [17 — Multi-Repo Coordination](./17-multi-repo-coordination.md)
