@benjaminthomas/spec-driven-dev 0.0.0-stage → 1.4.1

package/skills/generative-seo/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: generative-seo
+description: Run an evidence-based SEO + GEO (Generative Engine Optimization) program for ANY website or product codebase — auditing technical SEO, writing or retrofitting content so it gets cited by ChatGPT/Perplexity/AI Overviews, tracking AI-citation visibility, refreshing competitor research, and drafting distribution posts. Use whenever the user asks to audit SEO, improve AI-search/AI-citation visibility, write or optimize marketing/blog content for search or GEO, check whether a product shows up in ChatGPT/Perplexity answers, do competitor/keyword research, or wants a monthly SEO performance report — regardless of framework (Next.js, Astro, Remix, plain HTML, WordPress, etc.) or what the product is. Works on any repo; it interviews you once to learn the project's specifics (brand, domain, framework, docs location) and remembers the answers.
+license: MIT
+---
+
+# Generative SEO (GEO) Operations
+
+Runs an SEO + GEO program the same way a sharp in-house SEO operator would: technical
+audits, answer-first content built to be quoted by AI engines, an AI-citation tracker,
+competitor watch, and (draft-only) distribution. It is deliberately generic — first use
+in a repo spends a few minutes learning that project's facts, then behaves like a
+project-specific skill from then on.
+
+**Mode selection:** the argument names the mode (`content`, `audit`, `optimize`,
+`competitors`, `citations`, `report`, `social`). No argument → read the project's docs
+(below), summarize current state, and recommend the highest-impact next action.
+
+For the full evidence behind every rule below (which studies, what they found, why
+each technique works) and the complete technical checklist, see
+`references/geo-methodology.md`. Read it before an `audit` or before writing a
+first piece of `content` in a new project; skip re-reading it on later runs in the
+same project.
+
+---
+
+## First run in a project: learn the project
+
+Look for a config file at `docs/seo/geo-config.md` (or wherever the user says their
+SEO docs live — some repos keep them in `content/`, `marketing/`, or a wiki instead).
+If it exists, read it and skip to **Read these first**.
+
+If it does not exist, this is the first run — ask the user (batch these, don't
+interview one question at a time):
+
+1. **Product/brand name(s)** — and critically, if the product is a sub-brand of a
+   parent company or a different name than the company that builds it, get that
+   distinction explicit now (e.g. "Acme Corp is the company; Acme Flow is the
+   product we're marketing" or "same name, no distinction needed"). Getting this
+   wrong (writing "is Acme Corp free?" when the product is Acme Flow) is a
+   real, recurring mistake — nail it once here instead of guessing per-page later.
+2. **Primary domain** the content lives on (affects sitemap/robots checks and
+   internal-link audits).
+3. **Framework** — Next.js, Astro, Remix, SvelteKit, plain static HTML, a CMS
+   (WordPress/Webflow/etc.), or something else. This determines where
+   sitemap/robots/metadata/JSON-LD live (see `references/geo-methodology.md` for
+   the per-framework map) — if unsure, look at the repo yourself first
+   (`package.json`, top-level config files) before asking.
+4. **Where marketing/content pages live** in the repo (a directory, a headless
+   CMS, or "not in this repo" if content is managed elsewhere).
+5. **Existing design system doc**, if any (a `DESIGN.md`, a Storybook, a Figma
+   library) — new/edited pages should match it rather than invent a new look.
+6. **How to source real statistics** for content — product analytics the user can
+   query, a public dataset, or "external sources only." Never invent numbers
+   regardless of the answer.
+7. **Docs folder** for this skill's own working files (default: `docs/seo/` at
+   repo root — offer this default rather than making the user think of one).
+
+Write the answers to `<docs_dir>/geo-config.md` using
+`assets/geo-config-template.md` as the shape. Then create the four working docs
+from their templates in `assets/` (only the ones missing — never overwrite an
+existing one):
+
+| File | Template | Purpose |
+|---|---|---|
+| `<docs_dir>/geo-playbook.md` | `assets/geo-playbook-template.md` | This project's evidence-based rules + house style, filled in from the config answers |
+| `<docs_dir>/content-plan.md` | `assets/content-plan-template.md` | The execution backlog with statuses |
+| `<docs_dir>/competitor-analysis.md` | `assets/competitor-analysis-template.md` | Competitor landscape + keyword gaps |
+| `<docs_dir>/citation-log.md` | `assets/citation-log-template.md` | Dated AI-citation audit history |
+
+For `citations` mode specifically, also derive a **fixed prompt set**: 10–15
+realistic queries someone would type into ChatGPT/Perplexity/Google when looking
+for a product like this one (category term, "best X for Y" roundups, problem-first
+questions, a couple of named-competitor-alternative queries). Save them into
+`<docs_dir>/citation-log.md`'s header. Keep this list stable run-over-run — append
+new queries, don't rewrite the set, or trend comparison breaks.
+
+## Read these first (source of truth — keep them updated every run)
+
+- `<docs_dir>/geo-config.md` — project facts (brand, domain, framework, paths)
+- `<docs_dir>/geo-playbook.md` — this project's rules, filled in from the methodology reference
+- `<docs_dir>/content-plan.md` — phased content queue with statuses
+- `<docs_dir>/competitor-analysis.md` — competitor landscape + keyword gap map
+- `<docs_dir>/citation-log.md` — AI-citation audit history + the fixed prompt set
+
+---
+
+## Non-negotiable content rules (every page you write or edit)
+
+Full evidence (Princeton GEO paper, Ahrefs citation studies) in
+`references/geo-methodology.md`. Summary:
+
+1. **Answer-first**: the complete, direct answer to the target query lands in the
+   first ~200 words. Most AI citations pull from early-page content.
+2. **≥3 statistics, ≥1 quotable expert-voice line, cited sources** per substantive
+   page — measurably lifts AI-citation odds. Stats must be real and sourced (see
+   the project's config for where "real" comes from) — never invented.
+3. **Extractable structure**: H2/H3s phrased as the questions people actually ask;
+   Q&A blocks; comparison tables; a TL;DR/summary box; definition-style openings
+   ("X is …").
+4. **Self-contained sections**: every H2 section should make sense quoted in
+   isolation — AI retrieval is passage-level, not whole-page.
+5. **Author + published date + last-updated date** visible on-page. Refresh
+   anything older than ~6 months.
+6. **FAQ block + `FAQPage` JSON-LD** on pricing, feature, and comparison pages.
+7. Tone: practitioner-credible, specific, first-hand. No filler, never keyword-stuff.
+8. Word count follows the query's actual answer depth — never pad, never ship a
+   page so thin it can't stand on its own (a rough floor: ~300 words).
+9. Follow the naming/brand distinction captured in `geo-config.md` on every page —
+   re-check it before publishing if the page discusses "who makes this."
+10. Match whatever design system this repo already has (`geo-config.md` points at
+    it) — a GEO-optimized page that looks out of place hurts more than it helps.
+
+---
+
+## Mode: `audit` — technical SEO + GEO audit (add `--fix` to also apply fixes)
+
+Audit BOTH the codebase and the live site (fetch the live URLs — deployed state
+drifts from the repo). Report every failure with file:line. With `--fix`, apply
+code-level fixes and run the project's own check commands (lint/typecheck —
+inspect `package.json` scripts or the repo's build tooling; skip anything that
+doesn't exist rather than assuming `npm run check`).
+
+Full checklist (sitemap/robots by framework, JSON-LD schema types, AI-crawler
+allowlist, `llms.txt`, heading hygiene, internal linking, Core Web Vitals sanity)
+is in `references/geo-methodology.md` — pull it up for this mode.
+
+**Output:** severity-ordered findings table (blocker / high / med / low), each
+with file:line and the fix. With `--fix`: apply, verify with the project's checks,
+summarize the diff.
+
+## Mode: `content` — write the next content piece
+
+1. Read `<docs_dir>/content-plan.md`; pick the first `todo` item in the current
+   phase (or the item the user names). Flag any unresolved blockers first.
+2. Check the target query's live SERP (web search) — confirm intent, note what
+   ranks, find a differentiating angle grounded in what this specific product
+   actually does differently (pull that from `geo-config.md` / the codebase, not
+   assumption).
+3. Write the piece following the non-negotiable rules above. Comparison pages
+   must be honest about competitors — credibility is the citation currency.
+4. Implement it wherever this repo's content actually lives (per `geo-config.md`
+   — a route file, a CMS entry, a markdown collection) with full metadata,
+   JSON-LD, and design-system compliance.
+5. Add the URL to the project's sitemap mechanism. Update the item's status in
+   `content-plan.md` to `shipped (YYYY-MM-DD)`.
+6. Run the project's lint/typecheck/build if it has them. Present the draft for
+   review — content is outward-facing; the user approves before it goes live.
+7. AFTER the page is deployed and live, if the project has an IndexNow/Bing-ping
+   mechanism, use it (shortens AI-engine discovery from days to hours). If it
+   doesn't, mention manual IndexNow submission (bing.com/indexnow) as an option
+   rather than inventing tooling. Never ping before deploy.
+
+## Mode: `optimize` — GEO-retrofit an existing page
+
+Given a URL/path: score it against the non-negotiable rules (answer-first? stats?
+extractable structure? dates? FAQ? schema?), report a before/after checklist, then
+apply improvements preserving the page's voice and design.
+
+## Mode: `competitors` — refresh competitor & keyword research
+
+1. Re-run research (web search) covering the players already in
+   `competitor-analysis.md`, plus new AI-native entrants in the same category.
+2. Check whether the product's category term has a new canonical answer in
+   search; check who's cited in relevant "best X" roundups.
+3. Diff against the existing doc: new entrants, keyword-gap changes, threats.
+   Append a dated changelog entry — don't remove existing queue items. Suggest
+   content-plan additions.
+   Cadence: quarterly, or whenever the user senses a new competitor.
+
+## Mode: `citations` — AI-visibility audit
+
+1. Run the fixed prompt set from `citation-log.md` through web search (captures
+   Google/AI-Overview signals) and check Bing presence for the same queries.
+   Direct ChatGPT/Perplexity querying usually isn't possible from here — log
+   what's checkable and list the 5-minute manual checks for the user with exact
+   prompts to paste.
+2. For each query: record who ranks / is cited, whether this product appears
+   (distinguish **mention** vs **citation**), and which of the project's own
+   pages should be winning it.
+3. Append a dated entry to `citation-log.md`. Report the trend vs. the previous
+   entry.
+
+## Mode: `report` — periodic performance summary
+
+Compile from: citation-log trend, content-plan ship rate, live-site spot checks,
+and (if the user provides Search Console/Bing/GA exports — ask, don't assume
+access) impressions/clicks on target queries. Output: what shipped, what moved,
+top 3 recommended actions for next period. Set realistic expectations: Google
+traction is typically months out from a content ship; Bing/Perplexity move faster
+(weeks).
+
+## Mode: `social` — draft distribution posts for shipped content (drafts ONLY)
+
+This mode never posts anywhere — automated posting risks ToS violations on
+LinkedIn/Reddit/etc. and the account behind it. Output goes to
+`<docs_dir>/social-queue.md` (create from `assets/social-queue-template.md` on
+first run); the user reviews, pastes, and marks items posted.
+
+1. Read `social-queue.md` and `content-plan.md`. Pick shipped pages with no queue
+   entry yet — or the page the user names. Newest first, max 3 pages per run.
+2. For each page draft, in the founder/team's actual voice (first person,
+   practitioner tone, one concrete stat or claim pulled from the page, minimal
+   hashtags, ends with a question or the link — never reads like a press
+   release):
+   - A personal-profile post for whatever the primary channel is (ask if
+     unclear — LinkedIn and X are common defaults).
+   - A shorter, product-forward version for a company/brand page, if one exists.
+   - If the piece is worth republishing elsewhere (e.g. Medium), a checklist
+     entry noting the platform's canonical-URL mechanism must be used — never
+     copy-paste in a way that loses canonical attribution.
+   - Community threads (Reddit-style forums, Hacker News, niche Slack/Discord
+     communities): only where the skill has search budget to find 1–3 live
+     threads the page genuinely answers; draft a value-first reply that stands
+     on its own without the link, flagged for the user to post manually, in
+     their own voice. Never suggest posting the identical comment in 2 places.
+3. Append drafts under a dated heading, one entry per page, with a status marker
+   the user flips (`[ ] queued` → `[x] posted YYYY-MM-DD <URL>` or `[-]
+   skipped`). Never overwrite prior entries.
+4. Report what was drafted and what's still unposted from previous runs — an
+   aging queue means distribution, not content, is the bottleneck.
+
+---
+
+## Automation (scheduled agents)
+
+If the harness supports scheduled/cron-style agent runs, these are reasonable
+cadences — set them up only if the user asks, never silently:
+
+| Routine | Cadence | Action |
+|---|---|---|
+| Content | Weekly | Pick the next queue item, open a PR (never push straight to main) |
+| Citation audit | Monthly | Update the citation log on a branch |
+| Technical audit | Monthly | File findings as a report; PR fixes only for blockers |
+| Competitor refresh | Quarterly | Refresh competitor-analysis.md |
+| Social drafts | Weekly | Draft posts for newly-shipped pages |
+
+Scheduled runs always work on a branch + PR — content is outward-facing and needs
+human review before going live. If a run hits an unresolved blocker, report
+rather than plow ahead. Never invent statistics, in scheduled or interactive runs.
+
+## Standing cautions
+
+- A subdomain is a separate site for authority purposes — don't split content
+  onto a subdomain without a deliberate reason; it usually just dilutes signal.
+- Programmatic/templated pages need real data depth per page — thin
+  variable-injection pages risk scaled-content-abuse penalties for the whole
+  domain.
+- `llms.txt` and schema markup are hygiene, not strategy — don't over-invest
+  expecting them alone to move AI-citation odds. The actual lever is answer-first
+  content + real stats + third-party mentions (roundups, directories, forums,
+  YouTube) + fast indexing (Bing/IndexNow).
+- Anything gated behind a login the skill can't access (Search Console, Bing
+  Webmaster Tools, review-site dashboards, social platforms) → give the user a
+  precise action list; don't fake having checked it.

