create-hq 5.0.0

package/template/workers/content-sales/skills/cta-audit.md

@@ -0,0 +1,107 @@
+# Skill: CTA Audit
+
+Detailed analysis of call-to-action elements across page.
+
+## Input
+
+Page content JSON with extracted CTAs.
+
+## Process
+
+1. **Inventory all CTAs**
+   - Buttons
+   - Text links
+   - Form submissions
+   - Navigation prompts
+
+2. **Classify each CTA**
+   - Type (primary, secondary, tertiary)
+   - Goal (demo, signup, learn more)
+   - Commitment level (high, medium, low)
+
+3. **Evaluate each CTA**
+   - Copy effectiveness
+   - Visual prominence
+   - Placement strategy
+   - Context appropriateness
+
+4. **Assess overall strategy**
+   - CTA density
+   - Variety balance
+   - Journey alignment
+   - Conflict detection
+
+## CTA Evaluation Criteria
+
+### Copy Quality
+- **Excellent**: Benefit-driven, specific outcome ("Start Saving 40% Today")
+- **Good**: Action-oriented with context ("Get Your Free Demo")
+- **Adequate**: Clear but generic ("Request Demo")
+- **Poor**: Vague or passive ("Submit", "Click Here")
+
+### Visual Prominence
+- **Excellent**: High contrast, ample whitespace, prominent size
+- **Good**: Noticeable, clear hierarchy
+- **Adequate**: Visible but not prominent
+- **Poor**: Hard to find, blends with content
+
+### Placement
+- **Excellent**: At decision points, after value established
+- **Good**: Strategically placed, good density
+- **Adequate**: Present but not optimal
+- **Poor**: Misplaced, too early/late, wrong context
+
+## CTA Best Practices
+
+### Primary CTA
+- One per viewport
+- High contrast color
+- Benefit-driven copy
+- After value proposition
+
+### Secondary CTA
+- Lower commitment option
+- Complement primary
+- Text link or ghost button
+- Different action/audience
+
+### Micro-CTAs
+- Content engagement
+- Social sharing
+- Navigation helpers
+- Lead nurturing
+
+## Output
+
+```yaml
+cta_audit:
+  total_count: 6
+  breakdown:
+    primary: 2
+    secondary: 3
+    tertiary: 1
+  inventory:
+    - text: "Get a Demo"
+      type: "primary"
+      location: "hero"
+      rating: "A"
+      notes: "Well-placed, clear action"
+    - text: "Learn More"
+      type: "secondary"
+      location: "features"
+      rating: "C"
+      notes: "Generic copy, could be more specific"
+    - text: "Submit"
+      type: "primary"
+      location: "form"
+      rating: "D"
+      notes: "Generic, no benefit stated"
+  issues:
+    - "Two primary CTAs compete in hero section"
+    - "Form CTA uses generic 'Submit' text"
+    - "No CTA in pricing section"
+  recommendations:
+    - "Change 'Submit' to 'Start My Free Trial'"
+    - "Add secondary CTA to pricing comparison"
+    - "Consolidate hero CTAs to single primary"
+```

package/template/workers/content-sales/skills/value-prop-check.md

