Claude Code Multi-Agent Team on Railway

Main Claude Agent SDK process that decomposes tasks, assigns to specialists, and manages coordination.

Service: Railway (Node.js)

Bull queue for task distribution with priorities, retries, and dead letter handling.

Service: Railway Redis

Claude Code agent for UI/UX tasks: components, styling, accessibility, and frontend testing.

Service: Railway (Docker)

Claude Code agent for API/database tasks: endpoints, migrations, business logic, and integrations.

Service: Railway (Docker)

Claude Code agent for test coverage: unit tests, integration tests, E2E, and regression suites.

Service: Railway (Docker)

Claude Code agent for docs/README: API docs, architecture diagrams, changelogs, and guides.

Service: Railway (Docker)

Isolated working directories per agent — one worktree per specialist to avoid merge conflicts.

Service: Railway Volume

Supabase for cross-agent coordination: task status, handoffs, decisions log, and conflict resolution.

Service: Supabase

CI/CD pipeline for agent PRs: linting, tests, type checks, and auto-merge on green.

Service: GitHub

Deploy the orchestrator, Redis queue, and task decomposition logic

Deploy 4 specialist agents with domain-specific prompts and tools

Wire up shared state, git worktrees, and GitHub Actions integration

Orchestrator Task Decomposition

Orchestrator that decomposes a user goal into specialist tasks and pushes to Redis queue

import { query } from '@anthropic-ai/claude-agent-sdk'
import { Queue } from 'bullmq'
import { createClient } from '@supabase/supabase-js'

const taskQueue = new Queue('agent-tasks', {
  connection: { url: process.env.REDIS_URL! },
})

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_KEY!
)

interface SpecialistTask {
  specialist: 'frontend' | 'backend' | 'test' | 'docs'
  title: string
  description: string
  worktree: string
  dependencies: string[]
}

export async function decomposeGoal(goal: string, sessionId: string) {
  const decomposition = query({
    prompt: `Decompose this development goal into specialist tasks.

Goal: ${goal}

Output a JSON array of tasks. Each task must specify:
- specialist: one of 'frontend', 'backend', 'test', 'docs'
- title: short task title
- description: detailed requirements
- dependencies: array of task titles that must complete first

Respect parallelism where possible. Tests depend on implementation. Docs depend on everything.`,
    options: {
      systemPrompt: 'You are an orchestrator that decomposes development goals into parallel specialist tasks.',
      outputFormat: 'json',
    },
  })

  let tasks: SpecialistTask[] = []
  for await (const msg of decomposition) {
    if (msg.type === 'result') {
      tasks = JSON.parse(msg.result)
    }
  }

  // Persist and enqueue
  await supabase.from('sessions').insert({
    id: sessionId,
    goal,
    task_count: tasks.length,
    status: 'in_progress',
  })

  for (const task of tasks) {
    const worktree = `/worktrees/${sessionId}/${task.specialist}`
    await taskQueue.add(
      task.specialist,
      { ...task, sessionId, worktree },
      {
        priority: task.dependencies.length === 0 ? 1 : 2,
        attempts: 3,
        backoff: { type: 'exponential', delay: 5000 },
      }
    )
  }

  return { sessionId, taskCount: tasks.length }
}

Specialist Agent Worker

Worker process for a specialist agent that pulls from queue and runs Claude Code

import { Worker } from 'bullmq'
import { query } from '@anthropic-ai/claude-agent-sdk'
import { execSync } from 'node:child_process'

const SPECIALIST = process.env.SPECIALIST_ROLE! // 'frontend' | 'backend' | 'test' | 'docs'

const systemPrompts: Record<string, string> = {
  frontend: 'You are a frontend specialist. Focus on React components, Tailwind, accessibility (WCAG 2.2), and responsive design.',
  backend: 'You are a backend specialist. Focus on API design, database migrations, business logic, and integration.',
  test: 'You are a test specialist. Write comprehensive tests: unit, integration, and E2E with Playwright.',
  docs: 'You are a documentation specialist. Write clear READMEs, API docs, and architecture diagrams.',
}

const worker = new Worker(
  'agent-tasks',
  async (job) => {
    const { title, description, worktree, sessionId } = job.data

    // Create isolated worktree
    execSync(`git worktree add ${worktree} -b ${SPECIALIST}/${sessionId}`, { cwd: '/repo' })

    // Run Claude Code agent in worktree
    const result = query({
      prompt: `${title}\n\n${description}`,
      options: {
        cwd: worktree,
        systemPrompt: systemPrompts[SPECIALIST],
        allowedTools: ['Read', 'Write', 'Edit', 'Bash', 'Grep', 'Glob'],
      },
    })

    for await (const msg of result) {
      if (msg.type === 'result') {
        // Commit and push branch
        execSync(`git add -A && git commit -m 'feat(${SPECIALIST}): ${title}'`, { cwd: worktree })
        execSync(`git push origin ${SPECIALIST}/${sessionId}`, { cwd: worktree })
        return { success: true, branch: `${SPECIALIST}/${sessionId}` }
      }
    }
  },
  {
    connection: { url: process.env.REDIS_URL! },
    concurrency: 1, // One task at a time per specialist
  }
)

worker.on('completed', (job) => console.log(`${SPECIALIST} completed task ${job.id}`))
worker.on('failed', (job, err) => console.error(`${SPECIALIST} failed task ${job?.id}:`, err))