package/skills/generative-seo/assets/citation-log-template.md

@@ -0,0 +1,17 @@
+# AI Citation Log
+
+## Fixed prompt set
+
+<!--
+10-15 queries a real prospect would type into ChatGPT / Perplexity / Google
+when looking for a product like this one. Derived once on first `citations`
+run, kept stable so trend comparisons mean something — append, don't rewrite.
+-->
+
+- 
+
+## Audit history
+
+| Date | Prompt | Engine | Our status (mention/citation/absent) | Who wins | Note |
+|---|---|---|---|---|---|
+| | | | | | |

package/skills/generative-seo/assets/competitor-analysis-template.md

@@ -0,0 +1,20 @@
+# Competitor & Keyword Analysis
+
+## Competitor landscape
+
+| Competitor | Category term(s) they own | Notes |
+|---|---|---|
+| | | |
+
+## Keyword gap map
+
+| Query | Who ranks/is cited today | Should we contest it? |
+|---|---|---|
+| | | |
+
+## Changelog
+
+<!-- Append a dated entry each `competitors` run. Never delete prior entries. -->
+
+### YYYY-MM-DD
+- 

package/skills/generative-seo/assets/content-plan-template.md

@@ -0,0 +1,15 @@
+# Content Plan
+
+Status values: `todo`, `in-progress`, `blocked (reason)`, `shipped (YYYY-MM-DD)`.
+
+## Phase 0 — foundation (blockers)
+
+| Item | Target query | Status | Notes |
+|---|---|---|---|
+| | | todo | |
+
+## Phase 1
+
+| Item | Target query | Status | Notes |
+|---|---|---|---|
+| | | todo | |

