claude-code-arcane 1.0.0

package/skills/marketing-context/scripts/context_validator.py

@@ -0,0 +1,219 @@
+#!/usr/bin/env python3
+"""Validate marketing context completeness — scores 0-100."""
+
+import json
+import re
+import sys
+from pathlib import Path
+
+SECTIONS = {
+    "Product Overview": {"required": True, "weight": 10, "markers": ["one-liner", "what it does", "product category", "business model"]},
+    "Target Audience": {"required": True, "weight": 12, "markers": ["target compan", "decision-maker", "use case", "jobs to be done"]},
+    "Personas": {"required": False, "weight": 5, "markers": ["persona", "champion", "decision maker"]},
+    "Problems & Pain Points": {"required": True, "weight": 10, "markers": ["core problem", "fall short", "cost", "tension"]},
+    "Competitive Landscape": {"required": True, "weight": 10, "markers": ["direct", "competitor", "secondary"]},
+    "Differentiation": {"required": True, "weight": 10, "markers": ["differentiator", "differently", "why customers choose"]},
+    "Objections": {"required": False, "weight": 5, "markers": ["objection", "response", "anti-persona"]},
+    "Switching Dynamics": {"required": False, "weight": 5, "markers": ["push", "pull", "habit", "anxiety"]},
+    "Customer Language": {"required": True, "weight": 10, "markers": ["verbatim", "words to use", "words to avoid"]},
+    "Brand Voice": {"required": True, "weight": 8, "markers": ["tone", "style", "personality"]},
+    "Style Guide": {"required": False, "weight": 3, "markers": ["grammar", "capitalization", "formatting"]},
+    "Proof Points": {"required": True, "weight": 7, "markers": ["metric", "customer", "testimonial"]},
+    "Content & SEO": {"required": False, "weight": 3, "markers": ["keyword", "internal link"]},
+    "Goals": {"required": True, "weight": 2, "markers": ["business goal", "conversion"]}
+}
+
+
+def validate_context(content: str) -> dict:
+    """Validate marketing context file and return score."""
+    content_lower = content.lower()
+    results = {"sections": {}, "score": 0, "max_score": 100, "missing_required": [], "missing_optional": [], "warnings": []}
+    total_weight = sum(s["weight"] for s in SECTIONS.values())
+    earned = 0
+
+    for name, config in SECTIONS.items():
+        section_present = name.lower().replace("& ", "").replace("  ", " ") in content_lower or any(
+            m in content_lower for m in config["markers"][:2]
+        )
+
+        markers_found = sum(1 for m in config["markers"] if m in content_lower)
+        markers_total = len(config["markers"])
+
+        has_placeholder = bool(re.search(r'\[.*?\]', content[content_lower.find(name.lower()):content_lower.find(name.lower()) + 500] if name.lower() in content_lower else ""))
+
+        if section_present and markers_found > 0:
+            completeness = markers_found / markers_total
+            if has_placeholder and completeness < 0.5:
+                completeness *= 0.5  # Penalize unfilled templates
+            section_score = round(config["weight"] * completeness)
+            earned += section_score
+            status = "complete" if completeness >= 0.75 else "partial"
+        else:
+            section_score = 0
+            status = "missing"
+            if config["required"]:
+                results["missing_required"].append(name)
+            else:
+                results["missing_optional"].append(name)
+
+        results["sections"][name] = {
+            "status": status,
+            "markers_found": markers_found,
+            "markers_total": markers_total,
+            "score": section_score,
+            "max_score": config["weight"],
+            "required": config["required"]
+        }
+
+    results["score"] = round((earned / total_weight) * 100)
+
+    # Warnings
+    if "verbatim" not in content_lower and '"' not in content:
+        results["warnings"].append("No verbatim customer quotes found — copy will sound generic")
+    if not re.search(r'\d+%|\$\d+|\d+ customer', content_lower):
+        results["warnings"].append("No metrics or proof points with numbers found")
+    if "last updated" in content_lower:
+        date_match = re.search(r'last updated:?\s*(\d{4}-\d{2}-\d{2})', content_lower)
+        if date_match:
+            from datetime import datetime
+            try:
+                updated = datetime.strptime(date_match.group(1), "%Y-%m-%d")
+                age_days = (datetime.now() - updated).days
+                if age_days > 180:
+                    results["warnings"].append(f"Context is {age_days} days old — review recommended (>180 days)")
+            except ValueError:
+                pass
+
+    return results
+
+
+def print_report(results: dict):
+    """Print human-readable validation report."""
+    print(f"\n{'='*50}")
+    print(f"MARKETING CONTEXT VALIDATION")
+    print(f"{'='*50}")
+    print(f"\nOverall Score: {results['score']}/100")
+    print(f"{'🟢 Strong' if results['score'] >= 80 else '🟡 Needs Work' if results['score'] >= 50 else '🔴 Incomplete'}")
+
+    print(f"\n{'─'*50}")
+    print(f"{'Section':<25} {'Status':<10} {'Score':<10}")
+    print(f"{'─'*50}")
+    for name, data in results["sections"].items():
+        icon = {"complete": "✅", "partial": "⚠️", "missing": "❌"}[data["status"]]
+        req = " *" if data["required"] else ""
+        print(f"{icon} {name:<23} {data['status']:<10} {data['score']}/{data['max_score']}{req}")
+
+    if results["missing_required"]:
+        print(f"\n🔴 Missing Required Sections:")
+        for s in results["missing_required"]:
+            print(f"   → {s}")
+
+    if results["missing_optional"]:
+        print(f"\n🟡 Missing Optional Sections:")
+        for s in results["missing_optional"]:
+            print(f"   → {s}")
+
+    if results["warnings"]:
+        print(f"\n⚠️  Warnings:")
+        for w in results["warnings"]:
+            print(f"   → {w}")
+
+    print(f"\n* = required section")
+    print(f"{'='*50}")
+
+
+def main():
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Validates marketing context completeness. "
+                    "Scores 0-100 based on required and optional section coverage."
+    )
+    parser.add_argument(
+        "file", nargs="?", default=None,
+        help="Path to a marketing context markdown file. "
+             "If omitted, runs demo with embedded sample data."
+    )
+    parser.add_argument(
+        "--json", action="store_true",
+        help="Also output results as JSON."
+    )
+    args = parser.parse_args()
+
+    if args.file:
+        filepath = Path(args.file)
+        if not filepath.exists():
+            print(f"Error: File not found: {filepath}", file=sys.stderr)
+            sys.exit(1)
+        content = filepath.read_text()
+    else:
+        # Demo with sample data
+        content = """# Marketing Context
+*Last updated: 2026-01-15*
+
+## Product Overview
+**One-liner:** AI-powered mobility analysis for elderly care
+**What it does:** Smartphone-based fall risk assessment using computer vision
+**Product category:** HealthTech / Digital Health
+**Business model:** SaaS, per-facility licensing
+
+## Target Audience
+**Target companies:** Care facilities, nursing homes, 50+ beds
+**Decision-makers:** Facility directors, quality managers
+**Primary use case:** Automated fall risk assessment replacing manual observation
+**Jobs to be done:**
+- Reduce fall incidents by identifying high-risk residents
+- Meet regulatory documentation requirements efficiently
+- Give care staff actionable mobility insights
+
+## Problems & Pain Points
+**Core problem:** Manual fall risk assessment is subjective, time-consuming, and inconsistent
+**Why alternatives fall short:**
+- Manual observation takes 30+ minutes per resident
+- Paper-based assessments are completed once per quarter at best
+**What it costs them:** Falls cost €8,000-12,000 per incident, plus liability
+**Emotional tension:** Staff fear missing warning signs, blame after incidents
+
+## Competitive Landscape
+**Direct:** Traditional gait labs — $50K+ hardware, need trained staff
+**Secondary:** Wearable sensors — low compliance, residents remove them
+**Indirect:** Manual observation — subjective, inconsistent
+
+## Differentiation
+**Key differentiators:**
+- Uses standard smartphone (no special hardware)
+- AI-powered analysis (objective, repeatable)
+**Why customers choose us:** Fast, affordable, no hardware investment
+
+## Customer Language
+**How they describe the problem:**
+- "We never know who's going to fall next"
+- "The documentation takes forever"
+**Words to use:** mobility analysis, fall prevention, care quality
+**Words to avoid:** surveillance, monitoring, tracking
+
+## Brand Voice
+**Tone:** Professional, empathetic, evidence-based
+**Personality:** Trustworthy, innovative, caring
+
+## Proof Points
+**Metrics:**
+- 80+ care facilities served
+- 30% reduction in fall incidents (pilot data)
+**Customers:** Major care facility chains in Germany
+
+## Goals
+**Business goal:** Expand to 200+ facilities, enter Spain and Netherlands
+**Conversion action:** Book a demo
+"""
+        print("[Using embedded sample data — pass a file path for real validation]")
+
+    results = validate_context(content)
+    print_report(results)
+
+    if args.json:
+        print(f"\n{json.dumps(results, indent=2)}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/marketing-context/templates/marketing-context-template.md

@@ -0,0 +1,133 @@
+# Marketing Context
+
+*Last updated: [date]*
+
+## Product Overview
+**One-liner:** [What you do in one sentence]
+**What it does:** [2-3 sentences]
+**Product category:** [The "shelf" — how customers search for you]
+**Product type:** [SaaS, marketplace, e-commerce, service]
+**Business model:** [Pricing model and range]
+
+## Target Audience
+**Target companies:** [Industry, size, stage]
+**Decision-makers:** [Roles, departments]
+**Primary use case:** [The main problem you solve]
+**Jobs to be done:**
+- [Job 1]
+- [Job 2]
+- [Job 3]
+**Use cases:**
+- [Scenario 1]
+- [Scenario 2]
+
+## Personas
+
+| Persona | Role | Cares about | Challenge | Value we promise |
+|---------|------|-------------|-----------|------------------|
+| [Name] | User | | | |
+| [Name] | Champion | | | |
+| [Name] | Decision Maker | | | |
+| [Name] | Financial Buyer | | | |
+
+## Problems & Pain Points
+**Core problem:** [What customers face before finding you]
+**Why alternatives fall short:**
+- [Gap 1]
+- [Gap 2]
+**What it costs them:** [Time, money, opportunities]
+**Emotional tension:** [Stress, fear, doubt]
+
+## Competitive Landscape
+
+| Competitor | Type | How they fall short |
+|-----------|------|---------------------|
+| [Name] | Direct | [Gap] |
+| [Name] | Secondary | [Gap] |
+| [Name] | Indirect | [Gap] |
+
+## Differentiation
+**Key differentiators:**
+- [Differentiator 1]
+- [Differentiator 2]
+**How we do it differently:** [Approach]
+**Why that's better:** [Benefits]
+**Why customers choose us:** [Decision drivers]
+
+## Objections
+
+| Objection | Response |
+|-----------|----------|
+| "[Objection 1]" | [How to address] |
+| "[Objection 2]" | [How to address] |
+| "[Objection 3]" | [How to address] |
+
+**Anti-persona (NOT a good fit):** [Who should NOT buy this]
+
+## Switching Dynamics
+**Push (away from current):** [Frustrations]
+**Pull (toward us):** [Attractions]
+**Habit (keeping them stuck):** [Inertia]
+**Anxiety (about switching):** [Worries]
+
+## Customer Language
+**How they describe the problem:**
+- "[verbatim quote]"
+- "[verbatim quote]"
+**How they describe us:**
+- "[verbatim quote]"
+- "[verbatim quote]"
+**Words to use:** [list]
+**Words to avoid:** [list]
+
+| Term | Meaning |
+|------|---------|
+| [Product term] | [Definition] |
+
+## Brand Voice
+**Tone:** [professional, casual, playful, authoritative]
+**Style:** [direct, conversational, technical]
+**Personality:** [3-5 adjectives]
+**Voice DO's:** [list]
+**Voice DON'T's:** [list]
+
+## Style Guide
+**Grammar:** [Key rules]
+**Capitalization:** [Conventions]
+**Formatting:** [Standards]
+**Preferred terms:** [List]
+
+## Proof Points
+**Metrics:**
+- [Metric 1]
+- [Metric 2]
+**Customers:** [Notable logos]
+**Testimonials:**
+> "[quote]" — [Name, Title, Company]
+> "[quote]" — [Name, Title, Company]
+
+| Value Theme | Supporting Proof |
+|-------------|-----------------|
+| [Theme 1] | [Evidence] |
+| [Theme 2] | [Evidence] |
+
+## Content & SEO Context
+**Target keywords:**
+
+| Cluster | Primary Keyword | Secondary Keywords | Intent |
+|---------|----------------|-------------------|--------|
+| [Topic 1] | [keyword] | [kw1, kw2] | [informational/commercial] |
+
+**Internal links map:**
+
+| Page | URL | Use for | Anchor text |
+|------|-----|---------|-------------|
+| [Page name] | [URL] | [Topic] | [Suggested anchor] |
+
+**Writing examples:**
+- [URL or file — what makes it good]
+
+## Goals
+**Business goal:** [Primary objective]
+**Conversion action:** [What you want people to do]
+**Current metrics:** [If known]

package/skills/marketing-demand-acquisition/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: marketing-demand-acquisition
+description: "Demand generation and acquisition playbook for Series A+ startups — paid media, SEO, partnerships, attribution, and MQL/SQL workflows."
+argument-hint: ""
+category: "marketing-strategy"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash
+---
+# Marketing Demand & Acquisition
+
+Acquisition playbook for Series A+ startups scaling internationally (EU/US/Canada) with hybrid PLG/Sales-Led motion.
+
+## Core KPIs
+
+- **Demand Gen:** MQL/SQL volume, cost per opportunity, marketing-sourced pipeline $
+- **Paid Media:** CAC, ROAS, CPL, CPA, channel efficiency ratio
+- **SEO:** Organic sessions, non-brand traffic %, keyword rankings
+- **Partnerships:** Partner-sourced pipeline $, partner CAC, co-marketing ROI
+
+---
+
+## Demand Generation Framework
+
+| Stage | Tactics | Target |
+|-------|---------|--------|
+| TOFU | Paid social, display, content syndication, SEO | Awareness, traffic |
+| MOFU | Paid search, retargeting, gated content, email nurture | MQLs, demo requests |
+| BOFU | Brand search, direct outreach, case studies, trials | SQLs, pipeline $ |
+
+### Campaign Planning
+
+1. Define objective, budget, duration, audience
+2. Select channels based on funnel stage
+3. Create HubSpot campaign with proper UTM structure
+4. Configure lead scoring and assignment rules
+5. Launch with test budget, validate tracking
+
+---
+
+## Paid Media Channels
+
+| Channel | Best For | CAC Range |
+|---------|----------|-----------|
+| LinkedIn Ads | B2B, Enterprise, ABM | $150-400 |
+| Google Search | High-intent, BOFU | $80-250 |
+| Google Display | Retargeting | $50-150 |
+| Meta Ads | SMB, visual products | $60-200 |
+
+For detailed channel setup, budget allocation ($40k/month example), and campaign templates, see [references/campaign-templates.md](references/campaign-templates.md).
+
+---
+
+## SEO Strategy
+
+### Technical Checklist
+
+- [ ] XML sitemap, robots.txt, HTTPS, page speed >90 mobile
+- [ ] Core Web Vitals, structured data, canonical tags, hreflang
+
+### Keyword Tiers
+
+| Tier | Type | Priority |
+|------|------|----------|
+| 1 | High-intent BOFU (100-1k) | First |
+| 2 | Solution-aware MOFU (500-5k) | Second |
+| 3 | Problem-aware TOFU (1k-10k) | Third |
+
+---
+
+## Partnerships
+
+| Tier | Type | ROI |
+|------|------|-----|
+| 1 | Strategic integrations | Very high |
+| 2 | Affiliate partners | Medium-high |
+| 3 | Customer referrals | Medium |
+
+For partnership workflow, affiliate program setup, and regional playbooks, see [references/international-playbooks.md](references/international-playbooks.md).
+
+---
+
+## Attribution
+
+| Model | Use Case |
+|-------|----------|
+| First-Touch | Awareness campaigns |
+| Last-Touch | Direct response |
+| W-Shaped (40-20-40) | Hybrid PLG/Sales (recommended) |
+
+For HubSpot attribution setup and weekly metrics dashboard, see [references/attribution-guide.md](references/attribution-guide.md).
+
+---
+
+## MQL to SQL Handoff
+
+**SQL Criteria:** Director+, 50-5000 employees, $10k+ budget, 90-day timeline, high-intent action.
+
+**SLA:** SDR responds to MQL in 4 hours, AE books demo in 24 hours.
+
+---
+
+## Channel Benchmarks (B2B SaaS Series A)
+
+| Metric | LinkedIn | Google Search | SEO | Email |
+|--------|----------|---------------|-----|-------|
+| CTR | 0.4-0.9% | 2-5% | 1-3% | 15-25% |
+| CAC | $150-400 | $80-250 | $50-150 | $20-80 |
+
+---
+
+## References
+
+| File | Content |
+|------|---------|
+| [hubspot-workflows.md](references/hubspot-workflows.md) | Lead scoring, nurture, assignment workflows |
+| [campaign-templates.md](references/campaign-templates.md) | LinkedIn, Google, Meta campaign structures |
+| [international-playbooks.md](references/international-playbooks.md) | EU, US, Canada market tactics |
+| [attribution-guide.md](references/attribution-guide.md) | Multi-touch attribution and dashboards |
+
+## Related Skills
+
+- **paid-ads**: For executing paid acquisition campaigns
+- **content-strategy**: For content-driven demand generation
+- **campaign-analytics**: For measuring demand gen effectiveness

package/skills/marketing-demand-acquisition/references/attribution-guide.md

@@ -0,0 +1,217 @@
+# Attribution Guide
+
+Multi-touch attribution setup, analysis, and reporting.
+
+---
+
+## Table of Contents
+
+- [Attribution Models](#attribution-models)
+- [HubSpot Attribution Setup](#hubspot-attribution-setup)
+- [Google Analytics Configuration](#google-analytics-configuration)
+- [Reporting Dashboards](#reporting-dashboards)
+- [A/B Testing Framework](#ab-testing-framework)
+
+---
+
+## Attribution Models
+
+### Model Comparison
+
+| Model | Credit Distribution | Best For |
+|-------|---------------------|----------|
+| First-Touch | 100% to first interaction | Awareness campaigns |
+| Last-Touch | 100% to last interaction | Direct response, BOFU |
+| Linear | Equal across all touchpoints | Simple full-funnel view |
+| Time Decay | More credit to recent touches | Long sales cycles |
+| W-Shaped | 40% first, 20% middle, 40% last | Hybrid PLG/Sales-Led |
+
+### Recommended Model: W-Shaped
+
+For Series A hybrid motion:
+- 40% credit to first touch (awareness)
+- 20% distributed across middle touches
+- 40% credit to last touch (conversion)
+
+**Rationale:** Balances discovery and closing influence.
+
+---
+
+## HubSpot Attribution Setup
+
+### Enable Attribution Reports
+
+1. Navigate to Marketing → Reports → Attribution
+2. Select attribution model (W-Shaped recommended)
+3. Define conversion event (deal created, SQL stage)
+4. Set lookback window (90 days typical)
+
+### Attribution Report Types
+
+| Report | Purpose | Frequency |
+|--------|---------|-----------|
+| Revenue Attribution | Credit revenue to channels | Monthly |
+| Content Attribution | Credit to content assets | Weekly |
+| Campaign Attribution | Credit to campaigns | Per campaign |
+
+### Custom Attribution Report
+
+Create: Marketing → Reports → Create Report
+
+**Metrics:**
+- Marketing-sourced pipeline $
+- Marketing-influenced revenue
+- CAC by channel
+- ROAS by campaign
+
+**Dimensions:**
+- Channel (Organic, Paid, Email, Social, Referral)
+- Campaign
+- Region (US, EU, Canada)
+- Funnel stage (TOFU, MOFU, BOFU)
+
+**Validation:** Run report for past 90 days. Verify all channels appear with data.
+
+---
+
+## Google Analytics Configuration
+
+### GA4 Events to Track
+
+**Engagement Events:**
+```
+page_view        (auto-tracked)
+scroll           (75% depth)
+video_play       (product demos)
+file_download    (whitepapers, eBooks)
+```
+
+**Conversion Events:**
+```
+sign_up          (free trial, account)
+demo_request     (calendar booking)
+contact_form     (inbound interest)
+pricing_view     (pricing page visit)
+```
+
+### Custom Dimensions
+
+| Dimension | Source | Purpose |
+|-----------|--------|---------|
+| User Type | CRM sync | Free vs Paid |
+| Plan Type | CRM sync | Starter, Pro, Enterprise |
+| Lead Status | HubSpot | MQL, SQL, Customer |
+| Campaign ID | UTM | HubSpot campaign |
+
+### GA4 + HubSpot Integration
+
+1. Install HubSpot tracking code (includes GA4)
+2. Or use Google Tag Manager for advanced tracking
+3. Sync GA4 audiences → HubSpot lists for retargeting
+4. Import GA4 conversions to Google Ads
+
+**Validation:** Real-time report shows events firing. Conversion events marked correctly.
+
+---
+
+## Reporting Dashboards
+
+### Weekly Performance Dashboard
+
+| Metric | Purpose | Target |
+|--------|---------|--------|
+| Visits | Traffic volume | +10% WoW |
+| Unique visitors | Reach | +5% WoW |
+| Bounce rate | Engagement | <50% |
+| MQLs | Lead volume | Weekly target |
+| SQLs | Pipeline | Weekly target |
+| Conversion rate | Efficiency | >2% |
+
+### Monthly Executive Dashboard
+
+| KPI | Formula | Target |
+|-----|---------|--------|
+| Marketing-Sourced Pipeline | Sum of new pipeline $ | $X/month |
+| Marketing-Sourced Revenue | Closed-won from marketing | $Y/month |
+| Blended CAC | Total spend / customers | <$Z |
+| MQL→SQL Rate | SQLs / MQLs | >15% |
+| Pipeline Velocity | Avg days in pipeline | <60 days |
+| ROMI | Revenue / Marketing spend | >3:1 |
+
+### Dashboard Build Process
+
+1. Define KPIs with leadership
+2. Create data sources in HubSpot
+3. Build visualizations (charts, tables)
+4. Set up automated refresh
+5. Schedule weekly/monthly distribution
+
+**Validation:** Dashboard shows last 7 days data. All metrics calculating correctly.
+
+---
+
+## A/B Testing Framework
+
+### ICE Prioritization
+
+**Formula:** ICE = (Impact × Confidence × Ease) ÷ 3
+
+| Factor | Rating | Description |
+|--------|--------|-------------|
+| Impact | 1-10 | Effect on primary metric |
+| Confidence | 1-10 | Certainty of success |
+| Ease | 1-10 | Implementation difficulty |
+
+### Test Template
+
+```
+Hypothesis: [Adding a case study carousel to pricing will
+            increase demo requests by 20%]
+
+Metric: [Demo requests from /pricing page]
+Sample Size: [1000 visitors per variant]
+Duration: [2 weeks or until significance]
+Success Criteria: [20% lift, 95% confidence]
+
+Variant A (Control): [Current pricing page]
+Variant B (Treatment): [Pricing page + case study carousel]
+
+Tools: [HubSpot A/B test or Google Optimize]
+```
+
+### Statistical Requirements
+
+- Minimum confidence: 95%
+- Minimum sample: 1000 visitors per variant
+- Minimum duration: 2 weeks
+- Do not stop tests early (false positives)
+
+### Common Test Categories
+
+**Landing Page:**
+- Headline variations
+- CTA copy and color
+- Form length
+- Social proof placement
+- Hero image type
+
+**Ad Creative:**
+- Format (static vs video)
+- Messaging angle
+- Audience targeting
+- Landing page destination
+
+**Email:**
+- Subject line length
+- Personalization depth
+- Send time
+- CTA placement
+
+### Test Velocity Target
+
+Series A: 4-6 tests per month
+- Realistic win rate: 30-40%
+- Document all results (wins and losses)
+- Build testing knowledge base
+
+**Validation:** Test reaches statistical significance before declaring winner.