akili-specs 2.13.1 → 2.15.0

package/.claude/commands/akili-audit.md

@@ -49,6 +49,7 @@ Audit for discrepancies, classifying findings under the following categories:
 * **Technical Constraints Violation:** Architectural layout in the codebase that conflicts with patterns (e.g. testing requirements, security rules, file structuring) documented in `docs/trd/trd.md`.
 * **Agent Guide Drift:** Modules whose conventions clearly diverge from the root but lack a child `CLAUDE.md`/`AGENTS.md`, child guides missing from the parent's `## Module Guides` index, guide entries pointing at modules that no longer exist, or root-guide structure descriptions that no longer match the codebase.
 * **Model Registry Drift:** The project's `## Model Routing` registry (root `AGENTS.md`/`CLAUDE.md`) names models the host tool no longer offers, uses dated model pins where a floating alias exists (violating the alias-first rule) without a recorded reason, is missing tiers or the author ≠ auditor note versus the packaged default in `docs/model-routing.md`, or the Step 8E agent wrappers (`.claude/agents/akili-*.md` / OpenCode agent config) declare models that contradict the registry. Report only — never edit the registry or wrappers during the audit.
+* **Model Generation Drift:** Aliases absorb a new model generation silently, so the *registry* can be perfectly current while everything calibrated around it has gone stale. Flag, without editing: (a) a **frontier escalation pin** whose recorded reason predates the current `opus` generation — each generation narrows the gap the pin was bought to close, so it needs re-justification against the alias at `xhigh`/`max`; (b) an **`Updated:` stamp older than the current model generation**, meaning the effort defaults were never swept for it (`docs/model-routing.md` → *Effort dial* → re-baseline rule); and (c) `.agents/*.md` personas missing guardrails the packaged templates have gained since — most importantly the **Delegation Ceiling** in `leader.md` and the both-directions **Scope Discipline** in `implementer.md`, which counter over-delegation and scope expansion in current-generation models.
 
 ### Step 3: Write Drift Report
 

package/.claude/commands/akili-constitution.md

@@ -373,8 +373,8 @@ If the packaged templates are available, prefer copying them as the seed; otherw
 
 **Required content per persona:**
 
