openads-ai 0.1.0

package/scripts/postinstall.js

@@ -0,0 +1,38 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const pkgDir = path.resolve(__dirname, '..');
+
+function findPiPkgDir() {
+  // Candidate 1: Nested under openads-ai/node_modules
+  const nestedPath = path.resolve(pkgDir, 'node_modules', '@earendil-works', 'pi-coding-agent');
+  if (fs.existsSync(nestedPath)) return nestedPath;
+
+  // Candidate 2: Hoisted node_modules (climbing up)
+  let currentDir = pkgDir;
+  while (currentDir !== path.dirname(currentDir)) {
+    const parentNodeModules = path.resolve(currentDir, '..', 'node_modules', '@earendil-works', 'pi-coding-agent');
+    if (fs.existsSync(parentNodeModules)) return parentNodeModules;
+    currentDir = path.dirname(currentDir);
+  }
+  return null;
+}
+
+const piPkgDir = findPiPkgDir();
+if (!piPkgDir) {
+  console.log('OpenAds: @earendil-works/pi-coding-agent not found. Skipping white-label patch.');
+  process.exit(0);
+}
+
+const piPkgPath = path.join(piPkgDir, 'package.json');
+try {
+  const piPkg = JSON.parse(fs.readFileSync(piPkgPath, 'utf8'));
+  piPkg.piConfig = { name: 'openads', configDir: '.openads' };
+  fs.writeFileSync(piPkgPath, JSON.stringify(piPkg, null, 2));
+  console.log('OpenAds: Successfully patched pi-coding-agent for branding!');
+} catch (e) {
+  console.error('OpenAds: Failed to patch branding on pi-coding-agent package.json:', e.message);
+}

package/skills/ads/google-ads.md

@@ -0,0 +1,53 @@
+---
+name: google-ads
+description: Audit and optimize Google Ads campaigns, keywords, and bids.
+---
+# Google Ads Skill
+
+## When to Use This Skill
+
+Activate when the user is:
+- Auditing or analyzing Google Ads campaigns, ad groups, or keywords
+- Writing responsive search ads (RSAs)
+- Planning keyword strategy or negative keywords
+- Troubleshooting conversion tracking or ROAS issues
+- Using the `/audit-google-ads` or `/write-ad-copy` templates
+
+Read `product-marketing.md` first to understand the product context.
+
+---
+
+## Core Concepts to Apply
+
+### Campaign Structure Best Practices
+- **Single Theme Ad Groups (STAGs)**: One tight keyword theme per ad group
+- **Exact and Phrase match first**, add Broad only after proving performance
+- **Negative keywords** are as important as positive keywords
+
+### Bidding Strategy Decision Tree
+```
+Do you have ≥30 conversions/month?
+  Yes → Smart Bidding (Target CPA or Target ROAS)
+  No  → Manual CPC or Maximize Clicks with a max CPC cap
+          ↳ Never use Broad match on Manual CPC (budget bleed risk)
+```
+
+### Quality Score Levers
+1. **Expected CTR** — headline relevance to keyword
+2. **Ad Relevance** — keyword in headlines/description
+3. **Landing Page Experience** — load speed, relevance
+- QS 7+ is good; 9–10 is excellent; below 5 needs attention
+
+### Responsive Search Ads (RSA) Writing Rules
+- **15 headlines**, max 30 characters each (spaces count)
+- **4 descriptions**, max 90 characters each
+- Pin headline 1 = brand or primary value prop
+- Include at least one headline with the exact keyword
+- At least one urgency or CTA in descriptions
+
+---
+
+## MCP Tools to Use
+
+If Google Ads MCP is connected, you have access to tools for retrieving campaign performance, keyword metrics, search terms, and generating drafts.
+**Always use draft → preview → confirm for any write operation. Never execute without user confirmation.**

package/skills/ads/meta-ads.md

