self-replicating/docs/workflow-specifications.md

Workflow Specifications

Detailed specifications for all 8 autonomous workflows in the Self-Replicating Business System.

Workflow Execution Model

All workflows extend WorkflowBase which provides:

• ✅ Automatic retry logic (3 attempts with exponential backoff)
• ✅ Error handling and logging
• ✅ Database state tracking
• ✅ Alert integration
• ✅ Execution metrics

---

1. Market Validation Workflow

Type: MARKET_VALIDATION Phase: Validation (Sequential) Critical: Yes (pauses business on failure)

Purpose

Determine if a business idea is viable before investing resources.

Inputs

• Business ID
• Business idea (text)
• Business name

Process

1. Competitor Search

   • Google Custom Search API (if configured)
   • Fallback: Web scraping
   • Returns: Top 5 competitors with URLs, descriptions

2. Demand Analysis

   • Google Trends API
   • Search volume estimation
   • Trend direction (rising/stable/declining)
   • Seasonality detection

3. Claude AI Analysis

   • Combines competitor data + demand data
   • Generates viability score (0-100)
   • Identifies top 3 risks
   • Identifies top 3 opportunities
   • Makes go/no-go recommendation

4. Decision

   • Score ≥ 60 && Viable = Proceed to MVP
   • Score < 60 || Not Viable = Shutdown business

Outputs

{
  "viable": true,
  "score": 75,
  "analysis": "Strong market opportunity...",
  "risks": ["High competition", "Seasonal demand", "..."],
  "opportunities": ["Underserved niche", "Growing market", "..."],
  "competitors": [...],
  "demandData": {...}
}

Success Criteria

• Competitor search finds 2+ competitors
• Demand data shows search volume > 100/month
• Claude analysis completes within 30 seconds

---

2. MVP Development Workflow

Type: MVP_DEVELOPMENT Phase: Development (Sequential) Critical: Yes (pauses business on failure)

Purpose

Generate and deploy a functional MVP product.

Inputs

• Business ID
• Business idea
• Business name

Process

1. Code Generation

   • Claude generates Next.js 14+ code
   • Includes: Landing page, API routes, Tailwind styling
   • Returns: Map of filename → code content

2. Local Storage

   • Saves code to /data/businesses/{id}/mvp/
   • Creates directory structure
   • Writes all files
   • Generates README

3. Git Initialization (if Vercel enabled)

   • git init
   • git add .
   • git commit -m "Initial commit"

4. Deployment (if Vercel token configured)

   • Creates vercel.json
   • Runs vercel --prod
   • Extracts deployment URL

5. Database Update

   • Stores MVP URL
   • Updates status to LAUNCHING

Outputs

{
  "mvpUrl": "https://business-abc123.vercel.app",
  "filesGenerated": 8,
  "projectDir": "/data/businesses/abc123/mvp"
}

Success Criteria

• Generates minimum 5 files
• Deployment succeeds (or saves locally)
• MVP URL is accessible

---

3. Landing Page SEO Workflow

Type: LANDING_PAGE_SEO Phase: Marketing (Parallel) Critical: No

Purpose

Optimize landing page for search engines and organic traffic.

Inputs

• Business ID
• Business idea
• Target audience

Process

1. Keyword Research

   • Extract seed keywords from idea
   • Use Claude SEO Expert skill
   • Generate keyword list (10-20 keywords)

2. SEO Strategy

   • Claude generates comprehensive SEO plan
   • On-page optimization tips
   • Technical SEO checklist
   • Link building strategy

3. Content Optimization (if MVP exists)

   • Analyze current content
   • Generate optimized copy
   • Meta title (60 chars)
   • Meta description (155 chars)
   • H1, H2 tags

4. Content Calendar

   • Generate 10-20 blog post ideas
   • Keyword-focused topics
   • Publishing schedule

5. Database Update

   • Set seoOptimized = true

Outputs

{
  "keywordResearch": "...",
  "seoStrategy": "...",
  "contentIdeas": [...]
}

Success Criteria

• Keyword list generated
• SEO strategy document created
• Content calendar populated

---

4. Paid Ads Workflow

Type: PAID_ADS Phase: Marketing (Parallel) Critical: No

Purpose

Launch paid advertising campaigns on Facebook and Google.

Inputs

• Business ID
• Business idea
• Budget
• Target audience

Process

1. Facebook Ads

   • Claude Ads Expert generates strategy
   • Creates campaign via Facebook Ads API
   • Objective: CONVERSIONS
   • Budget: From business.budget or $500 default
   • Saves campaign to database

2. Google Ads

   • Claude Ads Expert generates strategy
   • Creates Search campaign via Google Ads API
   • Keywords: Extracted from idea
   • Budget: From business.budget or $500 default
   • Saves campaign to database

3. Database Update

   • Set adsActive = true
   • Set status = RUNNING_ADS

Outputs

{
  "facebook": {
    "success": true,
    "campaignId": "fb_123456",
    "strategy": "..."
  },
  "google": {
    "success": true,
    "campaignId": "google_789012",
    "strategy": "..."
  }
}

Success Criteria

• At least 1 campaign created (FB or Google)
• Campaign is active
• Budget allocated correctly

---

5. Content Marketing Workflow

Type: CONTENT_MARKETING Phase: Marketing (Parallel) Critical: No

Purpose

Create and publish SEO-optimized content.

Inputs

• Business ID
• Business idea
• Keywords

Process