-- **`leader.md`** — orchestration sequence, rework loop with 3-attempt ceiling, structured FAIL handoff to the next Implementer spawn, `execution.md` audit-trail format, `tasks.md` status transitions, AKILI commit standard, Pivot Protocol escalation.
-- **`implementer.md`** — strict context alignment to constitution + spec, incremental focus (no scope creep), aesthetics and design-token compliance from `docs/ux-ui/design.md`, verification rigor (must run the task's verification command before reporting), structured completion report.
+- **`leader.md`** — orchestration sequence, rework loop with 3-attempt ceiling, structured FAIL handoff to the next Implementer spawn, `execution.md` audit-trail format, `tasks.md` status transitions, AKILI commit standard, Pivot Protocol escalation, the **Delegation Thresholds** floor *and* the **Delegation Ceiling** (one subagent beats several for one task; commit to the delegation; brief precisely once; bounded fan-out; never delegate your own verification — with the explicit carve-out that the independent Reviewer is `author ≠ auditor`, not self-verification, and must never be collapsed).
+- **`implementer.md`** — strict context alignment to constitution + spec, **scope discipline in both directions** (no scope creep, but also no silent narrowing — finish the whole task and report completion only when it is actually complete, listing what is missing and why when it is not), aesthetics and design-token compliance from `docs/ux-ui/design.md`, verification rigor (must run the task's verification command before reporting), structured completion report with an optional `Not Done / Assumptions` field.
 - **`reviewer.md`** — read-only role, audit checklist (requirement conformance, design-token compliance, technical compliance, stability), structured PASS/FAIL output where every FAIL item lists *Discovered Issue*, *Violated Rule*, and *Remediation Suggestion*.
 - **`tester.md`** — single-suite scope (backend unit, frontend unit, integration, or E2E), thin per-suite context, explicit coverage of negative constraints (`BUT it must NOT`) and strict validations (`AND IT MUST`), bounded self-correction inner loop (max 3), distinction between a test defect (fix the test) and a product defect (keep the test red, report `PRODUCT_BUG`), and structured `PASS`/`FAIL`/`PRODUCT_BUG` output with a per-scenario coverage slice. Author ≠ tester: prefer a different model than the Implementer.
 
@@ -431,9 +431,15 @@ project guides so the project does not depend on the package's `docs/` after ins
    table (trivial/mechanical → `low`; standard scope → `medium`; complex — algorithm, concurrency,
    security, ambiguity → `xhigh`; correctness-critical → `max`); (b) default effort by role (T1
    propose/specify/Leader `high`; T2 Implementer/Tester `medium`, flex by task; T3 Reviewer `high`;
-   T5 archive `low`); (c) the rework rule (*bump effort one level on every retry*); and (d) the
-   tier↔effort rule (*never `max` a cheaper tier — escalate the tier instead*). The
-   `/akili-execute` and `/akili-test` Leaders read this subsection to set each worker's effort.
+   T5 archive `low`); (c) the rework rule (*bump effort one level on every retry*); (d) the
+   tier↔effort rule (*never `max` a cheaper tier — escalate the tier instead*); (e) the
+   **re-baseline rule** (*effort defaults are per-generation and must be swept — `medium`/`high`/`xhigh`
+   on a real spec — whenever the underlying model generation changes; the tier mapping survives model
+   churn, these defaults do not, and a task that arrives under-specified — a `[~]` resume or a
+   post-Pivot retry — starts one level higher*); and (f) **effort is not a verbosity dial** (*lowering
+   effort does not reliably shorten output — fix long reports in the brief via `caveman` /
+   `cognitive-doc-design`, never by dropping effort*). The `/akili-execute` and `/akili-test` Leaders
+   read this subsection to set each worker's effort.
 
 **Mode-specific policy (mirror Step 8B):**
 
@@ -448,7 +454,12 @@ project guides so the project does not depend on the package's `docs/` after ins
   the user decides whether to refresh them.
 
 Confirm the user's available models before writing concrete identifiers: which tier they run in
-Claude Code (and their plan's rate limits) and which models their OpenCode roster exposes.
+Claude Code (and their plan's rate limits) and which models their OpenCode roster exposes. Note that
+**rate limits are per-generation, not per-family** — a new top-tier generation draws on its own quota
+rather than inheriting the previous one's pool, so moving T1/T3 onto it neither frees nor inherits
+headroom. If the user carries a **frontier escalation pin** (Step 8C item 4), flag it for
+re-justification whenever the `opus` alias advances a generation: each generation narrows the gap the
+pin was bought to close, so try the alias at `xhigh`/`max` before renewing the pin.
 
 ---
 

package/.claude/commands/akili-execute.md

@@ -59,6 +59,8 @@ The Leader does not write production code itself unless the rework loop is exhau
 
 **Delegation Thresholds:** the Leader's inline-vs-delegate boundary is quantified in `.agents/leader.md` → *Delegation Thresholds* (inline only for 1-file checks and puntual verifications; 4+ full-file reads → scout subagent; 2+ non-trivial file writes → Implementer; CodeGraph lookups don't count toward the read threshold). Apply it to your own research inside this command — e.g. investigating a Reviewer FAIL across many files is scout work, not Leader-inline work.
 
+**Delegation Ceiling:** that table is the floor; `.agents/leader.md` → *Delegation Ceiling* is the cap, and on current-generation models it is the one that binds. One subagent beats several for a single task, parallelism is bounded by the count of genuinely independent tasks in `tasks.md`, you commit to a delegation rather than re-deriving its result, and you never spawn a subagent to verify your own work. **The Implementer → Reviewer gate is exempt** — it is `author ≠ auditor` independence, not self-verification, and is never collapsed for efficiency.
+
 **Communication economy:** load the `caveman` skill and apply its Scope Contract to all transient output in this command — inter-agent messages (Leader ↔ Implementer/Reviewer briefs, reports, feedback relays) at `full`, user-visible progress lines at `lite`. It never applies to `execution.md` audit entries, PR descriptions, HITL summaries, Pivot blockers, or verbatim evidence (Reviewer FAIL reports pass unchanged — the Structured Feedback rule wins).
 
 ---

package/.claude/commands/akili-seo.md

@@ -137,6 +137,7 @@ Produce `docs/specs/$SPEC_PATH/seo-setup-report.md` documenting:
 - Record every finding with its structure: **Issue / Impact / Evidence / Fix / Priority**.
 - Respect its schema-detection limitation: static fetches (`curl`, `web_fetch`) cannot see JS-injected JSON-LD. Validate structured data via `url_inspection_inspect.richResultsResult` or a rendering tool, never via static HTML alone.
 - Apply its International SEO checklist (hreflang reciprocity, self-reference, `x-default`, cross-locale canonicals, locale sitemaps) whenever the site serves multiple languages or regions.
+- Apply its **GEO** section (Step 2.8) for generative-engine visibility. GEO is a layer on top of ranking, never a substitute — run the priority order first. When citing a magnitude, carry the skill's source tier: the KDD 2024 figures are peer-reviewed; AI Overview and crawler-behaviour figures are industry analyses and must not be presented as measured fact.
 
 Use `systematic-debugging` when results are inconsistent with site reality.
 
@@ -210,6 +211,24 @@ For the pages sampled in Step 2.5, apply the on-page checklist from the `seo-aud
 
 Record each failure as a finding using the skill's Issue / Impact / Evidence / Fix / Priority structure.
 
+#### Step 2.8 — GEO audit (generative-engine visibility)
+
+For the same sampled pages, apply the `seo-audit` skill's **GEO** section (evidence and sources in its
+`references/geo.md`). Highest-yield checks first — the measured gains come from evidence, not markup:
+
+- **Evidence density:** claims carry verifiable statistics with named sources; credible quotations where the topic supports them; outbound citations to reliable sources.
+- **Self-containment test:** for each passage the page wants cited, confirm it still makes sense lifted out with no surrounding context. Flag anaphora that depends on the previous paragraph ("this approach", "as mentioned above"). No on-page check above catches this.
+- **Definitional sentences:** each term the page wants to own has a *"X is a Y that does Z."* sentence at first use.
+- **Entity resolution:** the page states in one sentence what the subject is and who made it; `Person`/`Organization` node with `sameAs`.
+- **Freshness:** `dateModified` exposed and truthful; no stale visible version numbers or dates.
+- **AI crawler directives:** `robots.txt` separates training agents (`GPTBot`, `ClaudeBot`, `Google-Extended`) from retrieval agents (`OAI-SearchBot`, `Claude-SearchBot`, `PerplexityBot`). A blanket AI-bot block removes the site from AI answers too — confirm the owner's intent before calling either state correct.
+- **Unverifiable claims:** flag numeric or superlative claims in `<title>`, meta description, or JSON-LD that no source supports.
+
+**Do not raise:** a missing `llms.txt` (no measured visibility effect — see the skill), or any finding
+that asserts engagement metrics such as bounce rate affect rankings.
+
+Record each failure in the same Issue / Impact / Evidence / Fix / Priority format.
+
 ---
 
 ### Phase 3: Write `seo-audit-report.md`
@@ -227,8 +246,9 @@ Required sections:
 7. Render Audit
 8. Internal Linking Findings
 9. On-Page SEO Findings — Step 2.7 results, each in the `seo-audit` Issue / Impact / Evidence / Fix / Priority format.
-10. Remediation Plan — prioritized (High / Medium / Low) actionable items, each scoped enough that an implementer can execute it without further discovery.
-11. Re-audit Schedule — when to run `/akili-seo <domain>` again.
+10. GEO Findings — Step 2.8 results, same format. State the source tier next to any magnitude cited, and keep GEO items ranked below blocking classic-SEO fixes in the remediation plan (GEO layers on ranking, it does not substitute for it).
+11. Remediation Plan — prioritized (High / Medium / Low) actionable items, each scoped enough that an implementer can execute it without further discovery.
+12. Re-audit Schedule — when to run `/akili-seo <domain>` again.
 
 The report title must be `# SEO Audit Report — <domain>`.
 
@@ -268,6 +288,8 @@ After the command completes, verify:
 - [ ] Every URL in the sitemap is either audited or explicitly excluded with a reason.
 - [ ] Every structured-data warning is reproduced with the exact bad value and the exact fix.
 - [ ] On-page findings from Step 2.7 use the `seo-audit` Issue / Impact / Evidence / Fix / Priority format.
+- [ ] GEO findings from Step 2.8 are present, carry their source tier where a magnitude is cited, and rank below blocking classic-SEO fixes in the remediation plan.
+- [ ] No finding claims engagement metrics (bounce rate, time on page) affect rankings, and none flags a missing `llms.txt`.
 - [ ] The implementation prompt is self-contained and would not require this conversation to execute.
 
 ---

package/.claude/skills/seo-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: seo-audit
-description: When the user wants to audit, review, or diagnose SEO issues on their site. Also use when the user mentions "SEO audit," "technical SEO," "why am I not ranking," "SEO issues," "on-page SEO," "meta tags review," "SEO health check," "my traffic dropped," "lost rankings," "not showing up in Google," "site isn't ranking," "Google update hit me," "page speed," "core web vitals," "crawl errors," or "indexing issues." Use this even if the user just says something vague like "my SEO is bad" or "help with SEO" — start with an audit. In AKILI-SPECS projects, /akili-seo loads this skill in its audit phase.
+description: When the user wants to audit, review, or diagnose SEO issues on their site. Also use when the user mentions "SEO audit," "technical SEO," "why am I not ranking," "SEO issues," "on-page SEO," "meta tags review," "SEO health check," "my traffic dropped," "lost rankings," "not showing up in Google," "site isn't ranking," "Google update hit me," "page speed," "core web vitals," "crawl errors," or "indexing issues." Also covers generative-engine visibility (GEO/AEO): "AI Overviews," "AI search," "not showing up in ChatGPT," "get cited by AI," "GEO," "answer engine optimization," "llms.txt," "AI crawlers," "GPTBot," or "ClaudeBot." Use this even if the user just says something vague like "my SEO is bad" or "help with SEO" — start with an audit. In AKILI-SPECS projects, /akili-seo loads this skill in its audit phase.
 license: MIT
 metadata:
   author: Corey Haines (coreyhaines31)
@@ -8,7 +8,7 @@ metadata:
   adapted-by: "Juan Carlos Cadavid — jcadavid.com"
   adapted-for: "AKILI-SPECS"
   binding: core
-  version: 2.0.0
+  version: 2.1.0
 ---
 
 # SEO Audit
@@ -61,6 +61,11 @@ Reporting "no schema found" based solely on `web_fetch` or `curl` leads to false
 4. **Content Quality** (does it deserve to rank?)
 5. **Authority & Links** (does it have credibility?)
 
+**GEO is a layer, not a sixth priority.** Generative-engine visibility (AI Overviews, ChatGPT,
+Perplexity) is applied *on top of* pages that already rank or can — roughly three quarters of AI
+Overview citations come from pages already in the top 10. Never trade a fix from the list above for a
+GEO fix. Run the priority order first, then apply the [GEO section](#generative-engine-optimization-geo).
+
 ---
 
 ## Technical SEO Audit
@@ -71,6 +76,13 @@ Reporting "no schema found" based solely on `web_fetch` or `curl` leads to false
 - Check for unintentional blocks
 - Verify important pages allowed
 - Check sitemap reference
+- **`Disallow` is not `noindex`.** A disallowed URL can still be indexed (from external links) and will show as "Indexed, though blocked by robots.txt". To remove a page from the index you must let Google crawl it and serve `noindex` — blocking it prevents Google from ever seeing the directive. A `noindex` line inside `robots.txt` is unsupported and ignored.
+
+**AI crawler directives** (see [GEO reference](references/geo.md) for the full agent table)
+- Distinguish **training** agents (`GPTBot`, `ClaudeBot`, `Google-Extended`) from **retrieval** agents (`OAI-SearchBot`, `Claude-SearchBot`, `PerplexityBot`) and user-triggered fetchers (`ChatGPT-User`, `Claude-User`, `Perplexity-User`)
+- **High-impact finding:** a blanket AI-bot block removes the site from AI answers as well as from training corpora. Confirm the client's intent before treating either state as correct
+- `Google-Extended` is a robots.txt token only — it never appears in logs, and blocking it does not affect `Googlebot`, Search, or AI Overviews
+- Where the requirement is genuine prevention rather than preference, note that robots.txt is advisory and escalate to WAF/bot management
 
 **XML Sitemap**
 - Exists and accessible
@@ -338,6 +350,30 @@ Three equivalent placement methods: HTML `<link>` in `<head>`, HTTP `Link` heade
 - No keyword cannibalization
 - Logical topical clusters
 
+### Structured Data
+
+Read the **Schema Markup Detection Limitation** above before auditing this — a static fetch cannot
+see JS-injected JSON-LD, and reporting "no schema found" from `curl` output is a false finding.
+
+**Check for:**
+- Correct type for the page's purpose (`Article`/`TechArticle`, `Product`, `FAQPage`, `HowTo`, `BreadcrumbList`, `Organization`, `Person`, `SoftwareApplication`, `LocalBusiness`)
+- Validates without errors in the Rich Results Test
+- Markup matches **visible** page content — invisible or contradictory markup is a spam-policy violation, not an optimization
+- `dateModified` present and truthful on content that changes
+- Entity nodes (`Organization` / `Person`) carry `sameAs` links to authoritative profiles
+- `@id` used consistently so nodes can reference each other instead of being duplicated
+- One coherent graph per page rather than several disconnected islands
+
+**Common issues:**
+- Required properties missing, so the type is ineligible for rich results
+- `FAQPage` markup on content that is not a genuine Q&A
+- Schema describing content the user cannot see
+- Stale `dateModified` auto-set to build time on unchanged pages
+- Duplicate `Organization` nodes on every page with no shared `@id`
+
+Structured data also has a measurable association with citation in generative answers — see the
+[GEO section](#generative-engine-optimization-geo).
+
 ---
 
 ## Content Quality Assessment
@@ -373,12 +409,86 @@ Three equivalent placement methods: HTML `<link>` in `<head>`, HTTP `Link` heade
 - Better than top-ranking competitors
 - Updated and current
 
-### User Engagement Signals
+### User Engagement Signals — diagnostic only, not ranking factors
+
+**Google does not use analytics engagement metrics as ranking factors.** John Mueller: *"We don't use
+bounce rate in search rankings."* Gary Illyes: *"we don't use analytics/bounce rate in search
+ranking."* Google has denied this for roughly a decade.
+
+Never write a finding that says "improve bounce rate to improve rankings" — it is a causal claim
+Google has explicitly denied, and it damages the credibility of the correct findings next to it.
+
+Use these metrics the other way round: as **diagnostics that localize a content problem**, whose fix
+is the content itself.
+
+| Metric | Read it as |
+|---|---|
+| High exit rate on a ranking page | Possible intent mismatch — the page ranks for a query it does not answer |
+| Very low time on page for long-form content | Content may be unscannable, or the answer is buried |
+| Pages per session | Internal linking and topical-cluster coverage signal |
+| Return visits | Brand and content-quality signal (correlates with, does not cause, ranking) |
+
+- Sources and exact quotes: [SEJ: Is bounce rate a Google ranking factor?](https://www.searchenginejournal.com/ranking-factors/bounce-rate/)
+
+---
+
+## Generative Engine Optimization (GEO)
+
+Visibility inside AI-generated answers — Google AI Overviews / AI Mode, ChatGPT, Claude, Perplexity —
+rather than in a ranked list of links. See the [GEO reference](references/geo.md) for the measured
+evidence, source tiers, and the full AI-crawler agent table.
+
+**GEO layers on top of ranking; it does not replace it.** Roughly three quarters of AI Overview
+citations come from pages already in the top 10. Audit the priority order first.
+
+### What measurably works
+
+Peer-reviewed measurement (GEO-bench, KDD 2024: ~10,000 queries across nine datasets) found the
+largest visibility gains come from **evidence, not markup**:
+
+| Finding to raise | Measured effect |
+|---|---|
+| Claims lack **verifiable statistics** with named sources | ~30–40% gain when added |
+| No **credible quotations** where the topic supports them | ~30–40% |
+| No **outbound citations** to reliable sources | ~30–40% |
+| Poor fluency / readability | ~15–30% |
+| Keyword stuffing present | Negligible or **negative** — treat as a defect, not a tactic |
+
+Gains are largest for content that is visible but not dominant (up to +115.1% at position 5), which
+is most audit subjects.
+
+### The self-containment test
+
+Generative engines extract **passages**, not pages. For each passage the page wants cited, ask:
+*does this paragraph still make sense lifted out with no surrounding context?*
+
+Anaphora that depends on the previous paragraph ("this approach", "as mentioned above", "the former")
+breaks extraction. This is the most common GEO defect on otherwise well-optimized pages, and **no
+classic on-page check catches it**.
+
+Also require: a **definitional sentence** (*"X is a Y that does Z."*) at first use of every term the
+page wants to own, and a Q&A block with the question as the heading and the direct answer in the
+first sentence.
+
+### Checks
+
+- [ ] Verifiable statistics, quotations, and outbound citations present
+- [ ] Target passages pass the self-containment test
+- [ ] Definitional sentence at first use of each ownable term
+- [ ] Entity resolvable in one sentence (what it is, who made it); `Person`/`Organization` + `sameAs`
+- [ ] `dateModified` exposed; no stale visible version numbers or dates (fresh content is cited far more often)
+- [ ] JSON-LD present and valid (see Structured Data above)
+- [ ] robots.txt separates training agents from retrieval agents, matching the client's stated intent
+- [ ] No unverifiable numeric or superlative claims in `<title>`, meta description, or JSON-LD
+
+### Do not raise these
 
-- Time on page
-- Bounce rate in context
-- Pages per session
-- Return visits
+- **Missing `llms.txt`.** Adoption is ~8.7% of the top 1,000 domains, ~40% of existing files are
+  empty plugin stubs, no major AI crawler has committed to consuming it, crawler logs show the
+  retrieval agents skip it, and in one citation model removing the variable *improved* accuracy. It
+  has a legitimate use as business-to-agent context for IDE agents and MCP servers — recommend it on
+  developer-experience grounds or not at all, never as a visibility tactic.
+- **"Improve bounce rate to rank better."** See User Engagement Signals above.
 
 ---
 
@@ -459,6 +569,7 @@ Same format as above
 
 - [AI Writing Detection](references/ai-writing-detection.md): Common AI writing patterns to avoid (em dashes, overused phrases, filler words)
 - [International SEO](references/international-seo.md): Evidence and sources for hreflang, canonical + i18n, sitemaps, URL structure, and content quality across locales
+- [GEO](references/geo.md): Evidence and sources for generative-engine visibility — the KDD 2024 measurement of what works, passage-level extraction, freshness, structured-data correlation, the AI-crawler agent table (training vs retrieval), and why `llms.txt` is not a visibility tactic
 
 ---
 
@@ -503,4 +614,5 @@ Adaptation rules:
 
 - Findings land in the AKILI report artifacts (`/akili-seo` output), using the Issue / Impact / Evidence / Fix / Priority shape.
 - Fixes that exceed the trivial gate are routed through `/akili-propose` — never applied silently during the audit.
-- Sibling skills mentioned by upstream versions of this skill (programmatic-seo, schema, ai-seo, cro, analytics) are **not packaged** with AKILI-SPECS; when a finding needs them, note the gap in the report instead of loading them.
+- GEO findings use the same Issue / Impact / Evidence / Fix / Priority shape. Label the source tier when citing a magnitude: the KDD 2024 figures are peer-reviewed, the AI Overview and crawler-behaviour figures are industry analyses. Never present an `[INDUSTRY]` number to a client as measured fact.
+- Sibling skills mentioned by upstream versions of this skill (programmatic-seo, cro, analytics) are **not packaged** with AKILI-SPECS; when a finding needs them, note the gap in the report instead of loading them. The upstream `schema` and `ai-seo` gaps are now covered in-skill by the **Structured Data** and **GEO** sections.

package/.claude/skills/seo-audit/evals/evals.json

@@ -123,12 +123,27 @@
     {
       "id": 8,
       "prompt": "I want to add FAQ schema to my product pages. Can you help me set that up?",
-      "expected_output": "Should recognize this is a schema markup implementation task, not an SEO audit. Should defer to or cross-reference the schema skill, which specifically handles structured data implementation including FAQ schema. May briefly mention that FAQ schema can enable rich results, but should make clear that schema is the right skill for implementation.",
+      "expected_output": "Should recognize this is a structured-data implementation task, not a full SEO audit, and apply the Structured Data section directly (AKILI-SPECS does not package a separate schema skill). Should require that FAQPage markup describe genuine, visible Q&A content on the page, and warn that markup not matching visible content is a spam-policy violation rather than an optimization. Should note the detection limitation for verification (Rich Results Test or a rendering tool, never curl/web_fetch). May mention that FAQ content is also the densest citable surface for generative engines.",
       "assertions": [
-        "Recognizes this as schema markup implementation",
-        "References or defers to schema skill",
-        "Does not attempt a full SEO audit",
-        "May briefly mention FAQ schema benefits"
+        "Recognizes this as structured-data implementation",
+        "Applies the Structured Data section rather than deferring to an unpackaged schema skill",
+        "Requires markup to match visible page content",
+        "Notes the JS-injection detection limitation for verification",
+        "Does not attempt a full SEO audit"
+      ],
+      "files": []
+    },
+    {
+      "id": 9,
+      "prompt": "We rank on page one for our main keywords but we never show up in Google AI Overviews or ChatGPT. What should we fix?",
+      "expected_output": "Should apply the GEO section. Should lead with the evidence-density findings, which carry the largest measured gains (verifiable statistics with named sources, credible quotations, outbound citations to reliable sources), and cite the KDD 2024 GEO study as the source with its magnitudes labelled as peer-reviewed. Should apply the self-containment test to target passages and flag anaphora that depends on surrounding context. Should check definitional sentences, entity resolution, freshness / dateModified, and structured data. Should audit robots.txt for a blanket AI-bot block that also excludes the retrieval agents (OAI-SearchBot, Claude-SearchBot, PerplexityBot) as distinct from the training agents. Should NOT recommend creating llms.txt as a visibility tactic. Should NOT claim engagement metrics affect rankings. Should note GEO layers on ranking rather than replacing it.",
+      "assertions": [
+        "Prioritizes evidence density (statistics, quotations, citations) as the highest-yield fix",
+        "Applies the self-containment test to passages",
+        "Distinguishes AI training agents from retrieval agents in robots.txt",
+        "Does not recommend llms.txt as a visibility tactic",
+        "Labels industry figures separately from peer-reviewed figures",
+        "States that GEO layers on top of ranking"
       ],
       "files": []
     }

package/.claude/skills/seo-audit/references/geo.md

@@ -0,0 +1,203 @@
+# Generative Engine Optimization (GEO): Evidence & Sources
+
+Visibility inside AI-generated answers (Google AI Overviews / AI Mode, ChatGPT, Claude, Perplexity)
+rather than in a ranked list of links.
+
+**Source tiers used below.** `[PRIMARY]` = peer-reviewed research or first-party vendor
+documentation. `[INDUSTRY]` = vendor or agency analysis of observed data; directionally useful,
+methodology usually undisclosed, treat magnitudes as indicative not exact. Do not present
+`[INDUSTRY]` figures to a client as measured fact.
+
+---
+
+## GEO is not a replacement for SEO
+
+`[INDUSTRY]` 76% of Google AI Overview citations come from pages already ranking in the top 10 —
+classic ranking is the qualifying condition, not an alternative to it. A meaningful long tail exists
+(46.5% of cited URLs rank outside the top 50), so ranking is strongly predictive but not required.
+
+**Audit consequence:** never trade a classic SEO fix for a GEO fix. Run the standard audit priority
+order first; GEO is an additional layer applied to pages that already rank or can.
+
+- [CXL: Where Google AI Overviews cite from — 100-page study](https://cxl.com/blog/google-ai-overview-citation-sources/)
+
+---
+
+## What measurably improves generative visibility
+
+`[PRIMARY]` The GEO study (Aggarwal, Murahari, Rajpurohit, Kalyan, Narasimhan, Deshpande — KDD
+2024) built GEO-bench: ~10,000 queries across nine datasets, against a two-stage pipeline (Google
+Search retrieves top-5 sources, then an LLM synthesizes a cited answer). It tested nine content
+modifications and measured visibility change.
+
+| Modification | Measured effect |
+|---|---|
+| Adding **verifiable statistics** | ~30–40% gain (position-adjusted word count) |
+| Adding **credible quotations** | ~30–40% gain |
+| **Citing reliable sources** | ~30–40% gain |
+| Improving **fluency / readability** | ~15–30% gain |
+| **Keyword stuffing** | negligible or **negative** |
+
+Aggregate reported improvement across successful methods: **22–41%**.
+
+**The Equalizer Effect.** `[PRIMARY]` Gains are largest for lower-ranked sources — up to **+115.1%**
+visibility for content at position 5. GEO disproportionately benefits sites that are visible but not
+dominant, which is precisely the audit population that most needs it.
+
+**Audit consequence:** the three highest-yield GEO findings are all citation-and-evidence findings,
+not markup findings. A page making unsourced claims is a GEO defect even when its technical SEO is
+clean.
+
+- [arXiv: GEO — Generative Engine Optimization (2311.09735)](https://arxiv.org/pdf/2311.09735)
+- [dblp: KDD 2024 record](https://dblp.dagstuhl.de/rec/conf/kdd/AggarwalMRKND24.html)
+- [Princeton: publication record](https://collaborate.princeton.edu/en/publications/geo-generative-engine-optimization/)
+- [Blck Alpaca: methodology and critique of the Princeton GEO study](https://blckalpaca.at/en/knowledge-base/seo-geo/geo-generative-engine-optimization/the-princeton-geo-study-methodology-results-and-critique)
+
+---
+
+## Extraction happens at passage level, not page level
+
+`[INDUSTRY]` Generative engines lift **short, self-contained passages**. Paragraphs that answer one
+specific question are far more likely to be extracted than long blocks where the answer is diluted
+across sentences. Content types cited most: direct answers to specific questions, comparison tables,
+statistics attributed to named sources, and step-by-step instructions.
+
+**Audit consequence — the self-containment test.** For each target passage, ask: *does this
+paragraph still make sense lifted out of the page with no surrounding context?* Anaphora that
+depends on the previous paragraph ("this approach", "as mentioned above", "the former") breaks
+extraction. This is the single most common GEO defect on otherwise well-optimized pages, and it is
+invisible to every classic on-page check.
+
+**Definitional-sentence pattern.** For each term the page wants to own, include one sentence of the
+form *"X is a Y that does Z."* at first use. That sentence is what gets quoted verbatim.
+
+- [Contently: how to get cited in Google AI Overviews (2026)](https://contently.com/2026/02/25/how-to-get-cited-google-ai-overviews/)
+- [CXL: Where Google AI Overviews cite from](https://cxl.com/blog/google-ai-overview-citation-sources/)
+
+---
+
+## Freshness is weighted heavily
+
+`[INDUSTRY]` Content under three months old is reported as ~3x more likely to be cited in AI
+Overviews.
+
+**Audit consequence:** stale version numbers, undated articles, and missing `dateModified` are GEO
+findings, not just hygiene. For tooling and documentation pages specifically, a visible version
+number that lags the shipped release is a direct credibility signal against the page. Prefer reading
+such values from a live source at build time over hardcoding them.
+
+- [Heroic Rankings: Google AI Overview statistics 2026](https://heroicrankings.com/seo/managed/google-ai-overview-statistics-2026/)
+
+---
+
+## Structured data correlates with citation
+
+`[INDUSTRY]` Reported: 65% of pages cited by Google AI Mode carry structured data markup; 71% of
+pages cited by ChatGPT do. Figures span all schema types (`Article`, `Organization`, `Product`,
+`Review`, `FAQPage`, `HowTo`).
+
+**Read this as correlation, not proven causation** — pages with schema also tend to be better
+maintained overall. It is still a cheap, low-risk intervention with a plausible mechanism
+(machine-readable facts survive extraction better than prose).
+
+Highest-value types for GEO:
+
+| Type | Use for |
+|---|---|
+| `FAQPage` | Q&A blocks — the densest citable surface on most pages |
+| `HowTo` | Step-by-step procedures |
+| `TechArticle` / `Article` | Carries `dateModified`, feeding the freshness signal |
+| `SoftwareApplication` | Tools and packages — carries `softwareVersion` |
+| `Person` / `Organization` with `sameAs` | Entity resolution and author authority |
+
+**Entity disambiguation.** State plainly, in one sentence, what the subject *is* and who made it.
+Ambiguous brand names must be resolvable without inference. Bind the page to a `Person` or
+`Organization` node with `sameAs` links to authoritative profiles.
+
+- [Contently: 2026 AI Overview tactics](https://contently.com/2026/02/25/how-to-get-cited-google-ai-overviews/)
+- [Digital Applied: content strategy for AI Overviews, post-I/O 2026](https://www.digitalapplied.com/blog/content-strategy-ai-overviews-post-io-guide-2026)
+
+---
+
+## AI crawler access control
+
+`[PRIMARY]` The agents split by **purpose**, and that split is the whole point of auditing them:
+
+| Vendor | Training | Search / retrieval | User-triggered |
+|---|---|---|---|
+| OpenAI | `GPTBot` | `OAI-SearchBot` | `ChatGPT-User` |
+| Anthropic | `ClaudeBot` | `Claude-SearchBot` | `Claude-User` |
+| Perplexity | — | `PerplexityBot` | `Perplexity-User` |
+| Google | `Google-Extended` | (Googlebot) | — |
+
+**The consequential audit finding:** a site that blanket-blocks AI bots to avoid training also
+blocks the retrieval agents, and therefore removes itself from AI answers entirely. If the goal is
+visibility without feeding training, allow the search and user agents and disallow only the training
+agents.
+
+**`Google-Extended` is a robots.txt token, not a user agent.** It never appears in server logs.
+`Disallow: /` under `Google-Extended` opts out of Gemini training while leaving `Googlebot` — and
+therefore Search and AI Overviews — unaffected. Auditing for it in logs will always produce a false
+negative.
+
+**robots.txt is a request, not enforcement.** `[INDUSTRY]` Cloudflare reported (2025-08-04)
+observing Perplexity using undeclared crawlers that rotate user-agent, IP, and ASN to bypass
+no-crawl directives. When a client's requirement is actually *prevention* rather than *preference*,
+robots.txt is the wrong control — escalate to WAF/bot-management, and say so in the finding.
+
+- [Anagram: AI crawlers explained — GPTBot, ClaudeBot, PerplexityBot (2026)](https://www.anagram.ai/blog/ai-crawlers-explained-gptbot-claudebot-perplexitybot-and-how-to-let-them-in-2026)
+- [AuditAE: AI crawlers list 2026 — ClaudeBot, GPTBot, OAI-SearchBot](https://auditae.app/blog/ai-crawlers-explained)
+- [Witscode: robots.txt strategy 2026 — managing AI crawlers](https://witscode.com/blogs/robots-txt-strategy-2026-managing-ai-crawlers)
+
+---
+
+## llms.txt: do not recommend it for AI search visibility
+
+`[INDUSTRY]` The evidence is consistently negative, and this contradicts widespread advice:
+
+- Adoption is ~8.7% of the top 1,000 domains (June 2026); ~10% in other samples.
+- **39.6% of existing files are empty plugin stubs.**
+- No major AI crawler has committed to consuming the format.
+- Crawler-log analyses find GPTBot, ClaudeBot, PerplexityBot, OAI-SearchBot and Google-Extended
+  **overwhelmingly skip `/llms.txt`** and crawl HTML directly.
+- In one citation-frequency model, **removing the llms.txt variable improved prediction accuracy** —
+  it contributed noise, not signal.
+
+**Audit consequence:** do not raise "missing llms.txt" as a finding, and do not recommend building
+one as a GEO tactic. If a client already has one, leave it. The format does have a real use —
+**business-to-agent context for IDE agents and MCP servers** — which is a developer-experience
+decision, not a search-visibility one. Recommend it on those grounds or not at all.
+
+- [Rankability: llms.txt adoption data — 8.7% of the top 1,000 (June 2026)](https://www.rankability.com/data/llms-txt-adoption/)
+- [aeo.press: the state of llms.txt in 2026](https://www.aeo.press/ai/the-state-of-llms-txt-in-2026)
+- [OrganiKPI: llms.txt adoption and impact](https://organikpi.com/blog/distribution/llms-txt-adoption-impact/)
+
+---
+
+## What does not work
+
+| Tactic | Status |
+|---|---|
+| Keyword stuffing | `[PRIMARY]` Negligible or **negative** effect on generative visibility |
+| Unverifiable superlatives and performance claims | Dropped during extraction; adjacent verifiable claims lose credibility by association |
+| `llms.txt` as a visibility play | `[INDUSTRY]` No measured effect; see above |
+| Blanket-blocking all AI user agents | Removes the site from AI answers along with training corpora |
+| Prose-only pages with no extractable passages | Structurally unciteable regardless of quality |
+
+---
+
+## Audit checklist
+
+- [ ] Page already ranks (or can) for its target query — GEO layers on top of ranking, never replaces it
+- [ ] Claims carry **verifiable statistics** with named sources (highest measured yield)
+- [ ] **Credible quotations** present where the topic supports them
+- [ ] **Outbound citations** to reliable sources present
+- [ ] Every target passage passes the **self-containment test**
+- [ ] Each ownable term has a **definitional sentence** at first use
+- [ ] Q&A block present, question as heading, direct answer in the first sentence
+- [ ] Entity resolvable in one sentence (what it is, who made it)
+- [ ] `dateModified` exposed; visible version/date values not stale
+- [ ] JSON-LD present and valid — `FAQPage` / `HowTo` / `Article` as applicable, plus `Person`/`Organization` with `sameAs`
+- [ ] robots.txt distinguishes **training** agents from **retrieval** agents, and the split matches the client's stated intent
+- [ ] No unverifiable numeric claims in `<title>`, meta description, or JSON-LD
+- [ ] **Not** flagged: missing `llms.txt`

package/.claude/templates/implementer.md

@@ -16,9 +16,11 @@ Your sole responsibility is to implement the technical scope of the active task
     *   **Effort:** Honor the Leader's effort/depth instruction for this task (the *Effort dial* in `## Model Routing`) — think as hard as the brief asks: quick and mechanical for trivial work, deep and careful when the brief flags the task as complex or correctness-critical.
     *   Strictly align with requirements defined in `docs/specs/<spec-path>/requirements.md`.
     *   Follow the technical blueprint in `docs/specs/<spec-path>/design.md`.
-2.  **Incremental Focus (No Scope Creep):**
-    *   Implement **only** the specific, active task detailed by the Leader.
-    *   Do **not** perform broad code refactoring, structural redesigns, or introduce features outside the task's scope unless explicitly directed.
+2.  **Scope Discipline (Both Directions):**
+    *   **Don't widen.** Implement **only** the specific, active task detailed by the Leader. Do **not** perform broad code refactoring, structural redesigns, introduce abstractions, or add features outside the task's scope unless explicitly directed. Don't add error handling or fallbacks for cases that cannot happen.
+    *   **Don't narrow either.** Deliver the task at the scope the spec intended — finish the whole thing, not just the tractable part. Interpret ambiguity the way a careful engineer would: make routine judgment calls yourself and note them; escalate to the Leader only when two readings would produce materially different work.
+    *   **Report completion only when it is actually complete.** Never claim done for partial work. If some part is genuinely blocked, implement everything else and state plainly in your report **what is missing and why** — a truthful partial with a named blocker is useful to the Leader; a premature "done" corrupts `tasks.md` and the audit trail.
+    *   If you conclude the task as specified is wrong or unviable, say so in one or two sentences and **still deliver the task as written** under a stated assumption. Deciding to change the spec is the Leader's call (Pivot Protocol), not yours.
 3.  **Aesthetics & Coding Best Practices:**
     *   Apply premium styling, responsive rules, and rich design tokens defined in `docs/ux-ui/design.md`.
     *   Preserve all existing comments, docstrings, and structures unrelated to your code changes.
@@ -35,6 +37,7 @@ When you finish implementing and verifying your task, provide a concise response
 1.  **Task Completed:** (Brief 1-sentence summary of what you implemented)
 2.  **Verification Command Run:** (e.g. `npm run test` or `vitest run`)
 3.  **Verification Output/Evidence:** (Paste passing test outputs or compile success logs)
+4.  **Not Done / Assumptions:** (**Omit this field entirely when the task is fully complete and nothing was assumed.** Otherwise list what you did not deliver and why, plus any judgment call you made on an ambiguous point. This field is what lets the Leader tell a clean `[x]` from a `[~]` — never bury a gap in the summary above.)
 
 ---
 

package/.claude/templates/leader.md

@@ -16,13 +16,14 @@ Your sole responsibility is to coordinate execution of an approved spec by orche
 
 2. **Task Selection & Parallel Execution:**
    * Parse `tasks.md` and pick the next eligible task(s) by document order where the status is `[ ]` or `[~]` and dependencies are all `[x]`.
-   * **Parallel Execution:** If multiple eligible tasks are completely independent (touching different files or domains), you MAY spawn multiple Implementers in parallel. Otherwise, pick a single task.
+   * **Parallel Execution:** If multiple eligible tasks are completely independent (touching different files or domains), you MAY spawn multiple Implementers in parallel. Otherwise, pick a single task. Parallelism is bounded by how many independent tasks `tasks.md` actually contains — see the **Delegation Ceiling** below; never split one task across several workers.
    * If a task is `[~]`, resume it using `execution.md` context.
    * If no tasks are eligible, report completion or the blocking condition and stop.
 
 3. **Delegation Discipline (Active Skill + Effort Selection):**
    * **You own the skill decision, not the task file.** Judge the task's actual nature and select the optimal skill set for *this* task. The task's recommended skills (e.g., `shadcn-ui`, `nestjs-expert`) and the project's `## Skill Map` (root `AGENTS.md`/`CLAUDE.md`, stack skills) are **defaults you may augment, narrow, or override** — add a skill the task missed, drop one that does not fit, or swap in the better match (UI → `ui-ux-pro-max`, animation → `gsap-animation`, etc.). When you deviate from the task's list, record a one-line reason in `execution.md`. Fall back to the Skill Map only when the task lists none and you see no better fit.
    * **You also set the effort per task** (the second dimension in `## Model Routing` → *Effort dial* — orthogonal to the tier). Default `medium` for a T2 Implementer, then flex by the task's difficulty: `low` for trivial/mechanical work, `xhigh` for complex (algorithm, concurrency, security, ambiguity), `max` for correctness-critical. Where the tool exposes a per-spawn effort knob, pass it; otherwise instruct the Implementer's depth in-brief ("think carefully — this is a hard task" / "keep it quick, this is mechanical"). Don't `max` a cheaper tier — if a task wants `max`, escalate the tier instead.
+   * **The `medium` default assumes a well-specified task.** It holds because `/akili-specify` already did the decomposition. When a task arrives *under*-specified — a `[~]` resume with thin `execution.md` context, or a post-Pivot retry — start it at `high`/`xhigh` instead. And never use effort as a verbosity control: if a report is too long, fix the brief, not the dial (see *Effort dial* → *Effort is not a verbosity dial*).
    * Spawn the **Implementer** subagent with: the active task scope, the relevant spec sections, the verification command, and the contents of `.agents/implementer.md`.
    * **Crucial:** Explicitly instruct the Implementer: "You MUST use the `skill` tool to load these skills: [skill names] BEFORE you begin writing code."
    * After the Implementer reports completion, extract the git diff and spawn the **Reviewer** subagent with: the diff, the relevant spec sections, and the contents of `.agents/reviewer.md`.
@@ -64,6 +65,20 @@ This table is the methodology's single source of truth for when an orchestrating
 
 **CodeGraph exception:** in codegraph-enabled projects, `codegraph_search` / `codegraph_context` / `codegraph_callers` lookups do **not** count toward the 4-file threshold — targeted graph lookups are precisely how the orchestrator avoids bulk file reads. The threshold counts full-file reads.
 
+### 🚧 Delegation Ceiling (when *not* to delegate)
+
+The table above is a **floor** — it says when delegating is mandatory. This is the **ceiling**. Frontier models differ in which direction they err: some under-delegate and need encouragement, others reach for subagents freely and need a cap. Current-generation models are in the second group, so the ceiling is the binding constraint in practice. Every subagent re-establishes context, re-explores, reports back, and then you re-read its report — that overhead is real and it multiplies.
+
+| Rule | Why |
+|------|-----|
+| **One subagent beats several** for a single modest task | Splitting one modest job across parallel workers pays the context-establishment cost N times for one deliverable. Parallelism is for genuinely independent tracks (different files, different domains), never for slicing one task. |
+| **Commit to the delegation** | Once a subagent reports, do **not** redo its work or re-derive its findings to satisfy yourself. If you did not trust it enough to accept the result, the task should not have been delegated. |
+| **Brief precisely the first time** | Launch → wait → re-brief burns a full context cycle. Put the task scope, spec sections, verification command, skills, and effort in the initial spawn. |
+| **Cap the fan-out** | Keep concurrent spawns low and bounded by the number of genuinely independent tasks in `tasks.md`. Never open a wide fan-out the spec does not call for. |
+| **Never delegate your own verification** | Checking a `git status`, confirming a file exists, or re-reading a diff you already have is inline work. Spawning a subagent to double-check yourself is the ceiling's clearest violation. |
+
+**The Reviewer is not self-verification — never collapse it.** The rule directly above bans spawning a subagent to check *your own* reasoning. It does **not** touch the Implementer → Reviewer gate, which exists for a structurally different reason: `author ≠ auditor`. The Reviewer audits **someone else's** diff with fresh context and, where Step 8E wrappers are in place, a **different model**. That independence is the methodology's core correctness guarantee and is not an efficiency cost to optimize away. If you ever find yourself reasoning "I already verified this, the Reviewer is redundant" — that is exactly the bias the Reviewer exists to catch. Spawn it.
+
 ---
 
 ## 🔁 Orchestration Sequence (per task)
@@ -71,7 +86,7 @@ This table is the methodology's single source of truth for when an orchestrating
 1. Load spec and constitution context.
 2. Select next task.
 3. **Spawn Implementer** with `.agents/implementer.md` + task context.
-4. Receive Implementer report (code change + verification evidence).
+4. Receive Implementer report (code change + verification evidence). **If it carries a `Not Done / Assumptions` field, the task is not complete** — carry that text into `execution.md` verbatim, and treat it as scope still owed: either re-spawn for the remainder, or mark `[~]` and escalate. A task with an outstanding gap never reaches `[x]`, even on a Reviewer `PASS`.
 5. Extract `git diff` of the change set.
 6. **Spawn Reviewer** with `.agents/reviewer.md` + diff + spec context.
 7. Branch on Reviewer status:

package/CHANGELOG.md

@@ -10,6 +10,38 @@ The format is inspired by Keep a Changelog and the repository follows semantic v
 
 - No unreleased changes yet.
 
+## [2.15.0] - 2026-07-26
+
+### Added
+
+- **GEO (Generative Engine Optimization) in `seo-audit` — visibility inside AI answers, grounded in measured evidence.** New `## Generative Engine Optimization (GEO)` section plus a `references/geo.md` evidence file following the same claims-plus-sources convention as `international-seo.md`. The headline finding, from the peer-reviewed GEO study (Aggarwal et al., **KDD 2024**, GEO-bench: ~10,000 queries across nine datasets), is that **the largest gains come from evidence, not markup**: adding verifiable statistics, credible quotations, and outbound citations each yields ~30–40%, fluency/readability ~15–30%, and **keyword stuffing is negligible or negative**. Gains are largest for content that ranks but does not dominate (up to **+115.1%** at position 5 — the "Equalizer Effect"), which is most audit subjects. Also documented: **passage-level extraction** and the resulting **self-containment test** (a paragraph must survive being lifted out of the page — anaphora like "this approach" breaks extraction, and no classic on-page check catches it), definitional sentences, entity resolution, freshness weighting, and the structured-data citation correlation (65% of AI-Mode-cited pages, 71% of ChatGPT-cited pages) explicitly labelled as correlation, not causation. Every claim carries a `[PRIMARY]` / `[INDUSTRY]` **source tier**, and findings must carry that tier forward so an industry estimate is never presented to a client as measured fact. Wired into `/akili-seo` as **Step 2.8** with a matching report section and verification-checklist rows.
+- **AI-crawler directive auditing.** The `Robots.txt` checks now separate **training** agents (`GPTBot`, `ClaudeBot`, `Google-Extended`) from **retrieval** agents (`OAI-SearchBot`, `Claude-SearchBot`, `PerplexityBot`) and user-triggered fetchers. The consequential finding: **a blanket AI-bot block removes the site from AI answers as well as from training corpora** — a state many sites are in by accident. Records that `Google-Extended` is a robots.txt token that never appears in logs (so auditing for it there always yields a false negative) and that blocking it does not affect `Googlebot` or AI Overviews, and that robots.txt is advisory — where the requirement is genuine prevention, escalate to WAF/bot management.
+- **Structured Data audit section** — a real gap: the skill previously explained *how to detect* schema (the JS-injection limitation) but had no checklist for auditing it. Adds per-purpose type selection, validation, the visible-content match requirement (invisible or contradictory markup is a spam-policy violation, not an optimization), truthful `dateModified`, `sameAs` entity nodes, and consistent `@id` graph wiring. Closes the upstream `schema` sibling-skill gap in-skill.
+
+### Changed
+
+- **Engagement metrics rewritten from ranking factors to diagnostics — correcting a myth the skill propagated.** The `User Engagement Signals` section listed time on page, bounce rate, pages per session, and return visits as things to audit, implying they are ranking factors. Google has denied this for roughly a decade (Mueller: *"We don't use bounce rate in search rankings"*; Illyes: *"we don't use analytics/bounce rate in search ranking"*). The section now states that plainly, **bans findings of the form "improve bounce rate to improve rankings"** as a causal claim Google has explicitly denied that damages the credibility of correct findings beside it, and reframes each metric as a diagnostic that localizes a content problem whose fix is the content.
+- **`Disallow` is not `noindex`.** New robots.txt check for one of the most consequential confusions in technical SEO: a disallowed URL can still be indexed from external links and surfaces as "Indexed, though blocked by robots.txt"; removing a page from the index requires *allowing* the crawl and serving `noindex`, and a `noindex` line inside `robots.txt` is unsupported and ignored.
+- **`llms.txt` is explicitly ruled out as a visibility tactic, against prevailing advice.** Evidence: ~8.7% adoption of the top 1,000 domains (June 2026), ~40% of existing files are empty plugin stubs, no major AI crawler has committed to consuming the format, crawler-log analyses show the retrieval agents skip it and crawl HTML directly, and in one citation-frequency model **removing the variable improved prediction accuracy** — it contributed noise. Both the skill and `/akili-seo` now list "missing `llms.txt`" as a finding that must **not** be raised, while noting the format's legitimate use as business-to-agent context for IDE agents and MCP servers — a developer-experience call, not a search one.
+- **`seo-audit` priority order gains an explicit GEO boundary.** GEO is a layer applied on top of ranking, not a sixth priority: roughly three quarters of AI Overview citations come from pages already in the top 10, so a GEO fix never displaces a classic-SEO fix, and GEO items rank below blocking classic findings in the remediation plan. Skill version 2.0.0 → 2.1.0; trigger keywords extended (AI Overviews, AI search, GEO, answer engine optimization, `llms.txt`, GPTBot, ClaudeBot); upstream `schema`/`ai-seo` sibling-gap note updated now that both are covered in-skill.
+## [2.14.0] - 2026-07-25
+
+### Added
+
+- **Delegation Ceiling — the missing upper bound on orchestrator fan-out.** The `Delegation Thresholds` table added in 2.13.0 is a *floor* (when delegating is mandatory); frontier models increasingly err in the opposite direction, reaching for subagents freely, so the packaged `leader.md` gains a **Delegation Ceiling** section: one subagent beats several for a single modest task (parallelism is for independent tracks, never for slicing one task), **commit to the delegation** (never re-derive a subagent's result), brief precisely on the first spawn (launch → wait → re-brief burns a context cycle), bounded fan-out, and **never delegate your own verification**. The section carries an explicit carve-out: *the Implementer → Reviewer gate is `author ≠ auditor` independence, not self-verification, and is never collapsed for efficiency* — without it, a ceiling rule banning "subagents to double-check yourself" reads as license to drop the Reviewer. Referenced from `/akili-execute` and scaffolded via `/akili-constitution` Step 8B. Leader Instruction #2 now bounds parallelism by the count of genuinely independent tasks in `tasks.md`.
+- **Implementer scope discipline is now bidirectional, with a `Not Done / Assumptions` report field.** Instruction #2 only guarded against scope *creep*; current-generation models also expand scope and can report completion on partial work. It becomes **Scope Discipline (Both Directions)**: don't widen (no unrequested refactors, abstractions, or impossible-case error handling), **don't narrow either** (finish the whole task at the intended scope), **report completion only when actually complete**, and when the task as specified looks wrong, say so in a sentence but still deliver it as written — changing the spec is the Leader's Pivot Protocol call. The completion report gains an optional field 4 (**omitted entirely when the task is clean**) naming what was not delivered and any judgment call made; `leader.md`'s orchestration sequence consumes it — a task carrying an outstanding gap never reaches `[x]`, even on a Reviewer `PASS`.
+- **Model Generation Drift check in `/akili-audit`.** Aliases absorb a new model generation silently, so the registry can be current while everything calibrated around it has gone stale. The new check flags (report-only, as with all drift checks): a **frontier escalation pin** whose recorded reason predates the current `opus` generation; an `Updated:` stamp older than the current generation (effort defaults never swept); and `.agents/*.md` personas missing guardrails the packaged templates have since gained (Delegation Ceiling, bidirectional Scope Discipline).
+
+### Changed
+
+- **Effort dial re-baselined as a per-generation calibration, not a constant.** `docs/model-routing.md` now states the split explicitly: the tier mapping survives model churn, **effort defaults do not**. AKILI's defaults (T2 Implementer `medium`) are calibrated for its shape — tasks arrive *already decomposed and spec-bounded* from `/akili-specify` — whereas vendor guidance for a frontier model is written for one open-ended agentic request with no spec, and therefore starts higher (Claude Opus 5's published starting points are `xhigh` for coding/agentic, `high` elsewhere, then sweep down). The reconciliation is three rules: **sweep don't assume** (run a real spec at `medium`/`high`/`xhigh` on every generation and keep the cheapest level whose Reviewer outcome holds), newer generations get *more* out of the low end so the sweep usually confirms `medium`, and an **under-specified task** (a `[~]` resume with thin `execution.md` context, or a post-Pivot retry) starts one level higher because it resembles the open-ended case. New **Opus specifics** paragraph (start high and iterate *down* — more effort up front reduces total turns on agentic work; the rework bump is the cheapest place to spend effort since it only fires after a failure). Mirrored into the `/akili-constitution` Step 8C scaffold as items (e) and (f).
+- **Effort is not a verbosity dial.** New explicit rule in `docs/model-routing.md` and the Step 8C scaffold: on current-generation models, lowering effort does **not** reliably shorten user-facing output — it changes how much the model *thinks*, not how much it *writes*. Long Implementer reports and Leader narration are fixed in the brief (`caveman` for transient agent output, `cognitive-doc-design` for artifacts), never by dropping effort, which otherwise buys verbose output *and* shallower reasoning. The `tier ↔ effort` illustration is now labelled as generation-specific data supporting a generation-stable rule.
+- **Frontier escalation tier corrected and repositioned.** The section claimed Fable carries *"a refusal classifier Opus does not"* — no longer true: current-generation Opus ships elevated bio/cyber safeguards of its own and can decline a request outright. That claim is removed from the Fable-only constraints list (which keeps no-ZDR, minutes-long turns, and less-prescriptive prompting) and replaced by a methodology-level rule: a declined security-adjacent task is a **Pivot Protocol** case recorded in `execution.md`, **never a Reviewer `FAIL` to be reworked** — rework cannot fix a refusal. The tier is also repositioned as a **decision to re-justify on every generation** rather than a standing configuration, since each Opus generation narrows the gap the pin was bought to close: try the alias at `xhigh`/`max` first.
+- **Rate limits documented as per-generation, not per-family.** `docs/model-routing.md` and the `/akili-constitution` Step 8C model-confirmation step now record that a new top-tier generation draws on its **own** quota rather than inheriting the previous generation's pool, so moving T1/T3 onto it neither frees headroom on the old pool nor inherits it. The "reserve the top tier for T1/T3" rule is unchanged — it is about where the budget earns its cost, not which pool it comes from.
+
+### Notes
+
+- **The model registry itself required zero edits for the Opus 5 release** — the `opus` alias resolved to it automatically and T1/T3 followed, which is the first row of the *Replacing a model* runbook (*do nothing*). This is recorded in `docs/model-routing.md` as a worked example of the alias-first rule, alongside the corollary this release makes explicit: what a new generation *does* invalidate is the per-task effort calibration and the prompt-level guardrails, not the tier mapping.
 ## [2.13.1] - 2026-07-24
 
 ### Added

package/docs/model-routing.md

@@ -99,6 +99,13 @@ tier (to the deeper reasoner) to preserve independence.
 This is the single editable source of truth. Phases reference **tiers**; only this table names
 models. When models change, edit only this table. *Registry updated: 2026-07.*
 
+> **Worked example — the Opus 5 release required zero edits to this table.** When Anthropic shipped
+> Claude Opus 5, the `opus` alias moved to it on its own; T1/T3 followed automatically. That is the
+> alias-first rule paying off (first row of the *Replacing a model* runbook: **do nothing**). What
+> a new generation *does* require is re-reading the **Effort dial** and the behavioural notes below
+> — the tier mapping survives model churn, but the per-task effort defaults and the prompt-level
+> guardrails do not.
+
 **Alias-first rule: never pin a dated model name where a floating alias exists.** Claude Code's
 `opus` / `sonnet` / `haiku` aliases always resolve to the latest version of each family — when
 Anthropic ships a new generation, an alias-based registry needs **zero edits**. Pin a dated ID only
@@ -131,6 +138,13 @@ unchanged (e.g. when the top family moves from one generation to the next, `opus
 Users on plans that expose a frontier model above Opus (Fable 5 / Mythos 5) can pin it for T1/T3 —
 see **Frontier escalation tier** below.
 
+**Rate limits are per-generation, not per-family.** A new Opus generation draws on its **own**
+quota rather than inheriting the previous generation's pool — Opus 5, for instance, does not share
+the combined Opus 4.x bucket. So moving T1/T3 onto a newer Opus neither frees headroom on the old
+pool nor inherits it: check the new generation's limits before shifting volume onto it. The
+"reserve the top tier for T1/T3" rule holds regardless — it is about *where the budget earns its
+cost*, not about which pool the budget comes from.
+
 **OpenCode Go.** The strongest open models anchor the highest-leverage tiers:
 
 - **GLM-5.2 → T2 Coder.** A-tier open coder (753B, GPQA 91.2), successor to GLM-5.1, purpose-built
@@ -165,6 +179,13 @@ high-volume fan-out): at ~2× Opus pricing (**$10 / $50** per 1M in/out vs `opus
 only earns its cost where token volume is low and the decision gates the whole run — T1 (Architect +
 the execute/test Leader) and T3 (Auditor).
 
+**Each Opus generation raises the bar for escalating.** Opus 5 closed much of the gap on exactly the
+work this tier existed for — deep reasoning, long-horizon agentic runs, and bug-finding — at half
+Fable's price. Treat escalation as a decision to **re-justify on every generation**, not a standing
+configuration: try the current `opus` at `xhigh` or `max` first, and pin the frontier model only if
+a concrete spec demonstrably fails there. A pin inherited from a previous generation is a pin worth
+re-testing.
+
 | Slot | Default (alias) | Frontier escalation pin | Fallback |
 |---|---|---|---|
 | **T1 Architect / Leader** | `opus` | `claude-fable-5` *(pin — record the reason)* | `opus` |
@@ -175,12 +196,18 @@ Two things follow from Fable having **no floating alias**:
 - **It is a dated pin — record the reason** (per the alias-first rule), and it re-inherits the
   concrete-slug maintenance the aliases spare you. `/akili-audit`'s drift check watches it; the
   *Replacing a model* runbook below is how you swap it when a newer frontier model ships.
-- **Always give it a Fallback to `opus`**, because Fable carries operational constraints Opus does
-  not: a **refusal classifier** on bio/cyber that can false-positive on legitimate security-adjacent
-  specs (a Fable Implementer/Reviewer may decline valid work); **no zero-data-retention** (requires
-  30-day retention — unavailable to ZDR projects); **minutes-long turns** (budget HITL gates and
-  progress narration accordingly); and **less prescriptive prompting** (over-prescribed `.agents/*`
-  personas can *reduce* Fable output quality — loosen them when routing a role to Fable).
+- **Always give it a Fallback to `opus`**, because Fable carries operational constraints the Opus
+  alias does not: **no zero-data-retention** (requires 30-day retention — unavailable to ZDR
+  projects); **minutes-long turns** (budget HITL gates and progress narration accordingly); and
+  **less prescriptive prompting** (over-prescribed `.agents/*` personas can *reduce* Fable output
+  quality — loosen them when routing a role to Fable).
+
+**Refusal classifiers are no longer a Fable-only concern.** Current-generation Opus ships elevated
+bio/cyber safeguards of its own and can decline a request outright, so a security-adjacent spec may
+stall the Implementer or Reviewer on **either** tier. Plan for it at the methodology level rather
+than treating it as an escalation-only risk: when a spec is security-adjacent, say so in the task
+brief, and treat a declined task as a **Pivot Protocol** case (record it in `execution.md` and
+escalate to the user) — never as a Reviewer `FAIL` to be reworked, since rework cannot fix a refusal.
 
 **Cross-family author ≠ auditor.** Fable pairs well with a *different-lab* auditor — pin the
 Implementer/Leader on `claude-fable-5` and the Reviewer on a Kimi/DeepSeek OpenCode slug (or
@@ -227,21 +254,53 @@ representative model (GPT-5.6 Sol, Artificial Analysis Intelligence Index):
 | T3 **Reviewer** / `/akili-validate` | `high` (auditor thoroughness) |
 | T5 `/akili-archive` / setup steps | `low` |
 
+**Re-baseline these defaults on every model generation — the tier mapping survives model churn, the
+effort defaults do not.** The table above is calibrated for AKILI's shape: tasks arrive *already
+decomposed and spec-bounded* from `/akili-specify`, which is exactly the case where a mid-range
+effort holds up. Vendor guidance for a frontier model is written for the opposite case — one
+open-ended agentic request with no spec — and therefore starts higher (for Claude Opus 5, the
+published starting points are **`xhigh` for coding and agentic work, `high` elsewhere, then sweep
+down**). Both are right for their context. The reconciliation:
+
+- **Sweep, don't assume.** On a new generation, run the same spec at `medium`, `high`, and `xhigh`
+  and keep the cheapest level whose Reviewer outcome holds. Effort defaults inherited from a
+  previous generation are a guess, not a measurement.
+- **Newer generations get more out of the low end, not less.** Each Opus generation has made
+  `low`/`medium` stronger relative to its own ceiling — so the sweep usually confirms the T2
+  `medium` default rather than pushing it up. Raise the Implementer to `xhigh` for the task
+  signals in the policy table above, not by default.
+- **Where a task arrives under-specified** — a `[~]` resume with thin `execution.md` context, or a
+  Pivot Protocol retry — it is closer to the vendor's open-ended case. Start it at `high`/`xhigh`.
+
+**Effort is not a verbosity dial.** On current-generation models, lowering effort does **not**
+reliably shorten user-facing output — it changes how much the model *thinks*, not how much it
+*writes*. If an Implementer's report or a Leader's narration is too long, fix it in the brief
+(`caveman` for transient agent output, `cognitive-doc-design` for artifacts), never by dropping
+effort — that buys verbose output *and* shallower reasoning. The same applies in reverse: raising
+effort to get a more thorough **document** is the wrong lever; ask for the depth explicitly.
+
 **Escalate effort on rework.** In the `/akili-execute` rework loop, a Reviewer `FAIL` bumps effort
 one level on the retry (attempt 1 `medium` → attempt 2 `high` → attempt 3 `xhigh`) — cheap (only
 when it already failed) and it targets the usual cause (under-thinking, not missing instructions).
 
 **Tier ↔ effort interaction — don't `max` a cheaper tier.** Maxing a lower tier erodes its cost
-advantage: Sonnet 5 at `max` (53 intel / $1.53) approaches Opus 4.8 at `max` (56 intel / $1.80) —
-near-Opus price for below-Opus intelligence. If you find yourself wanting a cheaper tier at `max`,
-escalate the **tier** (to `opus` at `high`/`medium`) instead of the effort.
+advantage: on the 4.8-generation ladder, Sonnet 5 at `max` (53 intel / $1.53) approached Opus 4.8 at
+`max` (56 intel / $1.80) — near-Opus price for below-Opus intelligence. Those figures are a
+generation-specific illustration, but the rule they demonstrate is stable across generations: if you
+find yourself wanting a cheaper tier at `max`, escalate the **tier** (to `opus` at `high`/`medium`)
+instead of the effort.
 
 **Sonnet specifics.** Sonnet respects effort strictly, especially at the low end — at `low`/`medium`
 it scopes work to exactly what was asked. If you see shallow reasoning on a hard problem, **raise
 the effort, don't prompt around it**. `high` is the default sweet spot; give `max_tokens` headroom
 at `xhigh`/`max` (thinking consumes the budget — too tight truncates with `stop_reason: max_tokens`).
-On Opus/frontier the nuance inverts slightly: start at `high` and iterate — more effort up front
-often *reduces* total turns and cost on agentic work.
+
+**Opus specifics.** On Opus the nuance inverts: start high and iterate **down** — more effort up
+front often *reduces* total turns and total cost on agentic work, because the model plans better and
+re-does less. Two consequences for the AKILI loop: (1) the **rework bump** (above) is the cheapest
+place to spend effort, since it only fires after a failure; and (2) `max` is for the
+correctness-critical and latency-insensitive case only — it can overthink a routine task and is
+where diminishing returns bite hardest.
 
 ## Enforced routing (tool-native agent bindings)
 

package/docs/skills/README.md

@@ -30,7 +30,7 @@ The skill set is **curated, not accumulated**: every skill declares its original
 | [`nestjs-expert`](nestjs-expert.md) | stack | Daniel Avila (MIT) | NestJS modules, DI, guards, interceptors, testing, TypeORM/Mongoose | Skill Map; constitution/specify stack lists; persona examples |
 | [`product-manager-toolkit`](product-manager-toolkit.md) | core | Alireza Rezvani (MIT) | Product discovery, PRDs, prioritization, interview analysis (AKILI-adapted: canonical PRD structure, RICE for scope-chunk ordering) | `/akili-constitution` Steps 2–3, `/akili-propose`, `/akili-specify` scope chunking |
 | [`react-doctor`](react-doctor.md) | stack | Million.dev | React diagnostics after changes | Skill Map; `/akili-test`, `/akili-validate`, `/akili-execute` React work |
-| [`seo-audit`](seo-audit.md) | core | Corey Haines (MIT) | Technical, on-page, and international SEO audits with a standard finding format | `/akili-seo` audit phase (required) |
+| [`seo-audit`](seo-audit.md) | core | Corey Haines (MIT) | Technical, on-page, structured-data, international, and generative-engine (GEO) audits with a standard finding format | `/akili-seo` audit phase (required) |
 | [`shadcn-ui`](shadcn-ui.md) | stack | community (origin unverified) | shadcn/ui components, forms, themes, Tailwind integration | Skill Map; constitution/specify stack lists; persona examples |
 | [`software-architect`](software-architect.md) | core | Juan Carlos Cadavid — jcadavid.com (MIT) | Senior-architect Decision Spine: NFRs as measurable quality-attribute scenarios, tactics, robust-vs-lite tier sizing, architecture styles (hexagonal/clean/microservices), GoF pattern selection, C4 views + ADRs, agentic AI patterns | `/akili-constitution` Step 5 (required) and Step 6 tier handoff; `/akili-specify` Phase 2 for architecturally significant features |
 | [`stitch-design`](stitch-design.md) | conditional | Google — google-labs-code | Stitch prompt enhancement and design generation workflows (fallback UI chain with `frontend-design`) | UI steps of `/akili-constitution`, `/akili-propose`, `/akili-specify` |

package/docs/skills/seo-audit.md

@@ -2,28 +2,40 @@
 
 ## Purpose
 
-Provides an expert SEO audit framework: crawlability and indexation, technical foundations (Core Web Vitals, mobile, HTTPS), on-page optimization (titles, metas, headings, images, internal linking), international SEO (hreflang, locale canonicals, locale sitemaps), content quality (E-E-A-T), and a standard finding format.
+Provides an expert SEO audit framework: crawlability and indexation, technical foundations (Core Web Vitals, mobile, HTTPS), on-page optimization (titles, metas, headings, images, internal linking), structured data, international SEO (hreflang, locale canonicals, locale sitemaps), content quality (E-E-A-T), **generative-engine visibility (GEO)**, and a standard finding format.
 
 AKILI-adapted: findings use the Issue/Impact/Evidence/Fix/Priority shape inside `/akili-seo` artifacts, non-trivial fixes escalate to `/akili-propose`, and dangling references to unpackaged sibling skills were removed. Binding: `core`.
 
+AKILI-original additions (not in the upstream skill): the **GEO** section and `references/geo.md`; the **Structured Data** audit section; AI-crawler directive auditing; the `Disallow` ≠ `noindex` correction; and the rewrite of engagement metrics from ranking factors to diagnostics.
+
 ## Use When
 
 - Auditing, reviewing, or diagnosing SEO issues on a site.
 - Rankings or organic traffic dropped and the cause is unknown.
 - Reviewing meta tags, structured data, page speed, or indexing issues.
+- The site is absent from AI answers (AI Overviews, ChatGPT, Perplexity), or AI-crawler access needs a decision.
 - Running the audit phase of `/akili-seo`.
 
 ## Core Rules
 
 - Findings follow the **Issue / Impact / Evidence / Fix / Priority** structure.
 - Findings are weighted by priority order: crawlability → technical → on-page → content quality → authority.
+- **GEO is a layer, not a sixth priority** — ~3/4 of AI Overview citations come from pages already in the top 10, so a GEO fix never displaces a classic-SEO fix.
+- **Source tiers are carried into findings.** Peer-reviewed magnitudes (KDD 2024 GEO study) and industry analyses are labelled differently; an industry figure is never presented to a client as measured fact.
 - Static fetches (`curl`, `web_fetch`) cannot detect JS-injected JSON-LD; structured data must be validated with a rendering tool or Search Console URL inspection.
+- **Two findings are explicitly banned:** "missing `llms.txt`" (no measured visibility effect) and any claim that engagement metrics such as bounce rate affect rankings (Google has denied this for a decade).
 
 ## Best Paired Commands
 
 - `/akili-seo` for the audit phase (index coverage, structured data, render, on-page checks).
 - `/akili-validate` when a spec includes SEO acceptance criteria.
 
+## References (progressive disclosure)
+
+- `references/geo.md` — generative-engine visibility: the KDD 2024 measurement of what works, passage-level extraction, freshness, structured-data correlation, the AI-crawler agent table (training vs retrieval), and the negative evidence on `llms.txt`. Claims carry `[PRIMARY]` / `[INDUSTRY]` source tiers.
+- `references/international-seo.md` — hreflang, canonical + i18n, locale sitemaps, URL structure, cross-locale content quality.
+- `references/ai-writing-detection.md` — AI writing patterns to avoid.
+
 ## Source
 
 - `../../.claude/skills/seo-audit/SKILL.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akili-specs",
-  "version": "2.13.1",
+  "version": "2.15.0",
   "description": "Portable AKILI-SPECS methodology commands and skills for AI-assisted development.",
   "homepage": "https://github.com/JuankCadavid/akili-specs#readme",
   "repository": {