diff --git a/agents/geo-analyzer.md b/agents/geo-analyzer.md index 9d697bb..637c942 100644 --- a/agents/geo-analyzer.md +++ b/agents/geo-analyzer.md @@ -263,6 +263,32 @@ For each JSON-LD block found, check: 4. **Graph integrity** — do `@id` references connect? No orphans? 5. **sameAs coverage** — does it include the main authoritative URIs? +### FAQ page presence (universal check) + +ChatGPT, Gemini, Perplexity citation rates spike on sites with a +dedicated FAQ page. Check: + +```bash +# FR + EN FAQ paths +for p in /faq /questions /questions-frequentes /aide /help /support; do + find . -maxdepth 3 -path "*${p}*" 2>/dev/null | head -3 +done + +# FAQ schema presence +grep -rE '"@type"\s*:\s*"(FAQPage|QAPage)"' --include="*.html" --include="*.astro" --include="*.tsx" --include="*.php" --include="*.vue" . 2>/dev/null | head -10 +``` + +Emit finding: +``` +FAQ PAGE : present at | absent +FAQ SCHEMA : FAQPage (collection) | QAPage (single Q) | none +Q&A COUNT : | not applicable +RECOMMENDATION : CREATE /faq with 20-50 real customer questions (P0 for GEO) | ADD schema to existing page | OK +``` + +If absent and site is informational/service/B2B → emit as MEDIUM-term +action (G5 batch, confirmation needed — visible page creation). + ### Gaps to fix — by site type **Content site / blog:** @@ -271,6 +297,7 @@ For each JSON-LD block found, check: - [ ] `dateModified` matches last content update - [ ] `speakable` on TL;DR / summary block - [ ] `BreadcrumbList` on every non-home page +- [ ] FAQ page with `FAQPage` schema — even 10 real questions lift AI citations **Local business:** - [ ] `LocalBusiness` with most specific subclass (Plumber/Dentist/etc.) @@ -513,6 +540,23 @@ High-impact, low-effort. For each: - Expected impact (high/medium/low) - AUTO (executed in STEP 13) or USER (documented in §11 of SEO.md) +**MANDATORY user action — AI index submission**: every FULL audit +MUST emit these 3 user actions (they are the entry points for AI +search engines into your site): + +1. **Bing Webmaster Tools** — submit + verify sitemap. Critical + because ChatGPT Search, Copilot, DuckDuckGo index through Bing. +2. **Google Search Console** — submit + request indexing for key + pages. Google AI Overviews ground on this index. +3. **IndexNow** — enable via plugin (RankMath, Yoast, Cloudflare) or + custom endpoint. Proactive push to Bing/Yandex/Seznam. + +See `~/.claude/agents/resources/automation-catalog.md` → +"Submit to AI indexes directly" for URLs + automation tools. + +Additionally, if business is local: **Apple Business Connect** +(feeds Apple Maps + Apple Intelligence local discovery). + ### Medium term (1-3 months) - Entity SEO campaigns (Wikidata creation with source gathering) @@ -764,6 +808,13 @@ PROCHAINE ETAPE : - **Focus on GEO, not classical SEO.** Overlapping concerns (meta title, sitemap, Core Web Vitals) belong to `seo-analyzer`. Do not duplicate. Reference them in §13 as "see SEO section" if needed. +- **Shared-file edit discipline.** On template files shared with + `seo-analyzer` (Layout.astro, index.html, base.html.twig, etc.), + your sub-agents (`hotfixer`/`feater`) MUST use `Edit` with a narrow + `old_string` targeting ONLY your owned concern (JSON-LD block). + NEVER `Write` on shared templates. `Write` is reserved for files + you solely own: robots.txt, llms.txt, llms-full.txt. Full-template + refactor → escalate as user action in §11. - **Respect PERMISSIVE/RESTRICTIVE choice.** Per user CLAUDE.md, default is PERMISSIVE. Only switch if client explicitly flags premium/regulated content. diff --git a/agents/resources/automation-catalog.md b/agents/resources/automation-catalog.md index d872ca4..8c4fb16 100644 --- a/agents/resources/automation-catalog.md +++ b/agents/resources/automation-catalog.md @@ -52,11 +52,38 @@ See `ai-visibility-tools.md`. Summary: - **OtterlyAI, Peec AI, Trendos, ZipTie, HubSpot AEO, SE Ranking** — commercial - **Manual spreadsheet + 20 queries/mois** — free, ~1h/mois -### Submit to AI indexes directly +### Submit to AI indexes directly (MANDATORY user action on FULL audit) -- **Bing Webmaster Tools** → submits to Bing + Copilot + ChatGPT Search (which uses Bing index) -- **IndexNow protocol** (indexnow.org) → proactive ping to Bing/Yandex -- **Google Search Console + URL Inspection** → request indexing (no ChatGPT index direct submit exists in 2026) +AI engines read from these indexes: +- ChatGPT Search, Copilot, DuckDuckGo, Ecosia → **Bing index** +- Google AI Overviews, Gemini (grounding mode) → **Google index** +- Perplexity, Brave AI → **own crawlers + Bing fallback** + +Therefore: submit to GSC + Bing Webmaster minimum on every FULL audit. + +- **Bing Webmaster Tools** (FREE) — https://www.bing.com/webmasters + Critical because ChatGPT Search, Copilot, DuckDuckGo all use Bing. + Features: URL inspection, sitemap submission, keyword research, SEO + reports, IndexNow API integration. Plugin for WordPress available. + Setup: 10 min (verify domain via meta tag or DNS). +- **Google Search Console** (FREE) — https://search.google.com/search-console + Covers Google search + AI Overviews grounding. URL inspection tool + requests live re-indexing (faster than waiting for crawl). +- **IndexNow protocol** (FREE) — https://www.indexnow.org + Proactive ping to Bing + Yandex + Seznam + DuckDuckGo. One-line + API call per URL change. Plugins: Yoast (built-in), RankMath, + Cloudflare (zone-level), Cloudflare Workers snippet. For custom + sites: `curl` POST to `https://api.indexnow.org/indexnow`. +- **Brave Web Discovery** (FREE) — enable in Brave browser settings + → "Aider Brave Search à découvrir du contenu". Visit your site in + Brave browser to help its indexation. Brave Search uses this for + index discovery, and Brave AI answers pull from Brave Search. +- **Kagi submit** (requires Kagi account) — smaller audience but + growing for privacy-focused search. +- **Apple Business Connect** → Apple Maps + Apple Intelligence local + discovery. Free but requires Apple ID. https://businessconnect.apple.com +- No direct "submit to ChatGPT" exists in 2026 — submission to Bing + is the canonical path. ### Maintain llms.txt / llms-full.txt @@ -113,12 +140,121 @@ typically batch D (structural change, user approval needed). - **SEOClarity** (enterprise) → content decay tracking - **Manual** — spreadsheet of top 50 pages + quarterly review cycle +## CMS plugin-first — install before editing templates + +**Rule**: when the site runs on a CMS, the highest-priority SEO action +is to install/configure the SEO plugin. Manual template edits +duplicate the plugin's output and create maintenance debt. + +### WordPress (2026 recommendations) + +- **RankMath Free** — default recommendation. Most features in free + tier, including Schema.org (Article, LocalBusiness, FAQ, HowTo, + Product), breadcrumbs, sitemap, redirect manager, GSC integration, + GEO-aware (content AI score). + Install: Plugins → Add New → "Rank Math SEO" → Install → Activate. + Setup wizard: ~10 min. +- **Yoast SEO Free** — most popular. Strong for meta + sitemap + + readability. Schema.org basic in free, extended in Premium (99 USD/an). +- **Yoast SEO Premium** (99 USD/an) — redirect manager, internal + linking suggestions, multiple focus keywords. +- **SEOPress Free** — French origin, GDPR-friendly, good Schema.org + coverage. +- **SEOPress Pro** (49-99 EUR/an) — white-label, WooCommerce Schema, + Google Analytics integration. +- **AIOSEO (All-in-One SEO)** — older player, solid baseline. +- **Slim SEO** — minimalist, auto-configuration, good for sites that + need SEO without admin complexity. + +Recommendation if unsure: **RankMath Free** → upgrade to RankMath Pro +(59 USD/an) only if Analytics integration or Schema Pro needed. + +### Shopify + +- **Plug in SEO** (free + 20 USD/mois) — scans store for SEO issues, + suggests fixes, handles meta templates for products/collections. +- **Smart SEO** (10-30 USD/mois) — auto-generates alt tags, meta + tags, JSON-LD (Product, Organization, Breadcrumbs). +- **SEO Manager** (20 USD/mois) — image SEO, structured data, 404 + redirects. +- **Avada SEO** — newer, good GEO-aware features. +- Shopify native: configure via Admin → Online Store → Preferences + (title, meta description, homepage), + per-product meta fields. + +### Drupal (7/8/9/10) + +Core SEO stack (install as modules, free): +- **Metatag** — meta tags (OG, Twitter Card, canonical) +- **Simple XML Sitemap** — sitemap generation +- **Pathauto** — clean URLs +- **Schema.org Metatag** — JSON-LD Schema.org output +- **Yoast SEO Drupal** — on-page readability + focus keyword analysis +- **Redirect** — 301 redirects +- **Google Analytics** — GA4 integration + +### Magento 1 / 2 + +Native Magento SEO is decent but limited. Paid extensions dominate: +- **SEO Suite Ultimate (Mageworx)** — canonical, URL rewrites, rich + snippets, meta templates (~250-500 EUR one-time) +- **Mirasvit SEO Suite** — similar scope, 149-399 USD +- **Amasty SEO Toolkit** — HTML sitemap, rich snippets, meta + templates +- Free basics: configure native URL rewrites + meta defaults in + System → Configuration → Catalog → SEO + +### PrestaShop + +- **PrestaShop SEO Expert** (free + paid) — meta templates, rich + snippets, image alt rules +- **JMarket SEO Pack** — structured data + breadcrumbs +- **Advanced SEO** module — meta per category/product with + placeholders +- Native: Configure → Shop Parameters → Traffic & SEO + +### Joomla + +- **JoomSEF** — URL rewriting + meta management +- **sh404SEF** — commercial (~60 EUR/year), full SEO suite +- **4SEO** — native integration, comprehensive +- **OSMap** — sitemap generator (free) + +### Ghost + +Native SEO is strong (meta + OG + Twitter Card + JSON-LD Article/Author +out of box). Customization via theme `default.hbs` + routes.yaml. +Plugins unnecessary for most sites. + +### Wix / Squarespace / Webflow (hosted CMS) + +**No theme file access.** All SEO changes happen in the admin UI: +- **Wix** — SEO panel per page; Wix SEO Wiz for guided setup; + redirects in Settings → Custom Domain → URL Redirects. +- **Squarespace** — Per-page SEO tab (title, description, image); + sitewide in Settings → Marketing → SEO; URL slugs editable. +- **Webflow** — Page Settings per page (meta title, description, + OG image); sitemap at `/sitemap.xml` (auto); robots.txt in Project + Settings → SEO. + +Agent cannot auto-apply anything on these platforms — emit detailed +USER action list per panel. + +### Extension of this catalog for NEW CMS + +If detected CMS not listed above, agent runs WebSearch: +``` +web_search: best SEO plugin 2026 +``` +and emits findings with pricing in the report. + +--- + ## Technical SEO actions ### Generate sitemaps - **Framework plugin** — `@astrojs/sitemap`, `next-sitemap`, `@nuxtjs/sitemap`, `rails-sitemap-generator`, etc. -- **Yoast / RankMath** (WordPress) → auto-generate +- **Yoast / RankMath / SEOPress** (WordPress) → auto-generate (see CMS plugins section above) - **Screaming Frog** (200 GBP/an) → crawler-based generation - Manual: only as last resort, hand-maintained sitemaps go stale fast diff --git a/agents/resources/llms-txt-template.md b/agents/resources/llms-txt-template.md index 4945964..aca6bc5 100644 --- a/agents/resources/llms-txt-template.md +++ b/agents/resources/llms-txt-template.md @@ -7,6 +7,12 @@ extract content via `/llms.txt`. A Search Engine Land study (2025) found 8 of 9 sites saw no measurable traffic change after adoption. +**Not to be confused with `/ai.txt`**: some blog posts and AI-generated +articles recommend a file named `/ai.txt` or `/about-data`. These are +NOT real standards — no spec exists, no AI engine reads them. If someone +asks about `/ai.txt`, the correct answer is "use `llms.txt` instead, it +is the only emerging proposed standard (Jeremy Howard, Sept 2024)". + **Why include it anyway**: - Low cost (small static file). - Real value for developer-facing sites — AI coding assistants (Cursor, diff --git a/agents/seo-analyzer.md b/agents/seo-analyzer.md index 73d5825..0301413 100644 --- a/agents/seo-analyzer.md +++ b/agents/seo-analyzer.md @@ -95,6 +95,57 @@ Rails, Django, other. Record rendering: **SSR / SSG / SPA / hybrid / ISR**. +### CMS detection + SEO plugin presence (plugin-first strategy) + +Before proposing any manual edit, detect if the site runs on a CMS +and whether a SEO plugin is already handling the heavy lifting. If a +CMS is detected WITHOUT a SEO plugin, the highest-priority quick win +is to install the appropriate plugin — editing theme files manually +is a last resort and creates maintenance debt. + +```bash +# WordPress signals +[ -f wp-config.php ] && echo "CMS: WordPress" +ls wp-content/plugins 2>/dev/null | head -20 +# Common SEO plugins +ls wp-content/plugins 2>/dev/null | grep -iE "yoast|wordpress-seo|seo-by-rank-math|rank-math|seopress|all-in-one-seo|aioseo|squirrly|slim-seo" + +# Drupal signals +[ -f core/CHANGELOG.txt ] && echo "CMS: Drupal" +find . -maxdepth 3 -name "*.info.yml" 2>/dev/null | xargs -I{} grep -l "yoast_seo\|metatag\|pathauto\|simple_sitemap" {} 2>/dev/null | head -5 + +# Magento / Shopify / PrestaShop / Joomla signals +[ -f composer.json ] && grep -iE "magento|shopify|prestashop|joomla" composer.json 2>/dev/null +[ -f config.xml ] && echo "CMS: Magento (likely)" +[ -f configuration.php ] && grep -q "JConfig" configuration.php 2>/dev/null && echo "CMS: Joomla" +# Shopify: detected via theme files (shopify.theme.toml, config/settings_data.json) +[ -f config/settings_data.json ] && [ -d sections ] && echo "CMS: Shopify (theme source)" + +# Ghost signals +[ -f config.production.json ] && grep -q "ghost" config.production.json 2>/dev/null && echo "CMS: Ghost" + +# Webflow / Wix / Squarespace: usually hosted — detected only via live HTML +# (FULL depth check: curl home page and look for meta generator tag) +``` + +Record: +``` +CMS CONTEXT +CMS : WordPress | Drupal | Magento | Shopify | Joomla | PrestaShop | Ghost | Webflow | Wix | Squarespace | none (custom) +SEO PLUGIN : | ABSENT | N/A (not CMS) +PLUGIN COVERAGE : meta | sitemap | OG | JSON-LD | breadcrumbs | redirects | +GAP : +RECOMMENDATION : KEEP & CONFIGURE plugin | INSTALL (P0 quick win) | MANUAL EDITS (no CMS) +``` + +**Decision rule**: +- CMS + SEO plugin present → CONFIGURE it via admin UI (settings). Do + NOT duplicate its output by editing theme files. +- CMS + no SEO plugin → emit P0 quick win in STEP 10: "Install + " with direct link + automation catalog refs. + Manual theme edits only on concerns the plugin does not cover. +- No CMS (custom code) → full manual edit via hotfixer/feater as usual. + ### Infrastructure signals ```bash @@ -329,7 +380,7 @@ Each embedded or self-hosted video should have: - `` if self-hosted - Thumbnail with OG image or structured data -### Internal linking +### Internal linking + topic clusters (silos sémantiques) Sample critical pages. Check: - Every important page reachable within 3 clicks from homepage? @@ -337,6 +388,29 @@ Sample critical pages. Check: - Footer has key legal + service links? - Orphan pages (no inbound internal links)? +**Topic clusters (silos sémantiques)** — beyond basic navigation, +evaluate whether the site organises content into topical silos: +- **Pillar page** (broad topic, e.g. "Guide complet SEO local") — + authoritative, long-form, targets head keyword. +- **Cluster pages** (narrow sub-topics, e.g. "Comment optimiser GMB", + "NAP cohérent") — each links TO the pillar + back is linked FROM + the pillar. +- **Cross-cluster links** — minimized; each silo should be internally + cohesive. + +Why this matters for both classical SEO and GEO: +- Classical: Google uses topical authority as ranking signal (2024+ + Helpful Content + E-E-A-T). Clustered sites rank entire clusters, + not just individual pages. +- GEO: AI engines extract the whole cluster when answering a query + — a well-linked cluster gets cited more often than isolated pages. + +Flag: +- Pages listed in nav but not linked from related content (orphans + within their topic) +- Pillar pages lacking inbound links from their clusters +- Excessive cross-cluster linking (dilutes topical authority) + ### Accessibility signals (a11y contributes to ranking) ```bash @@ -543,6 +617,21 @@ For each: AUTO items are a commitment, not a suggestion. +**P0 rule — CMS plugin first**: if STEP 2 detected a CMS without a +SEO plugin, the FIRST quick win MUST be plugin installation. Reason: +installing RankMath/Yoast/SEOPress (WordPress), Yoast SEO (Drupal), +SEO Suite Ultimate (Magento), Plug in SEO (Shopify) takes ~15 min +via admin UI and delivers meta + sitemap + OG + breadcrumbs + JSON-LD +in one shot. Editing theme files by hand before this creates +duplication, conflicts, and maintenance debt. See +`~/.claude/agents/resources/automation-catalog.md` CMS plugins +section for the exact install path per CMS. + +**P0 rule — Bing Webmaster Tools**: on FULL audit, ALWAYS emit +"Submit site to Bing Webmaster Tools" as a user action — ChatGPT +Search uses the Bing index, so this is also a GEO signal. See +automation-catalog.md for IndexNow + Bing. + ### Medium term (1-3 months) City/service pages (30/70 rule: 30% shared, 70% unique per city), blog launch, review campaigns, citation cleanup, image optimization @@ -682,7 +771,14 @@ Include in every sub-agent prompt: - **SvelteKit** — `` or `+layout.server.ts` load. Custom sitemap endpoint. - **Static HTML / PHP** — edit `` directly. `.htaccess` for redirects. - **React SPA** — flag SEO severely limited without SSR. `react-helmet` helps metadata but content indexation breaks. Recommend migration to Next.js/Astro. Note this in §0 (major alerts). -- **WordPress** — Yoast/RankMath/SEOPress handle meta + sitemap. Do not duplicate. +- **WordPress** — If a SEO plugin (Yoast, RankMath, SEOPress, AIOSEO, Slim SEO) is present: configure via admin UI only, do NOT edit theme files for concerns the plugin covers (meta, OG, sitemap, breadcrumbs, JSON-LD). If ABSENT: P0 quick win = install plugin before any manual edit. Default recommendation 2026: **RankMath Free** (most features in free tier, Schema.org and GEO-aware). +- **Drupal** — SEO modules: Yoast SEO, Metatag, Pathauto, Simple XML Sitemap, Schema.org Metatag. If present: configure modules. If absent: P0 = enable Metatag + Simple XML Sitemap + Pathauto (core SEO stack). +- **Magento (1/2)** — Native SEO decent but limited. Recommended: **SEO Suite Ultimate (Mageworx)** or **Mirasvit SEO Suite**. Configure URL rewrites, meta templates, rich snippets in admin. +- **Shopify** — Editing: theme files (`theme.liquid`, `product.liquid`, `article.liquid`). Plugins: **Plug in SEO**, **SEO Manager**, **Smart SEO** auto-handle most items. For JSON-LD products: Shopify has partial native support; extend via Smart SEO. +- **PrestaShop** — Native SEO OK. Modules: **PrestaShop SEO Expert**, **JMarket SEO**, built-in meta editors. Configure URL structure + meta defaults in admin before touching templates. +- **Joomla** — SEO extensions: **JoomSEF**, **sh404SEF**, **4SEO**. Configure in admin. +- **Ghost** — Native SEO strong (meta + OG + JSON-LD out of box). Usually no plugin needed; handle gaps via `default.hbs` edits. +- **Wix / Squarespace / Webflow (hosted CMS)** — No theme file access. ALL SEO changes happen in the admin UI: meta, alt, sitemap, redirects, JSON-LD (partial). Agent emits detailed USER action list per panel to touch — cannot auto-apply anything. ### Landing page rule @@ -858,6 +954,13 @@ PROCHAINE ETAPE : ### Scope - **Autonomous fixes = markup, assets, config, legal pages.** Never change business logic, layout, styles, routing unless confirmed. +- **Shared-file edit discipline.** On template files shared with + `geo-analyzer` (Layout.astro, index.html, base.html.twig, etc.), + your sub-agents (`hotfixer`/`feater`) MUST use `Edit` with a narrow + `old_string` targeting ONLY your owned concern (meta tags). NEVER + `Write` on shared templates. `Write` is reserved for files you + solely own: sitemap.xml, .htaccess, legal pages, new city/service + pages. Full-template refactor → escalate as user action in §11. - **Landing page protection.** Zero visible change except meta tags, footer links, JSON-LD, image optimization. - **Preserve existing valid SEO.** Don't rewrite correct tags. diff --git a/skills/seo/SKILL.md b/skills/seo/SKILL.md index 8bbd5c1..e74f303 100644 --- a/skills/seo/SKILL.md +++ b/skills/seo/SKILL.md @@ -120,8 +120,38 @@ their dispatch prompts: | Video transcripts | **seo-analyzer** (user action) | | If either agent detects a finding in a file it doesn't own, it emits -a "CROSS-AGENT NOTE" in its envelope; the dispatcher forwards it to -the owning agent at merge time. No direct cross-agent fix. +a "CROSS-AGENT NOTE" in its envelope. The dispatcher does NOT re-spawn +the owning agent (both have finished by merge time). Instead, cross-agent +findings are escalated into `SEO.md §11 — Actions utilisateur requises` +with an explicit "Automatisation possible avec: ..." block pulled from +`automation-catalog.md`. This is the Option B resolution (chosen by +user): simpler than a coordinator agent, aligns with the "every user +action lists automation" rule, and avoids architectural complexity. + +### Shared-file edit discipline (prevents last-writer-wins) + +Ownership is by *concern*, not by *file*. A single template +(`Layout.astro`, `index.html`, `base.html.twig`, `_document.tsx`…) +typically contains BOTH concerns simultaneously: + - meta tags (seo-analyzer) + - JSON-LD blocks (geo-analyzer) + +When the agents' sub-agents (hotfixer/feater) run in parallel they +could both target the same physical file. To avoid a `Write`-based +last-writer-wins scenario: + +**Rule** (embedded in both agent dispatch prompts below): + +> On any shared template file (anything containing multiple owned +> concerns), use the `Edit` tool with a **narrow, targeted** `old_string` +> that encloses ONLY your owned concern. NEVER use `Write` (full-file +> rewrite) on a shared template. `Write` is reserved for files you +> are the sole owner of (sitemap.xml, robots.txt, llms.txt, legal +> pages, new city pages, .htaccess). + +If a sub-agent determines `Edit` is insufficient (e.g. full template +refactor needed), it must STOP and escalate as a cross-agent note — +the dispatcher handles via §11 user action instead. ## STEP 1 — Spawn both agents IN PARALLEL @@ -161,8 +191,20 @@ FILE OWNERSHIP (authoritative, prevents parallel-edit conflicts): - YOU READ-ONLY: robots.txt (geo-analyzer owns), JSON-LD blocks (geo-analyzer owns structure; you flag NAP inconsistencies), llms.txt. - CROSS-AGENT NOTES: if you find issues in files you don't own, emit - them in your envelope under "CROSS-AGENT NOTES TO geo-analyzer:" - — the dispatcher forwards. + them in your envelope under "CROSS-AGENT NOTES TO geo-analyzer:". + Dispatcher escalates each note to SEO.md §11 as user action (with + automation options). Do NOT attempt direct cross-agent fix. + +SHARED-FILE EDIT DISCIPLINE (last-writer-wins prevention): +- On shared templates (Layout.astro, index.html, base.html.twig, etc.) + where meta tags + JSON-LD coexist, your sub-agents (hotfixer/feater) + MUST use `Edit` with a targeted `old_string` enclosing ONLY your + concern (meta tags). NEVER use `Write` (full-file rewrite) on shared + templates. +- `Write` is allowed only on files where you are the sole owner: + sitemap.xml, .htaccess, legal pages, new city/service pages. +- If full-template refactor is needed, STOP and emit as a cross-agent + note → user action in §11. Execute your agent spec at ~/.claude/agents/seo-analyzer.md starting at STEP 2 (skip STEP 0 and STEP 1 — context is provided above). @@ -196,8 +238,20 @@ FILE OWNERSHIP (authoritative, prevents parallel-edit conflicts): - YOU READ-ONLY: sitemap.xml, .htaccess, meta tags, heading structure (seo-analyzer owns structure), legal pages, images, hreflang. - CROSS-AGENT NOTES: if you find issues in files you don't own, emit - them in your envelope under "CROSS-AGENT NOTES TO seo-analyzer:" - — the dispatcher forwards. + them in your envelope under "CROSS-AGENT NOTES TO seo-analyzer:". + Dispatcher escalates each note to SEO.md §11 as user action (with + automation options). Do NOT attempt direct cross-agent fix. + +SHARED-FILE EDIT DISCIPLINE (last-writer-wins prevention): +- On shared templates (Layout.astro, index.html, base.html.twig, etc.) + where meta tags + JSON-LD coexist, your sub-agents (hotfixer/feater) + MUST use `Edit` with a targeted `old_string` enclosing ONLY your + concern (JSON-LD block). NEVER use `Write` (full-file rewrite) on + shared templates. +- `Write` is allowed only on files where you are the sole owner: + robots.txt, llms.txt, llms-full.txt. +- If full-template refactor is needed, STOP and emit as a cross-agent + note → user action in §11. Execute your agent spec at ~/.claude/agents/geo-analyzer.md starting at STEP 2 (skip STEP 0 and STEP 1 — context is provided above). @@ -312,6 +366,29 @@ Legal compliance). Merge rule: and the other says "keep schema X", flag explicitly in §0 and let the user decide +### CROSS-AGENT NOTES handling (Option B — §11 escalation) + +When an envelope contains a `CROSS-AGENT NOTES TO :` +block, the dispatcher: + +1. Does NOT re-spawn the target agent (it has finished). +2. Converts each note into a §11 user action entry with the format: + ``` + ### (cross-agent note from ) + + **Contexte:** a détecté ce point dans un fichier + appartenant à , mais l'audit parallèle s'est terminé + avant échange. + + **Action:** + + **Automatisation possible avec:** + + **Effort manuel:** + ``` +3. Tags it visibly in §0 if it's a legal/compliance blocker. +4. Keeps these notes visible on re-run — they don't silently vanish. + ## STEP 3 — Console summary ```