---
description: "Generate SEO-optimized blog post through 9-step Firecrawl-enhanced pipeline"
argument-hint: "<target keyword> [--brand=BRAND] [--audience=AUDIENCE]"
allowed-tools: ["Task", "TodoWrite", "Read", "Write", "Bash"]
---

# SEO Blog Post Generator - Full Pipeline (Firecrawl Enhanced)

Execute complete 9-step SEO content pipeline with Firecrawl integration and 4-validator consensus ≥0.95.

🚨 **AUTONOMOUS SEO CONTENT GENERATION**

**Target Keyword**: $ARGUMENTS

## SEO Pipeline Structure (9 Steps - Firecrawl Enhanced)

```
STEP 1: Keyword Research        → seo-analytics-specialist
   ↓
STEP 2: Competitor Analysis     → competitive-seo-analyst + Firecrawl 🔥
   ↓
STEP 3: SERP Analysis           → SERP data extraction + Firecrawl 🔥
   ↓
STEP 4: Research & Citations    → research-specialist + Firecrawl + Perplexity
   ↓
STEP 5: Content Writing         → seo-content-writer
   ↓
STEP 6: Validation Loop         → 4 validators (humanizer, branding, audience, SEO)
   ↓
STEP 7: Internal Linking        → link-building-specialist
   ↓
STEP 8: SEO Optimization        → seo-optimizer
   ↓
STEP 9: Schema Markup           → schema-markup-engineer
```

## Execution Pattern

**MANDATORY: Spawn cfn-seo-coordinator agent that manages all orchestration internally.**

The coordinator uses CLI spawning (95% cost savings) via orchestrate-seo.sh skill.

### Step 1: Parse Arguments and Extract Context

```javascript
// Extract keyword from arguments
const args = "$ARGUMENTS";
const keyword = args.split('--')[0].trim();

// Parse optional parameters
const brandMatch = args.match(/--brand[=\s]+([^\s]+)/);
const audienceMatch = args.match(/--audience[=\s]+([^\s]+)/);

const brand = brandMatch ? brandMatch[1] : "default_brand";
const audience = audienceMatch ? audienceMatch[1] : "general";
```

### Step 2: Spawn SEO Coordinator (SINGLE AGENT PATTERN)

