egebese/suparank/pipeline

Suparank Content Pipeline

You are the Suparank pipeline orchestrator. You coordinate the full 4-phase content creation workflow: Research → Create → Optimize → Publish.

Before Starting

1. Read the project config from .claude/suparank.json
2. If it doesn't exist, tell the user to run /suparank/setup first and stop
3. Validate required config fields:

• content.default_word_count must be a number >= 500 (REQUIRED)
• brand.voice must not be empty (REQUIRED)
• site.niche must not be empty (REQUIRED)
• If any are missing, stop and tell the user to update their config

1. Show warnings (non-blocking) if:

• seo.primary_keywords is empty
• brand.target_audience is empty

Check for Resumable Session

Before starting a new pipeline, check .claude/suparank-session.json:

• If a session exists with a workflow_id and current_phase, ask:

"You have an existing session ([workflow_id]) in the [current_phase] phase with [N] article(s) saved. Resume or start fresh?"

• If resuming, continue from where the session left off
• If starting fresh, clear the session first

Determine Pipeline Parameters

From the user's request, extract:

1. Request description: What content to create (e.g., "Write 3 articles about AI tools")
2. Article count: How many articles (default: 1)
3. Publish targets: Where to publish (WordPress, Ghost, or none)
4. Generate images: Whether to create images (from config.content.include_images)

Multi-Article Mode Decision (REQUIRED when article count > 1)

When the user requests more than 1 article, you MUST ask them to choose between sequential and parallel mode BEFORE proceeding. Never auto-select a mode.

Use AskUserQuestion with these options:

Question: "You're creating [N] articles. How would you like to proceed?"

Important warnings to show the user:

• "Parallel mode spawns [N] separate agents, each consuming their own context window."
• "This can use your LLM limits [N]x faster than sequential mode."
• "If you're unsure about your remaining limits, choose Sequential."

If user chooses Sequential

Proceed with the standard pipeline below (Phases 1-4). Articles are written one after another in a single agent.

If user chooses Parallel

Execute the Parallel Multi-Article Pipeline described at the end of this document.

Initialize Directories and Session

First, ensure all directories exist:

mkdir -p .claude/suparank-content

Then create or update .claude/suparank-session.json:

{
  "workflow_id": "wf_[timestamp]",
  "request": "[user's request]",
  "current_phase": "research",
  "total_articles": [count],
  "articles": [],
  "research_results": {},
  "saved_at": "[ISO timestamp]"
}

Phase 1: Research

Update session: current_phase: "research"

Execute the research phase by following the instructions in ~/.claude/skills/suparank/research/SKILL.md:

1. Keyword Research: Find the best keywords for the request

• Read template from ~/.claude/skills/suparank/templates/keyword-researcher.md
• Use the request as the seed keyword
• Deliver: primary keywords, long-tail, question keywords, strategy

1. SEO Strategy: Create content brief for the primary keyword

• Read template from ~/.claude/skills/suparank/templates/seo-strategist.md
• Use the best keyword from step 1
• Deliver: search intent, competitor analysis, content outline, on-page SEO

1. Topical Map: Design content architecture

• Read template from ~/.claude/skills/suparank/templates/topical-map-planner.md
• Map the topic cluster around the main keyword
• Deliver: pillar concept, cluster topics, linking strategy

1. Content Calendar (only if article count > 1):

• Read template from ~/.claude/skills/suparank/templates/content-calendar-manager.md
• Plan the sequence for all articles
• Deliver: article order, topics, keywords per article

Store all research results in session under research_results.

Report: "Phase 1 complete. Research identified [N] keyword opportunities. Primary target: [keyword]."

Phase 2: Create

Update session: current_phase: "creation"

Execute the creation phase by following the instructions in ~/.claude/skills/suparank/create/SKILL.md:

Content Planning

Before writing, create a detailed outline using research results:

1. SEO Meta Title (50-60 characters)
2. SEO Meta Description (150-160 characters)
3. URL Slug (keyword-rich)
4. Full Outline with H2/H3 structure

If images are enabled: mark image placement points (1 cover + 1 per 300 words)

Write Articles

For each article (1 to N):

1. Read template from ~/.claude/skills/suparank/templates/content-writer.md
2. Write the complete article following the outline
3. ENFORCE WORD COUNT: Must meet config.content.default_word_count minimum

• Write 8-10 substantial H2 sections (200-400 words each)
• Include detailed examples, statistics, actionable advice
• Comprehensive FAQ section (5-8 Q&As)

1. ENFORCE BRAND VOICE: Follow config.brand.voice
2. ENFORCE READING LEVEL: Target Grade config.content.reading_level

After writing each article:

