AI Pipeline

The multi-agent AI pipeline is the core of the platform. It transforms a user brief into production-ready SvelteKit code through three sequential agents.

Pipeline Flow

sequenceDiagram
    participant U as User
    participant API as Hono API
    participant P as Planner Agent
    participant I as Image Planner
    participant E as Executor Agent
    participant DB as Database

    U->>API: POST /api/generate { brief }
    API->>P: run(brief)
    P-->>API: DesignBrief
    API->>I: run(brief)
    I-->>API: ImageSpec[]
    API->>E: run(brief + images)
    E-->>API: GeneratedCode
    API->>DB: save result
    API-->>U: { projectId, preview }

Agent 1: Planner

File: src/lib/server/ai/agents/planner.ts

Input: Raw user brief (text)

Output: DesignBrief object

interface DesignBrief {
  style: 'corporate-minimal' | 'premium-editorial' | 'tech-bold' | 'warm-organic' | 'creative-expressive'
  brandPersonality: string[]       // 3–5 attributes
  targetAudience: string
  colorLogic: { primary: string; accent: string; neutral: string }
  typographyDirection: string
  sections: SectionPlan[]
  motionLevel: 'none' | 'subtle' | 'dynamic'
}

Responsibilities:

• Analyze brand context from brief
• Select appropriate design style
• Define section structure and hierarchy
• Establish visual system parameters

Agent 2: Image Planner

File: src/lib/server/ai/agents/image-planner.ts

Input: DesignBrief

Output: ImageSpec[]

interface ImageSpec {
  sectionId: string
  role: 'hero' | 'feature' | 'team' | 'background' | 'icon'
  prompt: string          // Full generation prompt with visual world prefix
  dimensions: { w: number; h: number }
  style: string           // Consistent visual world description
}

Key rule: All image prompts share a visual world prefix to ensure consistency across the entire page. This prefix is established once by the Image Planner and applied to all subsequent prompts.

Agent 3: Executor

File: src/lib/server/ai/agents/executor.ts

Input: DesignBrief + ImageSpec[]

Output: Complete code files

interface GeneratedCode {
  files: { path: string; content: string }[]
  dependencies: Record<string, string>
  setupInstructions: string
}

Responsibilities:

• Generate SvelteKit component files
• Apply design tokens from brief
• Implement responsive layouts
• Integrate Framer Motion animations
• Reference image specs for asset placeholders

MCP Integration

The Executor agent uses the Web Design Strategy MCP Server to:

• Look up tooling-stack.md before generating code (mandatory stack declaration)
• Query visual-hierarchy.md for typography/spacing rules
• Query layout-rules.md for section patterns

// Example MCP call in executor
const stack = await mcp.callTool('get_stack_for_project', { projectType: 'landing_page' })
const contrast = await mcp.callTool('calculate_contrast', { color1: '#1A6B4A', color2: '#FFFFFF' })

Error Handling

Each agent has a retry budget of 3 attempts with exponential backoff. If an agent fails after 3 attempts, the pipeline stops and returns a partial result with the error state stored in the database.

const AGENT_CONFIG = {
  maxRetries: 3,
  timeoutMs: parseInt(process.env.AI_TIMEOUT_MS ?? '30000'),
  backoffMs: [1000, 3000, 9000]
}

Context Propagation

Important

Each agent receives the full output of all previous agents. Do NOT strip fields when passing context forward — this causes data loss in the pipeline.

// ✅ Correct
const executorInput = { brief, images, ...previousContext }

// ❌ Wrong - strips generative_assets and design_system
const executorInput = { brief: brief.summary }