@stacksjs/defaults 0.75.108 → 0.75.110

package/ai/skills/stacks-marketing-competitors/PLAYBOOK.md

@@ -0,0 +1,283 @@
+> Adapted playbook. The [shared Stacks workflow](../stacks-marketing/WORKFLOW.md) governs implementation, current facts, and authorization.
+
+
+# Competitor & Alternative Pages
+
+You are an expert in creating competitor comparison and alternative pages. Your goal is to build pages that rank for competitive search terms, provide genuine value to evaluators, and position your product effectively.
+
+## Initial Assessment
+
+**Check for product marketing context first:**
+Read the established product context described in [the shared workflow](../stacks-marketing/WORKFLOW.md) before asking questions.
+
+**Never guess the competitor.** If the request doesn't name one and the context file doesn't identify it, ask, and stop there. Don't draft a polished page around the most likely candidate.
+
+Before creating competitor pages, understand:
+
+1. **Your Product**
+   - Core value proposition
+   - Key differentiators
+   - Ideal customer profile
+   - Pricing model
+   - Strengths and honest weaknesses
+
+2. **Competitive Landscape**
+   - Direct competitors
+   - Indirect/adjacent competitors
+   - Market positioning of each
+   - Search volume for competitor terms
+
+3. **Goals**
+   - SEO traffic capture
+   - Sales enablement
+   - Conversion from competitor users
+   - Brand positioning
+
+---
+
+## Core Principles
+
+### 1. Honesty Builds Trust
+- Acknowledge competitor strengths
+- Be accurate about your limitations
+- Don't misrepresent competitor features
+- Readers are comparing-they'll verify claims
+
+### 2. Depth Over Surface
+- Go beyond feature checklists
+- Explain *why* differences matter
+- Include use cases and scenarios
+- Show, don't just tell
+
+### 3. Help Them Decide
+- Different tools fit different needs
+- Be clear about who you're best for
+- Be clear about who competitor is best for
+- Reduce evaluation friction
+
+### 4. Modular Content Architecture
+- Competitor data should be centralized
+- Updates propagate to all pages
+- Single source of truth per competitor
+
+### 5. Evidence Discipline
+Comparison pages are public claims about another company. Every one should survive the competitor's own team reading it.
+- **"Not observed" is not "doesn't have."** A pricing page that doesn't list SSO is evidence about the page, not the product. Write "not listed on their pricing page (as of Mar 2026)" or drop the row. Use ✗ or "not available" only when their docs or a hands-on trial confirm the absence.
+- **Date competitor facts.** Pricing and features change. Put an "as of" date on pricing tables and in the competitor data file, and re-verify before republishing.
+- **One look is a snapshot.** A single visit can't support "they haven't changed pricing in years" or "no new features since 2024." That needs dated history (changelog, archived pages).
+- **State what changed, not why.** "They moved SSO to the Enterprise tier" is a fact. "Because they're squeezing upmarket" is a guess. Leave motive out unless they've said it publicly.
+- **Separate fact from interpretation.** Keep what their site says apart from what you think it means for the buyer, and keep both apart from what you recommend.
+
+---
+
+## Page Formats
+
+### Format 1: [Competitor] Alternative (Singular)
+
+**Search intent**: User is actively looking to switch from a specific competitor
+
+**URL pattern**: `/alternatives/[competitor]` or `/[competitor]-alternative`
+
+**Target keywords**: "[Competitor] alternative", "alternative to [Competitor]", "switch from [Competitor]"
+
+**Page structure**:
+1. Why people look for alternatives (validate their pain)
+2. Summary: You as the alternative (quick positioning)
+3. Detailed comparison (features, service, pricing)
+4. Who should switch (and who shouldn't)
+5. Migration path
+6. Social proof from switchers
+7. CTA
+
+---
+
+### Format 2: [Competitor] Alternatives (Plural)
+
+**Search intent**: User is researching options, earlier in journey
+
+**URL pattern**: `/alternatives/[competitor]-alternatives`
+
+**Target keywords**: "[Competitor] alternatives", "best [Competitor] alternatives", "tools like [Competitor]"
+
+**Page structure**:
+1. Why people look for alternatives (common pain points)
+2. What to look for in an alternative (criteria framework)
+3. List of alternatives (you first, but include real options)
+4. Comparison table (summary)
+5. Detailed breakdown of each alternative
+6. Recommendation by use case
+7. CTA
+
+**Important**: Include 4-7 real alternatives. Being genuinely helpful builds trust and ranks better.
+
+**AI-answer expectations by stage**: these pages often earn *citations* in AI answers, but whether AI *recommends* your brand from them depends on offsite consensus (reviews, forums, analysts) - for emerging brands, a self-ranked list can surface the competitors in the AI answer while you get only the citation. Still publish for search intent and category framing, but set expectations accordingly - see stacks-marketing-ai-seo's citations-vs-recommendations reference for the data.
+
+---
+
+### Format 3: You vs [Competitor]
+
+**Search intent**: User is directly comparing you to a specific competitor
+
+**URL pattern**: `/vs/[competitor]` or `/compare/[you]-vs-[competitor]`
+
+**Target keywords**: "[You] vs [Competitor]", "[Competitor] vs [You]"
+
+**Page structure**:
+1. TL;DR summary (key differences in 2-3 sentences)
+2. At-a-glance comparison table
+3. Detailed comparison by category (Features, Pricing, Support, Ease of use, Integrations)
+4. Who [You] is best for
+5. Who [Competitor] is best for (be honest)
+6. What customers say (testimonials from switchers)
+7. Migration support
+8. CTA
+
+---
+
+### Format 4: [Competitor A] vs [Competitor B]
+
+**Search intent**: User comparing two competitors (not you directly)
+
+**URL pattern**: `/compare/[competitor-a]-vs-[competitor-b]`
+
+**Page structure**:
+1. Overview of both products
+2. Comparison by category
+3. Who each is best for
+4. The third option (introduce yourself)
+5. Comparison table (all three)
+6. CTA
+
+**Why this works**: Captures search traffic for competitor terms, positions you as knowledgeable.
+
+---
+
+## Essential Sections
+
+### TL;DR Summary
+Start every page with a quick summary for scanners-key differences in 2-3 sentences.
+
+### Paragraph Comparisons
+Go beyond tables. For each dimension, write a paragraph explaining the differences and when each matters.
+
+### Feature Comparison
+For each category: describe how each handles it, list strengths and limitations, give bottom line recommendation.
+
+### Pricing Comparison
+Include tier-by-tier comparison, what's included, hidden costs, and total cost calculation for sample team size.
+
+### Who It's For
+Be explicit about ideal customer for each option. Honest recommendations build trust.
+
+### Migration Section
+Cover what transfers, what needs reconfiguration, support offered, and quotes from customers who switched.
+
+**For detailed templates**: See [references/templates.md](references/templates.md)
+
+---
+
+## Content Architecture
+
+### Centralized Competitor Data
+Create a single source of truth for each competitor with:
+- Positioning and target audience
+- Pricing (all tiers)
+- Feature ratings
+- Strengths and weaknesses
+- Best for / not ideal for
+- Common complaints (from reviews)
+- Migration notes
+
+**For data structure and examples**: See [references/content-architecture.md](references/content-architecture.md)
+
+---
+
+## Research Process
+
+### Deep Competitor Research
+
+For each competitor, gather:
+
+1. **Product research**: Sign up, use it, document features/UX/limitations
+2. **Pricing research**: Current pricing, what's included, hidden costs
+3. **Review mining**: G2, Capterra, TrustRadius for common praise/complaint themes
+4. **Customer feedback**: Talk to customers who switched (both directions)
+5. **Content research**: Their positioning, their comparison pages, their changelog
+
+### Ongoing Updates
+
+- **Quarterly**: Verify pricing, check for major feature changes
+- **When notified**: Customer mentions competitor change
+- **Annually**: Full refresh of all competitor data
+
+### Competitive Asset Audit
+
+When asked to check existing competitive content for stale or risky claims, audit every asset that makes claims about competitors: vs and alternative pages, battle cards, talk tracks, objection docs, and comparison tables in decks.
+
+1. **List each claim** about a competitor, with the asset and line it lives in.
+2. **Re-verify each claim** against the competitor's current site, docs, or changelog, and note the date you checked. If you can't browse, mark claims unchecked and list what to verify. Never mark one Current without a check date.
+3. **Mark each one**:
+   - **Current**: still true, source and date updated
+   - **Changed**: now wrong, with what it says now
+   - **Unverifiable**: had a source once, but nothing current confirms or rules it out. Soften to "not listed (as of date)" or remove
+   - **Overclaimed**: stated as fact with no source behind it (an unconfirmed ✗, a guessed motive, a "why we win" with no evidence). Rewrite to what the evidence supports or remove
+4. **Prioritize fixes**: public pages first (buyers and competitors read them), then anything reps say on calls, then internal docs.
+5. **Report**: assets audited, claims checked, counts by status, and a fix list with the replacement wording.
+
+Apply the Evidence Discipline rules above to every claim, including those in internal sales assets. Where several assets repeat one fact, fix it in the centralized competitor data so the fix carries through.
+
+---
+
+## SEO Considerations
+
+### Keyword Targeting
+
+| Format | Primary Keywords |
+|--------|-----------------|
+| Alternative (singular) | [Competitor] alternative, alternative to [Competitor] |
+| Alternatives (plural) | [Competitor] alternatives, best [Competitor] alternatives |
+| You vs Competitor | [You] vs [Competitor], [Competitor] vs [You] |
+| Competitor vs Competitor | [A] vs [B], [B] vs [A] |
+
+### Internal Linking
+- Link between related competitor pages
+- Link from feature pages to relevant comparisons
+- Create hub page linking to all competitor content
+
+### Schema Markup
+Consider FAQ schema for common questions like "What is the best alternative to [Competitor]?"
+
+---
+
+## Output Format
+
+### Competitor Data File
+Complete competitor profile in YAML format for use across all comparison pages.
+
+### Page Content
+For each page: URL, meta tags, full page copy organized by section, comparison tables, CTAs.
+
+### Page Set Plan
+Recommended pages to create with priority order based on search volume.
+
+### Asset Audit Report
+Claims checked per asset, status counts (current / changed / unverifiable / overclaimed), and a prioritized fix list with replacement wording.
+
+---
+
+## Task-Specific Questions
+
+1. What are common reasons people switch to you?
+2. Do you have customer quotes about switching?
+3. What's your pricing vs. competitors?
+4. Do you offer migration support?
+
+---
+
+## Related Skills
+
+- **stacks-marketing-programmatic-seo**: For building competitor pages at scale
+- **stacks-marketing-copywriting**: For writing compelling comparison copy
+- **stacks-marketing-seo-audit**: For optimizing competitor pages
+- **stacks-marketing-schema**: For FAQ and comparison schema
+- **stacks-marketing-sales-enablement**: For battle cards and internal sales collateral, decks, and objection docs

package/ai/skills/stacks-marketing-competitors/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: stacks-marketing-competitors
+description: Use when the user wants to create competitor comparison or alternative pages for SEO and buyer-facing use. Covers marketing planning and its Stacks implementation.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Marketing Competitors
+
+Read [the shared Stacks workflow](../stacks-marketing/WORKFLOW.md), then
+[PLAYBOOK.md](PLAYBOOK.md) before doing this task. Load the supporting references
+only for the branch the playbook routes to.
+
+This ports `competitors` from
+[coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills/tree/1efedbc5148b54b2f0f6c6c9fe0be62e151c7fff/skills/competitors).
+[NOTICE.md](NOTICE.md) records the snapshot and [LICENSE](LICENSE) retains the
+upstream MIT notice.
+
+## Stacks integration
+
+Keep marketing recommendations distinct from application API facts. Use the
+framework skill for any model, action, route, stx page, campaign job, or payment
+change. Use the user's existing brief and authorization; a playbook example
+does not supply a product fact or authorize sending, spending, or publishing.
+
+Platform limits and benchmarks in the snapshot need current primary-source
+verification before use. Return the requested artifact with consequential
+assumptions and evidence, then verify any implementation through its real
+behavior. Use TypeScript and Bun for executable helpers.

package/ai/skills/stacks-marketing-competitors/evals/evals.json

@@ -0,0 +1,119 @@
+{
+  "skill_name": "stacks-marketing-competitors",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Create a 'Best Asana Alternatives' page for our project management tool. We compete mainly on price (we're $8/user vs their $24/user) and simplicity (they've become bloated). Target audience is small teams (5-20 people).",
+      "expected_output": "Should check for product-marketing.md first. Should identify this as the plural alternatives format ([Competitor] Alternatives). Should include the essential sections: TL;DR comparison, brief paragraphs on each alternative (including the user's product positioned first or prominently), feature comparison table, pricing comparison, who each alternative is best for. Should use the modular content architecture approach. Should address SEO considerations for the target keyword 'Asana alternatives.' Should position the user's product with the stated differentiators (price, simplicity).",
+      "assertions": [
+        "Checks for product-marketing.md",
+        "Identifies as plural alternatives format",
+        "Includes TL;DR comparison section",
+        "Includes feature comparison table",
+        "Includes pricing comparison",
+        "Includes 'who it's best for' per alternative",
+        "Positions user's product prominently with differentiators",
+        "Addresses SEO for target keyword"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Write a 'HubSpot vs Salesforce' comparison page. We're HubSpot and want to show why we're the better choice for SMBs.",
+      "expected_output": "Should identify this as the 'you vs competitor' format. Should include structured comparison sections: overview of both, feature-by-feature comparison, pricing comparison, pros/cons of each, who each is best for, and migration path. Should be factually accurate about the competitor while strategically positioning the user's product. Should include a TL;DR at the top. Should address the SMB angle throughout. Should use the centralized competitor data architecture pattern.",
+      "assertions": [
+        "Identifies as 'you vs competitor' format",
+        "Includes structured comparison sections",
+        "Includes feature-by-feature comparison",
+        "Includes pricing comparison",
+        "Includes TL;DR at the top",
+        "Factually accurate about competitor",
+        "Strategically positions user's product for SMBs",
+        "Includes migration path or switching section"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "we need a page targeting 'mailchimp alternative' (singular). we're an email marketing platform focused on e-commerce brands.",
+      "expected_output": "Should trigger on casual phrasing. Should identify this as the singular alternative format ([Competitor] Alternative - positioning your product as THE alternative). Should focus the entire page on why the user's product is the best Mailchimp alternative for e-commerce. Should include: why people switch from Mailchimp, what the user's product does better (e-commerce specific features), feature comparison, pricing comparison, migration guide, customer testimonials. Should optimize for the singular keyword 'Mailchimp alternative.'",
+      "assertions": [
+        "Triggers on casual phrasing",
+        "Identifies as singular alternative format",
+        "Focuses on user's product as THE alternative",
+        "Includes why people switch from Mailchimp",
+        "Highlights e-commerce-specific advantages",
+        "Includes feature and pricing comparison",
+        "Includes migration guide",
+        "Optimizes for singular keyword"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "Can you create a comparison page for 'Notion vs Coda'? We're a third-party review site, not affiliated with either product.",
+      "expected_output": "Should identify this as the 'competitor vs competitor' format (third-party perspective). Should maintain objectivity since the user isn't either product. Should include balanced comparison: overview of both, feature comparison, pricing, pros/cons, use case recommendations. Should use the essential page sections from the skill. Should suggest how to monetize the page (affiliate links, CTA to the user's own product if relevant). Should address SEO for the 'Notion vs Coda' keyword.",
+      "assertions": [
+        "Identifies as 'competitor vs competitor' format",
+        "Maintains objectivity (third-party perspective)",
+        "Includes balanced feature comparison",
+        "Includes pricing comparison",
+        "Includes use case recommendations",
+        "Addresses SEO considerations",
+        "Suggests monetization approach"
+      ],
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "We want to build a whole competitor comparison hub. We have 5 main competitors and want to create alternative pages for each, plus head-to-head comparisons. How should we structure this?",
+      "expected_output": "Should apply the centralized competitor data architecture. Should recommend a hub structure with: individual alternative pages for each competitor (5 singular pages), a 'best alternatives' roundup page, head-to-head comparison pages for key matchups. Should address internal linking strategy between these pages. Should recommend the research process for gathering competitive data. Should address URL structure and site architecture for the hub.",
+      "assertions": [
+        "Applies centralized competitor data architecture",
+        "Recommends hub structure with multiple page types",
+        "Suggests individual and roundup alternative pages",
+        "Addresses internal linking between comparison pages",
+        "Recommends research process for competitive data",
+        "Addresses URL structure"
+      ],
+      "files": []
+    },
+    {
+      "id": 6,
+      "prompt": "I need to create a battle card for our sales team comparing us to Zendesk. It should help reps handle competitive objections during sales calls.",
+      "expected_output": "Should recognize this as internal sales enablement material, not a public comparison page. Should defer to or cross-reference the sales-enablement skill, which handles battle cards, objection handling docs, and internal competitive collateral. May provide some competitive positioning advice but should make clear that sales-enablement is the right skill for internal sales materials.",
+      "assertions": [
+        "Recognizes this as internal sales enablement material",
+        "References or defers to sales-enablement skill",
+        "Does not attempt to create internal battle card using public comparison page patterns"
+      ],
+      "files": []
+    },
+    {
+      "id": 7,
+      "prompt": "Write the comparison table for our Acme vs Northwind page. I checked Northwind's pricing page and it doesn't mention SSO, audit logs, or an API, so mark all three as ✗ for them. Also add a line that they raised prices last quarter because they're struggling to grow.",
+      "expected_output": "Should push back on marking SSO, audit logs, and API as unavailable based only on their absence from a pricing page: absence from a page is evidence about the page, not the product. Should suggest checking Northwind's docs/help center or a trial, and in the meantime write 'not listed on pricing page (as of [date])' or drop the rows. Should state the price change as a dated fact but remove the claimed motive ('because they're struggling') since nothing sources it. Should add an 'as of' date to the pricing comparison.",
+      "assertions": [
+        "Does not mark the three features as ✗ / not available based only on the pricing page",
+        "Recommends verifying via docs, help center, or trial",
+        "Uses 'not listed' or 'not observed' wording with a date, or drops the rows",
+        "Removes or refuses the unsourced motive claim about struggling to grow",
+        "Dates the pricing information"
+      ]
+    },
+    {
+      "id": 8,
+      "prompt": "We have 12 vs pages and 4 battle cards written over the last two years. Can you check them for anything that's out of date or that would get us in trouble?",
+      "expected_output": "Should run the competitive asset audit across both the public pages and the internal battle cards. Should list each competitor claim with where it lives, re-verify against current competitor sources with a check date, and mark each as current, changed, unverifiable, or overclaimed. Should flag unconfirmed ✗ marks, guessed motives, and unsupported 'why we win' claims as overclaimed. Should prioritize public pages first and give replacement wording, and recommend fixing shared facts in the centralized competitor data.",
+      "assertions": [
+        "Covers both public pages and internal battle cards",
+        "Re-verifies claims against current sources with a check date",
+        "Uses the current / changed / unverifiable / overclaimed statuses",
+        "Flags unconfirmed absence claims or unsupported 'why we win' lines",
+        "Prioritizes public pages first",
+        "Provides replacement wording in a fix list"
+      ],
+      "files": []
+    }
+  ]
+}