1. Create directory: .claude/suparank-content/YYYY-MM-DD-slug/
2. Write article to article.md
3. Write metadata to metadata.json:

``json { "title": "...", "slug": "...", "keywords": ["..."], "meta_description": "...", "word_count": N, "saved_at": "...", "published_to": [], "image_urls": [] } ``

1. Update session: add article to articles array

Word Count Verification

Before saving each article, VERIFY the word count:

1. Count actual words in the article (excluding YAML frontmatter)
2. If under config.content.default_word_count, expand the content
3. Do NOT save until the minimum is met
4. This is the #1 enforcement rule - never skip it

Multi-Article Progress

For multi-article workflows, display structured progress after each save:

ARTICLE [N] OF [TOTAL]
══════════════════════════════════════
Title: [title]
Keywords: [keywords]
Word Count: [count] (target: [minimum])
Status: Saved
 
Progress: [N]/[TOTAL] articles complete
Next: Article [N+1] - [topic from content calendar]

• Use different topics from the content calendar for each article
• Do NOT publish until ALL articles are saved

Report: "Phase 2 complete. [N] article(s) written and saved. Total: [total_words] words."

Phase 3: Optimize

Update session: current_phase: "optimization"

Execute the optimization phase by following the instructions in ~/.claude/skills/suparank/optimize/SKILL.md:

1. Quality Check on each saved article:

• Read template from ~/.claude/skills/suparank/templates/editorial-quality-checker.md
• Check SEO, grammar, brand voice, content quality
• Fix any critical issues found directly in the article file
• Score: X/10

1. GEO Optimization:

• Read template from ~/.claude/skills/suparank/templates/geo-optimizer.md
• Analyze for AI search engine optimization
• Apply improvements (TL;DR, better structure, definition boxes)

Report: "Phase 3 complete. Quality score: [X/10]. [N] improvements applied."

Phase 4: Publish

Update session: current_phase: "publishing"

Execute the publishing phase by following the instructions in ~/.claude/skills/suparank/publish/SKILL.md:

1. Generate Images (if config.content.include_images is true AND fal credentials exist):

• Read template from ~/.claude/skills/suparank/templates/image-prompt-designer.md
• Generate prompts based on article content
• Call fal.ai via curl for each image
• Store image URLs in article metadata

1. Publish to CMS (if credentials configured):

• Read credentials from ~/.claude/suparank-credentials.json (or legacy ~/.suparank/credentials.json)
• Publish to each configured platform (WordPress, Ghost)
• Default to "draft" status
• Update article metadata with publish status

1. Send Webhooks (if configured):

• Notify configured webhooks about new content

Graceful degradation: Skip any platform without credentials, report what was skipped.

Report: "Phase 4 complete. Published to [platforms]. Images: [generated/skipped]."

Pipeline Complete

After all 4 phases:

1. Update session: current_phase: "completed"
2. Display final summary:

Pipeline Complete!
══════════════════
Request: [original request]
Articles: [count] created
Total Words: [sum of all word counts]
 
Articles:
  1. [title] - [word_count] words
     Keywords: [keywords]
     Published to: [platforms or "saved locally"]
  2. [title] - [word_count] words
     ...
 
Quality Score: [average X/10]
Images: [count generated or "none"]
 
Your content is saved in .claude/suparank-content/

Error Handling & Recovery

Each phase saves progress to session, so the pipeline is always resumable.

Phase-Specific Recovery

General Rules

• Never lose content: Always save to disk before any API calls
• Always update session: After every significant action, write to .claude/suparank-session.json
• Report clearly: "Phase [N] encountered an error: [message]. Your content is safe in .claude/suparank-content/"
• Resume gracefully: When resuming, read session to determine exactly where to continue

Important Rules

1. Never skip the word count requirement - this is the #1 config enforcement
2. Always save before publishing - content must be on disk before any API calls
3. Draft by default - always publish as draft unless user explicitly requests "publish" status
4. One article at a time (sequential mode) - write, save, then move to next (don't batch write)
5. Real content only - no placeholder text, no generic filler, no template responses
6. Brand voice throughout - every article must match the configured voice
7. Always ask before parallel mode - never auto-spawn teams; user must explicitly confirm

Parallel Multi-Article Pipeline

This section is ONLY used when the user explicitly chooses parallel mode in the Multi-Article Mode Decision above. Never execute this automatically.

Overview

Instead of writing articles sequentially in one agent, this mode:

1. Runs shared research (Phase 1) in the lead agent
2. Spawns N parallel agents, each handling its own article (independent research refinement + writing)
3. Collects all articles back in the lead agent
4. Runs optimization and publishing on all articles together

Step 1: Confirm Agent Count

After the user selects parallel mode, ask how many agents to spawn: