CONTENTENGINE

Builder Spec (PRD) — v1.0 — February 2026

NOT FOR HUMAN READING — See CONTENTENGINE-GUIDE.html for human steps

Source: claude.ai/chat/f7a01dae-3d5b-40d7-b3de-d37b88505625

1. Project Overview

This PRD instructs Claude Code to build an automated X/Twitter content engine consisting of n8n workflows, Supabase tables, and LLM integrations that scrape target accounts via Apify, generate engagement replies, and score draft posts against X's published algorithm weights. The system operates in two layers: Layer 1 (n8n automation) handles data ingestion and reply generation; Layer 2 (LLM API) handles content scoring and voice-matched generation.

1.1 What This System Does

Layer 1 — Data & Automation (n8n)

• Scrapes target X accounts on a daily schedule via Apify Tweet Scraper
• Stores scraped posts with engagement metrics in Supabase
• Generates 3 reply options per target post via LLM API call
• Sends daily digest of reply candidates to operator via Telegram/email
• Posts operator-approved replies via X API Free tier
• Tracks reply performance (impressions, follower delta) via periodic scrape

Layer 2 — Intelligence (LLM API)

• Scores draft posts against X's 9 algorithm-weighted ranking factors
• Generates 2 optimized alternative versions of any draft
• Applies operator voice profile (few-shot examples from top posts) to all generated content

Shared Infrastructure

• Supabase (free tier) for all persistent data
• n8n (existing instance at n8n.masterymade.com) for all automation
• Apify for X data access (no X API read tier needed)

1.2 Architecture Summary

All automation runs on existing n8n instance. Supabase provides database. No VPS, no Docker, no custom backend required. LLM calls made directly from n8n HTTP Request nodes.

1.3 Key Constraints

2. Infrastructure Specification

2.1 Resource Budget

3. Routing / Orchestration Architecture

No model cascade. Single LLM provider (Anthropic Sonnet) for all generation tasks. Routing is workflow-based via n8n, not model-based.

3.1 Workflow Routing

4. Container / Isolation Architecture

Not applicable. No containers. All execution runs within existing n8n instance. Supabase is hosted SaaS. No Docker required.

5. Security / Data Protection

Standard security practices apply. No PII handling beyond X public data. All API credentials stored in n8n's built-in credential store (encrypted at rest). Supabase Row Level Security not required for single-user deployment — add RLS in Phase 4 for multi-tenant.

6. Core Execution Engine

6.1 Workflow Definitions

6.2 WF-01 Behavior: Scrape & Ingest

1. Cron trigger fires at 6:00 AM CT daily
2. Query Supabase target_accounts table for all active targets
3. For each target: call Apify Tweet Scraper API with username, maxItems=20, date filter=last 24h
4. Parse Apify response: extract tweet ID, text, author, likes, replies, retweets, quotes, bookmarks, posted_at
5. Upsert into Supabase scraped_posts table (dedup on x_post_id)
6. Tag new posts with status='new'
7. Output count of new posts to trigger WF-02

6.3 WF-02 Behavior: Reply Generation

1. Triggered by WF-01 completion (or manual trigger)
2. Query Supabase for posts where status='new' AND replies_generated=false
3. Load operator voice profile from voice_profiles table
4. For each post (batch of up to 50):
   • Build prompt: system prompt (reply-gen.md) + voice profile + target post text + target account context
   • Call Anthropic API (claude-sonnet-4-20250514, max_tokens=500)
   • Parse response: extract 3 reply options
   • Insert into reply_candidates table with status='pending'
5. Update scraped_posts replies_generated=true
6. Trigger WF-03

6.4 WF-05 Behavior: Post Scorer

1. Triggered by webhook (POST /webhook/score-post, body: {text: "draft post"})
2. Build prompt: system prompt (post-scorer.md) + X algorithm weights + draft text
3. Call Anthropic API (claude-sonnet-4-20250514, max_tokens=1000)
4. Parse structured response:
   • 9 metric scores (1-10 each with X algorithm weights)
   • Overall weighted score
   • 3 specific improvements
   • 2 optimized alternative versions
5. Return JSON response via webhook
6. Optionally log to Supabase scored_drafts table

