@jairodri/huckleberry-cli 1.0.1 → 1.1.0

package/skills/seo-machine/SKILL.md

@@ -0,0 +1,331 @@
+---
+name: seo-machine
+description: "Build an organic-traffic operating system for any site or app: a multi-phase, resumable engine that ships programmatic landing pages..."
+category: seo
+tier: nice-to-have
+reads:
+  - brand/keyword-plan.md
+  - brand/positioning.md
+  - brand/competitors.md
+  - brand/audience.md
+  - brand/stack.md
+writes:
+  - docs/seo-machine.md
+  - .seo/brand.md
+  - .seo/link-inventory.md
+  - .seo/config.json
+triggers:
+  - seo machine
+  - build organic traffic
+  - rank in google
+  - alternatives pages
+  - comparison pages
+  - programmatic seo playbook
+  - we need traffic
+---
+
+# SEO Machine
+
+End-to-end engine for building organic search traffic. Ships dozens of programmatic landing pages — alternatives, comparisons, use-cases, playbooks — backed by real keyword research, with a persistent roadmap the user resumes across sessions.
+
+Conversion-first (alternatives + comparisons before blogs). Publish-early (a thin page indexed today beats a perfect page indexed in three weeks). Stack-native (writes into the user's framework — Next.js, Astro, Rails+Inertia, or a portable markdown fallback).
+
+## Two modes, auto-detected
+
+| Mode | When | What it produces |
+|---|---|---|
+| **Initialize** | `docs/seo-machine.md` does not exist | Stack detection → brand context → keyword research → tech audit → roadmap + link inventory |
+| **Resume** | `docs/seo-machine.md` exists | Reads the tracker, picks the next pending phase (or one the user names), executes end-to-end through the quality gates |
+
+Detection rule on every invocation: check `docs/seo-machine.md` at repo root (or the path recorded in `.seo/config.json`). No file → Initialize. File exists → Resume. The user does not need to remember which mode they're in.
+
+## Publishing Order (the load-bearing decision rule)
+
+The roadmap orders patterns by **conversion intent first, traffic intent second**. This is the single most important decision the skill makes — it's why the alternatives + comparison pages ship before the playbooks + blog posts.
+
+| Order | Pattern | Why | Cost |
+|---|---|---|---|
+| 1 | `/alternatives/[competitor]` (Pattern A) | Highest conversion intent — the reader is already in market | ~4 hours per page |
+| 2 | `/compare/[a]-vs-[b]` (Pattern D) | Be the third option in any two-vendor comparison | ~3 hours per page |
+| 3 | `/for/[use-case]` and `/for/[audience]` (Pattern B/C) | JTBD without competitor name in query — high TP/volume ratio | ~4-5 hours per page |
+| 4 | `/playbooks/[topic]` (Pattern E) | Authority + AI-citation surface area + inbound link draw | ~2-3 days per page |
+| 5 | `/blog/...` (out of scope here) | Lowest conversion intent; defer until ~10 indexed pages exist | — |
+
+**Why this order matters:** alternatives pages convert 5–20× blog posts at 1/10 the search volume. Shipping one alternatives page is worth ten generic blog posts on the same topic. The roadmap should reflect this — Phase 0 (tech audit) → Phases 1–N (alternatives, then comparisons, then use-cases) → late phases (playbooks) → never (blogs, unless explicitly requested by the user).
+
+Striking-distance boosts (pages already ranking pos 5–20 in GSC) jump the queue when they exist — fastest wins per hour of work.
+
+---
+
+## On Activation
+
+1. Load brand context where present: `brand/keyword-plan.md`, `positioning.md`, `competitors.md`, `audience.md`, `stack.md`. Missing files are fine.
+2. Surface what loaded:
+   ```
+   Brand context loaded:
+   ├── Keyword Plan    ✓/✗  (seeds the roadmap; ✗ → generate during Initialize)
+   ├── Positioning     ✓/✗  (drives /compare and /alternatives angles)
+   ├── Competitors     ✓/✗  (target list for /alternatives pages)
+   ├── Audience        ✓/✗  (intent buckets for /for/<persona> pages)
+   └── Stack           ✓/✗  (selects references/stacks/<framework>.md)
+   ```
+3. Progressive enhancement: with zero brand files the skill still works — it derives signal from the repo (`CLAUDE.md`, `README.md`, `package.json`, design tokens, existing marketing pages) during Initialize Step 2. With full brand context it skips re-discovery and goes straight to research + roadmap.
+
+---
+
+## Hard prerequisites
+
+| # | Check | Failure mode |
+|---|---|---|
+| 1 | `git rev-parse --is-inside-work-tree` succeeds | Stop. Tell the user this skill writes a persistent roadmap; initialize git or run from a repo. |
+| 2 | A stack is detectable — one of `package.json`, `Gemfile`, `composer.json`, `requirements.txt`, `astro.config.*`, `next.config.*`, `nuxt.config.*`, `gatsby-config.*`, `_config.yml`, `config.toml`, `pyproject.toml` | Ask the user what stack they're on before continuing. |
+| 3 | Research backend resolved (see below) | Never refuse to run — fall through to manual mode. |
+
+**Research backend resolution order** (record the choice in `.seo/config.json` under `research_backend`):
+
+1. **Exa-stack** (mktg-native, default). Probe `mcp__exa__web_search_advanced_exa` with a minimal query. On success, use the full Exa research stack — Exa MCP + Firecrawl (SERP scrape) + `gh` (OSS competitor signal) + `/last30days` skill (Reddit/X/HN aggregation) + `mktg-x` (auth-walled Twitter) + the mktg-native `company-research` / `people-research` skills. The 7 Exa-native recipes in `references/exa-recipes.md` replace the Ahrefs cookbook entirely; the cross-API compound recipes in `references/api-stack-recipes.md` add capabilities Ahrefs alone can't do (pain-point clustering, OSS competitor teardown, outreach prospect discovery, newcomer surveillance).
+2. **Manual mode** — Exa-stack unavailable. Follow `references/manual-research.md` (free Google + Search Console + paste-from-UI fallback).
+
+> **Ahrefs as a footnote:** if `mcp__ahrefs__subscription-info-limits-and-usage` returns data AND the user wants numeric volume/KD/TP precision, layer Ahrefs on top of the Exa-stack rather than replacing it. The "Ahrefs appendix" at the bottom of `references/exa-recipes.md` documents which Ahrefs queries upgrade each Exa-native recipe with precise numbers. Ahrefs MCP is intentionally NOT in mktg's chained-in ecosystem table — it's a paid escalation, not a default dependency.
+
+---
+
+## Initialize mode
+
+Goal: end the run with a written `docs/seo-machine.md` containing keyword research, a phase tracker grouped by pattern, and technical-audit findings — plus `.seo/brand.md` and `.seo/link-inventory.md`.
+
+### Step 1 — Detect stack + frontend convention
+
+Read `references/stacks/detection.md`. Identify framework family, routing convention (file-based vs controller-based), component language, and existing marketing pages (`git ls-files | grep -iE 'marketing|landing|pages/(home|about|pricing)'`). Resolve ambiguity with `AskUserQuestion`. Persist to `.seo/config.json`.
+
+### Step 2 — Detect brand + product context
+
+Read every signal first, propose `.seo/brand.md`, then ask only about gaps. Signals: `CLAUDE.md`, `README.md`, `package.json` / `Gemfile.lock`, `tailwind.config.*` or design-token CSS, `app/views/marketing/*` or `pages/index.*`, `pricing` page.
+
+If `brand/voice-profile.md` and `brand/positioning.md` already exist (mktg-native project), read them and skip 80% of the questions — those files already say who the buyer is and what the brand sounds like.
+
+Otherwise use a single `AskUserQuestion` (3–4 questions max) to fill gaps. Required to know:
+
+- **Product one-liner** (≤20 words)
+- **Primary persona** (e.g. "B2B SaaS founder", "indie agency owner")
+- **3–7 direct competitors** by name
+- **Brand voice tags** (e.g. "honest, technical, no-jargon")
+- **Free tier?** (drives the "is [brand] free" keyword strategy)
+- **Anti-positioning** — what the product does NOT do (used in honest comparison sections)
+
+Write to `.seo/brand.md` using `assets/brand-template.md` as the skeleton.
+
+### Step 3 — Keyword research (Exa-native stack)
+
+Follow `references/exa-recipes.md` — 7 Exa-native recipes that replace the Ahrefs cookbook:
+
+| Recipe | Purpose | Primary API |
+|---|---|---|
+| A. Domain baseline | DR estimate from indexed-page count + brand mentions + GitHub stars (OSS) | Exa `company_research_exa` + `web_search_advanced_exa` + `gh` |
+| B. Competitor reverse-lookup | What competitors rank for | Exa `web_search_advanced_exa` `site:<competitor>` + AI summary |
+| C. Use-case sweep | `/for/` and `/playbooks/` topic discovery | Exa `deep_search_exa` + Firecrawl autocomplete + `/last30days` |
+| D. Comparison volume | Validate demand for `/compare/[a]-vs-[b]` before writing | Exa `web_search_advanced_exa` + Firecrawl SERP scrape |
+| E. SERP saturation | Replaces Ahrefs KD with SERP-composition-derived signal | Exa search + per-result `company_research_exa` |
+| F. Backlink prospecting | Referring-domain proxy via Exa | Exa search + DR proxy (see `off-page-seo` skill) |
+| G. Content gap | Their indexed keywords − ours, ranked by DR-cap fit | Recipes B + own-site Exa lookup |
+
+Then pull cross-API compound recipes from `references/api-stack-recipes.md` for moves Ahrefs alone can't do — pain-point cluster discovery (`/last30days` + `mktg-x` + Exa deep search), OSS competitor teardown (`gh` + DeepWiki + Exa), outreach prospect discovery (Exa Websets + people-research), newcomer surveillance (Exa Websets cron).
+
+When Exa is unavailable, fall back to `references/manual-research.md` (paste-from-UI workflow). When the user has paid Ahrefs, layer it on top per the appendix in `exa-recipes.md` — don't replace.
+
+Cache the raw output to `.seo/keyword-research.json`. Curate the decision-ready summary into the **Keyword Research Appendix** section of `docs/seo-machine.md`.
+
+### Step 4 — Technical foundations audit
+
+Run `scripts/tech_audit.py` (sitemap, robots, meta-tag uniqueness, schema). Whatever it finds becomes **Phase 0** in the roadmap. Day-0 crawl shapes Google's understanding of the site for months — retroactive fixes are harder.
+
+### Step 5 — Generate the roadmap
+
+Fill `assets/roadmap-template.md` with:
+
+- **Site facts** (domain, DR, stack, brand colors, fonts) from steps 1–2
+- **Reference data** — paths to controllers / page files this skill will edit
+- **Keyword Research Appendix** — curated, grouped by pattern
+- **Phase Status Tracker** — auto-populated:
+  - Phase 0: technical foundations fixes
+  - Phase 1+: one row per page candidate
+  - Group by pattern. Within a pattern, order by `traffic_potential` desc → `volume` desc → `KD` asc
+  - Striking-distance boosts near the front (fastest wins on existing sites)
+  - Off-page checklist (directories + outreach) tail-end, one phase per category
+
+Write to the configured path (default `docs/seo-machine.md`). Print the path back and recommend a human review pass before Phase 0.
+
+### Step 6 — Generate `.seo/link-inventory.md`
+
+Every phase reads this file to pick internal links. Use `assets/link-inventory-template.md`. Pre-populate from existing routes (features, tools, pricing, blog posts). Each phase appends to it as new pages ship.
+
+### Step 7 — Hand off
+
+```
+✓ Initialize complete
+
+  Roadmap:        docs/seo-machine.md
+  Brand context:  .seo/brand.md
+  Keyword cache:  .seo/keyword-research.json
+  Link inventory: .seo/link-inventory.md
+  Config:         .seo/config.json
+
+Next: review docs/seo-machine.md, then run me again to execute Phase 0.
+```
+
+Do not auto-execute Phase 0. Pattern priorities and competitor lists are decisions worth a human pass.
+
+---
+
+## Resume mode
+
+Goal: pick the next phase from the tracker, execute end-to-end with quality gates, hand back so the user can commit/PR.
+
+### Step 1 — Read state
+
+Load `docs/seo-machine.md`, `.seo/brand.md`, `.seo/link-inventory.md`, `.seo/config.json`. Find the **Phase Status Tracker**, identify the next `pending` phase with the lowest number, print it back along with the two phases that follow.
+
+### Step 2 — Confirm scope
+
+Single `AskUserQuestion`:
+- "Continue with Phase N: [title]?"
+- Options: "Yes, start Phase N" / "Pick a different phase" / "Re-audit (refresh research)" / "Just show the tracker"
+
+"Different" → list pending phases. "Re-audit" → loop back into Initialize steps 3–5. "Show" → print tracker and stop.
+
+### Step 3 — Execute
+
+Pattern → reference mapping:
+
+| Phase type | Reference |
+|---|---|
+| Phase 0 — technical foundations | `references/technical-audit.md` |
+| Pattern A — `/alternatives/[competitor]` | `references/patterns/alternatives.md` |
+| Pattern B/C — `/for/[use-case]` or `/for/[audience]` | `references/patterns/use-case.md` |
+| Pattern D — `/compare/[a]-vs-[b]` | `references/patterns/compare.md` |
+| Pattern E — `/playbooks/[topic]` long-form | `references/patterns/playbooks.md` |
+| Striking-distance boost | `references/striking-distance.md` |
+| Off-page checklist phase | `references/off-page.md` |
+| Internal-link spine audit | `references/quality-bars.md` (link-audit section) |
+
+For page-generating phases, the flow is always:
+
+1. **Re-research** — current competitor pricing, feature changes. Don't trust 60-day-old cached data on commercial-intent terms.
+2. **Generate the page payload** — output format follows the stack (`references/stacks/<framework>.md`) or `references/stacks/markdown-fallback.md`.
+3. **Verify** against the quality bar (word count, internal links, schema, honesty section on alts). Run `scripts/word_count.py` and `scripts/link_audit.py`. If a check fails, fix it — don't ship under-spec work.
+4. **Update `.seo/link-inventory.md`** with the new page.
+5. **Update the tracker row** in `docs/seo-machine.md` — status `completed`, PR ref or commit SHA. Same edit batch as the page work so reviewers see both in one diff.
+
+### Step 4 — Hand off (do NOT auto-commit)
+
+```
+✓ Phase N complete: [title]
+
+Files changed:
+  app/controllers/marketing_controller.rb  (added entry)
+  app/frontend/pages/Alternatives/Show.tsx (no change — uses existing layout)
+  docs/seo-machine.md                      (tracker updated)
+  .seo/link-inventory.md                   (new page registered)
+
+Quality gates:
+  ✓ Word count: 712 / 600 min
+  ✓ Internal links: 2 alts, 1 feature, 1 tool
+  ✓ FAQ JSON-LD attached
+  ✓ Honesty section present (3 rows)
+
+Suggested commit: "SEO Phase N: ship /alternatives/[slug]"
+
+Next phase pending: Phase N+1 — [title]
+```
+
+Open a PR only if the user has expressed they want that cadence. Otherwise let them drive git.
+
+---
+
+## Interactive principles
+
+| Rule | Why |
+|---|---|
+| Ask before you guess on positioning calls | The user's gut on which competitor or use-case to ship next often beats the data |
+| Show the numbers, not the conclusion | "vol 400, KD 12, TP 1,800" builds more trust than "the data is good" |
+| Be honest about what won't work | KD 80 at DR 8 = doomed. Say so, offer the closest winnable alternative |
+| One-sentence theory max per phase | The user doesn't need a recap of SEO theory every run |
+| Surface tradeoffs, not opinions | "5 thin alternatives or 2 deep ones first?" — state the tradeoff, ask |
+
+---
+
+## Adjacent skills (route here vs there)
+
+| Skill | When | When NOT |
+|---|---|---|
+| `seo-audit` | One-off diagnostic on an existing site | Forward execution — use this skill |
+| `seo-content` | Writing a single rankable article | A whole sprint — use this skill |
+| `competitor-alternatives` | One `/alternatives/<x>` page, ad-hoc | Pattern A as part of a sprint — use this skill |
+| `keyword-research` | Producing `brand/keyword-plan.md` | This skill consumes that artifact — chain them |
+| `ai-seo` | LLM-citation optimization for a few pages | Run after this skill ships ~10 indexed pages |
+
+---
+
+## Anti-patterns
+
+| Don't | Why |
+|---|---|
+| Target head terms when DR is low | "Social media management tool" at DR 8 is wasted work. KD ≤ DR+10 while DR is low. |
+| Ship pages with no inbound internal links | A new page nobody links to is an island. ≥2 inbound links from existing pages, same phase. |
+| Ship `/alternatives` pages without an "honesty" section | Three honest tradeoffs (where the competitor wins) is non-negotiable. Brand signal AND Google quality signal. |
+| Skip schema markup | FAQPage JSON-LD captures snippets. Article for playbooks. SoftwareApplication for homepage + use-case. Quality gate fails without them. |
+| Auto-commit | Always show diff summary; let the user commit (local conventions, hooks, branch naming). |
+| Restart Initialize when partial state exists | If `.seo/config.json` exists without the roadmap, prompt before wiping — they may have aborted mid-run. |
+
+---
+
+## File map
+
+| File | Purpose |
+|---|---|
+| `references/methodology.md` | Why-this-works theory + lessons from real phases |
+| `references/exa-recipes.md` | 7 Exa-native research recipes (replaces the old Ahrefs cookbook). Ahrefs appendix at the bottom for paid-precision escalation. |
+| `references/api-stack-recipes.md` | Cross-API compound recipes — pain-point mining, OSS competitor teardown, outreach prospect discovery, newcomer surveillance. Uses Exa + Firecrawl + gh + mktg-x + DeepWiki + last30days. |
+| `references/manual-research.md` | L0 fallback when no MCP available |
+| `references/patterns/alternatives.md` | Pattern A spec, data shape, quality bar, example |
+| `references/patterns/use-case.md` | Pattern B+C spec |
+| `references/patterns/compare.md` | Pattern D spec |
+| `references/patterns/playbooks.md` | Pattern E spec (2,500-word bar) |
+| `references/stacks/detection.md` | Stack-detection signal table |
+| `references/stacks/rails-inertia.md` | Rails + Inertia adapter (reference implementation) |
+| `references/stacks/nextjs.md` | Next.js App Router adapter |
+| `references/stacks/astro.md` | Astro content-collection adapter |
+| `references/stacks/markdown-fallback.md` | Universal markdown output format |
+| `references/technical-audit.md` | Phase 0 recipes (sitemap, robots, meta, schema) |
+| `references/striking-distance.md` | GSC pos 5–20 audit + boost recipe |
+| `references/off-page.md` | Backlink checklist + Ahrefs referring-domains research |
+| `references/quality-bars.md` | Verification spec per pattern |
+| `scripts/word_count.py` | Strip markup → word count |
+| `scripts/link_audit.py` | Verify internal-link minimums per page |
+| `scripts/tech_audit.py` | Sitemap.xml + robots.txt + meta-tag scanner |
+| `assets/roadmap-template.md` | `docs/seo-machine.md` skeleton |
+| `assets/brand-template.md` | `.seo/brand.md` skeleton |
+| `assets/link-inventory-template.md` | `.seo/link-inventory.md` skeleton |
+
+---
+
+## Outputs
+
+The skill writes to **project paths**, not `brand/`. This is why `writes:` in `skills-manifest.json` is `[]` — the manifest declares only `brand/*.md` writes, and seo-machine's outputs live in the user's repo, not in brand memory.
+
+| Output | Mode | Purpose |
+|---|---|---|
+| `docs/seo-machine.md` | Initialize (write), Resume (update phase row) | Persistent sprint roadmap — Phase Status Tracker + Reference Data + Keyword Research Appendix. Single source of truth across sessions. |
+| `.seo/brand.md` | Initialize | Product context derived from repo + user answers (one-liner, persona, competitors, voice tags, anti-positioning). |
+| `.seo/link-inventory.md` | Initialize (create), Resume (append per phase) | Every internal-link target the skill can use. Each phase appends new pages. |
+| `.seo/keyword-research.json` | Initialize | Cached raw output from Ahrefs / Exa / manual research. Read by every phase, refreshed every 30 days. |
+| `.seo/config.json` | Initialize | Stack info, research backend choice, project IDs. Persists machine-readable state. |
+| Phase-specific page files | Resume (per phase) | Stack-native page files (e.g. `app/controllers/marketing_controller.rb` + `app/frontend/pages/Alternatives/Show.tsx` for Rails+Inertia; `app/[pattern]/[slug]/page.tsx` for Next.js App Router; etc.). Paths follow `references/stacks/<framework>.md`. |
+
+This follows the **Long-Arc Sprint Persistence Pattern** documented in `AGENTS.md` — `docs/seo-machine.md` is the canonical doc that survives session interruption.
+
+## /cmo integration
+
+`/cmo` routes here under **Playbook #9 — SEO Authority Build, Path B (programmatic sprint)**. On a cold project /cmo first spawns `mktg-brand-researcher`, `mktg-audience-researcher`, `mktg-competitive-scanner` in parallel (foundation), runs `keyword-research` to populate `brand/keyword-plan.md`, then hands off here. After every phase, /cmo spawns `mktg-content-reviewer` + `mktg-seo-analyst` in one message to score the page batch before the user commits.
+
+See `skills/cmo/rules/playbooks.md` and `skills/cmo/rules/sub-agents.md` for the full handoff contract.

package/skills/seo-machine/assets/brand-template.md

@@ -0,0 +1,73 @@
+# {{PRODUCT_NAME}} — Brand Context for SEO
+
+> Read every time. This file is read by every phase of the SEO machine run.
+
+## Product
+
+- **Name:** {{PRODUCT_NAME}}
+- **One-liner (≤20 words):** {{ONE_LINER}}
+- **What we do:** {{LONG_DESCRIPTION}}
+- **Pricing structure:** {{PRICING_SUMMARY}}
+- **Free tier?** {{FREE_TIER_YN}}  — {{FREE_TIER_DETAILS}}
+
+## Audience
+
+- **Primary persona:** {{PERSONA_PRIMARY}}
+- **Secondary personas:** {{PERSONA_SECONDARY}}
+- **Industries we target:** {{INDUSTRIES}}
+- **Company size we target:** {{COMPANY_SIZE}}
+- **Jobs to be done (top 3):**
+  1. {{JTBD_1}}
+  2. {{JTBD_2}}
+  3. {{JTBD_3}}
+
+## Competitors
+
+(Used to populate `/alternatives/*` and `/compare/*` patterns. Order by perceived market share / brand recognition.)
+
+| Brand | Slug | URL | Tier (head / mid / niche) | Notes |
+|---|---|---|---|---|
+{{COMPETITORS_TABLE}}
+
+## Brand voice
+
+- **Voice tags:** {{VOICE_TAGS}}  e.g. "honest, technical, no-jargon, dry-witty, founder-led"
+- **Person/perspective:** {{PERSPECTIVE}}  e.g. "we" (team), "I" (founder-led), "you-focused"
+- **Forbidden words/phrases:** {{FORBIDDEN}}  e.g. "seamlessly," "revolutionary," "synergy"
+- **Reference brands for tone:** {{TONE_REFERENCES}}  e.g. "Linear's docs, Buttondown's homepage"
+
+## Anti-positioning (where we don't compete)
+
+(Used for honesty sections on `/alternatives/*` pages. List ≥5 things you intentionally don't do.)
+
+1. {{ANTI_POS_1}}
+2. {{ANTI_POS_2}}
+3. {{ANTI_POS_3}}
+4. {{ANTI_POS_4}}
+5. {{ANTI_POS_5}}
+
+## Concrete differentiators
+
+(Things you DO that competitors don't, used in `/alternatives/*` switch-reasons.)
+
+1. {{DIFF_1}}
+2. {{DIFF_2}}
+3. {{DIFF_3}}
+4. {{DIFF_4}}
+
+## Visual brand
+
+- **Accent color (primary):** {{ACCENT_PRIMARY}}
+- **Accent color (secondary):** {{ACCENT_SECONDARY}}
+- **Ink color:** {{INK_COLOR}}
+- **Surface color:** {{SURFACE_COLOR}}
+- **Hero font family:** {{FONT_HERO}}
+- **Body font family:** {{FONT_BODY}}
+- **Icon set:** {{ICON_SET}}
+
+## Links to existing surfaces
+
+- Homepage: {{HOMEPAGE_URL}}
+- Pricing: {{PRICING_URL}}
+- Existing blog/content: {{BLOG_URL}}
+- Existing features list: {{FEATURES_URL}}

package/skills/seo-machine/assets/link-inventory-template.md

@@ -0,0 +1,74 @@
+# {{PRODUCT_NAME}} — Internal Link Inventory
+
+> Pre-populated list of every URL the SEO machine run can link to. Each pattern phase MUST pick links from this inventory and MUST update this file when it ships a new page.
+
+## Existing pages (link targets)
+
+### Homepage + core marketing
+
+| Slug | URL | Title (anchor-text candidate) | Used by patterns |
+|---|---|---|---|
+| `/` | {{HOMEPAGE_URL}} | {{HOMEPAGE_TITLE}} | All |
+| `/pricing` | {{PRICING_URL}} | Pricing | D (compare), E (playbooks) |
+| `/about` | {{ABOUT_URL}} | About | (occasional) |
+
+### Features
+
+| Slug | URL | Title | Linked by |
+|---|---|---|---|
+{{FEATURES_INVENTORY}}
+
+### Tools (free utilities)
+
+| Slug | URL | Title | Linked by |
+|---|---|---|---|
+{{TOOLS_INVENTORY}}
+
+### Blog posts
+
+| Slug | URL | Title | Topic | Linked by |
+|---|---|---|---|---|
+{{BLOG_INVENTORY}}
+
+---
+
+## SEO-sprint-generated pages (linked OUT to siblings + IN from elsewhere)
+
+### `/alternatives/[slug]`
+
+| Slug | Ships in phase | URL | Inbound links from | Outbound links to |
+|---|---|---|---|---|
+{{ALTERNATIVES_TABLE}}
+
+### `/for/[slug]`
+
+| Slug | Ships in phase | URL | Inbound links from | Outbound links to |
+|---|---|---|---|---|
+{{FOR_TABLE}}
+
+### `/compare/[slug]`
+
+| Slug | Ships in phase | URL | Inbound links from | Outbound links to |
+|---|---|---|---|---|
+{{COMPARE_TABLE}}
+
+### `/playbooks/[slug]`
+
+| Slug | Ships in phase | URL | Inbound links from | Outbound links to |
+|---|---|---|---|---|
+{{PLAYBOOKS_TABLE}}
+
+---
+
+## Anchor-text variations (avoid repetition)
+
+When linking to the same destination from multiple pages, vary the anchor text. Repeating "click here" or the page's exact title harms diversity signals.
+
+Example acceptable variations for `/features/twitter-monitoring`:
+- "monitor Twitter mentions"
+- "real-time Twitter monitoring"
+- "Twitter mention tracking"
+- "our Twitter monitoring tool"
+- "ReplySocial's Twitter watch feature"
+
+When you ship a new page, append 4-5 anchor variations to this section so future phases can rotate them.

package/skills/seo-machine/assets/roadmap-template.md

@@ -0,0 +1,184 @@
+# {{PRODUCT_NAME}} SEO Machine — Roadmap
+
+> **Canonical document.** This file is the single source of truth for the multi-phase SEO machine run. Every worktree/agent picking up SEO work on this project reads this file first.
+
+---
+
+## How to use this document
+
+**Fresh agent or new worktree?** Do this:
+
+1. Read this entire `docs/seo-machine.md` file.
+2. Read the **Reference Data**, **Conventions**, and **Keyword Research Appendix** sections ONCE — they're shared facts every phase depends on. Don't re-research.
+3. Find the next pending phase in the **Phase Status Tracker**.
+4. Read the phase section. It is fully self-contained.
+5. Execute. Verify against the per-phase verification gate.
+6. **In the same commit as the work,** flip the tracker row to `completed` and append the PR number after it merges.
+7. Open the PR. Stop. Hand off.
+
+**Don't modify** Reference Data, Conventions, Keyword Appendix, or Phases without explicit user instruction — they are stable contracts.
+
+**You may freshly query Ahrefs** if you need data not pre-baked into your phase (current pricing, recent SERP shifts). Ahrefs project_id is in `.seo/config.json`.
+
+---
+
+## Phase Status Tracker
+
+| # | Phase | Pattern | Status | PR |
+|---|---|---|---|---|
+| 0 | Technical foundations | Setup | pending | – |
+{{TRACKER_ROWS}}
+
+**Conventions:**
+- `pending` → `in_progress` (when worktree starts) → `completed` (in same commit as PR)
+- PR column: `branch \`name\` (PR TBD)` then update to `#NNN` after `gh pr create`
+- If a phase is abandoned, status = `skipped` with one-line reason
+
+---
+
+## Reference Data (read once per agent)
+
+### 1. Site facts
+
+- **Domain:** {{DOMAIN}}
+- **Ahrefs project_id:** {{AHREFS_PROJECT_ID}}  (from `.seo/config.json`)
+- **Domain Rating:** {{DR}}  (as of {{DR_DATE}}) — caps KD targets at ≤{{DR_CAP}} while DR is still climbing
+- **Stack:** {{STACK}}
+- **Brand accent color:** {{ACCENT}}
+- **Hero font / body font:** {{FONTS}}
+- **Marketing pages root:** {{MARKETING_ROOT}}
+
+### 2. Existing programmatic surface (DO NOT DUPLICATE)
+
+{{EXISTING_PROGRAMMATIC_TABLE}}
+
+### 3. Critical files
+
+| File | What lives there |
+|---|---|
+{{CRITICAL_FILES_TABLE}}
+
+### 4. Data shapes
+
+See `~/.claude/skills/seo-machine/references/patterns/<pattern>.md` for full TypeScript interface per pattern. Stack-specific serialization in `references/stacks/<stack>.md`.
+
+### 5. Conventions
+
+**URL slugs:** lowercase, hyphenated, never underscored.
+
+**Honesty section is non-negotiable** on every `/alternatives/[brand]` page. 3-4 honest tradeoffs admitting where the competitor wins. Brand signal + Google quality signal.
+
+**Plural-form capture (Pattern A):** Every alt page's first H2 must read "Best [Brand] alternatives in {{YEAR}}". Plural keyword is 2-3× volume of singular.
+
+**Internal-link minimums per page:**
+- `/alternatives/*` → ≥2 sibling alts + ≥1 feature + ≥1 tool
+- `/for/*` → ≥2 features + ≥2 tools + ≥1 sibling `/for/`
+- `/compare/*` → both alts + ≥1 `/for/` + `/pricing`
+- `/playbooks/*` → ≥3 features + ≥2 tools + ≥2 `/for/` + ≥1 alt
+- Every page reachable from ≥2 other pages
+
+**Word counts:**
+- `/alternatives/*`: ≥600 words
+- `/for/*`: ≥800
+- `/compare/*`: ≥700
+- `/playbooks/*`: ≥2,500
+
+**Schema:** `BreadcrumbList` (auto), `FAQPage` (where FAQ section), `SoftwareApplication`/`Article` (page-type-dependent).
+
+---
+
+## Keyword Research Appendix
+
+All numbers from Ahrefs (or manual sources). Re-query if a phase is executed >90 days from now.
+
+### A.1 — `/alternatives/[brand]` candidates
+
+{{ALTERNATIVES_RESEARCH_TABLE}}
+
+### A.2 — `/for/[use-case]` candidates
+
+{{USE_CASE_RESEARCH_TABLE}}
+
+### A.3 — `/for/[audience]` candidates
+
+{{AUDIENCE_RESEARCH_TABLE}}
+
+### A.4 — `/compare/[a-vs-b]` candidates
+
+{{COMPARE_RESEARCH_TABLE}}
+
+### A.5 — `/playbooks/[topic]` candidates
+
+{{PLAYBOOK_RESEARCH_TABLE}}
+
+### A.6 — Striking-distance (positions 5-20 in GSC)
+
+{{STRIKING_DISTANCE_TABLE}}
+
+### A.7 — Already-saturated head terms (avoid)
+
+{{SATURATED_TABLE}}
+
+### A.8 — Out of scope (intentionally excluded)
+
+{{OUT_OF_SCOPE}}
+
+---
+
+## Phases
+
+> Each phase is a single deployable PR. Pre-bake everything needed; re-query Ahrefs only for fresh competitor pricing/features at execution time. Mark `in_progress` when you start, `completed` (with PR link) when merged.
+
+### Phase 0 — Technical foundations
+
+**Why:** the day-0 crawl shapes how Google understands the site for months. Fix these before shipping any content.
+
+**Scope:** see `~/.claude/skills/seo-machine/references/technical-audit.md` for the full audit recipe. Common Phase 0 tasks:
+
+1. Generate/verify sitemap.xml
+2. Verify robots.txt allows crawling and references sitemap
+3. Add unique title + description to existing pages
+4. Build schema helper for the stack (`SoftwareApplication`, `FAQPage`, `BreadcrumbList`, `Article` factories)
+5. Submit sitemap to Google Search Console + Bing Webmaster Tools
+
+**Files modified:** auto-populate from audit findings.
+
+**Verification:**
+- [ ] `python ~/.claude/skills/seo-machine/scripts/tech_audit.py --domain {{DOMAIN}}` returns 0 critical findings
+- [ ] Sitemap submitted in GSC (manual check)
+
+{{ADDITIONAL_PHASES}}
+
+---
+
+## Off-page checklist
+
+See `~/.claude/skills/seo-machine/references/off-page.md` for full strategy. Track submission status here:
+
+### Directory submissions (starter stack)
+
+- [ ] Product Hunt — scheduled launch
+- [ ] G2 — submitted product page
+- [ ] Capterra
+- [ ] SaaSHub
+- [ ] AlternativeTo — list as alternative to: {{COMPETITORS}}
+- [ ] Indie Hackers
+- [ ] Crunchbase
+
+### Listicle outreach targets
+
+See `.seo/backlink-targets.json` for the Ahrefs-researched target list.
+
+### Founder link trades
+
+(populate as opportunities surface)
+
+---
+
+## Glossary
+
+- **DR** — Ahrefs Domain Rating, 0-100 score of backlink authority
+- **KD** — Ahrefs Keyword Difficulty, 0-100 score of ranking difficulty for a keyword
+- **TP** — Traffic Potential, Ahrefs' estimate of total clicks the top-ranking page captures across all related keywords
+- **Striking distance** — pages currently ranking position 5-20 in GSC, one push from page 1
+- **Pattern A/B/C/D/E** — the five page patterns this skill bundles (alternatives, use-case, audience, compare, playbook)