npm - claude-flow-novice - Versions diffs - 2.18.14 → 2.18.16 - Mend

claude-flow-novice 2.18.14 → 2.18.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1970) hide show

package/.backups/unknown/1764316266_febf5b31ea38019bbb9cb80452adb4e8/original DELETED Viewed

@@ -1,1003 +0,0 @@
-# SEO Task Mode Guide (9-Step Firecrawl Enhanced)
-**Purpose:** Execute SEO content pipeline using Task() spawning from Main Chat (no coordinator agent)
-**When to Use:**
-- Debugging SEO pipeline issues
-- Learning the 9-step Firecrawl-enhanced process
-- Single-step testing (keyword research only)
-- Development of new SEO agents
-**Cost:** $5-15 per full pipeline (Anthropic pricing for all agents)
-**Alternative:** CLI Mode via `cfn-seo-coordinator` ($1/pipeline with Z.ai routing)
-**Pipeline Version:** 9-Step Firecrawl Enhanced (4 validators)
----
-## Table of Contents
-1. [Quick Start - Full Pipeline](#quick-start-full-pipeline)
-2. [9-Step Pipeline Guide (Firecrawl Enhanced)](#9-step-pipeline-guide)
-3. [Agent Selection by Step](#agent-selection-by-step)
-4. [Sprint Workflow](#sprint-workflow)
-5. [Validation Loop (4 Validators)](#validation-loop)
-6. [Single-Step Execution](#single-step-execution)
-7. [Content Type Variations](#content-type-variations)
-8. [Programmatic SEO at Scale](#programmatic-seo-at-scale)
-9. [Troubleshooting](#troubleshooting)
----
-## Quick Start - Full Pipeline
-**Example Task:** "Write a blog post about preserving family stories for OurStories"
-**Main Chat Execution:**
-```javascript
-// Step 1: Keyword Research
-Task("seo-analytics-specialist", `
-  Perform keyword research for blog post topic: "preserving family stories"
-  Deliverables:
-  - Primary keyword (target keyword)
-  - 10-15 secondary keywords (search volume, difficulty, CPC)
-  - Long-tail keyword variations
-  - Related questions (People Also Ask)
-  Output: content/seo-data/keyword-research-family-stories.json
-  Success Criteria:
-  - Primary keyword identified with search volume data
-  - Keyword difficulty ≤60 (rankable)
-  - Mix of high-volume and low-competition keywords
-`)
-// Step 2: Competitor Analysis
-Task("competitive-seo-analyst", `
-  Analyze top 3 competitors for keyword "preserve family stories"
-  Context:
-  - Primary keyword: [from Step 1 output]
-  - Target audience: Families, genealogists
-  Deliverables:
-  - Competitor content analysis (structure, word count, headers)
-  - Backlink profiles (domain authority, backlinks count)
-  - Content gaps (what competitors miss)
-  - SERP feature analysis (featured snippets, People Also Ask)
-  Output: content/seo-data/competitor-analysis-family-stories.md
-  Success Criteria:
-  - 3 competitors analyzed
-  - Content gaps identified (≥3 opportunities)
-  - SERP features mapped
-`)
-// Step 3: Content Outline
-Task("content-seo-strategist", `
-  Create SEO-optimized content outline for "preserve family stories" blog post
-  Context:
-  - Keyword research: content/seo-data/keyword-research-family-stories.json
-  - Competitor analysis: content/seo-data/competitor-analysis-family-stories.md
-  - Brand: OurStories
-  - Target word count: 1500-2000 words
-  Deliverables:
-  - H1 title (includes primary keyword)
-  - 5-7 H2 sections
-  - H3 subsections where needed
-  - Internal linking opportunities
-  - CTA placement recommendations
-  Output: content/outlines/preserve-family-stories-outline.md
-  Success Criteria:
-  - Primary keyword in H1
-  - Secondary keywords distributed across H2s
-  - Natural flow (not keyword stuffed)
-  - Addresses user intent
-`)
-// Step 4: Research (External - Perplexity API)
-// Note: This step uses Perplexity via OpenRouter, not a CFN agent
-// Main Chat executes this directly or via a research-helper script
-// Step 5: Content Writing
-Task("content-seo-strategist", `
-  Write blog post following outline: content/outlines/preserve-family-stories-outline.md
-  Context:
-  - Outline: content/outlines/preserve-family-stories-outline.md
-  - Research sources: content/research/family-stories-research.md
-  - Brand voice: OurStories (warm, personal, empowering)
-  - Target audience: Families, genealogists, memory keepers
-  Requirements:
-  - 1500-2000 words
-  - Conversational, human tone (avoid AI language)
-  - Include personal examples/anecdotes
-  - Natural keyword integration
-  - Engaging introduction
-  - Strong CTA at end
-  Deliverables:
-  - Full blog post draft (markdown)
-  Output: content/drafts/preserve-family-stories.md
-  Success Criteria:
-  - Meets word count target
-  - Primary keyword appears 3-5 times naturally
-  - Conversational tone (no "delve into", "unlock potential")
-  - Clear value proposition
-`)
-// Step 6: SEO Optimization
-Task("technical-seo-specialist", `
-  Optimize blog post for technical SEO
-  Context:
-  - Draft: content/drafts/preserve-family-stories.md
-  - Primary keyword: "preserve family stories"
-  - Target URL: /blog/preserve-family-stories
-  Tasks:
-  1. Meta title (50-60 chars, includes primary keyword)
-  2. Meta description (150-160 chars, compelling CTA)
-  3. Header optimization (H1, H2s include keywords)
-  4. Internal linking (3-5 relevant internal links)
-  5. Image alt text recommendations
-  6. URL slug optimization
-  7. Schema markup preparation (for Step 8)
-  Deliverables:
-  - Optimized blog post (with frontmatter metadata)
-  - SEO checklist (what was optimized)
-  Output: content/optimized/preserve-family-stories.md
-  Success Criteria:
-  - Meta title ≤60 chars, includes primary keyword
-  - Meta description compelling, ≤160 chars
-  - 3-5 internal links added
-  - Headers optimized (H1 has primary keyword)
-`)
-// Step 7: Validation (3 Validators in Parallel)
-Task("humanizer-validator", `
-  Validate blog post for natural, human-like writing
-  Context:
-  - Article: content/optimized/preserve-family-stories.md
-  - Iteration: 1
-  Check for:
-  - AI-generated language patterns (red flags)
-  - Conversational tone
-  - Personal examples/anecdotes
-  - Varied sentence structure
-  Output Format:
-  - Confidence score: [0.0-1.0]
-  - Issues found (with line numbers)
-  - Specific rewrites recommended
-  Threshold: ≥0.75 to pass
-`)
-Task("branding-validator", `
-  Validate blog post alignment with OurStories brand
-  Context:
-  - Article: content/optimized/preserve-family-stories.md
-  - Brand: OurStories
-  - Iteration: 1
-  Check for:
-  - Brand voice consistency (warm, personal, empowering)
-  - Value proposition clarity
-  - Tone alignment
-  - Messaging consistency
-  Output Format:
-  - Confidence score: [0.0-1.0]
-  - Brand alignment issues
-  - Recommended adjustments
-  Threshold: ≥0.75 to pass
-`)
-Task("audience-validator", `
-  Validate blog post fit for target audience
-  Context:
-  - Article: content/optimized/preserve-family-stories.md
-  - Audience: Families, genealogists, memory keepers
-  - Iteration: 1
-  Check for:
-  - Resonance with audience pain points
-  - Appropriate complexity level
-  - Relatable examples
-  - Clear value for target personas
-  Output Format:
-  - Confidence score: [0.0-1.0]
-  - Audience fit issues
-  - Suggested improvements
-  Threshold: ≥0.75 to pass
-`)
-// Main Chat collects validator scores and calculates consensus
-// IF consensus ≥0.95 → Proceed to Step 8
-// IF consensus <0.95 → Iterate (spawn Step 5 again with validator feedback)
-// Step 8: Publishing with Schema
-Task("schema-markup-engineer", `
-  Add schema markup and prepare for publishing
-  Context:
-  - Article: content/optimized/preserve-family-stories.md
-  - URL: https://ourstories.com/blog/preserve-family-stories
-  - Author: OurStories Team
-  - Published: 2025-11-01
-  Tasks:
-  1. Add Article schema (JSON-LD)
-  2. Add BreadcrumbList schema
-  3. Add Organization schema
-  4. Validate schema with Google Rich Results Test
-  5. Final formatting (headings, lists, bold, italics)
-  Deliverables:
-  - Final blog post with embedded schema
-  - Schema validation report
-  Output: content/published/preserve-family-stories.md
-  Success Criteria:
-  - Valid Article schema (no errors in Rich Results Test)
-  - Schema includes all required properties
-  - Final formatting polished
-`)
-```
----
-## 9-Step Pipeline Guide (Firecrawl Enhanced)
-### Step 1: Keyword Research
-**Agent:** `seo-analytics-specialist`
-**Inputs:**
-- Topic/title (from user request)
-- Target audience (optional)
-**Outputs:**
-- Primary keyword (target keyword)
-- Secondary keywords (10-15 with metrics)
-- Long-tail variations
-- People Also Ask questions
-- Search intent analysis
-**Tools:**
-- DataForSEO API (keyword metrics)
-- Google Search Console (existing rankings)
-- SE Ranking (keyword suggestions)
-**Success Criteria:**
-- Primary keyword identified (search volume >100/month)
-- Keyword difficulty ≤60 (rankable)
-- Mix of head terms and long-tail
-- Search intent clear (informational/transactional/navigational)
-**Output File:** `content/seo-data/keyword-research-[topic].json`
----
-### Step 2: Competitor Analysis
-**Agent:** `competitive-seo-analyst`
-**Inputs:**
-- Primary keyword (from Step 1)
-- Target SERP position (default: top 3)
-**Outputs:**
-- Top 3 competitor analysis
-- Content structure comparison
-- Backlink profiles
-- Content gaps (what competitors miss)
-- SERP features (featured snippets, PAA, images)
-**Tools:**
-- DataForSEO API (SERP data)
-- Ahrefs API (backlink analysis)
-- SE Ranking (competitor keywords)
-**Success Criteria:**
-- 3 competitors analyzed
-- Content gaps identified (≥3 opportunities)
-- SERP features mapped
-- Competitive advantage defined
-**Output File:** `content/seo-data/competitor-analysis-[topic].md`
----
-### Step 3: SERP Analysis (Firecrawl 🔥)
-**Agent:** `serp-analyst` + Firecrawl
-**Inputs:**
-- Primary keyword (from Step 1)
-- Competitor URLs (from Step 2)
-**Outputs:**
-- SERP feature map (featured snippets, PAA, images, videos)
-- Featured snippet opportunity analysis
-- People Also Ask questions (extracted)
-- SERP gap identification
-- Content format recommendations
-**Tools:**
-- Firecrawl (dynamic SERP page rendering)
-- DataForSEO SERP API (structured data)
-**Firecrawl Usage:**
-```bash
-# Scrape Google SERP for keyword
-firecrawl scrape \
-  --url "https://google.com/search?q=${keyword}" \
-  --wait-for-selector ".g" \
-  --extract-selectors "h3,span,.related-question-pair"
-```
-**Success Criteria:**
-- Featured snippet opportunity identified (if any)
-- ≥5 People Also Ask questions extracted
-- SERP feature gaps documented
-- Content format recommendation (listicle, how-to, guide)
-**Output File:** `content/seo-data/serp-analysis-[topic].json`
----
-### Step 4: Content Outline
-**Agent:** `content-seo-strategist`
-**Inputs:**
-- Keyword research (Step 1)
-- Competitor analysis (Step 2)
-- SERP analysis (Step 3) ← NEW
-- Brand voice guidelines
-- Target word count
-**Outputs:**
-- H1 title (SEO-optimized, targets featured snippet)
-- 5-7 H2 sections (addresses PAA questions)
-- H3 subsections
-- Internal linking strategy
-- CTA placement
-**Success Criteria:**
-- Primary keyword in H1
-- Secondary keywords in H2s (natural)
-- Addresses PAA questions from SERP analysis
-- Better structure than competitors
-**Output File:** `content/outlines/[topic]-outline.md`
----
-### Step 5: Research & Citations (Firecrawl + Perplexity)
-**Agent:** `research-specialist` + Firecrawl + Perplexity
-**Inputs:**
-- Content outline (Step 4)
-- Research questions (extracted from outline)
-- Source URLs (from competitor analysis)
-**Outputs:**
-- Research sources (5-10 credible sources)
-- Key facts/statistics (with citations)
-- Expert quotes (scraped from source pages)
-- Data for content support
-**Tools:**
-- Firecrawl (source page scraping)
-- Perplexity API (fact synthesis via OpenRouter)
-- Manual research (Google Scholar, industry publications)
-**Firecrawl Usage:**
-```bash
-# Batch scrape source pages for citations
-firecrawl batch-scrape \
-  --urls "source1.com,source2.com,source3.com" \
-  --format markdown \
-  --extract-selectors "blockquote,.expert-quote,.statistic"
-```
-**Success Criteria:**
-- ≥5 credible sources cited
-- Data supports outline sections
-- Expert quotes included (where relevant)
-- All citations scraped and verified
-**Output File:** `content/research/[topic]-research.md`
-**Main Chat Execution:**
-```bash
-# Example: Research via Perplexity API
-curl https://openrouter.ai/api/v1/chat/completions \
-  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "model": "perplexity/pplx-70b-online",
-    "messages": [{
-      "role": "user",
-      "content": "Research: Best methods for preserving family stories. Include statistics, expert quotes, and credible sources."
-    }]
-  }' > content/research/family-stories-research.json
-```
----
-### Step 6: Content Writing
-**Agent:** `seo-content-writer`
-**Inputs:**
-- Outline (Step 4)
-- Research (Step 5)
-- SERP analysis (Step 3) ← incorporates SERP gaps
-- Brand voice guidelines
-- Target word count (1500-2000 for blog)
-**Outputs:**
-- Full blog post draft (markdown)
-- Keyword integration (natural)
-- SERP gap coverage
-- Engaging introduction
-- Clear CTA
-**Success Criteria:**
-- Meets word count target
-- Conversational tone (no AI language)
-- Primary keyword appears 3-5 times naturally
-- Addresses SERP gaps from Step 3
-- Includes personal examples/anecdotes
-- Clear value proposition
-**Output File:** `content/drafts/[topic].md`
----
-### Step 7: Validation Loop (4 Validators)
-**Agents (Parallel):**
-1. `humanizer-validator` (natural writing)
-2. `branding-validator` (brand alignment)
-3. `audience-validator` (persona fit)
-4. `seo-validator` (keyword density, structure) ← NEW
-**Inputs:**
-- Draft article (Step 6)
-- Iteration number
-**Outputs (Per Validator):**
-- Confidence score (0.0-1.0)
-- Issues found (with line numbers)
-- Specific rewrites recommended
-**Consensus Calculation:**
-```javascript
-// Main Chat collects scores from 4 validators
-const humanizerScore = 0.85;  // From humanizer-validator output
-const brandingScore = 0.90;   // From branding-validator output
-const audienceScore = 0.92;   // From audience-validator output
-const seoScore = 0.88;        // From seo-validator output ← NEW
-const consensus = (humanizerScore + brandingScore + audienceScore + seoScore) / 4;
-// consensus = 0.8875
-if (consensus >= 0.95) {
-  console.log("✅ Validation passed - Proceed to Step 8");
-} else {
-  console.log(`🔄 Iteration required - Consensus: ${consensus.toFixed(2)}`);
-  // Spawn Step 6 again with validator feedback
-}
-```
-**Thresholds:**
-- Individual validator: ≥0.75
-- Consensus: ≥0.95 (average of 4)
----
-### Step 8: Internal Linking
-**Agent:** `link-building-specialist`
-**Inputs:**
-- Validated article (Step 7)
-- Site content inventory
-- Existing internal link structure
-**Tasks:**
-1. Analyze existing content for link opportunities
-2. Identify 3-5 contextual internal link targets
-3. Add internal links with optimized anchor text
-4. Suggest external authority links (2-3)
-5. Validate link context and relevance
-**Success Criteria:**
-- 3-5 internal links added
-- Anchor text optimized (not over-optimized)
-- Links contextually relevant
-- No broken links
-**Output File:** `content/linked/[topic].md`
----
-### Step 9: SEO Optimization
-**Agent:** `seo-optimizer`
-**Inputs:**
-- Linked article (Step 8)
-- Primary keyword
-- Target URL
-**Tasks:**
-1. Meta title (50-60 chars, includes keyword)
-2. Meta description (150-160 chars, compelling)
-3. Header hierarchy validation (H1→H2→H3)
-4. Image alt text generation
-5. URL slug optimization
-6. Final keyword density check
-**Success Criteria:**
-- Meta title ≤60 chars, includes primary keyword
-- Meta description compelling, ≤160 chars
-- Header hierarchy valid
-- All images have alt text
-**Output File:** `content/optimized/[topic].md`
----
-### Step 9 (Final): Schema Markup (Publishing)
-**Agent:** `schema-markup-engineer`
-**Inputs:**
-- Optimized article (Step 6, or final iteration from Step 7)
-- URL
-- Author
-- Publication date
-**Tasks:**
-1. Add Article schema (JSON-LD)
-2. Add BreadcrumbList schema
-3. Add Organization schema
-4. Validate with Google Rich Results Test
-5. Final formatting
-**Success Criteria:**
-- Valid Article schema (no errors)
-- All required properties included
-- Rich Results Test passes
-**Output File:** `content/published/[topic].md`
-**Schema Example:**
-```json
-{
-  "@context": "https://schema.org",
-  "@type": "Article",
-  "headline": "Preserve Family Stories: Complete Guide for 2025",
-  "description": "Learn proven methods to preserve family stories...",
-  "author": {
-    "@type": "Organization",
-    "name": "OurStories"
-  },
-  "datePublished": "2025-11-01",
-  "dateModified": "2025-11-01",
-  "image": "https://ourstories.com/images/family-stories.jpg"
-}
-```
----
-## Agent Selection by Step (9-Step Firecrawl Pipeline)
-| Step | Primary Agent | Secondary Tool | Use When |
-|------|---------------|----------------|----------|
-| 1. Keyword Research | seo-analytics-specialist | DataForSEO API | All content types |
-| 2. Competitor Analysis | competitive-seo-analyst | Firecrawl 🔥 | Blog posts, competitive niches |
-| 3. SERP Analysis | serp-analyst | Firecrawl 🔥 | All content (featured snippets, PAA) |
-| 4. Research & Citations | research-specialist | Firecrawl + Perplexity | Research-heavy content |
-| 5. Content Writing | seo-content-writer | - | All content types |
-| 6. Validation Loop | 4 validators (parallel) | - | All content |
-| 7. Internal Linking | link-building-specialist | - | Blog posts, pillar pages |
-| 8. SEO Optimization | seo-optimizer | - | All content |
-| 9. Schema Markup | schema-markup-engineer | Rich Results Test | All content |
-**Validators (Step 6 - Parallel Execution):**
-| Validator | Focus | Threshold |
-|-----------|-------|-----------|
-| humanizer-validator | Natural writing, no AI language | ≥0.75 |
-| branding-validator | Brand voice alignment | ≥0.75 |
-| audience-validator | Persona fit, resonance | ≥0.75 |
-| seo-validator | Keyword density, structure | ≥0.75 |
-**Consensus Requirement:** ≥0.95 (average of 4 validators)
-**Additional Specialists (Use When):**
-- `local-seo-optimizer` - Location pages, GBP content
-- `programmatic-seo-engineer` - Template-based page generation (100+ pages)
-- `geo-optimization-expert` - AI search optimization, citation tracking
-- `eeat-content-auditor` - E-E-A-T compliance, expert review
----
-## Sprint Workflow
-**When to Use Sprints:**
-- Large content projects (10+ articles)
-- Multi-phase rollouts (keyword research → outline → writing)
-- Team collaboration (separate planning and execution)
-**Sprint Pattern:**
-**Sprint 1: Planning (Steps 1-3)**
-```javascript
-// Sprint Goal: Complete keyword research and outlines for 10 articles
-Task("seo-analytics-specialist", `
-  Keyword research for 10 blog post topics
-  Topics:
-  1. Preserve family stories
-  2. Digital scrapbooking
-  3. Genealogy research tips
-  [... 7 more topics ...]
-  Deliverables:
-  - content/seo-data/keyword-research-sprint-1.json (all 10 topics)
-  Success: Primary keyword identified for each topic
-`)
-Task("content-seo-strategist", `
-  Create outlines for 10 blog posts
-  Context:
-  - Keyword research: content/seo-data/keyword-research-sprint-1.json
-  Deliverables:
-  - content/outlines/sprint-1/ (10 outline files)
-  Success: Each outline has 5-7 H2 sections, keywords integrated
-`)
-```
-**Sprint 2: Writing (Steps 4-5)**
-```javascript
-// Sprint Goal: Write 10 blog post drafts
-// Main Chat spawns 10 content-seo-strategist agents (one per article)
-// Or sequentially if resource-constrained
-```
-**Sprint 3: Optimization & Publishing (Steps 6-8)**
-```javascript
-// Sprint Goal: Optimize, validate, and publish 10 articles
-// Spawn technical-seo-specialist for each article
-// Then validators in parallel
-// Finally schema-markup-engineer for publishing
-```
----
-## Validation Loop
-**Iteration Pattern:**
-**Iteration 1:**
-1. Content written (Step 5)
-2. SEO optimized (Step 6)
-3. Validators run (Step 7)
-4. Consensus calculated
-**IF Consensus <0.95:**
-**Iteration 2:**
-```javascript
-// Main Chat spawns Step 5 again with validator feedback
-Task("content-seo-strategist", `
-  Rewrite blog post addressing validator feedback
-  Context:
-  - Current draft: content/optimized/preserve-family-stories.md
-  - Validator feedback:
-    - Humanizer (0.75): Remove AI phrases ("delve into" on line 23, "unlock potential" on line 67)
-    - Branding (0.85): Strengthen OurStories value proposition in intro
-    - Audience (0.92): Add more specific examples for genealogists
-  Tasks:
-  1. Remove all AI-generated phrases
-  2. Rewrite intro with stronger OurStories messaging
-  3. Add 2-3 specific genealogy examples
-  Success: Address all validator feedback, maintain SEO optimization
-`)
-// Then re-run Step 6 (SEO Optimization) if needed
-// Then re-run Step 7 (Validation)
-```
-**Iteration 3 (if needed):**
-Repeat pattern until consensus ≥0.95
-**Iteration Limit:** 3 iterations
-- After 3 iterations, escalate to manual review or product owner decision
----
-## Single-Step Execution
-**Use Case:** Testing individual agents or debugging specific steps
-**Example: Test Keyword Research Only**
-```javascript
-Task("seo-analytics-specialist", `
-  Test keyword research for topic: "preserve family stories"
-  Deliverables:
-  - Primary keyword
-  - 10 secondary keywords
-  Output: /tmp/test-keyword-research.json
-`)
-```
-**Example: Test Validator Only**
-```javascript
-Task("humanizer-validator", `
-  Validate this sample paragraph for AI language:
-  "In today's digital age, preserving family stories has become more important than ever.
-  By leveraging modern technology, you can unlock the potential of your family's legacy
-  and embark on a journey to delve into your heritage."
-  Expected: Confidence ≤0.50 (AI language detected)
-`)
-```
----
-## Content Type Variations
-### Blog Post (Full Pipeline)
-**Steps:** 1, 2, 3, 4, 5, 6, 7, 8
-**Validators:** humanizer + branding + audience
-**Word Count:** 1500-2000
-**Focus:** Keyword optimization, natural writing, brand voice
-### Landing Page
-**Steps:** 1, 3, 5, 6, 7, 8 (skip competitor analysis, minimal research)
-**Validators:** humanizer + branding + audience
-**Word Count:** 800-1200
-**Focus:** Conversion optimization, CTA strength, schema markup
-### Product Page
-**Steps:** 1, 5, 6, 7, 8 (minimal outline, focus on schema)
-**Validators:** humanizer + audience (branding optional)
-**Word Count:** 400-800
-**Focus:** Product schema, technical SEO, conversion
-### Local Business Content
-**Steps:** 1, 3, 5, 6, 7, 8 + `local-seo-optimizer`
-**Validators:** humanizer + audience
-**Word Count:** 600-1000
-**Focus:** Local keywords, GBP integration, LocalBusiness schema
-### Programmatic SEO (100+ Pages)
-**Steps:** 1, 3, 6, 7, 8 (use templates, not custom writing)
-**Agents:** `programmatic-seo-engineer` for Step 6
-**Validators:** humanizer + audience (scaled validation)
-**Word Count:** Variable (template-driven)
-**Focus:** Template quality, duplicate content prevention, schema at scale
----
-## Troubleshooting
-### Validator Consensus Too Low
-**Problem:** Validators consistently score <0.75
-**Solutions:**
-1. Check validator instructions (are they too strict?)
-2. Review validator feedback (what specific issues?)
-3. Provide clearer brand voice guidelines
-4. Use more specific examples in writing prompt
-**Example:**
-```javascript
-// Before (vague)
-Task("content-seo-strategist", "Write blog post about family stories")
-// After (specific)
-Task("content-seo-strategist", `
-  Write blog post about preserving family stories
-  Brand Voice: Warm, personal, empowering (like talking to a family member)
-  Tone: Conversational, not academic
-  Examples: Include specific scenarios (recording grandparent interviews, digitizing photos)
-  Avoid: Corporate jargon, AI phrases, generic advice
-`)
-```
-### Keyword Research Returns No Results
-**Problem:** DataForSEO API returns no keyword data
-**Solutions:**
-1. Check API credentials (DATAFORSEO_EMAIL, DATAFORSEO_PASSWORD)
-2. Verify API quota not exceeded
-3. Try broader search terms
-4. Fallback to manual research (Google Keyword Planner, Ahrefs)
-### Schema Validation Fails
-**Problem:** Google Rich Results Test shows errors
-**Solutions:**
-1. Check required properties (headline, author, datePublished)
-2. Validate image URLs (must be absolute, not relative)
-3. Ensure date format is ISO 8601 (YYYY-MM-DD)
-4. Test schema at https://validator.schema.org/
-### Writing Too "AI-Like"
-**Problem:** Humanizer validator scores ≤0.60
-**Solutions:**
-1. Add specific examples/anecdotes to prompt
-2. Request conversational tone explicitly
-3. Provide list of AI phrases to avoid
-4. Include sample paragraphs in desired style
-**Example:**
-```javascript
-Task("content-seo-strategist", `
-  Write blog post with HUMAN, conversational tone
-  Style Guide:
-  - ✅ Use contractions (don't, can't, you'll)
-  - ✅ Address reader directly (you, your)
-  - ✅ Include specific examples (not generic advice)
-  - ❌ NO "delve into", "unlock potential", "embark on journey"
-  - ❌ NO "In today's digital age" openings
-  - ❌ NO corporate jargon
-  Example paragraph in desired style:
-  "Think about the last family gathering. Did Grandma tell that story about her first job?
-  Those stories matter. Here's how to save them before they're gone."
-`)
-```
----
-## Cost Comparison: Task Mode vs CLI Mode
-| Execution Mode | Cost/Pipeline | Use Case |
-|----------------|---------------|----------|
-| **Task Mode** (this guide) | $5-15 | Debugging, learning, single articles |
-| **CLI Mode** (cfn-seo-coordinator) | $1 | Production, bulk content, cost optimization |
-**When Task Mode Makes Sense:**
-- Learning the SEO pipeline
-- Debugging agent behavior
-- Testing new validators
-- Single-article projects (<5 articles)
-**When to Switch to CLI Mode:**
-- Production content creation
-- Bulk article generation (10+ articles)
-- Ongoing content programs
-- Cost-sensitive projects
-**Switching to CLI Mode:**
-```bash
-# Instead of Task() spawning, use coordinator
-/cfn-seo-cli "Write blog post about preserving family stories for OurStories"
-# Coordinator handles all agent spawning via CLI (Z.ai routing)
-# Same 8-step pipeline, 95% cost savings
-```
----
-## Related Documentation
-- **CLI Mode Coordinator:** `.claude/agents/cfn-seo-team/cfn-seo-coordinator.md`
-- **Agent Delegation Matrix:** `.claude/agents/cfn-seo-team/DELEGATION_MATRIX.md`
-- **Integration Requirements:** `.claude/agents/cfn-seo-team/INTEGRATION_REQUIREMENTS.md`
-- **Validator Guides:**
-  - `.claude/agents/cfn-seo-team/seo-validators/humanizer-validator.md`
-  - `.claude/agents/cfn-seo-team/seo-validators/branding-validator.md`
-  - `.claude/agents/cfn-seo-team/seo-validators/audience-validator.md`
----
-## Quick Reference: Agent Spawning by Step (9-Step Firecrawl Pipeline)
-```javascript
-// Step 1: Keyword Research
-Task("seo-analytics-specialist", "Keyword research for [topic]")
-// Step 2: Competitor Analysis (Firecrawl)
-Task("competitive-seo-analyst", `
-  Analyze competitors for [keyword]
-  Use Firecrawl to scrape top 5 SERP results
-`)
-// Step 3: SERP Analysis (Firecrawl)
-Task("serp-analyst", `
-  Extract SERP features for [keyword]
-  - Featured snippets
-  - People Also Ask
-  - Image/video packs
-  - SERP gaps
-`)
-// Step 4: Research & Citations (Firecrawl + Perplexity)
-Task("research-specialist", `
-  Research [topic] with citations
-  Use Firecrawl for source scraping
-  Use Perplexity for fact synthesis
-`)
-// Step 5: Content Writing
-Task("seo-content-writer", "Write blog post from outline with SERP gaps addressed")
-// Step 6: Validation Loop (4 validators in parallel)
-Task("humanizer-validator", "Validate [article] for natural writing")
-Task("branding-validator", "Validate [article] for brand alignment")
-Task("audience-validator", "Validate [article] for audience fit")
-Task("seo-validator", "Validate [article] for keyword density and structure")
-// Step 7: Internal Linking
-Task("link-building-specialist", "Add internal links to [article]")
-// Step 8: SEO Optimization
-Task("seo-optimizer", "Optimize [article] meta, headers, images")
-// Step 9: Schema Markup
-Task("schema-markup-engineer", "Add schema markup and publish [article]")
-```
----
-**Version:** 1.0.0
-**Last Updated:** 2025-11-01
-**Maintained By:** CFN SEO Team
-**Feedback:** Share your SEO pipeline improvements!