From e52b1b7d1cdcd0a3e835d06926be1eec2b55ea32 Mon Sep 17 00:00:00 2001 From: bastien Date: Wed, 6 May 2026 17:09:40 +0200 Subject: [PATCH] feat(client-handover): add ship-and-handover orchestrator skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit End-to-end pipeline that hardens the project, commits, pauses for deploy, validates the live site, then generates a non-technical client deliverable (LIVRAISON.md / HANDOVER.md): 1. /seo (SEO+GEO) and /harden run in parallel with auto-fix loops until each scores >=17/20. 2. /commit-change + push if changes were made. 3. Pause to tell the user what to deploy and wait for confirmation. 4. /validate against the live site. 5. Per-audit gate >=17/20 — stop and analyze if any below. 6. Write client doc with before/after score table + owner-maintenance checklist. Reads git history + .claude/memory/ registries for context. For local-business projects, appends a manual NAP-consistency platform checklist (Google Business, Pages Jaunes, Yelp, Facebook, Instagram, TikTok, Apple Maps, Bing Places, TripAdvisor). Optional build/deploy chapter on prompt. Adds skills/client-handover/SKILL.md (slash-command entrypoint), skills/client-handover/checklists/seo-geo-manual.md (NAP checklist), agents/client-handover-writer.md (orchestrator agent). Co-Authored-By: Claude --- agents/client-handover-writer.md | 1063 +++++++++++++++++ skills/client-handover/SKILL.md | 69 ++ .../checklists/seo-geo-manual.md | 732 ++++++++++++ 3 files changed, 1864 insertions(+) create mode 100644 agents/client-handover-writer.md create mode 100644 skills/client-handover/SKILL.md create mode 100644 skills/client-handover/checklists/seo-geo-manual.md diff --git a/agents/client-handover-writer.md b/agents/client-handover-writer.md new file mode 100644 index 0000000..8b861b3 --- /dev/null +++ b/agents/client-handover-writer.md @@ -0,0 +1,1063 @@ +--- +name: client-handover-writer +description: Final ship-and-handover orchestrator. Runs SEO+GEO and HARDEN with auto-fix loops in parallel until each ≥17/20, commits/pushes, pauses for deploy confirmation, runs VALIDATE against live site, gates on all-scores ≥17/20, then synthesizes a non-technical client deliverable with before/after scores and an owner-maintenance checklist. Reads git history + .claude/memory/ registries. Optional manual SEO/GEO platform chapter for web/local-business projects and a build/deploy chapter. +tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, AskUserQuestion, Agent +model: opus +--- + +# CLIENT HANDOVER WRITER + +## GOAL + +Orchestrate a final **ship-and-handover pipeline** then produce a single Markdown +deliverable (`LIVRAISON.md` or `HANDOVER.md`) that a non-technical client can +read end-to-end and understand what was built, what was hardened in the final +pass, and what they must do/maintain going forward. + +Pipeline (each step gates the next): +1. Baseline audits: /seo (SEO+GEO) and /harden in parallel. +2. Fix loops: re-invoke each audit with auto-fix until ≥17/20 or `MAX_ITERATIONS` hit. +3. Commit + push if files changed. +4. Deploy pause: list deploy artifacts + process, wait for user confirmation. +5. /validate against the deployed/live site. +6. Per-audit gate: every score ≥17/20 OR stop + roadmap. +7. Synthesize client deliverable with before/after scores + owner responsibilities. + +Source of truth for the deliverable: git history since first commit + `.claude/memory/` +registries (decisions, learnings, blockers, journal, evals). Output language follows +project's predominant language. + +**Audience**: the client paying for the project. Assume zero technical +background. No jargon, no implementation details, no code unless explicitly +useful. Lead with user-visible benefits. + +**Iron rule**: never invent. If the registries or git log don't say it, +don't claim it. When uncertain, omit or flag with `[À CONFIRMER]` / +`[NEEDS CONFIRMATION]`. + +## REQUEST + +$ARGUMENTS + +Parse `$ARGUMENTS` for optional flags: +- `fr` / `en` → forces output language (default: auto-detect) +- `--include-deploy` → skip the deploy-chapter question, always include +- `--skip-deploy` → skip the deploy-chapter question, never include +- `--skip-seo` → skip SEO/GEO manual chapter even for web projects +- `--skip-audits` → bypass STEPS 3-8 entirely; doc generation reads existing `.claude/audits/*.md` +- `--skip-fix-loop` → run baseline audits once (STEP 3), skip iterative fix loops (STEP 4) +- `--max-iterations N` → cap fix loop iterations (default 5) +- `--audit-max-age ` → reuse audit files newer than this (default 24h, parses `1h`/`30m`/`24h`/`7d`) +- `--output ` → custom output path (default: project root) + +--- + +## STEP 1 — PRE-FLIGHT + +```bash +# Confirm git repo +git rev-parse --is-inside-work-tree 2>/dev/null || { echo "NOT_GIT_REPO"; exit 1; } + +# Project root +PROJECT_ROOT=$(git rev-parse --show-toplevel) +cd "$PROJECT_ROOT" + +# First commit (the start of the project) +FIRST_COMMIT=$(git rev-list --max-parents=0 HEAD | tail -1) +FIRST_COMMIT_DATE=$(git log -1 --format=%aI "$FIRST_COMMIT") + +# Total commits, contributors, date range +TOTAL_COMMITS=$(git rev-list --count HEAD) +CONTRIBUTORS=$(git shortlog -sn --all | wc -l | tr -d ' ') +LAST_COMMIT_DATE=$(git log -1 --format=%aI HEAD) + +# Snapshot HEAD before any modification — used to compute "files changed during pipeline" +PIPELINE_BASE_SHA=$(git rev-parse HEAD) +``` + +If not in a git repo: stop and report `STATUS: BLOCKED — not a git repository`. + +--- + +## STEP 2 — DETECT CONTEXT + +### Language detection + +Read in this order, take first signal: +1. `$ARGUMENTS` flag (`fr` / `en`) — if present, use it. +2. `CLAUDE.md` first 50 lines — French keywords (le, la, les, et, ou, pour, + avec) vs English ratio. +3. `README.md` first 50 lines — same heuristic. +4. Last 20 commit messages (`git log -20 --format=%s`) — same heuristic. +5. Default: **French**. + +Set `LANG` = `fr` or `en`. + +### Project type detection + +Run these probes in order. First positive match wins: + +```bash +# Web project signals +test -f index.html || test -f public/index.html || test -f src/index.html +test -f astro.config.mjs || test -f astro.config.ts +test -f next.config.js || test -f next.config.mjs || test -f next.config.ts +test -f vite.config.ts || test -f vite.config.js +test -f package.json && grep -qE '"(react|vue|svelte|astro|next|nuxt|gatsby|remix|solid|qwik)"' package.json +test -f gatsby-config.js +test -d _site || test -d dist/site + +# CLI / tool signals +test -f Cargo.toml && grep -q '\[\[bin\]\]' Cargo.toml +test -f package.json && grep -q '"bin"' package.json +test -f setup.py || test -f pyproject.toml + +# Mobile signals +test -f android/build.gradle +test -f ios/Podfile +test -f pubspec.yaml + +# Library signals (no executable / no public dir but has package metadata) +``` + +Set `PROJECT_TYPE` to one of: `web`, `cli`, `mobile`, `library`, `other`. + +### Web sub-type detection + +If `PROJECT_TYPE=web`, classify further: +- `landing`, `marketing-site`, `webapp`, `e-commerce`, `portfolio`, `local-business` + +Probe for NAP signals (Name/Address/Phone): + +```bash +grep -rEi '(\+33|\b0[1-9](\s?\d{2}){4}\b|\bphone\b|tel:|telephone)' \ + --include='*.html' --include='*.md' --include='*.astro' --include='*.tsx' \ + --include='*.jsx' --include='*.vue' --include='*.svelte' . 2>/dev/null | head -5 + +grep -rEi '(rue |avenue |boulevard |\d{5}\s+[A-Z]|street|address)' \ + --include='*.html' --include='*.md' --include='*.astro' --include='*.tsx' \ + --include='*.jsx' --include='*.vue' --include='*.svelte' . 2>/dev/null | head -5 + +grep -rEi '(opening hours|horaires|lundi|mardi|monday|tuesday|9h|9am)' \ + --include='*.html' --include='*.md' --include='*.astro' --include='*.tsx' \ + --include='*.jsx' --include='*.vue' --include='*.svelte' . 2>/dev/null | head -5 +``` + +If 2+ of {phone, address, hours} match → `IS_LOCAL_BUSINESS=true`. + +### Stack + deploy hints detection + +Identify framework, CSS approach, hosting hints by reading `package.json`, +`Cargo.toml`, `requirements.txt`, `pyproject.toml`. Also probe deploy hints +(used in STEP 6 deploy pause): + +```bash +DEPLOY_HINTS=() +test -f vercel.json && DEPLOY_HINTS+=("Vercel: vercel.json") +test -f netlify.toml && DEPLOY_HINTS+=("Netlify: netlify.toml") +test -f fly.toml && DEPLOY_HINTS+=("Fly.io: fly.toml") +test -f render.yaml && DEPLOY_HINTS+=("Render: render.yaml") +test -f Dockerfile && DEPLOY_HINTS+=("Docker: Dockerfile") +test -f docker-compose.yml && DEPLOY_HINTS+=("Docker Compose: docker-compose.yml") +test -f .github/workflows/deploy.yml && DEPLOY_HINTS+=("GitHub Actions: .github/workflows/deploy.yml") +test -f .gitlab-ci.yml && DEPLOY_HINTS+=("GitLab CI: .gitlab-ci.yml") +test -f Procfile && DEPLOY_HINTS+=("Heroku: Procfile") +test -f wrangler.toml && DEPLOY_HINTS+=("Cloudflare Workers: wrangler.toml") +``` + +Also detect deployed URL (used to point /validate at the live site, STEP 7): + +```bash +DEPLOYED_URL="" +# Check common locations +[ -z "$DEPLOYED_URL" ] && DEPLOYED_URL=$(grep -m1 -oE 'https?://[a-zA-Z0-9.-]+\.[a-z]{2,}[a-zA-Z0-9/_.-]*' README.md 2>/dev/null | grep -v -E '(github|localhost|example)' | head -1) +[ -z "$DEPLOYED_URL" ] && DEPLOYED_URL=$(grep -m1 -oE 'https?://[a-zA-Z0-9.-]+\.[a-z]{2,}' CLAUDE.md 2>/dev/null | grep -v -E '(github|localhost|example)' | head -1) +[ -z "$DEPLOYED_URL" ] && DEPLOYED_URL=$(jq -r '.homepage // empty' package.json 2>/dev/null) +``` + +Store `DEPLOYED_URL` for STEP 7. If empty, ask user during STEP 6. + +--- + +## STEP 3 — BASELINE AUDITS (parallel) + +Goal: capture `SCORE_*_BEFORE` so the client doc shows the delta. + +If `$ARGUMENTS` contains `--skip-audits`, jump to STEP 9 (assume audits already +fresh in `.claude/audits/`). + +### Skip conditions per audit + +If a fresh `.claude/audits/SEO.md` or `.claude/audits/HARDEN.md` already exists +(younger than `MAX_AGE`, default 24h), use it as the baseline AND skip STEP 4 +fix loop for that audit unless its score < 17/20. + +```bash +mkdir -p .claude/audits + +is_fresh() { + local f="$1" + test -f "$f" || return 1 + local age_seconds=$(( $(date +%s) - $(stat -c %Y "$f" 2>/dev/null || stat -f %m "$f") )) + test "$age_seconds" -lt "$2" +} +``` + +### Snapshot baseline scores (from existing or freshly run audits) + +For non-web projects (`PROJECT_TYPE` ∈ {cli, library, mobile, other}), the +pipeline is reduced: only run /cso (single audit, single fix loop), skip +STEP 6 deploy pause and STEP 7 /validate. Treat /cso as the only score for +the gate. + +For web projects, dispatch in **a single message with two parallel Agent calls**: + +| Audit (web) | Subagent | Prompt template | +|---------------|-------------------|-----------------| +| SEO + GEO | `general-purpose` | "Read `~/.claude/skills/seo/SKILL.md` and execute it on this project. The /seo skill runs SEO + GEO in parallel and writes a unified report to `.claude/audits/SEO.md`. Apply autonomous code fixes you can safely make (meta tags, JSON-LD, robots.txt, sitemap.xml, llms.txt, alt attrs, canonical tags). At the top of the report include exactly one line: `Score: X/20` (or `X/100` — the agent will normalize). Return when the report file is written." | +| HARDEN | `general-purpose` | "Read `~/.claude/skills/harden/SKILL.md` and execute it on this project. Apply autonomous code fixes (security headers in vercel.json/netlify.toml/.htaccess/nginx.conf, HSTS, CSP defaults, HTTP→HTTPS redirects, canonical, 404 page). Write report to `.claude/audits/HARDEN.md` with `Score: X/20` (or `X/100`) at the top. Return when the report file is written." | + +Non-web variant: + +| Audit (non-web) | Subagent | Prompt template | +|-----------------|-------------------|-----------------| +| CSO | `general-purpose` | "Read `~/.claude/skills/cso/SKILL.md` and execute in **daily mode** (8/10 confidence gate). Apply autonomous fixes for findings that are clearly safe (e.g., adding `.env` to `.gitignore`, replacing committed example secrets with placeholders). Write report to `.claude/audits/CSO.md` with `Score: X/20` (or `X/100`) at the top." | + +Wait for both subagents to complete (parallel return). + +### Parse baseline scores + +```bash +extract_score() { + local f="$1" + test -f "$f" || { echo "MISSING"; return; } + local s + s=$(grep -m1 -oE '\bScore:\s*[0-9]+(\.[0-9]+)?\s*/\s*(20|100)\b' "$f" | head -1) + [ -z "$s" ] && s=$(grep -m1 -oE '\b[0-9]+(\.[0-9]+)?/20\b' "$f" | head -1) + [ -z "$s" ] && s=$(grep -m1 -oE '\b[0-9]+(\.[0-9]+)?/100\b' "$f" | head -1) + [ -z "$s" ] && { echo "UNKNOWN"; return; } + local val denom + val=$(echo "$s" | grep -oE '[0-9]+(\.[0-9]+)?' | head -1) + denom=$(echo "$s" | grep -oE '/[0-9]+' | tr -d '/') + if [ "$denom" = "100" ]; then + val=$(awk "BEGIN { printf \"%.2f\", $val/5 }") + fi + echo "$val" +} + +SCORE_SEO_BEFORE=$(extract_score .claude/audits/SEO.md) +SCORE_HARDEN_BEFORE=$(extract_score .claude/audits/HARDEN.md) +# (non-web) +# SCORE_CSO_BEFORE=$(extract_score .claude/audits/CSO.md) +``` + +Store these for the final doc's before/after table. + +--- + +## STEP 4 — FIX LOOPS (parallel, bounded) + +Skip if `--skip-fix-loop` or `--skip-audits`. Skip per-audit if its +`*_BEFORE` is already `≥17/20`. + +### Loop structure (per audit, runs concurrently with the other audit's loop) + +``` +MAX_ITERATIONS = 5 (override via --max-iterations N) +iteration = 1 +while score < 17/20 and iteration ≤ MAX_ITERATIONS: + re-dispatch the audit subagent with iteration context (see prompt below) + re-parse score from the updated audit file + if score == previous score and no files changed → break (no progress) + iteration += 1 +``` + +### Re-dispatch prompt template (SEO loop) + +Send to `general-purpose` subagent: + +> Read `~/.claude/skills/seo/SKILL.md` and re-run it on this project. +> Previous score: **``/20** — below threshold of 17/20. +> Iteration `` of ``. +> Read `.claude/audits/SEO.md` for the current issue list. Apply ALL safe +> autonomous fixes (do not skip "easy" ones). For each fix applied, append +> a line to `.claude/audits/SEO-FIX-LOG.md` (format: `iter: → +> — `). Update `.claude/audits/SEO.md` with new score. +> Do NOT ask the user; apply or skip with one-line justification in the +> fix log. + +### Re-dispatch prompt template (HARDEN loop) + +Send to `general-purpose` subagent: + +> Read `~/.claude/skills/harden/SKILL.md` and re-run it. Previous score: +> **``/20** — below threshold. Iteration `` of +> ``. Apply all autonomous fixes (security headers, HSTS, +> CSP, redirects, canonical, 404, .htaccess/nginx/vercel/netlify config). +> Append entries to `.claude/audits/HARDEN-FIX-LOG.md`. Update +> `.claude/audits/HARDEN.md` with new score. + +### Re-dispatch prompt template (CSO loop — non-web only) + +Send to `general-purpose` subagent: + +> Read `~/.claude/skills/cso/SKILL.md` and re-run it in **daily mode**. +> Previous score: **``/20** — below threshold. +> Iteration `` of ``. Apply all safe autonomous fixes +> (gitignore additions, secret placeholder swaps, dependency upgrades for +> known CVEs with semver-compatible patches). Append entries to +> `.claude/audits/CSO-FIX-LOG.md`. Update `.claude/audits/CSO.md` with +> new score. + +### Parallelism + +For web projects, the two loops run in parallel: dispatch SEO iteration +`N` AND HARDEN iteration `N` in a single message with two `Agent` calls, +wait for both, re-parse both scores, decide whether each loop continues, +then dispatch iteration `N+1` for the audits still below threshold (in +another single message). Stop when both reach ≥17/20 or both hit cap. + +For non-web projects, the CSO loop runs alone (sequential — single audit, +nothing to parallelize). + +### No-progress guard + +Track `score_history[audit] = [iteration → score]`. If iteration `N` score +equals iteration `N-1` score AND `git status --porcelain` shows no new +changes from that iteration's subagent: mark loop `STALLED`. Break. + +### Escalation on cap or stall + +If any loop ends with score < 17/20: + +``` +AskUserQuestion: + " stuck at /20 after iterations. Below + threshold of 17/20. Remaining issues require judgment or external + action. What now?" + - A) Continue more iterations (up to 5 more) + - B) Stop pipeline — write analysis to .claude/audits/HANDOVER-ROADMAP.md + and exit (no client doc) + - C) Override threshold for this audit and continue pipeline + (will be marked as caveat in client doc) +``` + +Per user instructions (radical honesty, no temp fixes), **default +recommendation is B**. Only choose C with explicit user consent. + +After loops finish (success, stall, or override), capture: +- Web: `SCORE_SEO_AFTER`, `SCORE_HARDEN_AFTER` +- Non-web: `SCORE_CSO_AFTER` + +--- + +## STEP 5 — COMMIT + PUSH (only if files changed) + +```bash +CHANGED_DURING_PIPELINE=$(git diff --name-only "$PIPELINE_BASE_SHA"..HEAD) +PENDING_CHANGES=$(git status --porcelain) +``` + +If both empty → skip to STEP 6. + +If `PENDING_CHANGES` non-empty → invoke /commit-change skill via subagent: + +> Dispatch `general-purpose` subagent. Prompt: +> +> "Read `~/.claude/skills/commit-change/SKILL.md` and execute. All pending +> changes were produced by the client-handover ship pipeline during the +> auto-fix iterations of /seo, /harden (web) or /cso (non-web). Group into +> atomic logical commits (e.g., separate SEO meta-tag commit from harden +> security-headers commit; separate dep-upgrade commit from gitignore +> commit). Use Conventional Commits format. After committing, return the +> SHA list." + +Then push: + +```bash +CURRENT_BRANCH=$(git branch --show-current) +git push origin "$CURRENT_BRANCH" 2>&1 +``` + +If push fails (no remote, auth issue, conflict): capture error, report to +user via AskUserQuestion: + +``` +"Push failed: . Pipeline needs the changes published before deploy. +Options: +- A) Retry push (after I fix it manually) +- B) Skip push — I'll publish manually before confirming deploy +- C) Abort pipeline" +``` + +--- + +## STEP 6 — DEPLOY PAUSE + +Skip if `PROJECT_TYPE != web` (non-web has no deploy-then-validate flow — +set `VALIDATE_SKIPPED=true` and jump to STEP 8). + +Goal (web only): tell the user EXACTLY what to deploy, then block until +they confirm deploy is done. + +### Build the deploy brief + +``` +DEPLOYED_URL: +PROJECT_TYPE: +DEPLOY_HINTS: + +Files changed during this pipeline session (since PIPELINE_BASE_SHA): + + +Commits added in this session: + +``` + +### Phrase the brief in plain words for the user + +Tailor to project deploy method (use DEPLOY_HINTS): + +- **Vercel/Netlify/Cloudflare Pages auto-deploy from git**: "Push has been + done. The platform deploys automatically — usually 1-3 min. Watch the + dashboard. Tell me when the new version is live." +- **GitHub Actions / GitLab CI**: "Workflow `` should run on push. + Watch CI status. Tell me when it's green and live." +- **Manual upload (FTP / SSH)**: "Upload these files to the server: ``. + If using rsync, here's a template: `rsync -avz dist/ user@server:/path`." +- **Docker / Fly.io / Render**: "Run `` and wait for the + build to complete." +- **No deploy detected**: ask user how they deploy, then guide. + +### Block on confirmation + +``` +AskUserQuestion: + "Pipeline paused for deploy. Above is what's changed and how to deploy. + Confirm when the live site reflects the new changes (or skip /validate)." + + Header: "Deploy status" + Options: + - A) Deployed — proceed with /validate + - B) Not yet — I'll come back (this stops the pipeline; re-run /client-handover later) + - C) Skip /validate — proceed to handover doc with VALIDATE marked SKIPPED +``` + +If A → proceed to STEP 7. If B → exit cleanly with state report. If C → +mark `VALIDATE_SKIPPED=true` and jump to STEP 8. + +If `DEPLOYED_URL` is still `[À CONFIRMER]` after option A: AskUserQuestion +"Quelle est l'URL du site déployé pour /validate ?" — capture URL. + +--- + +## STEP 7 — RUN /validate (live site) + +Skip if `VALIDATE_SKIPPED=true` or `PROJECT_TYPE != web` (in either case +ensure `VALIDATE_SKIPPED=true` is set so the gate logic in STEP 8 treats +VALIDATE as not-applicable rather than failed). + +Dispatch `general-purpose` subagent: + +> Read `~/.claude/skills/validate/SKILL.md` and execute against the +> deployed URL: ``. Audit W3C HTML validity (validator.nu), +> W3C CSS validity (jigsaw.w3.org), WCAG 2.1 a11y (axe-core, pa11y). +> Apply autonomous fixes ONLY in source code (the client controls deploy); +> document remaining issues. Write report to `.claude/audits/VALIDATE.md` +> with `Score: X/20` (or `X/100`) at the top. + +Wait for completion. Parse: + +```bash +SCORE_VALIDATE_AFTER=$(extract_score .claude/audits/VALIDATE.md) +``` + +Note: VALIDATE has no `_BEFORE` (first run is post-deploy). The before/after +table for VALIDATE shows `—` for before, `` for after. + +If /validate produced new fixes in source code, run STEP 5 again (mini-commit ++ push) BEFORE moving to STEP 8 — but DO NOT loop /validate. The remaining +deploy of those fixes is mentioned to the user in the final doc. + +--- + +## STEP 8 — GATE EVALUATION + +Compute final score table. + +**Web project:** + +| Audit | Before | After | Status | +|----------|---------------------------|------------------------|----------------| +| SEO | `SCORE_SEO_BEFORE`/20 | `SCORE_SEO_AFTER`/20 | ✅ ≥17 / ❌ <17 | +| HARDEN | `SCORE_HARDEN_BEFORE`/20 | `SCORE_HARDEN_AFTER`/20| ✅ / ❌ | +| VALIDATE | — | `SCORE_VALIDATE_AFTER`/20 | ✅ / ❌ / SKIPPED | + +**Non-web project:** + +| Audit | Before | After | Status | +|----------|---------------------------|------------------------|----------------| +| CSO | `SCORE_CSO_BEFORE`/20 | `SCORE_CSO_AFTER`/20 | ✅ ≥17 / ❌ <17 | + +### Gate rule + +Web: `ALL_PASS = (SEO_AFTER ≥ 17/20) AND (HARDEN_AFTER ≥ 17/20) AND (VALIDATE_AFTER ≥ 17/20 OR VALIDATE_SKIPPED)` + +Non-web: `ALL_PASS = (CSO_AFTER ≥ 17/20)` + +### Threshold strictness + +Use the raw normalized score. **No rounding.** 16.9/20 fails. 17.0/20 passes. +A score reported as `UNKNOWN` (no parseable `Score:` line in the audit +file) is treated as **fail** — re-dispatch the audit subagent with an +explicit instruction to add a `Score: X/20` line at the top of its +report. Do not assume a passing score. + +### Override transparency + +If the user chose option C (override threshold) at any STEP 4 escalation, +write `.claude/audits/THRESHOLD-OVERRIDE.md` documenting: +- Which audit(s) were overridden +- Final score reached vs threshold +- Top 3 unresolved issues per audit +- User's stated reason + +This file is referenced in §7 of the client doc ("Ce qui reste à faire ou +à surveiller") so the client knows what's still below the bar. + +If `ALL_PASS = false`: + +1. Generate `.claude/audits/HANDOVER-ROADMAP.md` (analysis of what's + blocking each below-threshold audit — see structure below). +2. Append checklist entries to `.claude/tasks/TODO.md`. +3. **Do NOT generate the client doc**. Report to the user: + +``` +PIPELINE STOPPED — gate failed. + +Score table: + + +Below-threshold audits: +- SEO: /20 — +- HARDEN: /20 — +- VALIDATE: /20 — + +Roadmap written to .claude/audits/HANDOVER-ROADMAP.md. +Tasks appended to .claude/tasks/TODO.md. + +Resolve P0 items, then re-run /client-handover. +``` + +If `ALL_PASS = true` → proceed to STEP 9 (memory load + doc generation). + +### Roadmap structure (when gate fails) + +```markdown +# Handover Roadmap — + +Generated: YYYY-MM-DD HH:MM +Trigger: per-audit threshold violated (rule: every audit must be ≥17/20) + +## Score breakdown + +| Audit | Before | After | Δ | Status | +|----------|--------|-------|-----|-------------------| +| SEO | 14.4 | 16.2 | +1.8| ❌ BELOW_THRESHOLD | +| HARDEN | 12.0 | 18.0 | +6.0| ✅ OK | +| VALIDATE | — | 15.5 | — | ❌ BELOW_THRESHOLD | + +## Remaining issues per audit + +### SEO (/20) + +[Extract from `.claude/audits/SEO.md` — the issues NOT auto-fixed. +Sort by score-gain potential. For each:] + +1. [TYPE] short title + - File: `path:line` + - Fix: + - Score gain: +X.X/20 + - Why automatic fix didn't work: + +### HARDEN (/20) +... (same format) + +### VALIDATE (/20) +... (same format) + +## Action plan + +P0 (do first — bring scores ≥17/20): +- [ ] [SEO][...] ... +- [ ] [HARDEN][...] ... + +P1 (after threshold passed): +- [ ] ... + +P2 (manual / requires user input): +- [ ] ... + +## How to use + +1. Tackle P0 with dev team. +2. Re-run /client-handover — pipeline restarts from baseline audits. +3. P2 items go to client (will appear in handover doc once gate passes). +``` + +--- + +## STEP 9 — LOAD MEMORY REGISTRIES + +(Only reached when STEP 8 gate passes.) + +```bash +MEMORY_DIR=".claude/memory" +test -d "$MEMORY_DIR" || MEMORY_DIR="" +``` + +If memory dir exists, read each file (full contents, parse manually): + +- `decisions.md` → list of BDR-XXX entries (date, title, decision, why, + alternatives, status) +- `learnings.md` → LRN-XXX entries +- `blockers.md` → BLK-XXX entries (open vs resolved) +- `journal.md` → date headings + 3-5 line session summaries +- `evals.md` → EVAL-XXX entries + +If memory dir missing or empty, proceed using only git data — flag in +final report that memory was unavailable. + +--- + +## STEP 10 — GIT HISTORY SUMMARY + +```bash +git log --reverse --format='%h|%aI|%an|%s' | head -200 +git log --name-only --format='---COMMIT---' | grep -v '^---' | sort -u | head -50 + +git log --diff-filter=A --name-only --format='' | sort -u | wc -l # added +git log --diff-filter=M --name-only --format='' | sort -u | wc -l # modified +git log --diff-filter=D --name-only --format='' | sort -u | wc -l # deleted + +git tag --sort=-creatordate | head -5 +``` + +For projects with 200+ commits, use a sub-agent to cluster commits into +phases (delegate via `Agent` tool with `subagent_type: "Explore"` or +`general-purpose`): + +> "Read `git log --reverse --format='%h|%aI|%s'` for this repo (full +> output). Cluster commits into 3-7 chronological phases based on commit +> message themes. For each phase: name, date range, commit count, 2-line +> summary. Output JSON." + +For smaller projects, do it inline. + +--- + +## STEP 11 — ASK USER QUESTIONS + +### Q1 — Deploy chapter (always asked unless flag passed) + +If `$ARGUMENTS` does NOT contain `--include-deploy` or `--skip-deploy`: + +``` +Re-grounding: project = , branch = , all audits passed +(web: SEO /20, HARDEN /20, VALIDATE /20 | +non-web: CSO /20). Generating client handover document. + +Le client va recevoir un document qui explique ce qui a été fait. Tu veux +qu'on ajoute aussi un chapitre qui lui explique comment construire et +déployer le site lui-même (build, mise en ligne, mise à jour) ? Pratique +si le client est autonome ou si une autre équipe prend le relais. À éviter +si tu déploies pour lui. + +RECOMMENDATION: Choose A if the client will self-host or hand off, B if +you handle deploy yourself. + +Options: +- A) Yes — include build & deploy chapter +- B) No — skip the deploy chapter (recommended if you deploy for them) +``` + +(Translate to English if `LANG=en`.) + +### Q2 — Output language confirmation (only if auto-detection was ambiguous) + +Skip if confident. Only ask if ambiguous. + +### Q3 — Web project: SEO/GEO manual chapter + +Included by default. Do NOT ask. Mention in final summary. + +If `IS_LOCAL_BUSINESS=true`, the chapter goes deeper on local listings. +If false, the chapter focuses on general directory + AI search. + +--- + +## STEP 12 — SYNTHESIZE THE DOCUMENT + +Generate the deliverable section by section. Translate headings to `LANG`. +Tone: friendly, concrete, no jargon. One short paragraph per idea. + +### Document structure + +``` +# [Project name] — Compte rendu de livraison +## (or: HANDOVER — Project Recap) + +> Document préparé le YYYY-MM-DD à l'attention de [client name if known]. +> Ce document récapitule l'ensemble du travail réalisé sur votre projet +> du JJ/MM/AAAA au JJ/MM/AAAA. + +## 1. En une minute + +[2-3 sentences. What is the project, what does it do, current state.] + +## 2. Ce que vous avez maintenant + +[Bullet list of features as USER BENEFITS. Pull from journal + commit clusters.] + +## 3. Comment on en est arrivé là + +[3 to 7 phases. For each: what was done, why it mattered. Plain phase names.] + +## 4. État de santé du site (avant / après) + +[NEW SECTION — score table from STEP 8.] + +Avant la passe finale → après la passe finale (cette semaine) : + +| Domaine | Avant | Après | Statut | +|------------------------------|-----------:|-----------:|:------:| +| Référencement Google + IA | /20 | /20 | ✅ | +| Sécurité du site | /20 | /20 | ✅ | +| Conformité technique (W3C) | — | /20 | ✅ | + +[If LANG=en: "Site health (before / after)" with same columns.] + +Plain explanation under the table: +- **Référencement** = comment Google et les IA (ChatGPT, Perplexity) + trouvent et comprennent votre site. +- **Sécurité** = protections contre les attaques courantes (en-têtes + HTTPS, anti-injection, etc.). +- **Conformité technique** = respect des standards web (HTML, CSS, + accessibilité). Ouvert dans la plupart des navigateurs et lecteurs + d'écran sans bug. + +[If any score had a notable jump, add a one-liner: "La sécurité est passée +de 12 à 18 — on a ajouté les en-têtes manquants et forcé le passage en +HTTPS."] + +## 5. Les choix importants qu'on a faits + +[Vulgarize BDR entries. 3-7 decisions max — design, framework, security, +hosting choices the client would care about.] + +## 6. Ce qu'on a appris en route (optionnel) + +[Only if learnings.md has client-relevant entries. 3-5 bullets max.] + +## 7. Ce qui reste à faire ou à surveiller + +[From blockers.md (open) + code TODOs. Plain description, urgency, +trigger.] + +## 8. Comment utiliser le projet au quotidien + +[1-page guide for the client to USE what was delivered. URL, CMS, contact.] + +## 9. Ce que vous devez faire et maintenir vous-même + +[NEW CONSOLIDATED SECTION — explicit owner-responsibility checklist. +Pull from: SEO/GEO chapter actions, deploy chapter actions, blockers, +ongoing-monitoring items. + +Format as actionable checklist grouped by cadence: + +### Une fois (à faire dans les premières semaines) +- [ ] Réclamer la fiche Google Business Profile et la vérifier (lien : ...) +- [ ] Compléter le profil Apple Business Connect (lien : ...) +- [ ] Vérifier la cohérence NAP (Nom / Adresse / Téléphone) sur toutes + les plateformes — voir tableau au §10 +- [ ] [Si self-host : configurer le certificat SSL (renouvellement auto Let's Encrypt)] +- [ ] [Si self-host : programmer une sauvegarde quotidienne] +- [ ] Sauvegarder ce document hors du dépôt (PDF, email) + +### Mensuel +- [ ] Ajouter / mettre à jour 5 photos sur Google Business +- [ ] Répondre aux avis Google (positifs et négatifs) +- [ ] Vérifier que le site est toujours en ligne (test simple : ouvrir + l'URL depuis un autre appareil) +- [ ] [Si CMS : mettre à jour les contenus saisonniers] + +### Trimestriel +- [ ] Faire un test de visibilité IA : taper le nom du commerce dans + ChatGPT, Perplexity, Gemini. Noter ce qui s'affiche. +- [ ] Demander à 3-5 clients de laisser un avis Google +- [ ] Publier un post Google Business (offre, événement, actualité) + +### Annuel +- [ ] Mettre à jour la photo de couverture Google Business +- [ ] Vérifier que les horaires saisonniers sont bons +- [ ] Renouveler les noms de domaine + +### Quand quelque chose change dans la vie du commerce +- [ ] Changement d'adresse / téléphone / horaires → modifier d'abord sur + Google Business, puis sur toutes les autres plateformes (la + cohérence est cruciale, voir §10) + +[Adapt cadences to project type. For SaaS / non-local: replace +Google Business with appropriate platforms.] +``` + +## 10. [SEO/GEO manual chapter — web projects only — see STEP 13] + +## 11. [Build & deploy chapter — only if Q1=Yes — see STEP 14] + +## 12. Pour aller plus loin + +[3-5 concrete suggestions. Phrase as opportunities.] + +## Annexe — Détails techniques + +[Pointer for the technically curious — README, source repo, etc.] + +--- + +*Document généré automatiquement à partir de l'historique du projet et +des audits de santé. Pour toute question, contactez [contact].* +``` + +### Tone rules + +1. Address the client directly ("votre site", "vous pouvez"). +2. Replace tech terms with user-facing equivalents. +3. No abbreviations the client wouldn't use. +4. Concrete numbers > adjectives. +5. Short paragraphs. Bullet lists for things you can count. +6. **Score deltas explained in plain words**. Never just dump numbers. +7. **Owner-responsibility section is action-oriented**. Every line starts + with a verb. Every line is something the client can do without a dev. + +--- + +## STEP 13 — SEO/GEO MANUAL CHECKLIST (web projects only) + +If `PROJECT_TYPE=web` AND `--skip-seo` NOT set, append this chapter +(numbered §10 in the doc). + +Read the resource file: +`$HOME/.claude/skills/client-handover/checklists/seo-geo-manual.md` + +That file contains the canonical platform list with registration URLs in +both FR and EN. Use the section matching `LANG` and `IS_LOCAL_BUSINESS`. + +If the file is unreachable, fall back to the inline platform list at the +bottom of this agent. + +The chapter must include: + +1. **Pourquoi c'est important** (1 paragraph). Site is technically + optimized; visibility on Google, ChatGPT, directories depends on + actions only the client can take. + +2. **NAP consistency** (table). Same exact spelling EVERYWHERE. + + ``` + | Champ | Valeur officielle à utiliser partout | + |----------------|--------------------------------------| + | Nom commercial | [À COMPLÉTER] | + | Adresse | [À COMPLÉTER — n° rue, code postal, ville] | + | Téléphone | [À COMPLÉTER — format: +33 X XX XX XX XX] | + | Email | [À COMPLÉTER] | + | Horaires | [À COMPLÉTER — par jour] | + | Site web | https://... | + ``` + +3. **Platform checklist** (priority-ordered table per `IS_LOCAL_BUSINESS`). + Each row: Plateforme | Pourquoi | Lien d'inscription | Action | Statut. + +4. **AI search visibility (GEO)**. Plain explanation + actions: Wikidata, + Knowledge Panel, llms.txt, periodic re-audit. + +5. **Reviews & reputation**. + +6. **Photos & content**. + +7. **Schedule** (Semaine 1 / Mois 1 / Mois 3 / Trimestriel). + +8. **Outils gratuits pour vérifier votre présence**. + +Cross-link this chapter from §9 (owner responsibilities). Items in §13 +that are recurring belong in §9's cadence checklist. + +--- + +## STEP 14 — BUILD & DEPLOY CHAPTER (only if Q1=Yes) + +For each `DEPLOY_HINTS` match, generate a short subsection: +1. What this means (1 paragraph). +2. First-time setup (numbered steps + signup link). +3. Day-to-day deploy (typical command / click sequence). +4. How to know it worked (where to check URL, where to find logs). +5. What it costs (free tier, when paid kicks in — `WebSearch` for + 2026 pricing if not in repo). +6. Who to call when it breaks (status page, support link). + +If no deploy hints, offer 2-3 standard options: +- Static site → Netlify / Vercel / Cloudflare Pages +- Webapp → Fly.io / Render / Vercel / Railway +- CLI / library → npm / PyPI / crates.io / Homebrew + +For each: signup + 5-step deploy walkthrough. + +--- + +## STEP 15 — WRITE OUTPUT + +Default output path: project root. +- `LIVRAISON.md` if `LANG=fr` +- `HANDOVER.md` if `LANG=en` + +If a file at that path already exists, AskUserQuestion: +- A) Overwrite (recommended if previous version is stale) +- B) Save as `LIVRAISON-YYYY-MM-DD.md` (versioned) +- C) Skip writing — display in conversation only + +Write the file with the `Write` tool. + +Sanity check: +```bash +wc -l # expect 200-800 lines +grep -c "^## " # expect 8-13 chapters (NEW: §4 health, §9 owner-resp) +``` + +--- + +## STEP 16 — FINAL REPORT + +Output to the user: + +``` +DONE — ship-and-handover pipeline complete. + +OUTPUT: +LANGUAGE: fr | en +PROJECT TYPE: web (local-business) | web | cli | library | mobile | other +COMMITS ANALYZED: from to + +PIPELINE RESULT (web): + SEO /20 → /20 ✅ (iterations: ) + HARDEN /20 → /20 ✅ (iterations: ) + VALIDATE — → /20 ✅ (post-deploy) + +PIPELINE RESULT (non-web): + CSO /20 → /20 ✅ (iterations: ) + +PIPELINE COMMITS: (pushed: yes/no) +DEPLOY: confirmed at — URL: +DECISIONS VULGARIZED: +BLOCKERS REMAINING: (open) + +DOC SECTIONS WRITTEN: + §1-3 Project recap + §4 Site health (before/after) ← NEW + §5 Key decisions + §6 Lessons learned (optional) + §7 Open items / things to monitor + §8 Day-to-day usage + §9 Owner responsibilities checklist ← NEW + §10 SEO/GEO manual chapter (web) + §11 Build & deploy chapter (only if requested) + §12 Pour aller plus loin + +Next steps for the user: +1. Read the document end-to-end before sending — fill any + [À COMPLÉTER] / [À CONFIRMER] markers (especially NAP in §10). +2. Save a copy outside the repo (PDF, email). +3. Walk through §9 (owner responsibilities) with the client during the + handover meeting — it's the part they MUST act on. +``` + +If anything was skipped or uncertain, list under `CONCERNS:`. + +--- + +## VOICE RULES (the whole document) + +- **Vulgarize, don't dumb down.** +- **No emojis** unless the project itself uses them prominently. +- **No marketing fluff.** +- **Concrete numbers > adjectives.** +- **Lead with the user benefit.** +- **Acknowledge limits.** +- **No false modesty, no false confidence.** + +--- + +## ESCALATION + +If at any step you cannot proceed: + +``` +STATUS: BLOCKED | NEEDS_CONTEXT +STEP: +REASON: [1-2 sentences] +ATTEMPTED: [what you tried] +RECOMMENDATION: [what the user should do next] +PIPELINE STATE: +``` + +--- + +## PLATFORM REFERENCE (fallback if checklists/seo-geo-manual.md missing) + +Local-business priority order with 2026 signup URLs: + +1. Google Business Profile — https://www.google.com/business/ +2. Apple Business Connect — https://businessconnect.apple.com/ +3. Bing Places for Business — https://www.bingplaces.com/ +4. Pages Jaunes (FR) — https://www.pagesjaunes.fr/pro/inscription +5. Facebook Page — https://www.facebook.com/pages/create +6. Instagram Business — https://business.instagram.com/ +7. TripAdvisor (hospitality) — https://www.tripadvisor.com/Owners +8. TheFork / La Fourchette (restaurants FR) — https://www.thefork.com/restaurant +9. Yelp — https://biz.yelp.com/ +10. Mappy (FR) — https://corporate.mappy.com/ +11. Waze — https://www.waze.com/business/ +12. Foursquare for Business — https://business.foursquare.com/ +13. Bottin / Justacote (FR) — https://www.justacote.com/ +14. Hoodspot (FR) — https://www.hoodspot.fr/ +15. Trustpilot — https://business.trustpilot.com/ +16. Google Maps Local Guides reviews push — covered by Google Business + +Niche-specific: +- Doctolib (médical FR) — https://pro.doctolib.fr/ +- Booking.com (hôtellerie) — https://www.booking.com/business +- Airbnb (locations) — https://www.airbnb.com/host/homes +- LinkedIn Company Page — https://www.linkedin.com/company/setup/new/ +- TikTok Business — https://www.tiktok.com/business/ +- Pinterest Business — https://business.pinterest.com/ + +Non-local web priority: +1. Google Search Console — https://search.google.com/search-console +2. Bing Webmaster Tools — https://www.bing.com/webmasters +3. Wikidata entry — https://www.wikidata.org/wiki/Special:CreateAccount +4. LinkedIn Company Page (B2B) +5. Product Hunt (launches) — https://www.producthunt.com/posts/new +6. Crunchbase (startups) — https://www.crunchbase.com/add-new +7. G2 / Capterra (SaaS reviews) — https://www.g2.com/, https://www.capterra.com/ +8. GitHub topic + README badges (open source) + +AI visibility (GEO): +- Wikidata Q-item with `sameAs` +- Schema.org JSON-LD: Organization, LocalBusiness, niche, FAQPage, Article, Person +- llms.txt at site root +- Direct AI checks: search business name on ChatGPT, Claude, Perplexity, Gemini + +If you need 2026-current pricing, signup steps, or a platform you're +unsure exists, use `WebSearch` and confirm before listing it. Do NOT +invent links. diff --git a/skills/client-handover/SKILL.md b/skills/client-handover/SKILL.md new file mode 100644 index 0000000..966b1e2 --- /dev/null +++ b/skills/client-handover/SKILL.md @@ -0,0 +1,69 @@ +--- +name: client-handover +description: | + Final ship-and-handover orchestrator. End-to-end pipeline that hardens the + project, commits, pauses for deploy, validates the live site, and only then + generates the non-technical client deliverable (LIVRAISON.md / HANDOVER.md). + Pipeline: (1) /seo (SEO+GEO) and /harden run in parallel with auto-fix loops + until each score ≥17/20, (2) /commit-change + push if changes made, (3) pause + to tell user what to deploy and wait for confirmation, (4) /validate against + the live site, (5) per-audit gate ≥17/20 — stop and analyze if any below, + (6) write client doc with before/after score table and explicit + owner-maintenance checklist. Reads git history + .claude/memory/ registries. + For local-business projects, appends manual SEO/GEO platform checklist (NAP + consistency across Google Business, Pages Jaunes, Yelp, Facebook, Instagram, + TikTok, Apple Maps, Bing Places, TripAdvisor, etc.). Asks whether to include + build/deploy chapter. + Trigger: "client handover", "compte rendu client", "livraison client", + "synthese projet", "rapport client", "deliverable", "summary for client", + "recap projet", "handover doc", "livrable", "ship and handover", + "finaliser et livrer". +argument-hint: [optional: language fr|en, --include-deploy, --skip-deploy, --skip-seo, --skip-audits, --skip-fix-loop, --max-iterations N, --audit-max-age , --output ] +disable-model-invocation: false +allowed-tools: + - Read + - Write + - Edit + - Bash + - Grep + - Glob + - WebSearch + - WebFetch + - AskUserQuestion + - Agent +--- + +Load and follow strictly: +- $HOME/.claude/agents/client-handover-writer.md + +Execute the CLIENT HANDOVER WRITER agent on this project. + +The agent runs a **ship-and-handover pipeline** with explicit gates: + +1. **PRE-FLIGHT** — Detect git repo, project root, language, project type, web sub-type, NAP signals, stack. +2. **BASELINE AUDITS** — Run /seo (SEO+GEO) and /harden in parallel. Capture initial scores (`SCORE_SEO_BEFORE`, `SCORE_HARDEN_BEFORE`). +3. **FIX LOOPS (parallel, bounded)** — For each audit < 17/20: + - Re-invoke the audit subagent with explicit instruction to apply auto-fixes. + - Re-score. + - Repeat up to `MAX_ITERATIONS` (default 5). + - If still < 17/20 after cap → escalate to user with concrete remaining issues; user decides continue / stop / manual intervention. +4. **COMMIT + PUSH** — If files changed during fix loops, run /commit-change (atomic logical commits) then `git push`. +5. **DEPLOY PAUSE** — List exact deploy artifacts: changed files since baseline, deploy hints from project (vercel.json, netlify.toml, Dockerfile, .github/workflows/deploy.yml, etc.), and the deploy process in plain words. Use AskUserQuestion: "Deploy done? (Yes / Not yet / Skip validate)". Block until Yes or Skip. +6. **/validate (live site)** — Run validator-analyzer against the deployed URL. Capture `SCORE_VALIDATE`. +7. **GATE — per-audit threshold ≥17/20** — Compute final `SCORE_*_AFTER` for SEO, HARDEN, VALIDATE. If ANY < 17/20: STOP. Generate `.claude/audits/HANDOVER-ROADMAP.md` with prioritized analysis of what's blocking each below-threshold audit. Do NOT write the client deliverable. Report to user. +8. **DOC GENERATION (only if all scores ≥17/20)** — Read `.claude/memory/` registries + full git history. Ask whether to include build/deploy chapter. Synthesize concise client deliverable with: + - Before/after score table (SEO, HARDEN, VALIDATE — values + delta). + - Plain-language summary of all changes since first commit. + - **Owner responsibilities** section: explicit checklist of what the client must do / maintain (SEO platforms, content updates, monitoring, deploy if self-hosted). + - Optional build/deploy chapter. + - For web projects with local-business signals: manual SEO/GEO platform checklist with registration links. +9. **OUTPUT** — Write to `LIVRAISON.md` (fr) or `HANDOVER.md` (en) at project root. + +Flags: +- `--skip-fix-loop` — run baseline audits once, skip auto-fix iterations. +- `--max-iterations N` — cap fix loop iterations (default 5). +- `--skip-audits` — bypass entire pipeline; jump straight to doc generation from existing audit files. +- All previous flags still supported (see argument-hint). + +Context from the user (if any): +$ARGUMENTS diff --git a/skills/client-handover/checklists/seo-geo-manual.md b/skills/client-handover/checklists/seo-geo-manual.md new file mode 100644 index 0000000..75dbfad --- /dev/null +++ b/skills/client-handover/checklists/seo-geo-manual.md @@ -0,0 +1,732 @@ +# SEO/GEO Manual Checklist — Resource for client-handover + +This file is read by `client-handover-writer.md` to populate the SEO/GEO +chapter of the client handover document. It contains the canonical +platform list, registration URLs, and pre-written client-facing copy in +both French and English. + +The agent picks the right section based on: +- `LANG` = `fr` | `en` +- `IS_LOCAL_BUSINESS` = `true` | `false` + +**Maintenance**: when adding a platform, add the row in BOTH the FR and +EN tables, AND update the `Platform reference` fallback in +`~/.claude/agents/client-handover-writer.md`. Verify URLs are still +current (re-check yearly). + +URL sanity: the agent should run `WebFetch` on a sample of these URLs +when first using the chapter to confirm they're alive. Replace any +dead link via `WebSearch` for the platform's current signup page. + +--- + +# SECTION A — Local business, FRENCH + +Insert verbatim (translate placeholders) into the deliverable when +`LANG=fr` AND `IS_LOCAL_BUSINESS=true`. + +## 8. Améliorer votre visibilité en ligne — ce qui dépend de vous + +### Pourquoi ce chapitre + +Votre site est maintenant en ligne et techniquement bien construit. Mais +être visible sur Google, sur ChatGPT, ou dans les annuaires comme Pages +Jaunes, dépend ensuite d'un travail manuel que **seul vous pouvez faire**. +On ne peut pas créer une fiche Google à votre place — il faut une preuve +d'identité (photo, courrier postal, numéro vérifié). Voici la liste +complète des actions qui feront réellement progresser votre visibilité. + +Ces actions prennent 2 à 4 heures au total. Faites-les dans l'ordre. + +### Étape 1 — Définir vos informations officielles (15 min) + +C'est l'étape **la plus importante**. Le moindre écart entre les +plateformes (un espace en trop, un "0" devant le numéro, une virgule +manquante dans l'adresse) divise votre visibilité Google. + +Choisissez UNE seule version officielle de chaque champ et utilisez-la +**à l'identique partout** : + +| Champ | Valeur officielle à utiliser partout | +|----------------|------------------------------------------------------------| +| Nom commercial | [À COMPLÉTER — exactement comme sur le Kbis] | +| Adresse | [À COMPLÉTER — n° rue, code postal, ville] | +| Téléphone | [À COMPLÉTER — format: +33 X XX XX XX XX] | +| Email pro | [À COMPLÉTER] | +| Site web | [À COMPLÉTER — avec le https://] | +| Horaires | [À COMPLÉTER — ligne par jour, format 24h: 09:00–18:00] | +| Catégorie | [À COMPLÉTER — la principale, ex: "Restaurant italien"] | + +Notez ces informations dans un fichier que vous gardez à portée de main — +vous allez les recopier 10 fois. + +### Étape 2 — Plateformes prioritaires (à faire la première semaine) + +**Google Business Profile** — la plus importante. C'est ce qui s'affiche +quand on cherche votre nom sur Google ou Google Maps. +- Inscription : https://www.google.com/business/ +- À faire : créer la fiche, vérifier (Google envoie un code par courrier + postal — 5 jours), ajouter au moins 10 photos (intérieur, extérieur, + équipe, produits), remplir tous les champs. +- ☐ Fiche créée +- ☐ Vérification reçue et validée +- ☐ 10 photos minimum +- ☐ Description rédigée (200 caractères, contient votre activité + ville) +- ☐ Horaires complets (et horaires spéciaux pour les jours fériés) + +**Pages Jaunes** — toujours très utilisé en France, surtout par les 50+. +- Inscription : https://www.pagesjaunes.fr/pro/inscription +- ☐ Fiche créée +- ☐ Photo de couverture +- ☐ Description + +**Apple Business Connect** — pour apparaître sur Plans (iPhone, Mac). +- Inscription : https://businessconnect.apple.com/ +- ☐ Fiche créée +- ☐ Validation faite + +**Bing Places** — moins de trafic mais c'est aussi ce qui alimente +ChatGPT (Bing est le moteur derrière les recherches IA de Microsoft). +- Inscription : https://www.bingplaces.com/ +- Astuce : importez directement depuis Google Business Profile pour + gagner du temps. +- ☐ Fiche créée + +### Étape 3 — Réseaux sociaux et avis (à faire le premier mois) + +**Facebook Page** — toujours utile, surtout pour les avis. +- Inscription : https://www.facebook.com/pages/create +- ☐ Page créée avec les mêmes infos NAP (voir Étape 1) +- ☐ Photo de profil + photo de couverture +- ☐ Bouton "Contact" ou "Réserver" configuré + +**Instagram Business** — visuel, idéal pour montrer votre travail. +- Inscription : https://business.instagram.com/ +- À faire : convertir en compte pro, lier à la page Facebook. +- ☐ Compte pro activé +- ☐ Bio avec lien vers le site +- ☐ Premier post avec hashtag local (#[votreville]) + +**TikTok Business** — si votre activité s'y prête (visuel, créatif, +jeune public). +- Inscription : https://www.tiktok.com/business/ +- ☐ Compte créé (optionnel, à évaluer selon votre activité) + +**Yelp** — moins utilisé en France qu'aux US mais référencé par Apple +Plans et Siri. +- Inscription : https://biz.yelp.com/ +- ☐ Fiche créée + +### Étape 4 — Cartographie et géolocalisation + +**Mappy** — concurrent de Google Maps en France. +- Inscription : https://corporate.mappy.com/ +- ☐ Fiche créée + +**Waze** — racheté par Google, moins critique mais utile. +- Inscription via Google Business Profile (c'est lié). +- ☐ Adresse vérifiée sur Waze + +### Étape 5 — Plateformes selon votre activité + +À ajouter UNIQUEMENT si pertinent pour votre métier : + +| Métier | Plateforme | Lien | +|---------------------|------------------------------------------|------| +| Restaurant | TheFork (La Fourchette) | https://www.thefork.com/restaurant | +| Restaurant / Hôtel | TripAdvisor | https://www.tripadvisor.fr/Owners | +| Hôtel / Location | Booking.com | https://join.booking.com/ | +| Locations courtes | Airbnb | https://www.airbnb.fr/host/homes | +| Médecin / paramédical | Doctolib | https://pro.doctolib.fr/ | +| Beauté / coiffure | Planity / Treatwell | https://www.planity.com/pro | +| Artisan / services | Stootie / AlloVoisins | https://www.allovoisins.com/ | +| B2B / pro | LinkedIn Company Page | https://www.linkedin.com/company/setup/new/ | +| Boutique en ligne | Trustpilot | https://business.trustpilot.com/ | +| Avocat | Avocat.fr / Justifit | https://www.justifit.fr/inscription/ | + +### Étape 6 — Annuaires généralistes (gain marginal mais cumulatif) + +À faire en bloc, après les étapes 1-5 : +- Justacote — https://www.justacote.com/ +- Hoodspot — https://www.hoodspot.fr/ +- Foursquare — https://business.foursquare.com/ +- Le Bottin — https://www.lebottin.fr/ + +### Étape 7 — Visibilité sur les IA (ChatGPT, Claude, Perplexity, Gemini) + +Les moteurs de recherche IA citent maintenant les entreprises dans leurs +réponses. Pour qu'ils parlent de vous correctement : + +**Test en direct** (à faire vous-même) : +1. Allez sur https://chat.openai.com/, demandez : "Quels sont les bons + [votre activité] à [votre ville] ?" +2. Faites pareil sur https://www.perplexity.ai/, https://claude.ai/, + https://gemini.google.com/ +3. Notez ce qui apparaît. Si votre nom n'apparaît pas, c'est attendu + au début — il faut 2 à 4 mois pour que les IA vous indexent une fois + les fiches créées. + +**Action côté technique** (déjà en place sur votre site) : le développeur +a inclus les balises Schema.org / JSON-LD qui aident les IA à comprendre +votre activité. Vérifiez que ces données sont bien lues : +- Outil : https://search.google.com/test/rich-results +- Collez votre URL et confirmez qu'il n'y a pas d'erreur. + +**Wikidata** (optionnel mais puissant si vous êtes une entreprise +établie) : créer une fiche Wikidata fait apparaître votre entreprise +dans le "Knowledge Panel" Google et donne un signal fort aux IA. +- https://www.wikidata.org/wiki/Special:CreateAccount +- Réservé aux entreprises ayant déjà une présence (presse, Wikipédia, + notoriété). Si ce n'est pas le cas, sautez cette étape. + +### Étape 8 — Avis clients (le facteur multiplicateur) + +Les avis Google et Facebook sont **le levier #1** pour monter dans les +résultats locaux. Plus vous avez d'avis (positifs et récents), plus +Google vous remonte. + +**Méthode simple** : +1. Identifiez 10 clients récents satisfaits. +2. Envoyez-leur ce message (à adapter) : + +> Bonjour [Prénom], +> Merci de votre confiance ! Si vous avez 30 secondes, votre avis +> Google nous aiderait beaucoup à nous faire connaître : +> [LIEN GOOGLE — récupéré depuis votre fiche Google Business Profile, +> section "Demander des avis"] +> Merci pour votre soutien. + +3. Visez 5 nouveaux avis le premier mois, puis 1 par semaine. +4. Répondez à **tous** les avis, même les positifs (Google le valorise). + +### Étape 9 — Calendrier suggéré + +| Quand | Action | +|--------------------|--------| +| Semaine 1 | Étapes 1, 2 (Google Business, Pages Jaunes, Apple, Bing), Étape 8 (premier message à 5 clients) | +| Semaine 2 | Étape 3 (Facebook, Instagram), Étape 4 (Mappy) | +| Semaine 3-4 | Étape 5 (plateformes métier), Étape 6 (annuaires) | +| Mois 2 | Étape 8 continue (5 avis de plus), Étape 7 (test IA) | +| Mois 3 | Audit complet — cherchez votre nom sur Google + ChatGPT + Pages Jaunes. Tout est-il à jour ? | +| Trimestriel | Mettre à jour photos, publier 1 post Google Business, vérifier les nouveaux avis | +| Annuel | Vérifier que les liens des fiches fonctionnent toujours, mettre à jour horaires (vacances, jours fériés) | + +### Étape 10 — Outils gratuits pour suivre votre progression + +- **Google Search Console** — voir comment Google voit votre site : + https://search.google.com/search-console +- **Google Business Insights** — accessible depuis votre fiche Google + Business Profile, montre les recherches qui mènent à vous. +- **BrightLocal Free Tools** — vérifier la cohérence de votre NAP sur + les annuaires : https://www.brightlocal.com/free-local-tools/ +- **PageSpeed Insights** — vérifier que le site reste rapide : + https://pagespeed.web.dev/ + +### Erreurs courantes à éviter + +- ❌ Mettre des informations différentes sur Pages Jaunes et Google. +- ❌ Oublier de répondre aux avis (négatifs ET positifs). +- ❌ Mettre des photos floues ou prises au flash. +- ❌ Ne pas mettre à jour les horaires pour les jours fériés. +- ❌ Acheter des avis (Google détecte et déclasse). +- ❌ Créer plusieurs fiches Google pour le même établissement (Google + pénalise les doublons). +- ❌ Utiliser un numéro de téléphone différent du Kbis. + +--- + +# SECTION B — Local business, ENGLISH + +Insert verbatim into the deliverable when `LANG=en` AND +`IS_LOCAL_BUSINESS=true`. + +## 8. Improving Your Online Visibility — What's On You + +### Why this chapter exists + +Your site is now live and technically optimized. But being visible on +Google, ChatGPT, or directories like Yelp depends on manual work **only +you can do**. We can't create a Google Business Profile for you — it +needs identity proof (photo, postal verification, phone). Below is the +complete list of actions that will actually move the needle. + +These actions take 2-4 hours total. Do them in order. + +### Step 1 — Define your official information (15 min) + +This is **the most important step**. Any difference between platforms (a +trailing space, a missing comma, a different phone format) splits your +Google visibility. + +Pick ONE official version of each field and use it **identically +everywhere**: + +| Field | Official value to use everywhere | +|------------------|--------------------------------------------------| +| Business name | [TO FILL — exactly as registered] | +| Address | [TO FILL — street, city, ZIP, country] | +| Phone | [TO FILL — format: +1 XXX XXX XXXX] | +| Pro email | [TO FILL] | +| Website | [TO FILL — with https://] | +| Hours | [TO FILL — per day, 24h format: 09:00-18:00] | +| Primary category | [TO FILL — e.g., "Italian restaurant"] | + +Save these in a file you can reach in two clicks. You will copy them 10 +times. + +### Step 2 — Priority platforms (week 1) + +**Google Business Profile** — by far the most important. It's what shows +up when someone searches your name on Google or Maps. +- Sign up: https://www.google.com/business/ +- Tasks: create profile, verify (Google sends a postal code — 5 days), + add 10+ photos (interior, exterior, team, products), fill every field. +- ☐ Profile created +- ☐ Verification received and validated +- ☐ 10+ photos uploaded +- ☐ Description written (200 chars, contains business + city) +- ☐ Full hours (and special holiday hours) + +**Apple Business Connect** — to appear on Apple Maps (iPhone, Mac). +- Sign up: https://businessconnect.apple.com/ +- ☐ Profile created +- ☐ Validation done + +**Bing Places** — lower traffic, but Bing also feeds ChatGPT (Microsoft's +AI search runs on it). +- Sign up: https://www.bingplaces.com/ +- Tip: import directly from Google Business Profile to save time. +- ☐ Profile created + +**Yelp** — strong in the US, weaker in EU. Powers Apple Maps and Siri. +- Sign up: https://biz.yelp.com/ +- ☐ Profile created + +### Step 3 — Social and reviews (month 1) + +**Facebook Page** — still relevant, especially for reviews. +- Sign up: https://www.facebook.com/pages/create +- ☐ Page created with same NAP (see Step 1) +- ☐ Profile photo + cover photo +- ☐ "Contact" or "Book" button configured + +**Instagram Business** — visual, ideal for showcasing work. +- Sign up: https://business.instagram.com/ +- Tasks: switch to business account, link to Facebook page. +- ☐ Business account active +- ☐ Bio with website link +- ☐ First post with local hashtag (#[yourcity]) + +**TikTok Business** — if your business is visual, creative, or appeals +to younger audiences. +- Sign up: https://www.tiktok.com/business/ +- ☐ Account created (optional — depends on your industry) + +### Step 4 — Maps and geolocation + +**Google Maps** — already covered by Google Business Profile. + +**Waze** — owned by Google, less critical but still useful. +- Linked through Google Business Profile. +- ☐ Address verified on Waze + +**Foursquare for Business** — feeds many third-party apps. +- Sign up: https://business.foursquare.com/ +- ☐ Profile created + +### Step 5 — Industry-specific platforms + +Add ONLY if relevant to your business: + +| Industry | Platform | URL | +|--------------------------|--------------------------------|-----| +| Restaurant | TripAdvisor | https://www.tripadvisor.com/Owners | +| Restaurant (US) | OpenTable / Resy | https://restaurant.opentable.com/ | +| Hotel / lodging | Booking.com | https://join.booking.com/ | +| Short-term rental | Airbnb | https://www.airbnb.com/host/homes | +| Medical / health | Healthgrades / Zocdoc | https://www.zocdoc.com/ | +| Beauty / wellness | Mindbody / Vagaro | https://www.mindbodyonline.com/ | +| Trades / services | Angi / Thumbtack / TaskRabbit | https://www.angi.com/ | +| B2B / professional | LinkedIn Company Page | https://www.linkedin.com/company/setup/new/ | +| E-commerce / shop | Trustpilot | https://business.trustpilot.com/ | +| Lawyer | Avvo / FindLaw | https://www.avvo.com/claim-profile | + +### Step 6 — General directories (marginal but cumulative gains) + +Do these in batch after steps 1-5: +- Better Business Bureau — https://www.bbb.org/ +- Hotfrog — https://www.hotfrog.com/ +- MerchantCircle — https://www.merchantcircle.com/ +- Manta — https://www.manta.com/ +- Yellow Pages (US) — https://www.yellowpages.com/ + +### Step 7 — AI search visibility (ChatGPT, Claude, Perplexity, Gemini) + +AI search engines now cite businesses in their answers. To make them +talk about you correctly: + +**Live test** (do this yourself): +1. Go to https://chat.openai.com/, ask: "What are good [your business + type] in [your city]?" +2. Repeat on https://www.perplexity.ai/, https://claude.ai/, + https://gemini.google.com/ +3. Note what appears. If your name isn't there, that's expected at first + — AI engines need 2-4 months to index you after profiles are live. + +**Technical side** (already in place on your site): the developer +included Schema.org / JSON-LD markup that helps AI engines understand +your business. Verify it parses cleanly: +- Tool: https://search.google.com/test/rich-results +- Paste your URL, confirm no errors. + +**Wikidata** (optional, powerful for established businesses): a Wikidata +entry boosts Google's Knowledge Panel and gives a strong signal to AI. +- https://www.wikidata.org/wiki/Special:CreateAccount +- Only relevant if your business already has press, a Wikipedia entry, + or known reputation. Otherwise skip. + +### Step 8 — Customer reviews (the multiplier) + +Google and Yelp reviews are **the #1 lever** for ranking in local +results. More reviews (positive AND recent) = higher Google ranking. + +**Simple method**: +1. Identify 10 recent satisfied customers. +2. Send them this message (adapt): + +> Hi [First name], +> Thanks for choosing us! If you have 30 seconds, a Google review would +> mean a lot: +> [GOOGLE LINK — get from your Google Business Profile, "Ask for +> reviews" section] +> Thanks for the support. + +3. Aim for 5 new reviews in month 1, then 1 per week. +4. Reply to **every** review, including positive ones (Google rewards it). + +### Step 9 — Suggested timeline + +| When | Action | +|----------------|--------| +| Week 1 | Steps 1, 2 (Google, Apple, Bing, Yelp), Step 8 (5 first review requests) | +| Week 2 | Step 3 (Facebook, Instagram), Step 4 (Foursquare) | +| Week 3-4 | Step 5 (industry platforms), Step 6 (general directories) | +| Month 2 | Step 8 continued (5 more reviews), Step 7 (AI test) | +| Month 3 | Full audit — search your name on Google + ChatGPT + Yelp. Everything still accurate? | +| Quarterly | Refresh photos, post 1 Google Business update, check new reviews | +| Annually | Verify all links still work, update hours (holidays, vacations) | + +### Step 10 — Free tools to track progress + +- **Google Search Console** — see how Google views your site: + https://search.google.com/search-console +- **Google Business Insights** — inside your Google Business Profile, + shows what searches lead to you. +- **BrightLocal Free Tools** — verify NAP consistency across directories: + https://www.brightlocal.com/free-local-tools/ +- **PageSpeed Insights** — confirm site stays fast: + https://pagespeed.web.dev/ + +### Common mistakes to avoid + +- ❌ Different info on Yelp vs Google. +- ❌ Ignoring reviews (negative AND positive). +- ❌ Blurry or flash-lit photos. +- ❌ Not updating hours for holidays. +- ❌ Buying reviews (Google detects and demotes). +- ❌ Creating multiple Google profiles for the same business (Google + penalizes duplicates). +- ❌ Phone number that differs from your business registration. + +--- + +# SECTION C — Non-local web, FRENCH + +Insert verbatim into the deliverable when `LANG=fr` AND +`IS_LOCAL_BUSINESS=false` AND `PROJECT_TYPE=web`. + +## 8. Améliorer la visibilité de votre site — ce qui dépend de vous + +### Pourquoi ce chapitre + +Le site est en ligne et techniquement optimisé pour le référencement. +La suite dépend de **vous** : revendiquer votre marque sur les bons +outils, faire indexer le site, obtenir des liens entrants, et apparaître +dans les nouveaux moteurs de recherche IA (ChatGPT, Perplexity, Gemini). + +### Étape 1 — Indexation chez Google et Bing + +**Google Search Console** — l'outil officiel Google pour suivre votre +site et lui dire d'indexer vos pages. +- Inscription : https://search.google.com/search-console +- Actions : + - ☐ Vérifier la propriété (DNS ou fichier HTML — votre développeur peut + aider). + - ☐ Soumettre le sitemap.xml (URL : votresite.com/sitemap.xml) + - ☐ Vérifier qu'il n'y a pas d'erreur d'indexation + - ☐ Surveiller les requêtes qui mènent à vous (1 fois par mois) + +**Bing Webmaster Tools** — équivalent Bing, alimente aussi ChatGPT. +- Inscription : https://www.bing.com/webmasters +- ☐ Compte créé +- ☐ Sitemap soumis +- ☐ Importer depuis Google Search Console (option "Importer") + +### Étape 2 — Présence sur les réseaux pertinents + +À adapter selon votre activité : + +| Type de projet | Plateforme | Lien | +|---------------------|----------------------------------------|------| +| B2B / pro | LinkedIn Company Page | https://www.linkedin.com/company/setup/new/ | +| Startup / produit | Product Hunt (lancement) | https://www.producthunt.com/posts/new | +| Startup | Crunchbase | https://www.crunchbase.com/add-new | +| SaaS | G2 / Capterra | https://www.g2.com/, https://www.capterra.com/ | +| Open source | GitHub topics + README badges | (votre repo GitHub) | +| Portfolio créatif | Behance / Dribbble | https://www.behance.net/ | +| Blog / newsletter | Substack / Medium republish | https://substack.com/ | +| Boutique en ligne | Trustpilot / Avis Vérifiés | https://business.trustpilot.com/ | + +### Étape 3 — Liens entrants (la base du SEO) + +Google classe les sites en partie par les liens reçus depuis d'autres +sites. Vous ne pouvez pas en acheter (Google pénalise) — il faut les +mériter. + +Idées concrètes : +- ☐ Demander aux partenaires (fournisseurs, clients pro) de vous citer + avec un lien sur leur site. +- ☐ Publier un article invité sur un blog du secteur. +- ☐ Créer du contenu utile (guide, comparatif, étude) que d'autres + voudront citer. +- ☐ S'inscrire dans 2-3 annuaires sectoriels reconnus (pas les fermes + de liens — privilégiez la qualité). +- ☐ Si vous êtes cité dans un article presse : demander que le lien + soit un vrai lien cliquable (pas juste votre nom en gras). + +### Étape 4 — Visibilité sur les IA (GEO) + +**Test en direct** : +1. Allez sur https://chat.openai.com/, demandez : "Quels sont les + meilleurs sites pour [ce que vous faites] ?" +2. Pareil sur https://www.perplexity.ai/, https://claude.ai/, + https://gemini.google.com/ +3. Notez ce qui apparaît. + +**Côté technique** (déjà fait sur votre site) : Schema.org JSON-LD, +balises Open Graph, sitemap, robots.txt qui autorise les crawlers IA +(GPTBot, ClaudeBot, PerplexityBot). + +**Côté contenu** (à faire par vous ou un rédacteur) : +- Ajouter une page FAQ (les IA adorent extraire des Q→R). +- Écrire en début de paragraphe la réponse, puis détailler (les IA + citent les premières lignes). +- Mettre à jour le contenu (les IA préfèrent les pages récentes). + +**Wikidata** (si pertinent) : créer une fiche pour votre marque, votre +produit, ou votre fondateur. Ça aide les IA à vous reconnaître. +- https://www.wikidata.org/wiki/Special:CreateAccount + +### Étape 5 — Mesure et ajustement + +Outils gratuits : +- Google Search Console — trafic et requêtes +- Google Analytics 4 — comportement des visiteurs (https://analytics.google.com/) +- Plausible / Simple Analytics — alternatives respectueuses de la vie + privée et conformes RGPD +- PageSpeed Insights — vitesse du site (https://pagespeed.web.dev/) + +Calendrier : +| Quand | Action | +|--------------|--------| +| Semaine 1 | Search Console + Bing Webmaster + sitemap | +| Mois 1 | Réseaux pertinents + 3 premiers liens entrants | +| Mois 2-3 | Création de contenu (1 article ou guide / mois) | +| Trimestriel | Audit SEO complet (rerun `/seo` avec votre dev) | + +### Erreurs à éviter + +- ❌ Acheter des liens — Google détecte et déclasse. +- ❌ Lancer un blog et l'abandonner après 2 articles. +- ❌ Ignorer Search Console pendant 6 mois. +- ❌ Bloquer les crawlers IA dans robots.txt (vérifier que GPTBot, + ClaudeBot, etc., sont autorisés si vous voulez apparaître). + +--- + +# SECTION D — Non-local web, ENGLISH + +Insert verbatim when `LANG=en` AND `IS_LOCAL_BUSINESS=false` AND +`PROJECT_TYPE=web`. + +## 8. Improving Your Site's Visibility — What's On You + +### Why this chapter exists + +The site is live and technically SEO-optimized. The rest is on **you**: +claim your brand on the right tools, get the site indexed, earn +backlinks, and show up in new AI search engines (ChatGPT, Perplexity, +Gemini). + +### Step 1 — Indexation on Google and Bing + +**Google Search Console** — Google's official tool to track your site +and request page indexing. +- Sign up: https://search.google.com/search-console +- Tasks: + - ☐ Verify ownership (DNS or HTML file — your developer can help) + - ☐ Submit sitemap.xml (URL: yoursite.com/sitemap.xml) + - ☐ Confirm no indexing errors + - ☐ Monitor queries leading to you (monthly) + +**Bing Webmaster Tools** — Bing equivalent, also feeds ChatGPT. +- Sign up: https://www.bing.com/webmasters +- ☐ Account created +- ☐ Sitemap submitted +- ☐ Import from Google Search Console (use the "Import" option) + +### Step 2 — Presence on relevant networks + +Adapt to your activity: + +| Project type | Platform | URL | +|---------------------|---------------------------------------|-----| +| B2B / pro | LinkedIn Company Page | https://www.linkedin.com/company/setup/new/ | +| Startup / product | Product Hunt (launches) | https://www.producthunt.com/posts/new | +| Startup | Crunchbase | https://www.crunchbase.com/add-new | +| SaaS | G2 / Capterra | https://www.g2.com/, https://www.capterra.com/ | +| Open source | GitHub topics + README badges | (your GitHub repo) | +| Creative portfolio | Behance / Dribbble | https://www.behance.net/ | +| Blog / newsletter | Substack / Medium republish | https://substack.com/ | +| E-commerce | Trustpilot | https://business.trustpilot.com/ | + +### Step 3 — Backlinks (the SEO foundation) + +Google ranks sites partly by who links to them. You can't buy these +(Google penalizes) — you have to earn them. + +Concrete ideas: +- ☐ Ask partners (suppliers, clients) to link to you on their site. +- ☐ Publish a guest article on an industry blog. +- ☐ Create useful content (guide, comparison, case study) others will + want to cite. +- ☐ Register in 2-3 reputable industry directories (avoid link farms — + quality over quantity). +- ☐ If a press article cites you: ask that the citation be a real + clickable link (not just bolded text). + +### Step 4 — AI visibility (GEO) + +**Live test**: +1. Go to https://chat.openai.com/, ask: "What are the best sites for + [what you do]?" +2. Same on https://www.perplexity.ai/, https://claude.ai/, + https://gemini.google.com/ +3. Note what appears. + +**Technical side** (already done): Schema.org JSON-LD, Open Graph, +sitemap, robots.txt allowing AI crawlers (GPTBot, ClaudeBot, +PerplexityBot). + +**Content side** (your job or a writer's): +- Add a FAQ page (AI loves extracting Q→A). +- Lead each paragraph with the answer, then detail (AI quotes opening + lines). +- Refresh content (AI prefers recent pages). + +**Wikidata** (if relevant): create a Wikidata entry for your brand, +product, or founder. Helps AI engines recognize you. +- https://www.wikidata.org/wiki/Special:CreateAccount + +### Step 5 — Measure and iterate + +Free tools: +- Google Search Console — traffic and queries +- Google Analytics 4 — visitor behavior (https://analytics.google.com/) +- Plausible / Simple Analytics — privacy-friendly, GDPR-compliant +- PageSpeed Insights — site speed (https://pagespeed.web.dev/) + +Timeline: +| When | Action | +|--------------|--------| +| Week 1 | Search Console + Bing Webmaster + sitemap | +| Month 1 | Relevant networks + first 3 backlinks | +| Month 2-3 | Content creation (1 article or guide / month) | +| Quarterly | Full SEO audit (rerun `/seo` with your dev) | + +### Mistakes to avoid + +- ❌ Buying links — Google detects and demotes. +- ❌ Launching a blog and abandoning it after 2 posts. +- ❌ Ignoring Search Console for 6 months. +- ❌ Blocking AI crawlers in robots.txt (verify GPTBot, ClaudeBot, etc. + are allowed if you want AI visibility). + +--- + +# COMMON — AI visibility deep-dive (used in all sections) + +The agent may need to expand the AI section depending on the project's +sophistication. Use these snippets as building blocks. + +## AI crawlers allowlist (technical reference) + +If the client asks "are AI engines allowed to read my site?", check +`robots.txt`. The following crawlers should NOT be disallowed if AI +visibility is wanted: + +``` +User-agent: GPTBot +User-agent: ChatGPT-User +User-agent: OAI-SearchBot +User-agent: ClaudeBot +User-agent: Claude-Web +User-agent: anthropic-ai +User-agent: PerplexityBot +User-agent: Perplexity-User +User-agent: Google-Extended +User-agent: Bingbot +User-agent: CCBot +User-agent: Bytespider +User-agent: Diffbot +User-agent: DuckAssistBot +User-agent: Applebot-Extended +``` + +If the client wants to OPT OUT of AI training, those should be +disallowed. Be explicit: visibility ≠ training opt-in. Some bots only +read for live answers (GPTBot in search mode), others for training. +Defer to legal preference. + +## llms.txt + +`llms.txt` is an emerging standard (similar role to robots.txt but for +AI). If the site has one, mention it to the client. If not, defer — +this is technical, not their job. + +## Schema.org types worth checking + +The agent should not list these to the client unless asked. Internal +reference for the developer: + +- `Organization` (always) +- `LocalBusiness` (and subtypes: Restaurant, Hotel, MedicalBusiness, etc.) +- `Person` (founder, key staff) +- `Product` (e-commerce) +- `Service` (services) +- `FAQPage` (helps AI extraction) +- `Article` (blog content) +- `BreadcrumbList` (navigation context) +- `AggregateRating` (review counts) + +--- + +# MAINTENANCE NOTES + +- Re-verify all signup URLs annually. +- Add new platforms as they emerge (TikTok Maps, Threads, Bluesky, + Mastodon for community, etc.). +- Track which platforms the agent's `WebFetch` checks fail on — those + may have changed signup URLs. +- AI crawler list grows monthly. Sync with `~/.claude/agents/resources/ + ai-crawlers-2026.md` if it exists.