@@ -0,0 +1,45 @@
+---
+name: meta-ads
+description: Plan, launch, and optimize Meta (Facebook/Instagram) ad campaigns.
+---
+# Meta Ads Skill
+
+## When to Use This Skill
+
+Activate when the user is:
+- Planning, launching, or auditing Meta (Facebook/Instagram) ad campaigns
+- Writing ad copy or creative briefs for Meta
+- Troubleshooting delivery, ROAS, or frequency issues
+
+Read `product-marketing.md` first to understand the product context.
+
+---
+
+## Meta Campaign Architecture
+
+**Campaign Budget Optimization (CBO)** — Meta distributes budget across ad sets automatically. Use when you trust Meta's algorithm and have proven audiences.
+**Ad Set Budget Optimization (ABO)** — You control budget per ad set. Use during testing phases.
+
+## Creative Strategy
+- **UGC-style**: Lo-fi, authentic, filmed on phone
+- **Direct response**: Problem → Agitate → Solution in first 3 seconds
+- **Text hooks on video**: Caption key message; 85%+ watch without sound
+- **Variety**: 3+ creative concepts per campaign
+
+### Hook Formula (First 3 Seconds)
+- Option A (Pain Hook):  "Tired of [pain point]?"
+- Option B (Curiosity):  "Here's why [unexpected claim]..."
+- Option C (Direct):     "This [product] will [specific benefit]"
+- Option D (Social Proof): "[Number] people already [result]"
+
+### Ad Copy Structure
+1. Hook (1-2 lines)
+2. Empathy + Problem (2-3 lines)
+3. Solution + Differentiator (3-4 lines)
+4. Social Proof (1-2 lines)
+5. CTA (clear, single action)
+
+---
+
+## MCP Tools to Use
+If Meta Ads MCP is connected, you can pull campaign insights, ad sets, and ad creative performance. Ensure you review the performance to provide data-driven recommendations.

package/skills/ads/video-ads.md

@@ -0,0 +1,69 @@
+---
+name: video-ads
+description: Script and plan video ads for any platform.
+---
+# Video Ads
+
+## When to Use This Skill
+
+Activate when the user needs to:
+- Write a video ad script (Meta, YouTube, TikTok)
+- Plan a video creative brief for a production team
+- Optimize existing video ads for better performance
+- Choose the right video format for their platform
+
+Read `product-marketing.md` and `ad-creative.md` first.
+
+---
+
+## Video Ad Structures
+
+### 1. Problem-Solution (15-30 seconds)
+Best for: Meta, Instagram, TikTok
+```
+[0-3s]  Hook: State the pain point visually or verbally
+[3-10s] Agitate: Show what happens if they don't solve it
+[10-20s] Solution: Show your product fixing the problem
+[20-25s] Proof: Quick testimonial or stat
+[25-30s] CTA: "Try it free" / "Link in bio"
+```
+
+### 2. Testimonial / UGC (30-60 seconds)
+Best for: Meta, TikTok, YouTube Shorts
+```
+[0-3s]  Hook: "I tried [product] and here's what happened..."
+[3-20s] Story: Before state → discovered product → transformation
+[20-40s] Proof: Show specific results (screenshots, numbers)
+[40-50s] Recommendation: "If you're struggling with X, try this"
+[50-60s] CTA
+```
+
+### 3. Educational / How-To (60-120 seconds)
+Best for: YouTube pre-roll, LinkedIn
+```
+[0-5s]  Hook: "How to [desirable outcome] in [timeframe]"
+[5-60s] Teach: 3 actionable steps (value-first)
+[60-90s] Bridge: "But if you want to skip the manual work..."
+[90-110s] Product demo: Show it in action
+[110-120s] CTA
+```
+
+---
+
+## Platform-Specific Video Specs
+
+| Platform | Ideal Length | Aspect Ratio | Sound |
+|---|---|---|---|
+| Meta Feed | 15-30s | 1:1 or 4:5 | Optional (use captions) |
+| Instagram Stories | 15s max | 9:16 | On by default |
+| Instagram Reels | 15-30s | 9:16 | On (use trending audio) |
+| TikTok | 15-60s | 9:16 | On (use trending audio) |
+| YouTube Pre-roll | 6s or 15s | 16:9 | On |
+| YouTube In-stream | 30-120s | 16:9 | On |
+| LinkedIn | 30-90s | 1:1 or 16:9 | Off (use captions) |
+
+## The 3-Second Rule
+85% of people who don't engage in the first 3 seconds will never engage. The hook must:
+- Show motion immediately (no static frames)
+- Use text overlay with the key message
+- Create curiosity or pattern disruption

