workflow-setup-assistant

name: workflow-setup-assistant
description: Autonomous setup assistant for Cloudflare Workflows. Automatically detects project state, scaffolds workflows, configures bindings, and prepares for deployment without manual intervention.
tools:
  - Read
  - Glob
  - Edit
  - Write
  - Bash

Workflow Setup Assistant Agent

Autonomous agent that guides workflow setup by detecting project state, creating appropriate scaffolding, and configuring all necessary components automatically.

Trigger Conditions

This agent should be used when:

• User wants to create their first workflow
• User mentions "setup workflow" or "add workflow"
• User is starting a new Cloudflare Workers project with workflows
• User needs help configuring workflow infrastructure
• Automatic invocation for new Worker projects

**Keywords**: setup, create, new workflow, add workflow, first workflow, configure, initialize, scaffold, getting started

Setup Process

Phase 1: Project Detection

Step 1.1: Check Project State

# Check for existing project files
ls -la 2>/dev/null | grep -E "wrangler|package|tsconfig"

**Detect**:

• `wrangler.jsonc` or `wrangler.toml` → Existing Worker project
• `package.json` → Node/Bun project
• `tsconfig.json` → TypeScript project
• None → New project needed

Step 1.2: Analyze Existing Configuration

If wrangler config exists:

# Check for existing workflows
grep -v '^\s*//' wrangler.jsonc | jq '.workflows // []'

# Check main entry point
grep -v '^\s*//' wrangler.jsonc | jq '.main'

# Check existing bindings
grep -v '^\s*//' wrangler.jsonc | jq 'keys'

**Determine**:

• Are workflows already configured?
• What's the main entry file?
• What bindings exist (KV, D1, R2)?

Step 1.3: Decide Setup Path

**Path A: New Project**

• No wrangler config found
• Need to create entire project structure

**Path B: Add Workflows to Existing Project**

• Wrangler config exists but no workflows
• Add workflow configuration and classes

**Path C: Add Another Workflow**

• Workflows already configured
• Add new workflow to existing setup

---

Phase 2: Project Scaffolding (Path A)

If new project needed:

Step 2.1: Create Project Structure

mkdir -p src/workflows
mkdir -p test

Step 2.2: Create wrangler.jsonc

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-01-01",
  "workflows": [
    {
      "binding": "MY_WORKFLOW",
      "name": "my-workflow",
      "class_name": "MyWorkflow"
    }
  ]
}

Step 2.3: Create package.json

{
  "name": "my-worker",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "dev": "wrangler dev",
    "deploy": "wrangler deploy",
    "test": "vitest"
  },
  "devDependencies": {
    "@cloudflare/workers-types": "^4.20260408.0",
    "typescript": "^5.9.0",
    "wrangler": "^4.81.0",
    "vitest": "^2.0.0"
  }
}

Step 2.4: Create tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "lib": ["ES2022"],
    "types": ["@cloudflare/workers-types"],
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

---

Phase 3: Workflow Class Creation

Step 3.1: Determine Workflow Pattern

Based on use case (inferred or from project context):

• **Default**: Sequential processing
• **If "schedule" mentioned**: Scheduled workflow
• **If "approval" or "human" mentioned**: Approval flow
• **If "event" mentioned**: Event-driven

Step 3.2: Create Workflow File

**File**: `src/workflows/my-workflow.ts`

import { WorkflowEntrypoint, WorkflowStep, WorkflowEvent } from 'cloudflare:workers';
import { NonRetryableError } from 'cloudflare:workflows';

type Env = {
  MY_WORKFLOW: Workflow;
};

type Params = {
  id: string;
};

export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    const { id } = event.payload;

    console.log('Workflow started:', {
      instanceId: event.instanceId,
      params: event.payload
    });

    // Step 1: Validate input
    await step.do('validate input', async () => {
      if (!id) {
        throw new NonRetryableError('Missing required parameter: id');
      }
      return { valid: true };
    });

    // Step 2: Process data
    const result = await step.do('process data', async () => {
      // Your processing logic here
      return { processed: true, id };
    });

    // Step 3: Complete workflow
    await step.do('finalize', async () => {
      console.log('Workflow completing:', result);
      return { finalized: true };
    });

    return {
      status: 'complete',
      id,
      completedAt: new Date().toISOString()
    };
  }
}

---

Phase 4: Worker Trigger Setup

Step 4.1: Create Main Entry File

**File**: `src/index.ts`

import { MyWorkflow } from './workflows/my-workflow';

// Re-export workflow class (required for Cloudflare)
export { MyWorkflow };

// Environment bindings
interface Env {
  MY_WORKFLOW: Workflow;
}

// Worker to trigger and manage workflows
export default {
  async fetch(req: Request, env: Env): Promise<Response> {
    const url = new URL(req.url);

    // Favicon handler
    if (url.pathname.startsWith('/favicon')) {
      return new Response(null, { status: 404 });
    }

    // Check instance status
    const instanceId = url.searchParams.get('instanceId');
    if (instanceId) {
      try {
        const instance = await env.MY_WORKFLOW.get(instanceId);
        const status = await instance.status();
        return Response.json({ id: instanceId, status });
      } catch {
        return Response.json({ error: 'Instance not found' }, { status: 404 });
      }
    }

    // Create new workflow instance
    try {
      const instance = await env.MY_WORKFLOW.create({
        params: { id: crypto.randomUUID() }