@lucapimenta/copy-chief-black 1.0.0

package/framework/workflows/production-workflow.yaml

@@ -0,0 +1,221 @@
+# Production Workflow — Sub-workflow for copy production
+# Defines sequential steps per deliverable type with validation chain
+# Created: 2026-02-25 (Plano 1)
+
+version: "1.0"
+name: production-workflow
+parent: helix-pipeline
+phase: production
+
+# ═══════════════════════════════════════════
+# LANDING PAGE (11 sub-tasks)
+# ═══════════════════════════════════════════
+landing_page:
+  agent: landing-page-agent
+  output: production/landing-page/
+  steps:
+    - id: hero_block
+      name: "Hero Block (Above the fold)"
+      validate: blind_critic
+      threshold: 8
+    - id: problem_block
+      name: "Problem/Pain Block"
+      validate: blind_critic
+      threshold: 8
+    - id: mechanism_block
+      name: "Mechanism Reveal Block"
+      validate: blind_critic
+      threshold: 8
+    - id: solution_block
+      name: "Solution Block"
+      validate: blind_critic
+      threshold: 8
+    - id: proof_block
+      name: "Social Proof Block"
+      validate: blind_critic
+      threshold: 8
+    - id: offer_block
+      name: "Offer/Stack Block"
+      validate: blind_critic
+      threshold: 8
+    - id: cta_block
+      name: "CTA Block"
+      validate: blind_critic
+      threshold: 8
+    - id: faq_block
+      name: "FAQ Block"
+      validate: blind_critic
+      threshold: 7
+    - id: review_lp
+      name: "Full LP Review"
+      validate: layered_review
+      layers: 3
+    - id: stress_test
+      name: "Emotional Stress Test"
+      validate: emotional_stress_test
+      threshold: 8
+    - id: final_validation
+      name: "BLACK Validation"
+      validate: black_validation
+      threshold: 8
+      human_gate: true
+
+# ═══════════════════════════════════════════
+# VSL (15 sub-tasks)
+# ═══════════════════════════════════════════
+vsl:
+  agent: production-agent
+  output: production/vsl/
+  steps:
+    - id: chapter_1
+      name: "Chapter 1 — Hook/Lead"
+      tool: write_chapter
+      validate: blind_critic
+      threshold: 8
+    - id: chapter_2
+      name: "Chapter 2 — Problem Amplification"
+      tool: write_chapter
+      validate: blind_critic
+      threshold: 8
+    - id: chapter_3
+      name: "Chapter 3 — Mechanism Reveal"
+      tool: write_chapter
+      validate: blind_critic
+      threshold: 8
+    - id: chapter_4
+      name: "Chapter 4 — Solution/Product"
+      tool: write_chapter
+      validate: blind_critic
+      threshold: 8
+    - id: chapter_5
+      name: "Chapter 5 — Social Proof"
+      tool: write_chapter
+      validate: blind_critic
+      threshold: 8
+    - id: chapter_6
+      name: "Chapter 6 — Offer/CTA"
+      tool: write_chapter
+      validate: blind_critic
+      threshold: 8
+    - id: assembly
+      name: "Full VSL Assembly"
+      type: assemble
+    - id: review_1
+      name: "Layered Review (Layer 1)"
+      validate: layered_review
+      layer: 1
+    - id: review_2
+      name: "Layered Review (Layer 2)"
+      validate: layered_review
+      layer: 2
+    - id: review_3
+      name: "Layered Review (Layer 3)"
+      validate: layered_review
+      layer: 3
+    - id: stress_test
+      name: "Emotional Stress Test"
+      validate: emotional_stress_test
+      threshold: 8
+    - id: specificity_check
+      name: "Specificity Check (Face 1 + Face 2)"
+      validate: blind_critic
+      copy_type: specificity
+      threshold: 8
+    - id: logo_test
+      name: "Logo Test"
+      validate: blind_critic
+      copy_type: logo_test
+      threshold: 8
+    - id: anti_homogeneization
+      name: "Anti-Homogeneização Check"
+      validate: emotional_stress_test
+      copy_type: genericidade
+      threshold: 8
+    - id: final_validation
+      name: "BLACK Validation"
+      validate: black_validation
+      threshold: 8
+      human_gate: true
+
+# ═══════════════════════════════════════════
+# CREATIVES (8 sub-tasks)
+# ═══════════════════════════════════════════
+creatives:
+  agent: criativos-agent
+  output: production/creatives/
+  steps:
+    - id: hooks_5
+      name: "Generate 5 Hook Variations"
+      validate: blind_critic
+      threshold: 7
+    - id: scripts_3
+      name: "Generate 3 Full Scripts"
+      validate: blind_critic
+      threshold: 8
+    - id: ugc_scripts
+      name: "Generate UGC Scripts"
+      validate: blind_critic
+      threshold: 7
+    - id: image_concepts
+      name: "Image Ad Concepts"
+      validate: blind_critic
+      threshold: 7
+    - id: review_creatives
+      name: "Full Creatives Review"
+      validate: layered_review
+      layers: 2
+    - id: stress_test
+      name: "Emotional Stress Test"
+      validate: emotional_stress_test
+      threshold: 8
+    - id: logo_test
+      name: "Logo Test (all creatives)"
+      validate: blind_critic
+      copy_type: logo_test
+      threshold: 8
+    - id: final_validation
+      name: "BLACK Validation"
+      validate: black_validation
+      threshold: 8
+
+# ═══════════════════════════════════════════
+# EMAIL SEQUENCE (6 sub-tasks)
+# ═══════════════════════════════════════════
+emails:
+  agent: production-agent
+  output: production/emails/
+  steps:
+    - id: welcome_sequence
+      name: "Welcome Sequence (3 emails)"
+      validate: blind_critic
+      threshold: 7
+    - id: nurture_sequence
+      name: "Nurture Sequence (5 emails)"
+      validate: blind_critic
+      threshold: 7
+    - id: abandon_sequence
+      name: "Cart Abandon Sequence (3 emails)"
+      validate: blind_critic
+      threshold: 8
+    - id: review_emails
+      name: "Full Email Review"
+      validate: layered_review
+      layers: 2
+    - id: stress_test
+      name: "Emotional Stress Test"
+      validate: emotional_stress_test
+      threshold: 8
+    - id: final_validation
+      name: "BLACK Validation"
+      validate: black_validation
+      threshold: 8
+
+# ═══════════════════════════════════════════
+# CONFIG
+# ═══════════════════════════════════════════
+config:
+  max_iterations_per_step: 3
+  on_threshold_fail: iterate  # iterate | skip | escalate
+  iteration_strategy: fix_and_revalidate
+  checkpoint_after_each_step: true
+  recovery_on_tool_failure: true  # Uses recovery-handler.ts