package/skills/analytics/analytics.md

@@ -0,0 +1,32 @@
+---
+name: analytics
+description: Set up tracking, analyze traffic, and fix attribution gaps.
+---
+# Analytics Skill
+
+## When to Use This Skill
+
+Activate when analyzing website traffic, setting up GA4, tracking events, or dealing with attribution gaps.
+
+---
+
+## The Attribution Problem
+Always remind the user: no platform has 100% perfect tracking. 
+- **Platform data (Ads, Meta)** claims credit for everything.
+- **GA4** underreports due to GDPR consent rejection and cross-device drops.
+- **Truth** is usually in the middle. Use GA4 for relative trends, not absolute truth.
+
+## GA4 Event Strategy
+Recommend standard events over custom events when possible:
+1. `generate_lead`
+2. `sign_up`
+3. `purchase`
+4. `add_to_cart`
+
+## UTM Best Practices
+Enforce strict UTM taxonomy:
+- `utm_source`: The platform (e.g., `google`, `facebook`, `linkedin`)
+- `utm_medium`: The channel type (e.g., `cpc`, `social`, `email`)
+- `utm_campaign`: The specific campaign name
+- `utm_content`: The ad variant or creative
+- `utm_term`: The keyword (for search)

package/skills/automation/autoresearch.md