6.5 Prompt Specifications

Reply Generation Prompt (prompts/reply-gen.md)

SYSTEM: You generate engaging X/Twitter replies for a strategic engagement campaign.

RULES:
- Every reply must add VALUE (insight, data, experience, contrarian take)
- Never generic ("Great post!", "So true!", "This 🔥")
- Never sycophantic — speak as a peer, not a fan
- Match the operator's voice profile below
- Keep replies under 280 characters
- Generate exactly 3 options: (1) Agreement + extension, (2) Contrarian/question, (3) Personal experience/data

VOICE PROFILE:
{{voice_profile}}

TARGET POST:
Author: @{{target_username}}
Text: {{post_text}}
Engagement: {{likes}} likes, {{replies}} replies, {{retweets}} RTs

Generate 3 reply options as JSON array:
[{"type": "agree_extend", "text": "..."}, {"type": "contrarian", "text": "..."}, {"type": "experience", "text": "..."}]

Post Scorer Prompt (prompts/post-scorer.md)

SYSTEM: You are an X/Twitter algorithm expert. Score posts against X's published ranking algorithm weights.

X ALGORITHM WEIGHTS (from open-source codebase):
1. Reply Spark (weight 75): Probability of generating replies + author engagement
2. Conversation Depth (13.5): Will people click into conversation thread?
3. Profile Pull (12.0): Will readers visit the author's profile?
4. Conversation Dwell (10.0): Will people spend 2+ minutes on this?
5. Retweet Trigger (1.0): Is this shareable/quotable?
6. Favorite Factor (0.5): Is this likeable?
7. Hook Strength (custom): Does first line stop the scroll?
8. Format Score (custom): Proper line breaks, length, media potential?
9. Readability (custom): Clear, conversational, no "shout" patterns?

SCORING: Rate each metric 1-10. Weight the final score per algorithm weights above.

POST TO ANALYZE:
{{draft_text}}

Return JSON:
{
  "scores": {"reply_spark": N, "conversation_depth": N, ...},
  "weighted_total": N,
  "improvements": ["specific change 1", "specific change 2", "specific change 3"],
  "alternatives": ["optimized version 1", "optimized version 2"]
}

7. Database Schema

-- CONTENTENGINE Schema v1.0
-- Run in Supabase SQL Editor

CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