package/framework/workflows/research-dag.yaml

@@ -0,0 +1,288 @@
+# Research Pipeline — DAG Definition
+# Sprint S40.4 — DAG Pipeline Engine
+# Schema: ~/.claude/schemas/pipeline-dag.schema.yaml
+# Created: 2026-03-01
+
+id: research-pipeline
+name: "Research Pipeline"
+version: "1.0"
+description: "Audience research pipeline using the VOC Squad architecture: 5 specialized analysts running in parallel, feeding into synthesis. Ref: voc-squad.md, voc-research.md"
+
+nodes:
+  # ═══════════════════════════════════════════
+  # ENTRY — Context Loading
+  # ═══════════════════════════════════════════
+  - id: context-load
+    label: "Context Loading"
+    type: task
+    persona: "@researcher"
+    tools: []
+    status: pending
+    description: "Load niche library (biblioteca_nicho_*.md) + offer CONTEXT.md before any research begins"
+    deliverable: "CONTEXT.md"
+
+  # ═══════════════════════════════════════════
+  # VOC SQUAD — 5 Analysts in Parallel
+  # ═══════════════════════════════════════════
+  - id: voc-squad
+    label: "VOC Squad (Parallel)"
+    type: parallel_group
+    persona: "@researcher"
+    status: pending
+    parallel_members:
+      - voc-youtube
+      - voc-instagram
+      - voc-tiktok
+      - voc-reddit
+      - voc-amazon
+    description: "5 specialized analysts run concurrently. Each uses platform-specific prompts from ~/.claude/templates/agent-prompts/voc-{platform}-analyst.md. All use general-purpose subagent type for MCP access."
+
+  - id: voc-youtube
+    label: "YouTube Analyst"
+    type: task
+    persona: "@researcher"
+    tools:
+      - firecrawl_agent
+      - voc_search
+    status: pending
+    description: "Extract VOC from YouTube comments on viral content (10K+ views, 100+ comments). Focus: testimonials, timestamps, CTR patterns. Min: 50 quotes with username + engagement."
+    deliverable: "research/voc/raw/youtube-extraction.md"
+
+  - id: voc-instagram
+    label: "Instagram Analyst"
+    type: task
+    persona: "@researcher"
+    tools:
+      - firecrawl_agent
+      - voc_search
+    status: pending
+    description: "Extract VOC from Instagram Reels comments (5K+ likes). Focus: saves, shares, carousels. Min: 50 quotes with username + engagement."
+    deliverable: "research/voc/raw/instagram-extraction.md"
+
+  - id: voc-tiktok
+    label: "TikTok Analyst"
+    type: task
+    persona: "@researcher"
+    tools:
+      - firecrawl_agent
+      - voc_search
+    status: pending
+    description: "Extract VOC from TikTok comments on viral content (50K+ views). Focus: stitches, duets, trend sounds. Min: 50 quotes with username + engagement."
+    deliverable: "research/voc/raw/tiktok-extraction.md"
+
+  - id: voc-reddit
+    label: "Reddit/Forum Analyst"
+    type: task
+    persona: "@researcher"
+    tools:
+      - firecrawl_agent
+      - voc_search
+    status: pending
+    description: "Extract VOC from Reddit threads (50+ upvotes). Focus: raw unfiltered language, AMAs, throwaway accounts. Min: 50 quotes with username + engagement."
+    deliverable: "research/voc/raw/reddit-extraction.md"
+
+  - id: voc-amazon
+    label: "Amazon/Review Analyst"
+    type: task
+    persona: "@researcher"
+    tools:
+      - firecrawl_agent
+    status: pending
+    description: "Extract VOC from product reviews (1-2 stars for pain, 5 stars for desire). Verified Purchase only. Min: 30 reviews."
+    deliverable: "research/voc/raw/amazon-extraction.md"
+
+  # ═══════════════════════════════════════════
+  # COMPETITOR ANALYSIS (Parallel with VOC)
+  # ═══════════════════════════════════════════
+  - id: competitor-spy
+    label: "Ads Library Spy"
+    type: task
+    persona: "@miner"
+    tools:
+      - fb_ad_library.get_meta_platform_id
+      - fb_ad_library.get_meta_ads
+      - fb_ad_library.analyze_ad_video
+    status: pending
+    description: "Discovery-first competitor analysis. 4 levels: Nicho (Apify keyword), Sub-nicho (Apify), Mecanismo (Apify), Concorrentes diretos (MCP). Scale Score calculation for all found advertisers."
+    deliverable: "research/competitors/processed/ads-library-spy.md"
+
+  - id: competitor-summary
+    label: "Competitor Summary"
+    type: task
+    persona: "@miner"
+    tools: []
+    status: pending
+    description: "Synthesize competitor analysis: TOP 10 by Scale Score, TOP 5 videos with breakdown, patterns, gaps, recommendations"
+    deliverable: "research/competitors/summary.md"
+
+  # ═══════════════════════════════════════════
+  # VOC PROCESSING (after VOC Squad completes)
+  # ═══════════════════════════════════════════
+  - id: voc-processing
+    label: "VOC Processing & Dedup"
+    type: task
+    persona: "@researcher"
+    tools:
+      - voc_search
+    status: pending
+    description: "Merge all 5 analyst outputs. Dedup by Jaccard > 0.8. Triangulate cross-platform. Calculate DRE levels. Extract micro-unidades linguisticas (6 dimensions). Min final: 200 quotes, DRE level avg >= 3."
+    deliverable: "research/voc/processed/"
+
+  - id: voc-summary
+    label: "VOC Summary"
+    type: task
+    persona: "@researcher"
+    tools: []
+    status: pending
+    description: "Create voc/summary.md (<= 500 tokens) with: top emotions, DRE identification, key quotes (username+engagement), language patterns. Create voc/trends-analysis.md with cross-platform patterns."
+    deliverable: "research/voc/summary.md"
+
+  # ═══════════════════════════════════════════
+  # MECHANISM RESEARCH
+  # ═══════════════════════════════════════════
+  - id: mechanism-research
+    label: "Mechanism Research"
+    type: task
+    persona: "@researcher"
+    tools:
+      - firecrawl_agent
+      - firecrawl_scrape
+    status: pending
+    description: "Research scientific backing for MUP candidates. Find studies, data, expert quotes. Identify Sexy Cause candidates. Ref: primeiros-principios-copy-chief.md"
+    deliverable: "research/mechanism/summary.md"
+
+  # ═══════════════════════════════════════════
+  # AVATAR SYNTHESIS
+  # ═══════════════════════════════════════════
+  - id: avatar-synthesis
+    label: "Avatar Synthesis"
+    type: task
+    persona: "@researcher"
+    tools:
+      - voc_search
+    status: pending
+    description: "Synthesize avatar profile from VOC + competitor data: demographics, psychographics, DRE identification, awareness level, escalation levels 1-5. Extract language-patterns.md (6 micro-unidades dimensions)."
+    deliverable: "research/avatar/summary.md"
+
+  # ═══════════════════════════════════════════
+  # RESEARCH SYNTHESIS
+  # ═══════════════════════════════════════════
+  - id: research-synthesis
+    label: "Research Synthesis"
+    type: task
+    persona: "@researcher"
+    tools: []
+    status: pending
+    description: "Consolidate all research into synthesis.md: confidence score calculation, top insights, avatar summary, MUP candidates, competitor gaps. Confidence must reach >= 70% to pass gate."
+    deliverable: "research/synthesis.md"
+
+  # ═══════════════════════════════════════════
+  # EXIT GATE
+  # ═══════════════════════════════════════════
+  - id: research-gate
+    label: "Research Gate"
+    type: gate
+    persona: "@gatekeeper"
+    tools:
+      - validate_gate
+    status: pending
+    threshold: 70
+    description: "Validates all research deliverables exist and meet quality thresholds: 4 summaries, synthesis.md with confidence >= 70%, emotions categorized (35+ quotes), DRE identified."
+
+edges:
+  # Context load → VOC Squad (parallel) + Competitor Spy
+  - from: context-load
+    to: voc-squad
+    type: requires
+
+  - from: context-load
+    to: competitor-spy
+    type: requires
+
+  # VOC Squad → each analyst
+  - from: voc-squad
+    to: voc-youtube
+    type: requires
+
+  - from: voc-squad
+    to: voc-instagram
+    type: requires
+
+  - from: voc-squad
+    to: voc-tiktok
+    type: requires
+
+  - from: voc-squad
+    to: voc-reddit
+    type: requires
+
+  - from: voc-squad
+    to: voc-amazon
+    type: requires
+
+  # All VOC analysts → VOC Processing
+  - from: voc-youtube
+    to: voc-processing
+    type: produces
+
+  - from: voc-instagram
+    to: voc-processing
+    type: produces
+
+  - from: voc-tiktok
+    to: voc-processing
+    type: produces
+
+  - from: voc-reddit
+    to: voc-processing
+    type: produces
+
+  - from: voc-amazon
+    to: voc-processing
+    type: produces
+
+  # VOC Processing → VOC Summary
+  - from: voc-processing
+    to: voc-summary
+    type: produces
+
+  # Competitor spy → competitor summary
+  - from: competitor-spy
+    to: competitor-summary
+    type: produces
+
+  # VOC data → mechanism research (needs VOC to identify MUP candidates)
+  - from: voc-summary
+    to: mechanism-research
+    type: requires
+
+  # VOC data → avatar synthesis
+  - from: voc-summary
+    to: avatar-synthesis
+    type: requires
+
+  - from: competitor-summary
+    to: avatar-synthesis
+    type: requires
+
+  # All four summaries → research synthesis
+  - from: voc-summary
+    to: research-synthesis
+    type: produces
+
+  - from: competitor-summary
+    to: research-synthesis
+    type: produces
+
+  - from: mechanism-research
+    to: research-synthesis
+    type: produces
+
+  - from: avatar-synthesis
+    to: research-synthesis
+    type: produces
+
+  # Research synthesis → research gate
+  - from: research-synthesis
+    to: research-gate
+    type: produces

