diff --git a/README.md b/README.md index d967882..bed2c93 100644 --- a/README.md +++ b/README.md @@ -56,9 +56,9 @@ cp agents-md/AGENTS.md your-project/ | Tool | Directory | Files | Format Notes | |------|-----------|------:|--------------| -| Claude Code | `claude-code/` | 15 | CLAUDE.md + 7 scoped rules + 6 skills + hooks template | +| Claude Code | `claude-code/` | 17 | CLAUDE.md + 8 scoped rules + 7 skills + hooks template | | Cursor | `cursor/` | 14 | .cursorrules + 13 .mdc files with 4 activation modes | -| GitHub Copilot | `github-copilot/` | 22 | copilot-instructions.md + 7 instructions + 6 prompts + 2 chat modes + 6 skills | +| GitHub Copilot | `github-copilot/` | 23 | copilot-instructions.md + 7 instructions + 6 prompts + 2 chat modes + 7 skills | | Windsurf | `windsurf/` | 14 | 14 .md files in .windsurf/rules/ with 4 trigger types, within 6K/12K char limits | | Kilo Code | `kilo-code/` | 21 | 5 mode files + 3 Memory Bank files + 7 concerns + 6 skills | | Cline | `cline/` | 14 | 14 .md files in .clinerules/ with Plan/Act paradigm | @@ -68,7 +68,7 @@ cp agents-md/AGENTS.md your-project/ | Gemini CLI | `gemini-cli/` | 1 | Single GEMINI.md with all content as sections | | JetBrains / Junie | `jetbrains-junie/` | 1 | Single .junie/guidelines.md, always loaded | | AGENTS.md | `agents-md/` | 1 | Single vendor-neutral file, supported by 20+ tools | -| **Total** | | **137** | | +| **Total** | | **140** | | --- @@ -86,7 +86,7 @@ Every tool covers the same material, adapted to its native format. Tools with mu - **Accessibility** -- i18n, offline-first, low-bandwidth, low-literacy design, mesh networking, device seizure resilience - **Emotional safety** -- Progressive disclosure of traumatic content, configurable detail levels, content warnings, secondary trauma mitigation -**6 process skills** (workflow guides invoked on demand): +**7 process skills** (workflow guides invoked on demand): - **git-workflow** -- Atomic commits, ephemeral branches, PR curation, AI-Assisted tags, code survival rate tracking - **testing-strategy** -- Spec-first generation, five anti-patterns to avoid (snapshot trap, mock everything, happy path only, test-after-commit, coverage theater), mutation-guided improvement @@ -94,6 +94,7 @@ Every tool covers the same material, adapted to its native format. Tools with mu - **plan-first-development** -- Spec, design, decompose, implement one subtask at a time, generation-then-comprehension pattern - **code-review** -- Layered review pipeline, Ousterhout red flags, AI-specific failure patterns, advocacy-specific data leak checks - **security-audit** -- Advocacy threat model assessment, slopsquatting defense, prompt injection / rules file backdoor detection, MCP server security +- **geo-seo-audit** -- GEO/SEO verification workflow (Core Web Vitals, structured data, indexing controls, AI citation-risk checks) --- @@ -121,15 +122,15 @@ For Claude Code specifically, see `hooks-template.md` for setting up determinist **Windsurf** -- `.windsurf/rules/*.md` with four trigger types: Always On, Model Decision, Glob, and Manual. Hard constraint of 6,000 characters per file and 12,000 characters combined. Always On files budgeted to ~8K total to leave headroom for contextually loaded files. Note: Windsurf generates persistent memories about your codebase -- review and clear regularly for sensitive projects. -**Kilo Code** -- `.kilocode/rules/` with five mode-specific rule files (Ask, Architect, Code, Debug, Orchestrator), a Memory Bank (`brief.md`, `context.md`, `history.md`) for progressive context disclosure, seven concern files, and six process skills in `.kilocode/skills/`. +**Kilo Code** -- `.kilocode/rules/` with five mode-specific rule files (Ask, Architect, Code, Debug, Orchestrator), a Memory Bank (`brief.md`, `context.md`, `history.md`) for progressive context disclosure, seven concern files, and seven process skills in `.kilocode/skills/`. **Cline** -- `.clinerules/` directory with 14 Markdown files. Emphasizes Cline's Plan/Act paradigm: explore in Plan Mode before changing anything in Act Mode. All concern and skill content as separate rule files. -**Roo Code** -- `.roomodes` JSON defining custom modes (Review and Interview) with tool restrictions and model assignments, plus `.roo/rules/` containing five mode-specific rule files (Architect, Code, Debug, Review, Interview), seven concern files, and six skill files. Supports Boomerang Task delegation between modes. +**Roo Code** -- `.roomodes` JSON defining custom modes (Review and Interview) with tool restrictions and model assignments, plus `.roo/rules/` containing five mode-specific rule files (Architect, Code, Debug, Review, Interview), seven concern files, and seven skill files. Supports Boomerang Task delegation between modes. **Augment Code** -- `.augment/rules/*.md` with a `main.md` core file plus 13 concern and skill files. All files loaded as directory-based rules. -**Aider** -- Single `CONVENTIONS.md` file loaded as read-only context. All seven concerns and six skills condensed into clearly-headed sections. Adapted for Aider's `/architect` and `/code` mode workflow. +**Aider** -- Single `CONVENTIONS.md` file loaded as read-only context. All seven concerns and seven skills condensed into clearly-headed sections. Adapted for Aider's `/architect` and `/code` mode workflow. **Gemini CLI** -- Single `GEMINI.md` file at project root. All content as sections in one self-contained file. diff --git a/agents-md/AGENTS.md b/agents-md/AGENTS.md index 5ae0317..7865423 100644 --- a/agents-md/AGENTS.md +++ b/agents-md/AGENTS.md @@ -486,3 +486,102 @@ desloppify next Do not be lazy. Large refactors and small detailed fixes — do both with equal energy. No task is too big or too small. Fix things properly, not minimally. Use `plan` / `plan queue` to reorder priorities or cluster related issues. Rescan periodically. The scan output includes agent instructions — follow them, do not substitute your own analysis. + +## GEO + SEO — Advocacy Website Visibility + +Websites for animal advocacy serve two discovery channels: traditional search engines and AI answer systems (ChatGPT, Perplexity, Google AI Overviews, Claude, Gemini). The game has shifted from keyword matching to **intent satisfaction** (does your content completely solve the user's problem?), **entity authority** (does Google's knowledge graph recognize your brand?), and **technical excellence** (can crawlers efficiently process your site?). AI generates an answer first, then scores content against it using embedding distance. Only 17–32% of AI Overview citations come from pages ranking in the organic top 10 — lower-authority pages can win with the right structure (source: Authoritas AI Overviews study, 2024). Domain Authority correlates with AI citations at r=0.18; topical authority (r=0.40) and branded web mentions (r=0.664) are the real predictors (source: Kalicube GEO correlation study, 2025). + +### Core Web Vitals (March 2026) + +Google confirmed CWV as ranking factors measured via real Chrome user data at the 75th percentile. + +| Metric | Good | Needs Improvement | Poor | +|--------|------|-------------------|------| +| LCP (Largest Contentful Paint) | ≤ 2.5s | 2.5–4.0s | > 4.0s | +| INP (Interaction to Next Paint) | ≤ 200ms | 200–500ms | > 500ms | +| CLS (Cumulative Layout Shift) | ≤ 0.1 | 0.1–0.25 | > 0.25 | + +43% of sites still fail the INP threshold. Sites with INP above 200ms saw an average ranking drop of 0.8 positions; LCP above 3s causes 23% more traffic loss vs faster competitors. The primary INP technique is `scheduler.yield()` (Chrome-native, with `setTimeout` fallback) — breaks long tasks so the browser can handle user input between them. + +### HTML Structure + +One `

` per page. Phrase `

` headings as questions — produces 7× more AI citations for smaller sites. First paragraph after any heading must directly answer the question in 40–60 words. AI pulls from the first 30% of content 44% of the time. Keep paragraphs 2–4 sentences. Structure content as self-contained 120–180 word modules — generates 70% more ChatGPT citations than unstructured prose. Use semantic HTML (`
`, `
`, `
`, etc.). Never hide content behind JavaScript-only rendering; AI crawlers generally do not execute JS. + +### Semantic Writing for AI + +AI retrieval happens at sentence and paragraph level. **Entity salience:** make the primary entity the grammatical subject — active voice gives a salience score of 0.74 vs passive 0.11. **Atomic claims:** every sentence must be a self-contained semantic triple with explicit context (subject + verb + object + attribution). **Proper noun density:** AI-cited text averages 20.6% proper nouns; name the organization, researcher, report, and year. **Content density sweet spot:** 5,000–20,000 characters — under 5,000 chars gets ~66% extracted; over 20,000 chars gets only 12%. Open every major section with a direct 40–60 word answer. + +### Content Strategy and E-E-A-T + +Match search intent before writing — study top-5 results to understand what format Google considers the best match (informational → guides; commercial investigation → comparisons; transactional → product pages). Google's Helpful Content System (integrated since March 2024) rewards content that solves problems genuinely; since June 2025, Google issues manual actions for scaled AI content abuse. Unedited AI drafts bounce 18% higher. Use AI in a human-led editorial process. Content with proper author metadata gets cited 40% more. E-E-A-T signals: original data, verified author bios with Person schema, specific citations with dates, third-party recognition. Every content page needs a visible author name, link to an author profile page with `@type: Person` schema, and a trust chain: Article → author `@id` → Person schema → `sameAs` external profiles. + +### Wikipedia and Wikidata + +Wikipedia accounts for 47.9% of ChatGPT's top-10 cited sources. Wikidata serves 11 million queries daily across 119 million entities; companies have gained Knowledge Panels within 7 days of creating a Wikidata entry. Add Wikidata Q-ID and Wikipedia URL to Organization schema `sameAs`. Build an entity web: organization → key tools → key people → related organizations → policy areas. Ensure structured data is consistent with Wikipedia — inconsistency reduces AI confidence. + +**Wikipedia COI (mandatory):** Never directly edit your own organization's Wikipedia article. Disclose affiliation on the Talk page. Propose edits through Talk-page requests or neutral editors. Use only independent, reliable sources. Follow Wikipedia's Conflict of Interest and Notability guidelines. + +### Structured Data (JSON-LD) + +Sites with structured data achieve 41% AI citation rates vs 15% without; only 12.4% of websites implement it. Implement JSON-LD in `` on every page: Organization + WebSite schema (every page); Article schema with `datePublished`, `dateModified`, author `@id` (every content page); FAQPage schema for Q&A sections; BreadcrumbList for navigation; Person schema for author pages. Always use `@id` to connect entities. Keep `dateModified` accurate and synchronized with the visible date. Validate at https://validator.schema.org/. + +### Meta Tags and Technical SEO + +Title: 50–60 chars, primary keyword first, unique per page. Meta description: 150–160 chars, direct factual answer + one statistic, never duplicated. Security headers required in 2026: HSTS, CSP, `X-Content-Type-Options`, `X-Frame-Options`. Require SSR or SSG — client-side-only rendering is a strategic error. Manage crawl budget: block low-value parameter URLs and internal search in robots.txt; fix redirect chains; return proper HTTP status codes (200/301/404/410). Use WebP/AVIF with `` element, `srcset`, explicit `width`/`height`, `loading="lazy"`. Descriptive file names. Keep page weight under 1MB. Supply chain: pin exact dependency versions, use `npm ci` in CI, scan with Socket.dev or Snyk. + +### Site Architecture and Internal Linking + +Hub-and-spoke topic cluster model increases AI citation rates from 12% to 41%; bidirectional links increase citation probability by 2.7×. Pillar page (2,000–4,000 words) + 8–15 cluster pages with bidirectional links. Max 3 levels deep; no important page more than 3 clicks from homepage. Breadcrumbs with BreadcrumbList schema. Use descriptive anchor text — never "read more". Audit for orphan pages. + +### Content Freshness + +76% of the most-cited AI content was updated within 30 days; Perplexity gives a 3.4× citation advantage to content updated within 30 days. Use visible `