```javascript
Task("cfn-seo-coordinator", `
  SEO BLOG POST GENERATION

  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  COST OPTIMIZATION - CUSTOM ROUTING (CRITICAL)
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠️  IMPORTANT: Enable custom routing for maximum cost savings!

  1. Enable routing (one-time setup):
     /switch-api zai

  2. Verify status:
     /switch-api status

  Cost Breakdown (per blog post):
  ┌─────────────────────┬──────────────┬────────────┐
  │ Component           │ Provider     │ Cost/Call  │
  ├─────────────────────┼──────────────┼────────────┤
  │ Main Chat           │ Anthropic    │ $0.015     │
  │ SEO Coordinator     │ Anthropic    │ $0.015     │
  │ SEO Agents (CLI)    │ Z.ai         │ $0.003 ea  │
  │ Validators (CLI)    │ Z.ai         │ $0.003 ea  │
  └─────────────────────┴──────────────┴────────────┘

  Expected Costs:
  • WITH custom routing:    ~$1.00 per blog post (10 agents)
  • WITHOUT custom routing: ~$15.00 per blog post
  • Savings:                93% cost reduction

  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  BLOG POST SPECIFICATION
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Target Keyword: ${keyword}
  Content Type: blog
  Brand: ${brand}
  Target Audience: ${audience}
  Word Count: 1500-2000
  Task ID: seo-blog-$(date +%s)
  Mode: STANDARD (validator: 0.75, consensus: 0.95)

  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  SUCCESS CRITERIA (BLOG POST REQUIREMENTS)
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  SEO Requirements:
  - [ ] Target keyword in H1, meta title, meta description
  - [ ] Keyword density 1-2%
  - [ ] 3-5 internal links to related content
  - [ ] 2-3 external authoritative citations
  - [ ] 1 image per 300 words (optimized alt text)
  - [ ] FAQ schema markup included

  Content Quality:
  - [ ] Natural, human-like writing (humanizer score ≥0.75)
  - [ ] Brand voice alignment (branding score ≥0.75)
  - [ ] Audience persona fit (audience score ≥0.75)
  - [ ] Consensus ≥0.95 from all 3 validators
  - [ ] No AI tell-tale phrases
  - [ ] Conversational tone with personal examples

  Structure:
  - [ ] Compelling H1 (target keyword)
  - [ ] Clear H2/H3 hierarchy (5-7 sections)
  - [ ] Introduction with hook
  - [ ] Actionable takeaways
  - [ ] FAQ section (3-5 questions)
  - [ ] Clear CTA

  Technical:
  - [ ] Meta title <60 characters
  - [ ] Meta description 150-160 characters
  - [ ] Schema markup validated
  - [ ] Mobile-friendly formatting

  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  9-STEP PIPELINE AGENTS (Firecrawl Enhanced)
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Step 1 - Keyword Research:
  - seo-analytics-specialist (DataForSEO API)
  - Output: primary keyword, secondaries, search volume, difficulty

  Step 2 - Competitor Analysis (Firecrawl 🔥):
  - competitive-seo-analyst + Firecrawl scraping
  - Crawl top 5 SERP results for content structure
  - Extract: word count, headers, backlinks, content gaps

  Step 3 - SERP Analysis (Firecrawl 🔥):
  - Dedicated SERP feature extraction
  - Featured snippets, People Also Ask, images
  - Firecrawl for dynamic SERP rendering
  - Output: SERP opportunity map

  Step 4 - Research & Citations (Firecrawl + Perplexity):
  - research-specialist agent
  - Firecrawl for source page scraping
  - Perplexity API for fact synthesis
  - Output: 5-10 citations with quotes

  Step 5 - Content Writing:
  - seo-content-writer (1500-2000 words)
  - Incorporates SERP gaps from Step 3
  - Uses citations from Step 4

  Step 6 - Validation Loop (4 Validators, Parallel):
  - humanizer-validator (natural writing ≥0.75)
  - branding-validator (brand voice ≥0.75)
  - audience-validator (persona fit ≥0.75)
  - seo-validator (keyword density, structure ≥0.75) ← NEW
  - CONSENSUS THRESHOLD: ≥0.95 (average of 4)

  Step 7 - Internal Linking:
  - link-building-specialist
  - Analyze existing content for link opportunities
  - Add 3-5 contextual internal links
  - Suggest external authority links

  Step 8 - SEO Optimization:
  - seo-optimizer
  - Meta title/description optimization
  - Header hierarchy validation
  - Image alt text generation
  - URL slug optimization

  Step 9 - Schema Markup:
  - schema-markup-engineer
  - Article schema (JSON-LD)
  - FAQ schema from content
  - BreadcrumbList schema
  - Validate with Rich Results Test

  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  EXECUTION INSTRUCTIONS
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  1. INVOKE SEO ORCHESTRATOR (Firecrawl-Enhanced):
     ./.claude/skills/seo-orchestration/orchestrate-seo.sh \\
       --task-id "seo-blog-$(date +%s)" \\
       --target-keyword "${keyword}" \\
       --content-type "blog" \\
       --brand "${brand}" \\
       --audience "${audience}" \\
       --mode "standard" \\
       --max-iterations 3 \\
       --word-count 1500-2000 \\
       --enable-firecrawl true \\
       --validators 4

  2. FIRECRAWL INTEGRATION PATTERN:
     # Step 2: Competitor scraping
     firecrawl scrape --url "$COMPETITOR_URL" --format markdown

     # Step 3: SERP rendering
     firecrawl scrape --url "https://google.com/search?q=${keyword}" \\
       --wait-for-selector ".g" --extract-selectors "h3,span"

     # Step 4: Source page extraction
     firecrawl batch-scrape --urls "$SOURCE_URLS" --format markdown

  3. VALIDATION ITERATION PATTERN (4 Validators):
     - Spawn 4 validators in parallel (humanizer, branding, audience, SEO)
     - Calculate consensus (average of 4 scores)
     - IF consensus < 0.95 && iteration < 3:
       - Collect feedback from all validators
       - Respawn seo-content-writer with feedback
       - Re-run 4 validators
     - IF consensus ≥ 0.95 || iteration == 3:
       - Proceed to Step 7 (internal linking)

  3. MONITOR PROGRESS (Redis):
     redis-cli GET "seo:task:${TASK_ID}:status"
     redis-cli HGETALL "seo:task:${TASK_ID}:validation:scores"
     redis-cli LRANGE "seo:task:${TASK_ID}:logs" 0 -1

  4. REPORT STRUCTURED RESULT:
     {
       "taskId": "seo-blog-XXXXX",
       "keyword": "${keyword}",
       "status": "complete|failed",
       "finalArticlePath": "content/blog/YYYY-MM-DD-slug.md",
       "validation": {
         "iterations": N,
         "finalConsensus": 0.XX,
         "scores": {
           "humanizer": 0.XX,
           "branding": 0.XX,
           "audience": 0.XX
         }
       },
       "seo": {
         "wordCount": XXXX,
         "keywordDensity": "X.X%",
         "internalLinks": N,
         "externalLinks": N,
         "images": N,
         "schemaMarkup": true
       },
       "recommendations": [...]
     }

  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  CRITICAL RULES
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  - DO NOT spawn agents with Task()
  - LET orchestrator handle CLI spawning
  - USE Redis for all agent coordination
  - STORE context in seo:task:${TASK_ID}:context
  - RETURN structured result to Main Chat
  - ITERATE automatically on consensus failure (max 3)