package/framework/workflows/research-workflow.md

@@ -0,0 +1,89 @@
+# Research Workflow
+
+> Quando e como usar subagents para pesquisa.
+> **v2.0:** general-purpose obrigatorio (custom types NAO herdam MCPs)
+
+## WARNING: Subagent Type
+
+> **SEMPRE usar `subagent_type="general-purpose"` para tasks de research.**
+> O tipo `researcher` NÃO tem acesso a MCPs (Apify, Firecrawl, Playwright) no runtime.
+> Custom subagent types recebem apenas Read, Write, WebSearch — sem ToolSearch para carregar deferred tools.
+
+## Quando Usar
+
+- Extração de VOC (Voice of Customer)
+- Análise de concorrentes
+- Pesquisa de mecanismo
+- Profiling de avatar
+- Qualquer coleta de dados externos
+
+## Como Invocar
+
+```
+Task(
+  subagent_type="general-purpose",
+  prompt="[descrição da pesquisa]
+         Oferta: [nome]
+         Tipo: [voc|competitors|mechanism|avatar]
+         Output: [caminho do arquivo]
+
+         IMPORTANTE: Use ToolSearch para carregar Apify tools antes de extrair.
+         Prioridade: Apify > Playwright > Firecrawl > WebSearch (ultimo resort)."
+)
+```
+
+## Workflow Padrão
+
+```
+1. IDENTIFICAR tipo de research necessário
+2. INVOCAR general-purpose com prompt específico + instrução de usar ToolSearch
+3. AGUARDAR retorno (caminho + summary)
+4. LER summary.md para verificar qualidade
+5. SE gaps → invocar novamente com foco específico
+6. PROSSEGUIR para próxima fase
+```
+
+## Exemplo: VOC Research
+
+```
+Task(
+  subagent_type="general-purpose",
+  prompt="Extrair VOC do YouTube para nicho concursos.
+         Oferta: hacker
+         Buscar: 'como passar em concurso público'
+         Mínimo: 50 quotes
+         Output: concursos/hacker/research/voc/raw/youtube-extraction.md
+
+         INSTRUÇÃO TÉCNICA:
+         1. Use ToolSearch para carregar Apify tools (query: 'apify youtube')
+         2. Use call-actor com actor YouTube scraper para extrair comentários REAIS
+         3. NÃO use WebSearch como primeira opção — é ÚLTIMO RESORT
+         4. Processe em batches de 15, salve em arquivo"
+)
+```
+
+## Outputs Esperados
+
+```
+{oferta}/research/{type}/
+├── raw/           ← Dados brutos (NUNCA carregar)
+├── processed/     ← Dados categorizados
+└── summary.md     ← 500 tokens (SEMPRE ler primeiro)
+```
+
+## Qualidade Mínima
+
+- 50+ quotes por plataforma
+- Confidence ≥70%
+- Gaps explicitamente identificados
+- Métricas de engagement incluídas
+
+## Próximo Passo
+
+Após research completo → Invocar `general-purpose` com prompt de synthesizer para consolidar, ou prosseguir para HELIX.
+
+---
+
+*v2.0 - Fix: researcher → general-purpose (custom types sem MCPs)*
+*BSSF Score 9.2, GBS 95%*
+*Atualizado: 2026-02-20*