package/skills/generative-seo/assets/geo-config-template.md

@@ -0,0 +1,33 @@
+---
+product_name:
+brand_name:
+domain:
+framework:
+marketing_pages_dir:
+sitemap_mechanism:
+robots_mechanism:
+design_system_doc:
+stats_source:
+docs_dir: docs/seo
+---
+
+# Brand & naming notes
+
+<!--
+Free text. If the product is a sub-brand of a parent company, or the software
+name differs from the company name, state the rule here explicitly, e.g.:
+
+"Acme Corp is the parent company (a services agency). Acme Flow is the
+product. Never write 'is Acme Corp free' or 'who is Acme Corp for' — the
+software is Acme Flow; Acme Corp builds it. Correct brand uses: legal
+operator, IP ownership, author/publisher credit."
+
+If there's no distinction (company name == product name), just say so.
+-->
+
+# House style notes
+
+<!--
+Anything specific to how this project writes: tone, banned phrases, a
+tagline that must appear consistently, units/currency conventions, etc.
+-->

package/skills/generative-seo/assets/geo-playbook-template.md

@@ -0,0 +1,22 @@
+# GEO Playbook — {{product_name}}
+
+Filled in from `geo-config.md` and `references/geo-methodology.md` in the
+generative-seo skill. This file is the project-specific source of truth — the
+skill's reference file has the general evidence; this one has what this project
+has decided to do about it.
+
+## Category / positioning
+
+<!-- What category term is this project trying to own? What's the one-line
+differentiator vs the obvious alternatives? -->
+
+## Content rules specific to this project
+
+<!-- Start from SKILL.md's non-negotiable rules; add anything specific here
+(e.g. "always include a pricing comparison table", "never use the word X"). -->
+
+## What's proven vs still a hypothesis
+
+<!-- Track which tactics this project has actually validated (ranked, got
+cited, drove signups) vs ones still being tried. Update after each `report`
+or `citations` run. -->