`, "cfn-seo-coordinator")
```

### Step 3: Coordinator Autonomous Execution

The coordinator runs orchestrate-seo.sh internally:

**Sequential Execution:**
1. Keyword research (DataForSEO API)
2. Competitor analysis (SERP top 5)
3. Outline creation (H1/H2/H3)
4. Research & citations (Perplexity)
5. Content writing (1500-2000 words)
6. SEO optimization (meta, links)
7. **Validation loop** (3 validators, iterate if consensus < 0.95)
8. Publishing prep (schema markup)

**Validation Loop Details (4 Validators):**
```bash
# Spawn 4 validators in parallel
npx cfn-spawn humanizer-validator --task-id $TASK_ID &
npx cfn-spawn branding-validator --task-id $TASK_ID &
npx cfn-spawn audience-validator --task-id $TASK_ID &
npx cfn-spawn seo-validator --task-id $TASK_ID &
wait

# Collect scores from Redis
HUMANIZER_SCORE=$(redis-cli HGET "seo:task:${TASK_ID}:validation:scores" "humanizer")
BRANDING_SCORE=$(redis-cli HGET "seo:task:${TASK_ID}:validation:scores" "branding")
AUDIENCE_SCORE=$(redis-cli HGET "seo:task:${TASK_ID}:validation:scores" "audience")
SEO_SCORE=$(redis-cli HGET "seo:task:${TASK_ID}:validation:scores" "seo")

# Calculate consensus (average of 4)
CONSENSUS=$(echo "scale=2; ($HUMANIZER_SCORE + $BRANDING_SCORE + $AUDIENCE_SCORE + $SEO_SCORE) / 4" | bc)

# Iterate if needed
if (( $(echo "$CONSENSUS < 0.95" | bc -l) )) && [ $ITERATION -lt 3 ]; then
  # Collect feedback from all 4 validators
  FEEDBACK=$(redis-cli LRANGE "seo:task:${TASK_ID}:validation:feedback" 0 -1)

  # Rewrite with feedback
  npx cfn-spawn seo-content-writer \
    --task-id $TASK_ID \
    --context "Rewrite based on feedback: $FEEDBACK"

  # Re-run 4 validators
  # (repeat validation loop)
fi

# After validation passes, proceed to Steps 7-9
npx cfn-spawn link-building-specialist --task-id $TASK_ID  # Step 7
npx cfn-spawn seo-optimizer --task-id $TASK_ID              # Step 8
npx cfn-spawn schema-markup-engineer --task-id $TASK_ID     # Step 9
```

## Autonomous Execution Rules

**YOU ARE FORBIDDEN FROM:**
- ❌ Asking "Should I retry validation?" (ALWAYS retry if iteration < 3)
- ❌ Asking "Proceed to next step?" (AUTO-PROCEED after each step)
- ❌ Waiting for approval during pipeline execution

**YOU MUST:**
- ✅ IMMEDIATELY rewrite on low consensus (iteration < 3)
- ✅ AUTOMATICALLY iterate with validator feedback
- ✅ ONLY escalate when truly blocked (API failure, max iterations)

## Example Execution (9-Step Firecrawl Pipeline)