package/framework/workflows/research-workflow.yaml

@@ -0,0 +1,92 @@
+# Research Workflow — Sub-workflow for audience research
+# Defines sequential steps within the research phase
+# Created: 2026-02-25 (Plano 1)
+
+version: "1.0"
+name: research-workflow
+parent: helix-pipeline
+phase: research
+
+steps:
+  - id: setup
+    name: "Load niche library + offer context"
+    type: context_load
+    files:
+      - "{nicho}/biblioteca_nicho_{nicho}_CONSOLIDADA.md"
+      - "{offer}/CONTEXT.md"
+    auto: true
+
+  - id: voc_extraction
+    name: "VOC Extraction (4 platforms)"
+    type: agent_task
+    agent: general-purpose
+    description: "Extract VOC from YouTube, TikTok, Instagram, Reddit via Apify"
+    tools_required: [firecrawl_agent, voc_search]
+    output: research/voc/
+    deliverables:
+      - summary.md
+      - trends-analysis.md
+    min_quotes: 200
+    platforms: [youtube, tiktok, instagram, reddit]
+    auto: true
+
+  - id: competitor_analysis
+    name: "Competitor Analysis (Ads Library)"
+    type: agent_task
+    agent: general-purpose
+    description: "Discovery-first competitor analysis via Apify + Meta Ads"
+    tools_required: [fb_ad_library.get_meta_ads]
+    tools_recommended: [fb_ad_library.analyze_ad_video]
+    output: research/competitors/
+    deliverables:
+      - summary.md
+      - processed/ads-library-spy.md
+    auto: true
+
+  - id: mechanism_discovery
+    name: "Mechanism Discovery"
+    type: agent_task
+    agent: general-purpose
+    description: "Discover MUP candidates from research data"
+    depends_on: [voc_extraction, competitor_analysis]
+    output: research/mechanism/
+    deliverables:
+      - summary.md
+    auto: true
+
+  - id: avatar_synthesis
+    name: "Avatar Synthesis"
+    type: agent_task
+    agent: general-purpose
+    description: "Synthesize avatar profile from VOC + competitors"
+    depends_on: [voc_extraction]
+    output: research/avatar/
+    deliverables:
+      - summary.md
+    auto: true
+
+  - id: research_synthesis
+    name: "Research Synthesis"
+    type: agent_task
+    agent: general-purpose
+    description: "Consolidate all research into synthesis.md"
+    depends_on: [voc_extraction, competitor_analysis, mechanism_discovery, avatar_synthesis]
+    output: research/
+    deliverables:
+      - synthesis.md
+    auto: true
+
+  - id: research_gate
+    name: "Research Gate Validation"
+    type: gate_validation
+    gate: research
+    tool: validate_gate
+    threshold: 70
+    depends_on: [research_synthesis]
+    auto: true
+
+config:
+  parallel_steps: [voc_extraction, competitor_analysis]
+  sequential_after: [mechanism_discovery, avatar_synthesis, research_synthesis, research_gate]
+  max_retries: 2
+  timeout_minutes: 120