1. Content Generation

   • Claude generates SEO-optimized content
   • Meta title, description
   • Headlines (H1, H2, H3)
   • 500+ word landing page copy

2. Publishing (future)

   • Publish to CMS
   • Schedule blog posts
   • Social media sharing

Outputs

{
  "contentGenerated": true,
  "contentLength": 1200
}

Success Criteria

• Content generated (500+ words)
• SEO-optimized format

---

6. Email Automation Workflow

Type: EMAIL_AUTOMATION Phase: Marketing (Parallel) Critical: No

Purpose

Set up email sequences for lead nurturing.

Inputs

• Business ID
• Business name

Process

1. Template Creation

   • Welcome email
   • Onboarding sequence (3-5 emails)
   • Drip campaign

2. Sendgrid Setup (if configured)

   • Create templates via API
   • Set up automation rules

3. Database Update

   • Set emailAutomation = true

Outputs

{
  "configured": true,
  "templates": 2
}

Success Criteria

• Templates created
• Automation configured

---

7. Analytics Setup Workflow

Type: ANALYTICS_SETUP Phase: Marketing (Parallel) Critical: No

Purpose

Install tracking and analytics for data-driven optimization.

Inputs

• Business ID
• MVP URL

Process

1. Google Analytics

   • Create GA4 property
   • Install tracking code
   • Set up conversion goals

2. Meta Pixel

   • Create Facebook Pixel
   • Install pixel code
   • Configure custom events

3. Conversion Tracking

   • Track: page views, signups, purchases
   • Configure event tracking

Outputs

{
  "googleAnalytics": {
    "configured": true,
    "trackingId": "G-XXXXXXXXXX"
  },
  "metaPixel": {
    "configured": true,
    "pixelId": "1234567890"
  }
}

Success Criteria

• GA4 tracking installed
• Pixel tracking installed
• Events configured

---

8. Optimization Loop Workflow

Type: OPTIMIZATION_LOOP Phase: Continuous (Forever) Critical: No

Purpose

Continuously optimize campaigns and budgets for maximum ROI.

Schedule

Runs every 24 hours (configurable via OPTIMIZATION_INTERVAL_MINUTES)

Inputs

• Business ID

Process

1. Metrics Collection

   • Fetch from Google Analytics
   • Fetch from Facebook Ads API
   • Fetch from Google Ads API
   • Aggregate data

2. Campaign Analysis

   • Calculate ROAS for each campaign
   • Calculate CTR, conversion rate
   • Classify performance: good/acceptable/poor

3. Budget Optimization

   • High performers (ROAS > 3): +20% budget
   • Poor performers (ROAS < 1): -30% budget
   • Record budget changes

4. Pause Underperformers

   • ROAS < 0.5: Pause campaign
   • Losing 50%+ on ad spend

5. A/B Testing (future)

   • Create ad variants
   • Test different copy/targeting

6. Metrics Recording

   • Save daily snapshot to database
   • Update business revenue

Outputs

{
  "metrics": {
    "revenue": 5000,
    "adSpend": 1500,
    "roas": 3.33
  },
  "budgetChanges": [
    {
      "campaignId": "...",
      "action": "increase_budget",
      "change": "+20%"
    }
  ],
  "pausedCampaigns": ["..."],
  "adTests": {
    "testsRunning": 2
  }
}

Success Criteria

• Metrics collected successfully
• At least 1 optimization performed
• No campaigns with ROAS < 0.5 left active

---

Workflow Dependencies

Market Validation
  └─> MVP Development
      └─> [PARALLEL]
          ├─> Landing Page SEO
          ├─> Paid Ads
          ├─> Content Marketing
          ├─> Email Automation
          └─> Analytics Setup
              └─> Optimization Loop (forever)

Error Handling

Retry Policy

• Max retries: 3
• Backoff: Exponential (2s, 4s, 8s)
• Timeout: 2 minutes per attempt

Failure Actions

Critical Workflows (1, 2):

• Pause business
• Send critical alert
• Stop lifecycle execution

Non-Critical Workflows (3-8):

• Log error
• Send warning alert
• Continue lifecycle

Recovery

Workflows can be manually re-run:

# Retry failed workflow
pnpm retry-workflow --business-id abc123 --type MARKET_VALIDATION

---

Monitoring Workflows

Database Tracking

Each workflow run creates a WorkflowRun record:

SELECT
  workflowType,
  status,
  attempts,
  error,
  completedAt - startedAt as duration
FROM "WorkflowRun"
WHERE businessId = 'abc123'
ORDER BY createdAt DESC;

Logs

# View workflow logs
docker logs srb-orchestrator | grep "MARKET_VALIDATION"

# Real-time monitoring
docker logs -f srb-orchestrator

Metrics

• Execution time (should be < 5 minutes)
• Success rate (should be > 95%)
• Retry rate (should be < 10%)

---

Extending Workflows

To add a new workflow:

1. Create file: src/workflows/09-new-workflow.ts
2. Extend WorkflowBase
3. Implement execute() method
4. Add to WorkflowExecutor map
5. Add to Prisma WorkflowType enum
6. Update orchestrator lifecycle

Example:

export class NewWorkflow extends WorkflowBase {
  protected type: WorkflowType = 'NEW_WORKFLOW';

  protected async execute(context: WorkflowContext): Promise<WorkflowResult> {
    const business = await this.getBusiness(context.businessId);

    // Your logic here

    return {
      success: true,
      data: { ... }
    };
  }
}

---

Last Updated: 2026-02-04