Workflow Creator

Create effective workflows that guide the AI Agent through structured, repeatable tasks.

What Are Workflows?

Workflows are markdown files that define a series of steps for the Agent to follow when performing repetitive tasks. They enable:

• Consistency - Same process every time

• Efficiency - No need to re-explain steps

• Automation - Slash command invocation (e.g., /deploy )

• Documentation - Steps are version-controlled and shareable

Workflow Structure

Workflows are saved to .agent/workflows/{workflow-name}.md with this format:

description: [short description of what this workflow does]

[Workflow Title]

[Brief overview of the workflow purpose]

Prerequisites

[Optional: List any requirements before starting]

Steps

1. [First step with clear instruction]
2. [Second step]
3. [Third step] ...

Notes

[Optional: Additional context, warnings, or tips]

Workflow Creation Process

Step 1: Identify the Workflow

Ask the user:

• What repetitive task do you want to automate?

• What are the exact steps you follow each time?

• Are there any variations or conditional paths?

• What command name do you want? (e.g., /deploy , /test )

Step 2: Define Steps

Write clear, actionable steps:

• Use imperative verbs ("Run", "Create", "Check")

• Include exact commands when applicable

• Specify file paths and parameters

• Note any user inputs needed

Step 3: Add Turbo Annotations

Use annotations to auto-run safe commands:

• // turbo

• Auto-run the next step only

• // turbo-all

• Auto-run ALL steps in the workflow

Steps

1. Backup existing files

// turbo 2. Run npm install

3. Update configuration (requires user review)

// turbo 4. Run npm run build

Step 4: Validate the Workflow

Check against this list:

• Clear, descriptive name and description?

• Steps are sequential and logical?

• Commands are exact and copy-pasteable?

• Turbo annotations only on safe commands?

• Prerequisites listed if any?

• Total file under 12,000 characters?

Quick Templates

For ready-to-use templates, see references/workflow-templates.md.

Deployment Workflow

description: Deploy application to production

Deploy to Production

Prerequisites

• All tests passing
• On main branch

Steps

// turbo

1. Run tests to confirm everything passes:

   npm run test
   
   

• Build production bundle: npm run build

// turbo 3. Deploy to production:

npm run deploy

• Verify deployment by checking the live URL.

Code Review Workflow

---
description: Review a pull request systematically
---

# PR Review

## Steps

1. Fetch and checkout the PR branch:
   ```bash
   git fetch origin pull/<PR_NUMBER>/head:pr-<PR_NUMBER>
   git checkout pr-<PR_NUMBER>

- 
Review the diff for:

- Code quality and style

- Security concerns

- Test coverage

- Performance implications

- 
Run tests locally:

npm run test

- 
Provide feedback or approve the PR.

### Database Migration Workflow

```markdown
---
description: Run database migrations safely
---

# Database Migration

## Prerequisites

- Database backup completed
- Migration files ready in `migrations/`

## Steps

1. Create a backup before migration:
   ```bash
   npm run db:backup

// turbo
2. Run pending migrations:

npm run db:migrate

- 
Verify data integrity:

npm run db:verify

- 
If issues found, rollback:

npm run db:rollback

## Output Location

Workflows must be saved in `.agent/workflows/` directory:

.agent/workflows/
├── deploy.md           # /deploy command
├── test.md             # /test command
├── pr-review.md        # /pr-review command
├── db-migrate.md       # /db-migrate command
└── security-scan.md    # /security-scan command

### File Naming

- Use kebab-case: `{workflow-name}.md`
- Name becomes the slash command: `deploy.md` → `/deploy`
- Keep names short and memorable

### Frontmatter

Required YAML frontmatter:

```yaml
---
description: [Short description shown when listing workflows]
---

Managing Workflows

Listing Workflows

Scan .agent/workflows/
 to show available commands.

Invoking Workflows

User types /workflow-name
 to trigger:

- /deploy
 → .agent/workflows/deploy.md

- /test
 → .agent/workflows/test.md

Updating Workflows

When updating:

- Preserve turbo annotations unless asked to change

- Maintain step numbering

- Test commands before committing

Common Workflow Categories

Category
Examples
Description

Build/Deploy
/deploy
, /build
, /release

Compilation and deployment

Testing
/test
, /e2e
, /lint

Running test suites

Database
/db-migrate
, /db-seed
, /db-backup

Database operations

Git
/pr-review
, /release-notes

Version control tasks

Security
/security-scan
, /audit

Security checks

Maintenance
/cleanup
, /update-deps

Maintenance tasks

Development
/dev-setup
, /new-feature

Development workflows

Best Practices

- Keep steps atomic - One action per step

- Be explicit - Include exact commands, not vague instructions

- Use turbo wisely - Only on safe, non-destructive commands

- Document prerequisites - What must be true before starting

- Include rollback - How to undo if something fails

- Stay under 12K chars - Split large workflows if needed

- Version control - Workflows should be committed to git