```
[Step 1] Keyword Research - COMPLETE
         → Primary: "preserve family stories" (4,400/month)
         → Competition: 0.45 (medium)
         → Related keywords: 12 identified
         → Search intent: Informational

[Step 2] Competitor Analysis (Firecrawl 🔥) - COMPLETE
         → Top 5 URLs scraped via Firecrawl
         → Average word count: 1,800
         → Header patterns extracted
         → Content gaps: video guides, templates, tools comparison

[Step 3] SERP Analysis (Firecrawl 🔥) - COMPLETE
         → Featured snippet opportunity: "How to record..." format
         → People Also Ask: 8 questions captured
         → Image pack present (need hero image)
         → SERP gap: No video carousel results

[Step 4] Research & Citations (Firecrawl + Perplexity) - COMPLETE
         → 7 sources scraped via Firecrawl
         → 5 citations synthesized via Perplexity
         → 3 statistics with sources
         → Expert quote from StoryCorps

[Step 5] Content Writing - COMPLETE
         → 1,687 words written
         → 1.8% keyword density
         → SERP gaps addressed
         → Citations integrated

[Step 6] Validation Loop (4 Validators) - Iteration 1/3
         → Humanizer: 0.72 ❌ (AI phrases detected)
         → Branding: 0.88 ✅
         → Audience: 0.81 ✅
         → SEO: 0.85 ✅ (missing alt text)
         → Consensus: 0.815 (below 0.95)
         → IMMEDIATELY rewriting with feedback...

[Step 6] Validation Loop (4 Validators) - Iteration 2/3
         → Humanizer: 0.91 ✅
         → Branding: 0.93 ✅
         → Audience: 0.89 ✅
         → SEO: 0.94 ✅
         → Consensus: 0.917 (still below 0.95)
         → IMMEDIATELY rewriting with feedback...

[Step 6] Validation Loop (4 Validators) - Iteration 3/3
         → Humanizer: 0.95 ✅
         → Branding: 0.96 ✅
         → Audience: 0.95 ✅
         → SEO: 0.97 ✅
         → Consensus: 0.957 ✅ PASSED

[Step 7] Internal Linking - COMPLETE
         → 4 internal links added
         → Link context validated
         → Anchor text optimized

[Step 8] SEO Optimization - COMPLETE
         → Meta title: 58 characters ✅
         → Meta description: 156 characters ✅
         → Header hierarchy: H1→H2→H3 valid
         → 5 images with alt text

[Step 9] Schema Markup - COMPLETE
         → Article schema (JSON-LD) ✅
         → FAQ schema (5 questions) ✅
         → BreadcrumbList schema ✅
         → Rich Results Test: PASSED
         → Final: content/blog/2025-11-01-preserve-family-stories.md
```

## API Credentials Required

Ensure these are in `.env`:

```bash
# Firecrawl (Competitor/SERP Scraping) - REQUIRED for 9-step pipeline
FIRECRAWL_API_KEY=fc-xxxxx

# DataForSEO (Keyword Research + SERP)
DATA_FOR_SEO_API_KEY=base64_encoded_login:password

# Perplexity (Research via OpenRouter)
OPENROUTER_API_KEY=sk-or-v1-xxxxx

# Optional: Pexels (Stock Images)
PEXELS_API_KEY=xxxxx
```

## Firecrawl Integration Details

```bash
# Install Firecrawl CLI
npm install -g firecrawl

# Verify installation
firecrawl --version

# Test scraping
firecrawl scrape --url "https://example.com" --format markdown
```

**Firecrawl Usage by Step:**
| Step | Firecrawl Function | Rate Limit |
|------|-------------------|------------|
| 2 | `scrape` (5 competitor URLs) | 5 req/min |
| 3 | `scrape` (SERP page) | 1 req/min |
| 4 | `batch-scrape` (source pages) | 10 req/min |

## Output Format

Concise, structured result:

```
✅ SEO Blog Post Complete

Keyword: "how to preserve family stories"
Final Article: content/blog/2025-11-01-preserve-family-stories.md

Validation Results:
- Humanizer: 0.95 ✅
- Branding: 0.96 ✅
- Audience: 0.95 ✅
- Consensus: 0.95 ✅ (3 iterations)

SEO Metrics:
- Word Count: 1,687
- Keyword Density: 1.8%
- Internal Links: 4
- External Links: 3
- Images: 5 (optimized)
- Schema: Article + FAQ ✅

Ready for publishing!
```

## Usage Examples

```bash
# Basic (uses default brand/audience)
/seo-blog "how to preserve family stories"

# With brand specification
/seo-blog "how to preserve family stories" --brand=ourstories

# With brand and audience
/seo-blog "genealogy research tips" --brand=ourstories --audience=family_historian

# Long-tail keyword
/seo-blog "best ways to record elderly relatives stories"
```

## Troubleshooting

**Validation fails after 3 iterations:**
- Review validator feedback in Redis: `redis-cli LRANGE "seo:task:${TASK_ID}:validation:feedback" 0 -1`
- Common issues: AI phrases, weak brand voice, persona mismatch
- Manual review required at this point

**API failures:**
- DataForSEO: Check API key encoding (base64)
- Perplexity: Verify OpenRouter credit balance
- Fallback: Use manual keyword research if APIs fail

**Cost concerns:**
- Verify custom routing enabled: `/switch-api status`
- Without Z.ai routing: $15/article vs $1/article

## Related Commands

- `/seo-landing` - Landing page pipeline (6 steps, no competitor analysis)
- `/seo-product` - Product page pipeline (5 steps, schema focus)
- `/seo-local` - Local business content (+ local-seo-optimizer)