package/skills/generative-seo/assets/social-queue-template.md

@@ -0,0 +1,8 @@
+# Social Distribution Queue
+
+Drafts only — nothing here gets posted automatically. Review, edit into your own
+voice, paste, then flip the status marker.
+
+Status markers: `[ ] queued` → `[x] posted YYYY-MM-DD <URL>` or `[-] skipped`.
+
+<!-- Append a new dated H2 per `social` run. Never overwrite prior entries. -->

package/skills/generative-seo/references/geo-methodology.md

@@ -0,0 +1,143 @@
+# GEO Methodology Reference
+
+The evidence behind the rules in SKILL.md, and the full technical checklist for
+`audit` mode. Read this once per project before the first `audit` or `content`
+run; the summary in SKILL.md is enough for later runs.
+
+## Table of contents
+
+1. [The evidence](#the-evidence)
+2. [Technical checklist](#technical-checklist)
+3. [Sitemap / robots by framework](#sitemap--robots-by-framework)
+4. [JSON-LD schema types](#json-ld-schema-types)
+5. [AI-crawler allowlist](#ai-crawler-allowlist)
+
+---
+
+## The evidence
+
+**Answer-first placement.** Research on what generative engines (AI Overviews,
+ChatGPT search, Perplexity) actually quote found citations skew heavily toward
+early-page content — a large share of cited passages come from roughly the first
+third of the page. Practical takeaway: don't bury the direct answer under a long
+intro, definitions section, or history lesson. State it, then elaborate.
+
+**Statistics and quotable lines.** Studies analyzing what content gets cited by
+AI answer engines (Princeton's GEO paper; independent studies from SEO tooling
+vendors) found that adding concrete statistics, direct quotes, and citations to
+sources measurably increases the odds a passage gets pulled into an AI-generated
+answer — reported lifts in the 30–40%+ range for visibility, depending on the
+study and baseline. This is the single highest-leverage on-page lever available.
+
+**Extractable structure.** AI engines assemble answers from passages, not whole
+pages. Content that mirrors how people actually ask ("How do I…", "What is…",
+"X vs Y") in H2/H3 headings, uses genuine Q&A blocks, comparison tables, and a
+TL;DR/summary block gets extracted more cleanly than prose that requires reading
+top-to-bottom to make sense.
+
+**Self-contained passages.** Because retrieval is passage-level, a section that
+depends on context from three paragraphs earlier ("as mentioned above...") reads
+as incomplete when lifted alone — which is exactly how it will be consumed.
+
+**Freshness signals.** Visible author, published date, and last-updated date are
+both a trust signal to AI crawlers and a genuine correctness signal — stale
+numbers get corrected by AI engines using other sources instead. Re-verify and
+refresh anything older than about 6 months, especially anything with a number
+in it.
+
+**Structured Q&A + schema.** `FAQPage` JSON-LD gives engines an unambiguous,
+pre-parsed question/answer pair to lift verbatim — lower effort for the engine
+than extracting an answer from prose, which matters when the engine is choosing
+between two similarly good sources.
+
+**What has weak or no proven effect (don't over-invest):** `llms.txt` files and
+generic schema markup are commonly recommended but have thin independent
+evidence of directly causing AI-citation lift — treat them as cheap hygiene
+(an hour of work, do it once) rather than a strategy. The actual strategy is the
+content quality levers above, plus off-site signals (third-party mentions in
+roundups/directories/forums/video) and fast technical indexing.
+
+---
+
+## Technical checklist
+
+Run through all of these for `audit` mode; report failures with file:line.
+
+1. **Sitemap** includes every indexable page with an honest `lastModified`;
+   excludes anything robots disallows; no auth-gated URLs. See framework map below.
+2. **Robots** disallows app/API/auth routes; explicitly allows AI-answer-engine
+   bots (see allowlist below) unless the user has a specific reason to block
+   AI training/retrieval (rare — confirm before ever adding a disallow for these).
+3. Every marketing/content page has: unique `title` (not duplicating a sitewide
+   template), unique `description` (~140–160 chars), a canonical URL, and
+   OG + Twitter/X card metadata.
+4. JSON-LD present and valid — see schema-type table below.
+5. `llms.txt` in the site root — a markdown index of key pages with one-line
+   descriptions. Low proven impact; still a cheap one-time hedge (see evidence
+   section — don't over-invest beyond the first pass).
+6. All public content is server-rendered or otherwise present in the initial
+   HTML response — many AI crawlers don't execute JavaScript, so client-only
+   marketing copy is invisible to them.
+7. **Live checks**: fetch `/robots.txt`, `/sitemap.xml` (or the framework's
+   equivalent), `/llms.txt`, and the homepage on the live domain — confirm they
+   match the repo and return 200; spot-check that sitemap URLs resolve.
+8. Heading hygiene: exactly one H1 per page; H2s phrased as the questions the
+   page targets, where the page targets a specific query.
+9. Internal linking: every content page links to its category/pillar page and
+   vice versa; pillar pages link out to their spokes.
+10. Core Web Vitals sanity: no oversized unoptimized images (use the framework's
+    image component if it has one), no obvious layout shift from late-loading
+    content, no render-blocking resources that are trivially deferrable.
+
+---
+
+## Sitemap / robots by framework
+
+Confirm the actual files in the repo before assuming — frameworks change these
+mechanisms across versions.
+
+| Framework | Sitemap | Robots | Metadata |
+|---|---|---|---|
+| Next.js (App Router) | `app/sitemap.ts` (dynamic) or `public/sitemap.xml` | `app/robots.ts` or `public/robots.txt` | `generateMetadata` / static `metadata` export per route; root `metadataBase` in root layout |
+| Astro | `@astrojs/sitemap` integration (generates at build) or manual `public/sitemap.xml` | `public/robots.txt` | Per-page `<head>` in `.astro` files, or a shared `<SEO>` component |
+| Remix / React Router | A resource route returning XML (e.g. `app/routes/sitemap[.]xml.tsx`) | A resource route or `public/robots.txt` | `meta` export per route |
+| SvelteKit | `src/routes/sitemap.xml/+server.ts` | `static/robots.txt` | `<svelte:head>` per page |
+| Plain static site | Hand-maintained or generated `sitemap.xml` at the root | `robots.txt` at the root | Per-HTML-file `<head>` tags |
+| WordPress / Webflow / other CMS | Usually auto-generated by an SEO plugin (Yoast, RankMath) or the platform itself | Same — check the plugin/platform settings, don't hand-edit generated files | Plugin-managed fields per page/post |
+
+If none of these match, ask the user rather than guessing — inventing a
+mechanism that doesn't fit the framework produces code that won't build.
+
+## JSON-LD schema types
+
+| Page type | Schema | Notes |
+|---|---|---|
+| Every page (sitewide, once) | `Organization` | Name, logo, sameAs (social profiles) |
+| Homepage / pricing (for a product) | `SoftwareApplication` + `Offer` | Only if the product genuinely is software with a price; don't force this onto a services business |
+| Any page with a real FAQ | `FAQPage` | Must match the visible on-page Q&A exactly — don't add schema for content that isn't rendered |
+| Blog / article content | `Article` + `author` + `datePublished` + `dateModified` | Keep `dateModified` in sync with the visible "last updated" date |
+| Blog / article content | `BreadcrumbList` | Only where there's a real breadcrumb trail |
+| Ranked list/roundup content | `ItemList` | For "best X" style pages |
+
+Sanitize any inline JSON-LD script against injection if the data includes
+user-controlled or dynamic strings (e.g. `JSON.stringify(data).replace(/</g,
+"\\u003c")` in a Node/JS context) — this is standard defensive practice for
+inlining JSON into HTML, not framework-specific.
+
+## AI-crawler allowlist
+
+Bot user-agents to explicitly allow in `robots.txt` (or the framework's robots
+mechanism) so AI answer engines can retrieve and potentially cite the content —
+disallowing these is usually the opposite of what a project pursuing AI-search
+visibility wants:
+
+- `OAI-SearchBot`, `ChatGPT-User`, `GPTBot` (OpenAI)
+- `ClaudeBot`, `Claude-SearchBot`, `Claude-User` (Anthropic)
+- `PerplexityBot`, `Perplexity-User` (Perplexity)
+- `Bingbot`, `Google-Extended` (Microsoft/Google AI training + retrieval)
+- `CCBot` (Common Crawl — feeds many downstream AI training sets)
+
+If the user has an explicit reason to keep content out of AI training data
+(e.g. a paywalled or licensed-content business model), confirm before adding
+these — the default recommendation is "allow all" for anyone wanting AI-search
+visibility, but that's not universal.

package/skills/spec-checkpoint/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: spec-checkpoint
+description: >
+  Create a comprehensive checkpoint commit with detailed analysis of all changes. Use this skill
+  when the user says "checkpoint", "commit everything", "save my progress", "create a commit",
+  or wants to stage and commit all current changes with a well-crafted message. Also use when
+  the user says "/spec-checkpoint" (or their host's equivalent invocation syntax) or asks to
+  snapshot current work. This skill stages all changes and creates a descriptive commit — it
+  does not push.
+license: MIT
+---
+
+# Checkpoint Commit
+
+Create a checkpoint commit that captures all current changes — but only after the code passes lint, type check, and build.
+
+## Project config (read first)
+
+Load `.spec-driven.yml`: walk up from the current directory to the home folder, and the first one
+found wins (a `multi-repo` config only applies inside the repos it lists). Its values beat anything
+you would detect or assume. This skill uses `commands` (lint/typecheck/test/build), `git.commit_style`, and `layout`/`repos`.
+
+**Multi-repo:** run this in every listed repo that has changes, making one commit per repo with the same subject. **Monorepo:** run the checks for the packages that changed, or the root commands if that's how the repo works.
+
+**No config?** If the `spec-setup` skill is available, run it first, then continue here. If it
+isn't, detect what this skill needs from the repo, ask about anything ambiguous, and offer to save
+the answers to `.spec-driven.yml` (keys: `layout`, `repos`, `tracker`, `git`, `commands`,
+`specs_dir`).
+
+## Instructions
+
+### Step 1: Analyze Changes
+
+Run these commands to understand the full picture:
+
+1. `git status` — see all tracked and untracked files
+2. `git diff` — see detailed changes in tracked files
+3. `git diff --cached` — see already-staged changes
+4. `git log -5 --oneline` — understand this repo's commit message style
+
+### Step 2: Quality Checks
+
+Use `commands` from `.spec-driven.yml`. For any that are missing, find the repo's own lint, typecheck, test, and build commands — `package.json` scripts (with the
+repo's package manager), `Makefile`, `pyproject.toml`, `Cargo.toml`, CI config, or `CLAUDE.md`/
+`AGENTS.md`. Run each one the repo has; skip (and say so) any it doesn't. If any fail, fix the
+issues before proceeding — do not skip or ignore failures.
+
+Iterate until every check passes cleanly. Only then move to the next step.
+
+### Step 3: Stage Everything
+
+Stage all changes — tracked modifications, deletions, and new untracked files:
+
+```bash
+git add -A
+```
+
+Then review `git status` again. If anything staged looks like it could hold secrets —
+`.env*`, `*.pem`, `*_rsa`, `credentials.json`, `secrets.*`, or an unfamiliar filename that might
+contain an API key — unstage it (`git restore --staged <file>`) and tell the user what was
+excluded and why, rather than committing it silently. Don't rely on the filename alone for
+anything you don't recognize; skim its diff if you're unsure.
+
+### Step 4: Craft the Commit Message
+
+Write a commit message in the config's `git.commit_style` (`conventional` → `feat: …`, `ticket` → `STP-123: …` using the ticket ID from the branch name, `freeform`). Without config, follow the project's existing conventions (observed from `git log`). Structure:
+
+- **First line**: clear, concise summary in imperative mood (50-72 chars)
+  - Use conventional commit prefixes where the project uses them: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`, etc.
+- **Body** (separated by blank line): a short TL;DR of the changes — 1-3 sentences max. No bullet lists, no file-by-file breakdowns, no lengthy explanations.
+- **Footer**: co-author attribution, naming whichever agent/model is actually running this
+  skill — never hardcode a specific vendor or model name, since this skill runs under many
+  different hosts
+
+### Step 5: Commit
+
+Create the commit using a heredoc for proper formatting:
+
+```bash
+git commit -m "$(cat <<'EOF'
+{first line}
+
+{tldr}
+
+Co-Authored-By: {agent name} <noreply@example.com>
+EOF
+)"
+```
+
+Fill in `{agent name}` with whatever the current agent/model actually identifies as (e.g. "Claude", "Codex", "Cursor Agent") — if your host has no clean way to identify itself, omit the footer entirely rather than guessing.
+
+### Step 6: Report
+
+Display:
+- The commit hash and message summary
+- Files changed count
+- Insertions/deletions summary
+
+## Important
+
+- Stage and commit everything except files that look like secrets or credentials (see Step 3) — check contents, not just filenames, before assuming something is safe to commit
+- If the repo has no git history, run `git init` first
+- All quality checks (lint, type-check, build) MUST pass before committing — fix issues, don't skip them
+- Keep the commit body short — a TL;DR, not an essay
+- Follow the project's existing commit conventions (check the log first)
+- Do not push — only commit locally