-- Target accounts for Reply Engine
CREATE TABLE target_accounts (
  id UUID DEFAULT uuid_generate_v4() PRIMARY KEY,
  x_username TEXT NOT NULL UNIQUE,
  display_name TEXT,
  follower_count INT,
  list_name TEXT DEFAULT 'default',  -- group targets by list
  priority INT DEFAULT 5,            -- 1=highest, 10=lowest
  active BOOLEAN DEFAULT true,
  notes TEXT,                         -- why this target matters
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Scraped posts from target accounts
CREATE TABLE scraped_posts (
  id UUID DEFAULT uuid_generate_v4() PRIMARY KEY,
  x_post_id TEXT NOT NULL UNIQUE,
  author_username TEXT NOT NULL,
  content TEXT NOT NULL,
  likes INT DEFAULT 0,
  replies INT DEFAULT 0,
  retweets INT DEFAULT 0,
  quotes INT DEFAULT 0,
  bookmarks INT DEFAULT 0,
  impressions INT,
  posted_at TIMESTAMPTZ,
  scraped_at TIMESTAMPTZ DEFAULT NOW(),
  replies_generated BOOLEAN DEFAULT false,
  status TEXT DEFAULT 'new',          -- new, processed, skipped
  created_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE INDEX idx_scraped_status ON scraped_posts(status);
CREATE INDEX idx_scraped_author ON scraped_posts(author_username);

-- Reply candidates (LLM-generated)
CREATE TABLE reply_candidates (
  id UUID DEFAULT uuid_generate_v4() PRIMARY KEY,
  scraped_post_id UUID REFERENCES scraped_posts(id),
  target_username TEXT NOT NULL,
  target_post_text TEXT,              -- denormalized for digest readability
  reply_type TEXT NOT NULL,           -- agree_extend, contrarian, experience
  reply_text TEXT NOT NULL,
  status TEXT DEFAULT 'pending',      -- pending, approved, rejected, posted, failed
  posted_at TIMESTAMPTZ,
  reply_x_post_id TEXT,               -- X post ID after posting
  created_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE INDEX idx_replies_status ON reply_candidates(status);

-- Reply performance tracking
CREATE TABLE reply_performance (
  id UUID DEFAULT uuid_generate_v4() PRIMARY KEY,
  reply_candidate_id UUID REFERENCES reply_candidates(id),
  impressions INT DEFAULT 0,
  likes INT DEFAULT 0,
  replies INT DEFAULT 0,
  profile_visits INT DEFAULT 0,
  follower_delta INT DEFAULT 0,       -- followers gained from this reply
  measured_at TIMESTAMPTZ DEFAULT NOW(),
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Scored drafts (post scorer history)
CREATE TABLE scored_drafts (
  id UUID DEFAULT uuid_generate_v4() PRIMARY KEY,
  draft_text TEXT NOT NULL,
  scores JSONB NOT NULL,              -- {reply_spark: 7, conversation_depth: 5, ...}
  weighted_total DECIMAL(5,2),
  improvements JSONB,                 -- ["improvement 1", "improvement 2", ...]
  alternatives JSONB,                 -- ["alt version 1", "alt version 2"]
  final_posted_text TEXT,             -- what actually got posted (if any)
  final_post_id TEXT,                 -- X post ID if posted
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Voice profile for operator
CREATE TABLE voice_profiles (
  id UUID DEFAULT uuid_generate_v4() PRIMARY KEY,
  profile_name TEXT DEFAULT 'default',
  top_posts JSONB NOT NULL,           -- array of 10-20 best performing posts as few-shot examples
  style_notes TEXT,                   -- "direct, stoic, uses metaphors, never uses emojis"
  tone_keywords JSONB,                -- ["operator", "stoic", "leveraged", "no-fluff"]
  avoid_patterns JSONB,               -- ["exclamation marks", "emoji", "hashtags"]
  active BOOLEAN DEFAULT true,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Phase 2: Own post history (populated by Apify self-scrape)
-- CREATE TABLE own_posts ( ... );
-- Phase 2: Embeddings column on scraped_posts and own_posts
-- ALTER TABLE scraped_posts ADD COLUMN embedding vector(1536);
-- Phase 2: Content ideas
-- CREATE TABLE content_ideas ( ... );

8. Human Checkpoints (CRITICAL)

9. Execution Phases

Future Extensions (NOT In Scope — Build Later)

10. Target File Structure

11. File Sync / Communication

Not applicable. No file sync required. All workflows imported directly into n8n via JSON import. SQL run directly in Supabase SQL Editor.

12. Environment Variable Template

# === CONTENTENGINE .env.template ===

# === SUPABASE ===
SUPABASE_URL=                  # https://xxxxx.supabase.co — from Supabase dashboard
SUPABASE_ANON_KEY=             # eyJ... — from Supabase Settings > API
SUPABASE_SERVICE_KEY=          # eyJ... — from Supabase Settings > API (service role)

# === APIFY ===
APIFY_TOKEN=                   # apify_api_xxxxx — from Apify Settings > Integrations

# === ANTHROPIC ===
ANTHROPIC_API_KEY=             # sk-ant-xxxxx — from console.anthropic.com

# === X / TWITTER ===
X_BEARER_TOKEN=                # AAAA... — from developer.x.com app
X_API_KEY=                     # Consumer key
X_API_SECRET=                  # Consumer secret
X_ACCESS_TOKEN=                # OAuth access token (user-level)
X_ACCESS_SECRET=               # OAuth access token secret

# === TELEGRAM ===
TELEGRAM_BOT_TOKEN=            # 123456:ABC-xxxxx — from @BotFather
TELEGRAM_CHAT_ID=              # Your personal chat ID — from @userinfobot

13. Cost Projections

13.1 Infrastructure Costs (Monthly)

13.2 Variable Costs (Usage-Based)

END OF PRD — Companion to CONTENTENGINE-GUIDE.html and CONTENTENGINE-ADR.html