@@ -0,0 +1,114 @@
+# Skill: Value Proposition Check
+
+Assess value proposition clarity, differentiation, and impact.
+
+## Input
+
+- Page content JSON
+- Brand messaging guidelines
+- Competitor positioning (if available)
+
+## Process
+
+1. **Identify value proposition elements**
+   - Headline/tagline
+   - Subheadline
+   - Supporting points
+   - Proof elements
+
+2. **Evaluate core components**
+   - What: Product/service clarity
+   - Who: Target audience specificity
+   - Why: Benefit articulation
+   - How: Differentiation
+
+3. **Assess communication**
+   - Clarity (instantly understood?)
+   - Specificity (concrete vs vague?)
+   - Credibility (provable?)
+   - Memorability (sticky?)
+
+4. **Score effectiveness**
+   - Component presence
+   - Communication quality
+   - Strategic alignment
+
+## Value Proposition Framework
+
+### Essential Components
+
+| Component | Question | Good Example | Bad Example |
+|-----------|----------|--------------|-------------|
+| What | What do you offer? | "AI-powered banking assistant" | "Next-gen solution" |
+| Who | Who is it for? | "Community banks and credit unions" | "Businesses everywhere" |
+| Why | Why does it matter? | "Reduce call center volume 40%" | "Transform your operations" |
+| How | How is it different? | "Only AI trained on banking regulations" | "Industry-leading technology" |
+
+### Quality Indicators
+
+**Clarity**
+- Understood in <5 seconds
+- No jargon required
+- Specific, not abstract
+
+**Specificity**
+- Numbers over adjectives
+- Outcomes over features
+- Examples over generalizations
+
+**Credibility**
+- Backed by proof
+- Realistic claims
+- Third-party validation
+
+**Differentiation**
+- Unique vs competitors
+- Ownable position
+- Clear alternative
+
+## Scoring Rubric
+
+| Score | Description |
+|-------|-------------|
+| 90-100 | Exceptional - all components strong, differentiated |
+| 70-89 | Good - most components present, some gaps |
+| 50-69 | Adequate - basic value prop, weak differentiation |
+| 30-49 | Poor - unclear or missing key components |
+| 0-29 | Failed - no clear value proposition |
+
+## Output
+
+```yaml
+value_prop_score: 78
+headline_analysis:
+  text: "AI That Understands Banking"
+  clarity: 85
+  specificity: 70
+  differentiation: 80
+  issues:
+    - "Could be more specific about outcomes"
+components:
+  what:
+    present: true
+    score: 80
+    evidence: "AI-powered platform"
+  who:
+    present: true
+    score: 85
+    evidence: "Banks and credit unions"
+  why:
+    present: true
+    score: 70
+    evidence: "Benefits mentioned but not quantified"
+  how:
+    present: false
+    score: 40
+    evidence: "Differentiation unclear"
+recommendations:
+  - priority: "high"
+    issue: "Missing differentiation"
+    suggestion: "Add 'Only AI trained on 10,000+ banking regulations'"
+  - priority: "medium"
+    issue: "Vague benefits"
+    suggestion: "Quantify outcomes: 'Reduce call volume 40%'"
+```

package/template/workers/content-sales/worker.yaml

@@ -0,0 +1,93 @@
+worker:
+  id: content-sales
+  name: "Content Worker - Conversion Copy"
+  type: ContentWorker
+  version: "1.0"
+
+execution:
+  mode: on_demand
+  max_runtime: 5m
+
+context:
+  base:
+    - workers/public/content-sales/
+    - workers/public/content-shared/
+    - companies/example-company/knowledge/verticals/
+    - companies/example-company/knowledge/campaign-playbook.md
+  exclude:
+    - node_modules/
+    - dist/
+
+output:
+  destination: workspace/reports/content/
+  format: markdown
+  naming: "{date}-content-sales-{page}.md"
+
+skills:
+  - conversion-analysis
+  - cta-audit
+  - value-prop-check
+
+instructions: |
+  Conversion Copy Analyst for ExampleCo
+
+  Purpose: Analyze content for conversion optimization, CTA effectiveness, and value proposition clarity.
+
+  ## Analysis Process
+  1. Load page content from content/ directory
+  2. Identify conversion goals for page type
+  3. Audit CTAs, value props, and persuasion elements
+  4. Score and recommend improvements
+
+  ## Page Conversion Goals
+  - Homepage: Demo request, explore products
+  - Product pages: Feature understanding, demo request
+  - Solutions pages: Vertical-specific demo, case study download
+  - Pricing: Plan selection, sales contact
+  - Resources: Content download, newsletter signup
+
+  ## Scoring Categories
+  - CTA effectiveness (0-100): Clear, compelling, well-placed
+  - Value proposition clarity (0-100): Benefits clear, differentiated
+  - Persuasion elements (0-100): Social proof, urgency, trust
+  - Conversion path (0-100): Clear journey, low friction
+
+  ## CTA Analysis Criteria
+  - Visibility: Above fold, contrasting, prominent
+  - Clarity: Action clear, outcome stated
+  - Motivation: Benefit-driven, low friction
+  - Placement: Strategic, contextual
+  - Quantity: Not overwhelming, appropriate density
+
+  ## Value Proposition Checklist
+  - [ ] Clear what product does
+  - [ ] Clear who it's for
+  - [ ] Specific benefits stated
+  - [ ] Differentiation from alternatives
+  - [ ] Proof to support claims
+
+  ## Persuasion Elements
+  - Social proof (testimonials, logos, stats)
+  - Authority (certifications, awards, press)
+  - Scarcity/urgency (when appropriate)
+  - Risk reversal (guarantees, trials)
+  - Reciprocity (free resources, tools)
+
+  ## Red Flags
+  - CTAs below fold only
+  - Generic CTA text ("Submit", "Click here")
+  - Missing value proposition
+  - No social proof
+  - Friction in conversion path
+  - Too many competing CTAs
+
+  ## Output
+  Generate markdown report with:
+  - Conversion optimization score
+  - CTA inventory and ratings
+  - Value prop assessment
+  - Prioritized recommendations
+
+  ## Knowledge Dependencies
+  - verticals/: Audience-specific messaging
+  - campaign-playbook.md: Campaign and conversion strategy