@@ -0,0 +1,59 @@
+---
+name: autoresearch
+description: Autonomously generate, score, and iterate on marketing assets.
+---
+# Autoresearch (Autonomous Improvement Loop)
+
+## When to Use This Skill
+
+Activate this skill when the user wants to autonomously generate, test, and iterate on marketing hypotheses. This is the **Modify → Verify → Keep/Discard → Repeat** loop applied to digital marketing.
+
+Use this for tasks like:
+- Generating 50 headline hypotheses, scoring them against the ICP context, and keeping the top 5
+- Iterating on ad copy variants and checking them against character limits or ad strength rules
+- Brainstorming A/B test concepts and evaluating their statistical viability
+- Running an overnight loop to optimize landing page structures
+
+Read `product-marketing.md` first to understand the context against which you are scoring or generating ideas.
+
+---
+
+## The Autoresearch Loop
+
+When running an autoresearch task, follow this strict loop. Do not stop until the goal is reached or the user interrupts.
+
+### 1. Modify (Generate)
+Generate a batch of new variants based on the strategy. If this is iteration 2+, look at what succeeded/failed in previous loops to inform your generation.
+
+### 2. Verify (Score)
+Score the generated variants. If a tool is available (e.g. Adloop's ad strength checker, or an external LLM evaluation), use it. If not, use internal logic to score them against the `product-marketing.md` constraints (e.g., "Does this mention the primary pain point? Does it fit character limits?").
+
+### 3. Keep / Discard
+Keep only the variants that pass the verification threshold. Discard the rest. Document *why* they were discarded to inform the next loop.
+
+### 4. Repeat
+If the goal is met (e.g., "I need 10 excellent ad variants"), stop and present the results. If not, return to Step 1.
+
+---
+
+## Setting Up a Plan
+
+Before starting the loop, you must define the boundaries. If the user hasn't provided this, ask them to define:
+1. **Goal**: What are we trying to achieve? (e.g., "Generate 20 high-converting headlines")
+2. **Metric**: How do we score them? (e.g., "Must pass PAS framework criteria and be under 30 characters")
+3. **Scope**: What is out of bounds? (e.g., "Do not use the word 'Free'")
+
+(Tip: recommend the user type `/autoresearch:plan` to launch the configuration wizard).
+
+---
+
+## Output Format
+
+While looping, keep the user updated with a concise progress log:
+```
+Loop 1: Generated 10. 2 passed, 8 discarded. (Reason: too long)
+Loop 2: Generated 10. 4 passed, 6 discarded. (Reason: weak hook)
+...
+```
+
+At the end, present the final "Kept" list formatted as a markdown table or code block, ready for export.

package/skills/content/copywriting.md

@@ -0,0 +1,86 @@
+---
+name: copywriting
+description: Write persuasive ad copy, headlines, and marketing content.
+---
+# Copywriting
+
+## When to Use This Skill
+
+Activate when the user needs to write, rewrite, or review copy for ads, landing pages, emails, or any marketing asset.
+
+Read `product-marketing.md` first.
+
+---
+
+## Core Principles
+
+1. **Clarity over cleverness.** If they have to think about what the headline means, they will bounce.
+2. **You > We.** Count "You" vs "We/Our" — ratio should be at least 3:1 in favor of "You."
+3. **Benefits > Features.** Features tell what it does. Benefits sell what it means for them.
+4. **Specifics sell.** "Save 4 hours a week" beats "Save time."
+5. **One CTA per piece.** Every piece of copy should have ONE core emotion, ONE primary benefit, ONE call to action.
+
+---
+
+## Creative Frameworks
+
+### AIDA
+- **Attention**: Hook them immediately.
+- **Interest**: Keep them reading.
+- **Desire**: Show the transformation.
+- **Action**: Tell them what to do next.
+
+### PAS
+- **Problem**: Name the exact pain point.
+- **Agitation**: Make the pain feel urgent.
+- **Solution**: Present your product as the fix.
+
+### Before-After-Bridge
+- **Before**: Here's your world today (painful).
+- **After**: Here's what it looks like solved (desirable).
+- **Bridge**: Here's how to get there (your product).
+
+---
+
+## Persuasion Principles
+
+Apply these when writing any copy:
+
+- **Loss aversion**: "Stop losing $500/year" outperforms "Save $500/year."
+- **Social proof**: Real numbers beat vague claims. "Used by 10,247 marketers" > "Trusted by many."
+- **Anchoring**: Show the expensive option first to make the target option feel reasonable.
+- **Curiosity gap**: Open a loop the reader needs to close. Works well for awareness ads.
+- **Urgency**: Only use if real. Fake urgency destroys trust permanently.
+
+---
+
+## Creative Angles to Test
+
+Always propose multiple angles:
+1. **The Pain Hook**: "Tired of [pain point]?"
+2. **The Curiosity Hook**: "Here's why [unexpected claim]..."
+3. **The Direct Hook**: "This [product] will [specific benefit]"
+4. **The Social Proof Hook**: "[Number] people already [result]"
+5. **The Founder Story**: Why was this built?
+6. **Us vs. Them**: Compare to the old way of doing things.
+7. **The Mythbuster**: Challenge a common industry belief.
+
+---
+
+## Platform-Specific Copy Rules
+
+### Google Ads (RSAs)
+- 15 headlines, max 30 characters each (spaces count)
+- 4 descriptions, max 90 characters each
+- Pin headline 1 = brand or primary value prop
+- Include at least one headline with the exact keyword
+
+### Meta Ads
+- Hook in the first line (it shows before "See more")
+- Structure: Hook → Empathy → Solution → Proof → CTA
+- 85%+ watch video without sound — text overlays matter
+
+### Email Subject Lines
+- Under 50 characters
+- Write 5, pick the most curiosity-inducing one
+- Preview text is your second headline — don't waste it

package/skills/content/emails.md

@@ -0,0 +1,55 @@
+---
+name: emails
+description: Write email sequences that nurture ad leads into customers.
+---
+# Email Marketing
+
+## When to Use This Skill
+
+Activate when the user needs to:
+- Write a welcome or onboarding email sequence
+- Create a nurture sequence for leads captured from ads
+- Draft a promotional email or launch announcement
+- Improve email open rates or click-through rates
+
+Read `product-marketing.md` first. Emails must use the same tone and value prop as the ads that captured the lead.
+
+---
+
+## Email Sequence Types
+
+### 1. Welcome Sequence (Post-Signup)
+Triggered when someone signs up or downloads a lead magnet.
+- **Email 1** (Day 0): Deliver what you promised + introduce yourself
+- **Email 2** (Day 1): Share your best piece of content or a quick win
+- **Email 3** (Day 3): Tell your origin story or share a customer success story
+- **Email 4** (Day 5): Address the #1 objection
+- **Email 5** (Day 7): Soft pitch — "If you're ready, here's how to start"
+
+### 2. Nurture Sequence (Lead → Customer)
+For leads who clicked an ad but didn't buy:
+- Alternate between value (tips, case studies) and pitch (offers, demos)
+- Ratio: 3 value emails for every 1 pitch email
+- Include a "breakup email" at the end: "Should I stop emailing you?"
+
+### 3. Re-engagement Sequence
+For dormant leads or inactive users:
+- "We miss you" with a compelling reason to come back
+- Show what's new since they left
+- Offer an incentive (discount, extended trial)
+
+---
+
+## Email Copywriting Rules
+
+1. **Subject line** — Write 5, pick the most curiosity-inducing one. Keep under 50 characters.
+2. **Preview text** — Don't waste it. This is your second headline.
+3. **Opening line** — Never start with "Hi [Name], I hope this email finds you well." Start with a hook.
+4. **One email, one goal** — Don't pitch, share a blog post, AND ask for a referral in the same email.
+5. **CTA** — One clear button or link. "Reply to this email" works for engagement.
+6. **P.S. line** — Most-read part of an email after the subject line. Put your strongest point here.
+
+## Key Metrics
+- **Open rate**: Benchmark 20-30%. Below 15%? Subject lines need work.
+- **Click rate**: Benchmark 2-5%. Below 1%? CTA or content isn't compelling.
+- **Unsubscribe rate**: Normal is < 0.5%. Above 1%? Sending too often or wrong audience.

package/skills/cro/cro.md

@@ -0,0 +1,83 @@
+---
+name: cro
+description: Improve conversion rates on landing pages, signups, and funnels.
+---
+# Conversion Rate Optimization
+
+## When to Use This Skill
+
+Activate when the user needs to:
+- Improve a landing page or signup flow
+- Diagnose why ad traffic isn't converting
+- Plan or analyze an A/B test
+- Optimize forms, CTAs, or checkout flows
+
+Read `product-marketing.md` first.
+
+---
+
+## The Message Match Rule
+
+The #1 reason ads don't convert: the landing page says something different than the ad.
+
+| Ad Headline | ❌ Bad Landing Page | ✅ Good Landing Page |
+|---|---|---|
+| "Cut your ad spend by 30%" | "Welcome to AdTool Pro" | "Cut your ad spend by 30% — here's how" |
+| "Free SEO audit in 60 seconds" | "Our SEO Services" | "Get your free SEO audit now" |
+
+---
+
+## Landing Page Structure
+
+Every high-converting page follows this hierarchy:
+1. **Hero** — Benefit headline + subheadline (how) + CTA
+2. **Social proof** — Logos, testimonials, or numbers
+3. **Problem** — Describe the pain they came here to solve
+4. **Solution** — Show how your product fixes it
+5. **Objection handling** — FAQ or trust signals
+6. **Final CTA** — Repeat the primary call to action
+
+### Above-the-Fold Checklist
+- [ ] Headline states the primary benefit (not a feature)
+- [ ] Subheadline explains how in one sentence
+- [ ] CTA button is visible without scrolling
+- [ ] Social proof is present
+- [ ] No navigation menu (landing page ≠ homepage)
+
+---
+
+## A/B Testing
+
+### Experiment Design
+Never run a test without:
+1. **A clear hypothesis**: "If we [change X], then [metric Y] will improve because [rationale]."
+2. **A single variable**: Don't change headline, image, AND button color at once.
+3. **Sufficient traffic**: Use a sample size calculator. Testing with 50 visitors is meaningless.
+
+### Rules
+- Don't stop a test early just because it looks like it's winning.
+- Wait for at least **95% statistical significance**.
+- Run for at least **7-14 days** to account for day-of-week anomalies.
+- If traffic is low, test **macro changes** (the whole offer, the pricing). Micro changes (button color) require massive traffic.
+
+---
+
+## Quick Wins (Ordered by Impact)
+
+1. **Reduce form fields** — Every field removed increases conversion ~5-10%
+2. **Make CTA specific** — "Start my free trial" > "Submit"
+3. **Add a testimonial near the CTA** — Social proof at the point of decision
+4. **Remove navigation** — Landing pages should have one exit: the CTA
+5. **Improve load speed** — Every 1s delay = ~7% drop in conversions
+
+## Prioritization (ICE Score)
+When the user has multiple optimization ideas:
+- **Impact** (1-10): How much will this move the needle?
+- **Confidence** (1-10): How sure are we?
+- **Ease** (1-10): How easy to implement?
+- Score = I × C × E. Test highest first.
+
+## Key Metrics
+- **Conversion rate** = conversions ÷ visitors
+- **Bounce rate** > 70%? Message match is broken or page loads too slow
+- **Scroll depth** — If users don't pass the fold, the hero isn't working

package/skills/product-marketing.md

@@ -0,0 +1,53 @@
+---
+name: product-marketing
+description: Core context about the business, ICP, and value proposition.
+---
+# Product Marketing Foundation
+
+## When to Use This Skill
+
+Read this skill **first** before applying any other marketing skill. It defines your product context, ICP, positioning, and messaging — every other skill uses this as its foundation.
+
+This skill activates when the user is:
+- Setting up their marketing context for the first time
+- Working on any marketing task and no product context has been established
+- Explicitly asking you to understand their product
+
+---
+
+## Instructions
+
+If a `PRODUCT_CONTEXT.md` file exists in the project root or the context was loaded from the OpenAds setup config, read it first and use it.
+
+If no context exists:
+Ask the user to fill out this context. Once established, reference it in every subsequent task.
+
+### Required Context to Establish
+
+```yaml
+# Product Marketing Context
+product:
+  name: ""
+  tagline: ""
+  category: ""          # e.g. "SaaS", "ecommerce", "mobile app", "marketplace"
+
+icp:                    # Ideal Customer Profile
+  who: ""               # Job title or persona description
+  key_pain: ""          # The #1 problem they have that you solve
+
+positioning:
+  differentiator: ""    # Your defensible advantage
+  value_metric: ""      # How they measure success
+
+messaging:
+  primary_message: ""   # One sentence: what you do and for whom
+  tone: ""              # e.g. "authoritative but approachable", "playful"
+```
+
+## Using This Context in Other Skills
+
+When applying any other marketing skill, always:
+1. Reference `product.name` and `icp.who` in every output
+2. Align copy and recommendations to `positioning.differentiator`
+3. Use `messaging.tone` for all written content
+4. Frame results in terms of `icp.key_pain`

package/skills/research/competitors.md

@@ -0,0 +1,54 @@
+---
+name: competitors
+description: Analyze competitor positioning, ads, and messaging gaps.
+---
+# Competitive Analysis
+
+## When to Use This Skill
+
+Activate when the user needs to:
+- Understand what competitors are saying in their ads
+- Find gaps in competitor messaging they can exploit
+- Benchmark their positioning against alternatives
+- Research competitor landing pages, offers, or pricing
+
+Read `product-marketing.md` first.
+
+---
+
+## Competitor Ad Analysis Framework
+
+### 1. Message Mapping
+For each competitor, capture:
+- **Primary headline claim** — What do they promise in their top-of-funnel ads?
+- **Proof points** — What evidence do they use? (social proof, stats, awards)
+- **CTA style** — Soft ("Learn more") or hard ("Start free trial")?
+- **Emotional angle** — Fear, aspiration, urgency, curiosity?
+
+### 2. Gap Analysis
+After mapping 3-5 competitors, look for:
+- **Unspoken benefits** — What does your product do that nobody is talking about?
+- **Overused claims** — What is everyone saying? (Avoid it — you'll blend in.)
+- **Audience blind spots** — Is everyone targeting the same persona? Is there an underserved segment?
+
+### 3. Positioning Matrix
+
+| | Low Price | High Price |
+|---|---|---|
+| **Simple** | Commodity play | Premium simplicity |
+| **Complex** | Budget enterprise | Full-suite leader |
+
+Place yourself and competitors on this grid. Your ad messaging should clearly communicate which quadrant you own.
+
+---
+
+## Output Format
+
+Produce a competitive brief:
+```
+Competitor: [Name]
+  Headline claim: [Their main promise]
+  Proof: [What evidence they use]
+  Weakness: [Where they fall short]
+  Opportunity: [What you can say that they can't]
+```