package/template/workers/content-shared/cli.ts

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+/**
+ * Content Analysis CLI
+ * Entry point for running content analysis from command line
+ *
+ * Usage: npx content-analyze <page-path> [options]
+ *
+ * Options:
+ *   --report    Generate markdown report
+ *   --issues    Create GitHub issues (dry-run by default)
+ *   --cms       Submit to CMS
+ *   --worker    Which worker analysis (brand|sales|product|legal|all)
+ *   --output    Output directory
+ *   --live      Disable dry-run mode (actually create issues/submit to CMS)
+ *   --high-only Only process high-priority items
+ *   --max       Maximum issues to create (default: 10)
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { parsePageFile } from './lib/parser.js';
+import { analyzePageFull, type AnalysisConfig } from './lib/analyze.js';
+import { generateSuggestions } from './lib/recommendations.js';
+import {
+  processAnalysisOutput,
+  formatOutputResultJSON,
+  type OutputConfig,
+} from './lib/output.js';
+
+// ============================================
+// CLI Argument Parsing
+// ============================================
+
+interface CLIArgs {
+  pagePath: string;
+  report: boolean;
+  issues: boolean;
+  cms: boolean;
+  worker: 'brand' | 'sales' | 'product' | 'legal' | 'all';
+  output: string;
+  live: boolean;
+  highOnly: boolean;
+  max: number;
+  help: boolean;
+  version: boolean;
+}
+
+function parseArgs(args: string[]): CLIArgs {
+  const result: CLIArgs = {
+    pagePath: '',
+    report: true,
+    issues: false,
+    cms: false,
+    worker: 'all',
+    output: 'workspace/reports/content',
+    live: false,
+    highOnly: false,
+    max: 10,
+    help: false,
+    version: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '--help' || arg === '-h') {
+      result.help = true;
+    } else if (arg === '--version' || arg === '-v') {
+      result.version = true;
+    } else if (arg === '--report') {
+      result.report = true;
+    } else if (arg === '--issues') {
+      result.issues = true;
+    } else if (arg === '--cms') {
+      result.cms = true;
+    } else if (arg === '--live') {
+      result.live = true;
+    } else if (arg === '--high-only') {
+      result.highOnly = true;
+    } else if (arg === '--worker' && args[i + 1]) {
+      const worker = args[++i] as CLIArgs['worker'];
+      if (['brand', 'sales', 'product', 'legal', 'all'].includes(worker)) {
+        result.worker = worker;
+      }
+    } else if (arg === '--output' && args[i + 1]) {
+      result.output = args[++i];
+    } else if (arg === '--max' && args[i + 1]) {
+      result.max = parseInt(args[++i], 10) || 10;
+    } else if (!arg.startsWith('-') && !result.pagePath) {
+      result.pagePath = arg;
+    }
+  }
+
+  return result;
+}
+
+function printHelp(): void {
+  console.log(`
+Content Analysis CLI
+
+Usage:
+  npx content-analyze <page-path> [options]
+  content-analyze <page-path> [options]
+
+Arguments:
+  page-path     Path to page JSON file (from content extraction)
+
+Options:
+  --report      Generate markdown report (default: true)
+  --issues      Create GitHub issues (dry-run by default)
+  --cms         Submit to CMS
+  --worker      Which analysis to run: brand|sales|product|legal|all (default: all)
+  --output      Output directory (default: workspace/reports/content)
+  --live        Disable dry-run mode (actually create issues/submit)
+  --high-only   Only process high-priority items
+  --max N       Maximum issues to create (default: 10)
+  --help, -h    Show this help message
+  --version, -v Show version
+
+Examples:
+  # Analyze a page and generate report
+  npx content-analyze ./pages/home.json
+
+  # Analyze with GitHub issues (dry run)
+  npx content-analyze ./pages/pricing.json --issues
+
+  # Full analysis with CMS submission (live)
+  npx content-analyze ./pages/about.json --issues --cms --live
+
+  # Brand-only analysis
+  npx content-analyze ./pages/home.json --worker brand
+
+  # High priority only with custom output
+  npx content-analyze ./pages/home.json --high-only --output ./reports
+`);
+}
+
+function printVersion(): void {
+  console.log('@hq/content-shared v1.0.0');
+}
+
+// ============================================
+// Main CLI Entry Point
+// ============================================
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (args.version) {
+    printVersion();
+    process.exit(0);
+  }
+
+  if (!args.pagePath) {
+    console.error('Error: Page path is required');
+    console.error('Run with --help for usage information');
+    process.exit(1);
+  }
+
+  // Resolve and validate page path
+  const pagePath = path.resolve(args.pagePath);
+  if (!fs.existsSync(pagePath)) {
+    console.error(`Error: File not found: ${pagePath}`);
+    process.exit(1);
+  }
+
+  console.log(`[CLI] Analyzing: ${pagePath}`);
+  console.log(`[CLI] Worker: ${args.worker}`);
+  console.log(`[CLI] Mode: ${args.live ? 'LIVE' : 'dry-run'}`);
+  console.log('');
+
+  try {
+    // 1. Parse page content
+    console.log('[1/4] Parsing page content...');
+    const pageContent = await parsePageFile(pagePath);
+
+    // 2. Configure analysis based on worker type
+    const analysisConfig: AnalysisConfig = {
+      enableBrand: args.worker === 'all' || args.worker === 'brand',
+      enableConversion: args.worker === 'all' || args.worker === 'sales',
+      enableAccuracy: args.worker === 'all' || args.worker === 'product',
+      enableCompliance: args.worker === 'all' || args.worker === 'legal',
+    };
+
+    console.log('[2/4] Running analysis...');
+    const analysis = analyzePageFull(pageContent, analysisConfig);
+
+    // 3. Generate suggestions
+    console.log('[3/4] Generating suggestions...');
+    const suggestions = generateSuggestions(analysis);
+    console.log(`      Found ${suggestions.length} suggestions`);
+
+    // 4. Process outputs
+    console.log('[4/4] Processing outputs...');
+    const outputConfig: Partial<OutputConfig> = {
+      reportPath: args.output,
+      workerName: `content-${args.worker}`,
+      enableGitHub: args.issues,
+      enableCMS: args.cms,
+      maxIssues: args.max,
+      highPriorityOnly: args.highOnly,
+      dryRun: !args.live,
+    };
+
+    const result = await processAnalysisOutput(analysis, outputConfig);
+
+    // Print results
+    console.log('');
+    console.log('=== Results ===');
+    console.log(`Report: ${result.reportPath || 'Not generated'}`);
+    console.log(`GitHub Issues: ${result.issuesCreated}`);
+    console.log(`CMS Submissions: ${result.suggestionsSubmitted}`);
+
+    if (result.errors.length > 0) {
+      console.log('');
+      console.log('Errors:');
+      for (const error of result.errors) {
+        console.log(`  - ${error}`);
+      }
+    }
+
+    // Output JSON for worker integration
+    console.log('');
+    console.log('=== JSON Output ===');
+    console.log(JSON.stringify(formatOutputResultJSON(result), null, 2));
+
+  } catch (error) {
+    console.error('Error:', error instanceof Error ? error.message : 'Unknown error');
+    process.exit(1);
+  }
+}
+
+// Run if executed directly
+main().catch(error => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});