name: onboard description: Onboard an existing project — detects archetype, installs claude-config, runs full audit (dette/SEO-GEO/UI-UX/perf/sécu/a11y/doc), produces improvement plan in .claude/audits/ + .claude/tasks/. Use on repos not created via /init-project. argument-hint: [optional hints: "Python FastAPI" | "add gsd" | "Next.js monorepo" | "force-archetype:wordpress"] disable-model-invocation: true

allowed-tools: Read, Write, Edit, Bash, Glob, Grep

ORCHESTRATOR: ONBOARD

REQUEST

$ARGUMENTS

STEP 0 — PLUGIN CHECK + AUTO-ACTIVATE

Load $HOME/.claude/agents/plugin-advisor.md with hint "onboarding existing project + $ARGUMENTS".

ACTION REQUIRED → show RECOMMENDATIONS block, offer: A) apply recos B) type "force". STOP.
PROPOSED CHANGES exist → show list, ask "Apply? (yes / no / customize)". Apply on confirm.
OK → ✅ Plugin check passed — [active plugins] — complexity: <score>%, continue.

Complexity score is carried forward for STEP 4 graphify decision.

STEP 1 — ARCHETYPE DETECTION

Load $HOME/.claude/lib/archetype-detector.md. Apply algorithm on current working directory.

If user passed force-archetype:<name> in $ARGUMENTS → skip detection, use that archetype, print 🎯 Archetype forcé : <name>. Verify ~/.claude/lib/project-archetypes/<name>.md exists, else STOP with error.

Otherwise:

Scan filesystem for signals (respect counter-signals / exclusions).
Score each archetype in ~/.claude/lib/project-archetypes/*.md (hors _TEMPLATE.md).
Apply selection rules from archetype-detector.md.

Output format:

ARCHETYPE DETECTION
Top scores:
  1. <name>  XX/YY (zz%) — strong:N, medium:N, weak:N  [SELECTED | AMBIGUOUS]
  2. ...

SELECTED: <name>  (confiance: HAUTE | MOYENNE | BASSE)

Cases:

SELECTED HAUTE → continue STEP 2 avec l'archétype.
SELECTED MOYENNE → afficher "⚠️ Confiance moyenne — confirmez ? (yes / switch to / describe manually)". STOP.
AMBIGUOUS → présenter options A/B/C/D comme dans archetype-detector.md. STOP.
UNKNOWN → présenter questions manuelles (type de projet, public/interne, DB, stack). STOP.

Afficher les implications auto-appliquées de l'archétype :

IMPLICATIONS (auto depuis archétype <name>):
  - public       : true | false
  - database     : required | optional | none
  - audit_stack  : [analyze, code-clean, seo, design-review, perf, cso, a11y, doc]
  - plugins      : context7=<y/n>, ui-ux-pro-max=<y/n>, gstack=<y/n>

Si archétype a un bloc d'avertissement spécifique (ex: react-spa en public → avertissement SEO) : l'afficher en pleine largeur, demander confirmation ou exploration migration. Stocker la réponse pour STEP 7.

STEP 1b — MONOREPO GATE

Si filesystem scan détecte un monorepo (plugin-advisor signal OR apps/+packages/+workspace config) :

MONOREPO DETECTED
Packages found: [list]
Options:
  A) Onboard entire workspace (one CLAUDE.md at root)
  B) Onboard a specific package (cd into it)
  C) Onboard each package separately (sequential)
Choice? (A / B <name> / C)

STOP. La réponse détermine si STEP 1 tourne une fois (A) ou N fois (C) ou avec un PROJECT_ROOT différent (B).

STEP 2 — BASELINE CONFIG (onboarder agent)

Load $HOME/.claude/agents/onboarder.md. Passer un BRIEF minimal issu du filesystem scan :

archetype (depuis STEP 1)
project_name (depuis package.json/pyproject.toml/README.md/dir name)
stack (depuis manifests détectés)
purpose (depuis README.md première section)
build_cmd, test_cmd, lint_cmd (depuis package.json scripts / Makefile / README)
Les champs manquants à ce stade restent null — STEP 3 les remplira via interview

L'agent génère :

CLAUDE.md (brouillon — à raffiner après STEP 3)
.claude/settings.json
.claudeignore
.gitignore (safety check)
.claude/tasks/TODO.md, .claude/memory/{decisions,learnings,blockers,journal,evals}.md
Pas encore ROADMAP.md (décision STEP 9)

Si CLAUDE.md existe déjà : lire son contenu, ne PAS écraser — fusionner après STEP 3.

STEP 2.5 — ANIMATION LIB (propose, opt-in)

Vérifier si le stack peut consommer motion (ex-framer-motion, rebranded nov 2024) et proposer l'install si absent. Aucun install sans confirmation utilisateur — on ajoute une dep à un projet existant.

source "$HOME/.claude/lib/animation-lib-check.sh"
result=$(detect_anim_eligibility)
status=$(echo "$result" | cut -d'|' -f1)
pkg=$(echo "$result" | cut -d'|' -f2)
reason=$(echo "$result" | cut -d'|' -f3)

Cas :

status=eligible AND aucune lib anim détectée → proposer :
```
🎬 ANIMATION LIB
Stack: <reason>. Aucune lib d'animation détectée.
Install `<cmd>` ? (yes / skip)
```
Sur yes → exécuter recommend_anim_install_cmd "$pkg" puis confirmer. Sur skip → continuer silencieusement.
status=eligible AND une lib anim déjà présente (motion, framer-motion, gsap, lottie, react-spring, popmotion, auto-animate) → log info uniquement :
```
🎬 Animation lib déjà présente : <lib> — pas d'action.
```
status=no → skip silencieusement (raison loggée seulement en mode verbose).

STEP 3 — DEEP INTERVIEW

L'orchestrateur pilote directement l'interview (l'agent interviewer.md est laissé pour /init-project où le BRIEF format est attendu ; ici on reste en markdown libre dans la CLAUDE.md).

Source des questions :

3a — set minimum business (hardcodé ci-dessous, toujours posé sauf si déjà connu)
3b — bloc ## Interview questions (adaptive) du fichier ~/.claude/lib/project-archetypes/<name>.md

3a — Set minimum business (toujours posé sauf si déjà trouvé dans README/CLAUDE.md existant)

Users cibles / persona principal ?
Stade projet ? (prototype / bêta / prod / maintenance)
Deadlines clés ? (MVP, release, audit externe)
Taille équipe + rôles ?
Contraintes légales ? (RGPD, RGAA a11y, HIPAA, autres)
Budget perfs ? (TTI cible, taille bundle, contraintes hébergement)

3b — Questions adaptatives par archétype

Charger le bloc ## Interview questions (adaptive) depuis ~/.claude/lib/project-archetypes/<name>.md. Poser uniquement ce qui n'est pas déjà connu.

3c — Filtrage

Ne pas redemander ce qui est déjà dans :

README.md
package.json / pyproject.toml / Cargo.toml
Un CLAUDE.md existant
Les réponses STEP 1 / 1b

Présenter toutes les questions en UN BLOC. Attendre les réponses. STOP.

Après réponses : mettre à jour le brouillon CLAUDE.md avec les infos obtenues.

STEP 3.5 — CTX7 DOC AUDIT (avant graphify)

Vérifier que le projet a les docs de ses fast-libs accessibles.

command -v ctx7 &>/dev/null && ctx7 --version 2>/dev/null | head -1 || echo "ctx7-not-installed"
ls .ctx7-cache/ 2>/dev/null

Détection fast-libs

Parse manifests selon l'archétype :

nextjs-app-router → chercher : next, react, prisma, @supabase/, drizzle-orm, next-auth, @clerk/
react-spa → chercher : react, @tanstack/*, zustand, jotai
rest-api-node → chercher : fastify, @nestjs/*, prisma, drizzle-orm
rest-api-python → chercher : fastapi, pydantic, sqlalchemy (si ≥ 2.0)
astro-static → chercher : astro, @astrojs/*
wordpress / cli-tool / library / dotfiles-meta / static-html → souvent aucune fast-lib, audit léger

Vérification cache

Pour chaque fast-lib détectée :

Existe un fichier .ctx7-cache/<lib>.md ?
Fraîcheur < 7 jours ?

Actions

ctx7 installé + fast-libs détectées + cache manquant/obsolète → proposer :

📚 DOC AUDIT ctx7
Fast-libs détectées : [liste]
Cache manquant/obsolète : [liste]

Pré-fetcher les docs maintenant ? (yes / skip)

Si yes :

  mkdir -p .ctx7-cache
  ctx7 docs /vercel/next.js "app router middleware routing" > .ctx7-cache/nextjs-core.md
  # ... pour chaque lib détectée

Ajouter .ctx7-cache/ au .gitignore si absent.

ctx7 non installé MAIS fast-libs détectées → WARN :

⚠️  ctx7 non installé — risque de code utilisant des APIs obsolètes
 sur : [liste fast-libs]
 Install : `npm install -g ctx7 && ctx7 setup --claude`
 Ou continuer sans (non recommandé pour fast-libs).

Demander : yes install now / continue without / skip audit.

Pas de fast-lib → skip silencieusement.

STEP 4 — GRAPHIFY (si complexity ≥ 30% et pas déjà présent)

command -v graphify &>/dev/null && echo "available" || echo "not-installed"
test -f graphify-out/GRAPH_REPORT.md && echo "graph-exists"

Pas installé → skip avec message : graphify non installé — skip audit architectural. Install : (voir graphify/SKILL.md)
Complexity < 30% → skip silencieusement, projet trop petit pour justifier.
Graphe déjà présent + récent (fichier < 7j) → skip, réutiliser l'existant.
Sinon → run :
```
graphify . --output graphify-out 2>&1 | tail -20
```
Puis test -f graphify-out/GRAPH_REPORT.md pour valider.

Print : 🔗 Knowledge graph : graphify-out/GRAPH_REPORT.md (N nodes, M edges).

STEP 4.5 — AUDIT WORKSPACE + ARCHETYPE CONTEXT

Créer le dossier transitoire .onboard-audit/ à la racine projet :

mkdir -p .onboard-audit
# Gitignore (ajout idempotent)
grep -q '^\.onboard-audit/' .gitignore 2>/dev/null || \
  printf '\n# onboard audit raw outputs (consumed by /onboard STEP 7)\n.onboard-audit/\n' >> .gitignore

Ce dossier contient les sorties brutes des audits (L3a+L3b). STEP 7 (L4) les synthétise vers .claude/audits/ (rapports) et .claude/tasks/ (backlog). Peut être supprimé après L4 sans perte.

Injection contexte archétype

Extraire de ~/.claude/lib/project-archetypes/<archetype>.md les blocs qui rendent les audits sécu/dette vraiment contextuels (pas de checklist web injectée sur du firmware). Écrire dans .onboard-audit/archetype-context.md :

ARCH_FILE="$HOME/.claude/lib/project-archetypes/<archetype>.md"
OUT=".onboard-audit/archetype-context.md"

{
  echo "# Archetype context — <archetype>"
  echo
  # Frontmatter: name, category, public, database
  echo "## Profile"
  awk '/^---$/{n++; next} n==1' "$ARCH_FILE" | grep -E '^(name|category|public|database):'
  echo
  # Section "## Implications" (contient "Surface sécurité")
  echo "## Implications"
  awk '/^## Implications/{p=1; next} p && /^## [A-Z]/{p=0} p' "$ARCH_FILE"
  echo
  # Section "## Typical pain points" (source vérité pour audits adaptatifs)
  echo "## Typical pain points"
  awk '/^## Typical pain points/{p=1; next} p && /^## [A-Z]/{p=0} p' "$ARCH_FILE"
} > "$OUT"

Ce fichier est lu par les prompts cso/analyze/code-clean pour cibler leurs checks sur les vulnérabilités réellement applicables à l'archétype (ex: buffer overflow + secure boot pour firmware-embedded, supply chain + export leakage pour library, XSS + CSRF pour nextjs-app-router).

STEP 5 — ANALYZE (read-only, general)

Spawn un subagent analyzer (isolé, pas de partage de contexte) :

Agent(
  subagent_type="analyzer",
  description="Onboard — deep read-only analysis",
  prompt="""
  Read-only factual analysis of the project at <PROJECT_ROOT>.
  ARCHETYPE context: <archetype_name> — <category, public, database>.
  Focus areas (ordered) :
    1. Architecture risks (fragile couplings, missing abstractions, cycles)
    2. Dette technique visible (TODO/FIXME/HACK markers, commented code, god files)
    3. Patterns utilisés (bons et mauvais) — cite fichier:ligne
    4. Stale code suspects (last modified > 2 ans, no refs)
    5. Test coverage visible (quels modules testés, lesquels aveugles)
    6. Config drift (multiple configs pour même chose, values en dur)
  NO solutions. NO code changes. NO write outside the report.
  Write the report to `<PROJECT_ROOT>/.onboard-audit/analyze.md` with sections:
    ## Summary (3 bullet points)
    ## Architecture risks
    ## Dette technique
    ## Patterns (good + bad)
    ## Stale code suspects
    ## Test coverage blind spots
    ## Config drift
    ## Cross-references (vers graphify-out/GRAPH_REPORT.md si présent)
  Max 500 lignes. Priorise les éléments avec preuve concrète (fichier:ligne).
  """
)

Attendre la fin. Vérifier que .onboard-audit/analyze.md existe et est non vide.

STEP 6 — AUDIT DISPATCH selon archétype

Lire le bloc audit_stack: du fichier ~/.claude/lib/project-archetypes/<archetype>.md.

Mapping audit_stack entry → action :

Entry	Action	Livraison
`analyze`	Déjà fait en STEP 5	L3a
`code-clean`	Spawn subagent `code-cleaner` (audit-only)	L3a
`cso`	Si gstack ON → Skill(cso). Sinon → Agent general-purpose avec checklist OWASP + deps audit	L3a
`doc`	Spawn subagent `doc-syncer` (auto-mode OFF, report-only)	L3a
`seo`	Subagents seo-analyzer + geo-analyzer en parallèle	L3b
`design-review`	Si gstack ON → Skill design-review. Sinon → Agent ui-ux-pro-max context statique	L3b
`perf`	Si gstack ON + URL → Lighthouse. Sinon → static bundle audit	L3b
`a11y`	Si gstack ON + URL → axe-core. Sinon → Agent static a11y audit	L3b

STEP 6 dispatch (L3a portion)

Lancer EN PARALLÈLE (un seul message, plusieurs Agent calls) les audits correspondant aux entrées de audit_stack: qui sont en L3a (code-clean, cso, doc).

Dispatch code-cleaner (si `code-clean` dans audit_stack)

Agent(
  subagent_type="code-cleaner",
  description="Onboard — code-clean audit only",
  prompt="""
  AUDIT-ONLY mode — NO fixes, NO refactoring, NO file modifications.
  Target: <PROJECT_ROOT>. ARCHETYPE: <archetype>.
  Produce a report covering:
    1. Dead code (unused exports, unreachable branches, commented-out blocks)
    2. Style violations (per project linter config if present, else per global CLAUDE.md rules)
    3. Structural issues (god files, overly deep nesting, poor separation of concerns)
    4. Stale imports / unused deps (package.json vs actual imports, pyproject.toml vs imports)
    5. Duplicate code (copy-paste patterns)
    6. Outdated deps (if manifest present — list; do NOT run npm audit unless safe)
  Write the report to `<PROJECT_ROOT>/.onboard-audit/code-clean.md` with sections matching above.
  Each issue cite fichier:ligne. Prioritise par Sévérité (Critique/Haute/Moyenne/Basse).
  Max 500 lignes. Do NOT spawn sub-subagents (refactorer). Pure audit.
  """
)

Dispatch security — `cso` (si `cso` dans audit_stack)

Décision selon plugin state :

# gstack actif ?
bash $HOME/.claude/lib/toggle-external.sh list 2>/dev/null | grep -E "^gstack\s+(enabled|on)"

gstack ON → invoquer le skill cso via Skill tool en lui passant le contexte archétype :
```
Skill(skill="cso", args="comprehensive --report-only --output .onboard-audit/cso.md --archetype <archetype> --context-file .onboard-audit/archetype-context.md")
```
Note : le skill cso écrit son rapport lui-même ; on redirige via --output si supporté, sinon on capture la sortie et on écrit .onboard-audit/cso.md dans le skill parent. Les flags --archetype / --context-file informent le skill même s'il ne les consomme pas nativement (lisibilité + compat future).

gstack OFF → fallback via Agent general-purpose, prompt archetype-adaptive :

Agent(
subagent_type="general-purpose",
description="Onboard — security audit fallback (archetype-adaptive)",
prompt="""
READ-ONLY security audit. No file modifications.
Target: <PROJECT_ROOT>. ARCHETYPE: <archetype>. Category: <category>. Stack: <stack>.

STEP 0 — Lire <PROJECT_ROOT>/.onboard-audit/archetype-context.md.
Il contient : le profil de l'archétype (category, public, database), les "Implications" (dont
"Surface sécurité"), et les "Typical pain points" applicables. **Tous les checks ci-dessous
doivent être filtrés/priorisés selon ce contexte — ne pas chercher du XSS dans du firmware.**

Checks UNIVERSELS (toujours, quel que soit l'archétype) :
  1. Secrets en repo : git grep -iE '(API_KEY|TOKEN|PASSWORD|SECRET|PRIVATE_KEY)\\s*=' -- ':!*.md'
  2. `.env` committé ? `.env.example` présent avec placeholders ?
  3. Dépendances avec failles connues (npm audit / pip-audit / cargo audit / govulncheck — non-destructif)
  4. Runtime obsolète (Node <20, Python <3.10, PHP <8.2, Go <1.21, Rust MSRV documenté ?)
  5. Présence d'un SECURITY.md (politique disclosure)
  6. Si Dockerfile : image de base pinnée (pas `latest`), user non-root, multi-stage ?

Checks CONDITIONNELS (appliquer SI et seulement si la catégorie matche) :

─── category ∈ {framework, api, ecommerce, cms} (web surface) ───
  - SQL injection : chaînes concaténées dans queries (grep 'SELECT.*\\+', f-strings SQL, string interp)
  - XSS : dangerouslySetInnerHTML, v-html, innerHTML, `{{{...}}}`, template render non-échappé
  - AuthN/AuthZ : tokens en dur, JWT sans signature vérifiée, sessions sans flags Secure/HttpOnly/SameSite
  - CORS : `Access-Control-Allow-Origin: *` sur routes auth
  - CSP : présence d'un header / meta, pas de `unsafe-inline` / `unsafe-eval`
  - HTTPS : redirect http→https forcé, HSTS header, cookies avec flag Secure
  - CSRF : tokens anti-CSRF sur forms mutants (POST/PUT/DELETE)
  - Rate limiting sur endpoints sensibles (login, reset password, signup)
  - Path traversal : `../` non validé sur uploads / file serving

─── category == embedded (firmware / MCU) ───
  - Buffer overflows : `strcpy`, `strcat`, `sprintf`, `gets` sans bounds check
  - `malloc` dans ISR ou section critique
  - Stack size suffisant ? Watchdog activé ?
  - Secure Boot activé ? Firmware signing ?
  - OTA : signature vérifiée avant flash ?
  - JTAG / SWD fuses disable en prod ?
  - Debug logs (`printf` UART) actifs en release ?
  - Secrets / keys compilés en dur (extractibles par flash dump) ?
  - Flags compilateur : `-Wall -Wextra -Werror` + `-fstack-protector-strong` ?
  - Downgrade attacks : version min du firmware vérifiée avant OTA ?

─── category == library (package réutilisable) ───
  - Supply chain : deps transitives avec CVEs (audit strict)
  - Exports publics : leakage depuis internes (`export *` abusif, __init__.py qui ré-exporte tout) ?
  - Types lâches : `any` en TypeScript sur surface publique, `py.typed` manquant, `#[non_exhaustive]` oublié sur enums Rust publics
  - Semver : changelog cohérent ? Breaking changes documentés ?
  - SECURITY.md disclosure policy obligatoire

─── category == cli ───
  - Argument injection : `exec`/`spawn`/`subprocess` avec interpolation d'args user sans quoting
  - Path traversal : paths user-fournis sans normalisation
  - Privilèges : nécessite sudo/admin ? Scope minimal ?
  - Binaires deps (git, docker, ffmpeg) : version vérifiée avant exec ?
  - Signal handling : SIGINT → cleanup propre (pas de state corruption) ?

─── category == infra (terraform / docker-compose / k8s) ───
  - Credentials hardcodées dans `.tf`, `docker-compose.yml`, helm values
  - Terraform state committé (`terraform.tfstate`, `*.tfstate.backup`) ?
  - IAM policies avec wildcards (`"Action": "*"`, `"Resource": "*"`) ?
  - Secrets : secret manager (Vault/KMS/SSM) vs env var brute ?
  - Network : security groups / firewalls ouverts (0.0.0.0/0) ?

─── category == data-science (notebooks) ───
  - `.ipynb` committés avec outputs contenant creds DB ou PII
  - Datasets avec PII non anonymisées committés
  - Notebook en prod (`.ipynb` exécuté directement) vs extraction en module ?

─── category == desktop (Electron / Tauri) ───
  - `nodeIntegration: true` + `contextIsolation: false` = RCE via XSS renderer
  - `webSecurity: false` — ne jamais désactiver
  - IPC : channels non validés côté main
  - Auto-updater : signature vérifiée ?

Pour chaque issue trouvée : fichier:ligne, sévérité (Critique/Haute/Moyenne/Basse), rattachement
explicite au pain point de l'archétype si c'est un mapping direct.

Write report to `<PROJECT_ROOT>/.onboard-audit/cso.md` avec :
  - En-tête : "ARCHETYPE-ADAPTIVE mode — checklist tuned for <archetype> (<category>). gstack cso skill not active."
  - Section "Universal" puis sections conditionnelles effectivement exécutées
  - Sections non applicables : ne PAS les inclure (pas de "N/A — skip")
Max 600 lignes (plus large que default pour accommoder les checks archetype-spécifiques).
"""
)

Dispatch doc-syncer (si `doc` dans audit_stack)

Agent(
  subagent_type="doc-syncer",
  description="Onboard — doc drift audit only",
  prompt="""
  REPORT-ONLY mode — NO edits, NO auto-sync.
  Target: full project at <PROJECT_ROOT>.
  Scope:
    1. README drift (build/test commands, install steps, usage examples vs actual code)
    2. CLAUDE.md drift (stack versions, commands)
    3. CHANGELOG.md freshness (last entry vs last commit date)
    4. INSTALL/CONFIGURE/USAGE/CONTRIBUTING drift if present
    5. Feature delta (feature added in code but not documented, feature documented but removed)
    6. Inline comments (JSDoc/docstring/rustdoc/godoc) coverage for public API
  Cross-reference with git log last 6 months.
  Write report to `<PROJECT_ROOT>/.onboard-audit/doc.md` with sections above,
  each drift cite file:line + commit-hash + date.
  Max 500 lignes.
  """
)

Après les 3 dispatches

Attendre la fin des 3 subagents. Vérifier que les 3 fichiers existent et sont non vides :

for f in .onboard-audit/{code-clean,cso,doc}.md; do
  [ -s "$f" ] && echo "OK $f" || echo "MISSING $f"
done

Si un subagent a échoué : afficher l'erreur, proposer à l'utilisateur :

⚠️  Audit <nom> a échoué : <erreur>
Options :
  A) Retry
  B) Skip et continuer (rapport partiel en L4)
  C) Abort onboard

STEP 6 dispatch (L3b portion) — seo/geo + design + perf + a11y

Pré-check ressources navigateur :

# gstack actif ?
bash $HOME/.claude/lib/toggle-external.sh list 2>/dev/null | grep -E "^gstack\s+(enabled|on)"
# URL déployée fournie par l'utilisateur en STEP 3 ?
echo "${BRIEF_deployed_url:-none}"
# dev server launchable ?
grep -E '"(dev|start|serve)":' package.json 2>/dev/null | head -3

Lancer EN PARALLÈLE les audits présents dans audit_stack: de l'archétype (multiples Agent calls dans un seul message) :

Dispatch SEO+GEO (si `seo` dans audit_stack)

Le skill /seo appelle déjà seo-analyzer + geo-analyzer en parallèle, mais pour garder la cohérence "tout dans .onboard-audit/", on invoque les deux agents directement :

Agent(
  subagent_type="seo-analyzer",
  description="Onboard — SEO audit (classical engines)",
  prompt="""
  AUDIT-ONLY mode — NO edits, NO auto-fixes. Target: <PROJECT_ROOT>.
  Classical search engines: Google, Bing, DuckDuckGo.
  Archetype: <archetype>. Public: <true/false>. Deployed URL (si fournie): <url or none>.
  Coverage:
    - meta (title, description, OG, Twitter Card)
    - robots.txt, sitemap.xml, canonical, hreflang
    - JSON-LD / Schema.org classical
    - Core Web Vitals (estimé si pas d'URL live)
    - headings hierarchy, alt attrs, images formats
    - i18n / lang attribute
  Si URL live fournie AND gstack actif: utiliser les outils live.
  Sinon: audit statique sur le code (HTML templates, Astro pages, Next Metadata API, etc.).
  Write report to `<PROJECT_ROOT>/.onboard-audit/seo.md`.
  Structure sections par catégorie, chaque issue cite fichier:ligne + sévérité.
  Max 500 lignes.
  """
)

Agent(
  subagent_type="geo-analyzer",
  description="Onboard — GEO audit (AI engines)",
  prompt="""
  AUDIT-ONLY mode — NO edits, NO auto-fixes. Target: <PROJECT_ROOT>.
  AI search engines: ChatGPT, Perplexity, Claude, Gemini, Google AI Overviews, Copilot.
  Archetype: <archetype>. Public: <true/false>. Deployed URL: <url or none>.
  Coverage:
    - AI crawler directives in robots.txt (GPTBot, ClaudeBot, PerplexityBot, etc.)
    - llms.txt / llms-full.txt presence and quality
    - Schema.org types GEO-optimised (QAPage, Speakable, HowTo, Person+Article, Organization graph)
    - Entity SEO (Wikidata QID, sameAs, @id consistency, Knowledge Panel signals)
    - Content shape for LLM extraction (Definition Lead, TL;DR, Q→A structure, citable stats, freshness)
    - AI visibility monitoring recommendations
  Write report to `<PROJECT_ROOT>/.onboard-audit/geo.md`.
  Max 500 lignes. Cite fichier:ligne, sévérité.
  """
)

SEO+GEO skip rules:

Si archetype.public == false ET seo dans audit_stack → ne devrait pas arriver, mais si oui : skip silencieusement, .onboard-audit/seo.md et geo.md non créés.
Si projet a 0 contenu HTML/template (ex: React SPA public) → lancer quand même mais signaler en haut du rapport : "⚠️ SPA détectée — SEO intrinsèquement limité, voir archetype warning dans .onboard-audit/archetype-warnings.md".

Dispatch design-review (si `design-review` dans audit_stack)

Cas gstack ON + URL live OU dev server launchable :

Skill(
  skill="gstack:design-review",
  args="--url <url or http://localhost:PORT> --output .onboard-audit/design.md --audit-only"
)

Si le skill ne supporte pas --output, capturer la sortie et écrire à la main vers .onboard-audit/design.md.

Cas gstack OFF OU pas de site déployable (ex: react-spa sans dev server):

Agent(
  subagent_type="general-purpose",
  description="Onboard — static design review fallback",
  prompt="""
  AUDIT-ONLY mode — NO edits. Static design review du code UI.
  Target: <PROJECT_ROOT>. Archetype: <archetype>.
  Context: ui-ux-pro-max plugin state = <active/inactive>.
  Si ui-ux-pro-max actif : lire ses guidelines depuis les skills ui-ux-pro-max.
  Coverage (static, depuis code uniquement) :
    1. Design system (tokens : colors, spacing, radius, typography) — présent ou absent ?
       Cohérence : toutes les couleurs sont-elles dans les tokens ou hardcodées dans les composants ?
    2. Composants réutilisables vs duplication (Button en 5 variantes dispersées ?)
    3. Dark mode support ? Responsive (breakpoints) ? État de l'a11y dans les composants ?
    4. Animations (présence, durées < 300ms, ease-out par défaut — cf. emil-design-eng si actif)
    5. État vide / loading / error dans les composants
    6. Typography hiérarchie (combien de tailles différentes ? trop ?)
    7. Couleurs : contrastes ratio (AA minimum = 4.5:1 pour texte)
    8. Interactions : focus visible, hover states, disabled states
    9. Micro-interactions (billboard design ? transform scale(0.97) on :active ?)
  Write report to `<PROJECT_ROOT>/.onboard-audit/design.md`.
  Note en haut : "STATIC MODE — gstack inactif ou pas de dev server ; audit limité au code."
  Max 500 lignes. Cite fichier:ligne.
  """
)

Skip rules:

Si design-review pas dans audit_stack (backend, CLI, lib) → skip silencieusement.
Si archetype frontend mais pas de composants détectés (tout HTML pur) → noter "pure HTML — design review réduit aux sections 3-8".

Dispatch perf (si `perf` dans audit_stack)

Cas gstack ON + URL live :

Skill(
  skill="gstack:browse",
  args="--lighthouse --url <url or http://localhost:PORT> --output .onboard-audit/perf-lighthouse.json"
)

Puis parser le JSON Lighthouse (scores perf/a11y/bp/seo/pwa + top opportunities) → écrire .onboard-audit/perf.md.

Cas gstack OFF OU pas d'URL :

Agent(
  subagent_type="general-purpose",
  description="Onboard — static perf audit",
  prompt="""
  AUDIT-ONLY mode — NO edits.
  Target: <PROJECT_ROOT>. Archetype: <archetype>.
  Static perf audit (pas de browser) :
    1. Bundle analyzers config présent ?
       - Next: `@next/bundle-analyzer` dans deps ?
       - Vite: `rollup-plugin-visualizer` ?
       - Webpack: `webpack-bundle-analyzer` ?
       Si NON, recommander l'install + usage.
       Si OUI et script existe, tenter execution NON-DESTRUCTIVE si safe (produit un HTML/rapport, pas de modif code).
    2. Dependencies taille — identifier les grosses deps (> 100kb) depuis package-lock.json / pnpm-lock.yaml.
    3. Images dans `public/` ou `assets/` : compter non-optimisées (PNG/JPG > 200kb sans WebP/AVIF variant).
    4. Polices web : Google Fonts via <link> (blocking) vs self-hosted ? font-display: swap ?
    5. Code splitting : dynamic imports () présents ? Chaque route a son chunk ?
    6. Lazy loading : `loading="lazy"` sur les <img> ? IntersectionObserver pour composants lourds ?
    7. React-specific: React.memo / useMemo / useCallback overuse ou sous-utilisé ?
    8. CSS: quantité totale, CSS-in-JS runtime cost, unused CSS ?
    9. SSR/SSG/ISR strategy (si Next/Astro) — cohérente avec le contenu ?
    10. Core Web Vitals estimés à partir du code (TTFB impossible, mais LCP/CLS inférables).
  Write report to `<PROJECT_ROOT>/.onboard-audit/perf.md`.
  Note "STATIC MODE" si sans browser.
  Max 500 lignes.
  """
)

Dispatch a11y (si `a11y` dans audit_stack)

Cas gstack ON + URL live :

Skill(
  skill="gstack:browse",
  args="--axe --url <url> --output .onboard-audit/a11y-axe.json"
)

Parser axe-core résultats (violations, incomplete, inapplicable, passes) → .onboard-audit/a11y.md.

Cas statique :

Agent(
  subagent_type="general-purpose",
  description="Onboard — static a11y audit",
  prompt="""
  AUDIT-ONLY mode — NO edits.
  Target: <PROJECT_ROOT>. Archetype: <archetype>.
  Static a11y audit (WCAG 2.1 AA + RGAA 4.1 France) :
    1. <html lang="…"> présent sur toutes les pages ?
    2. Landmarks (header/nav/main/footer/aside) utilisés ou encore div-soup ?
    3. Heading hierarchy (h1 unique, pas de saut h1→h3) — scanner tous les templates.
    4. Images : <img> ont tous un alt ? alt décoratif = "" ? alt redondant avec caption ?
    5. Formulaires : chaque <input> a un <label>, aria-label, ou aria-labelledby ?
    6. Boutons vs liens : <a> sans href, <div onClick>, <span role="button"> → red flags.
    7. Focus visible : outline:none sans :focus-visible alternative ? tabindex="-1" abusif ?
    8. Couleurs : contrastes (peut se vérifier depuis tokens si présents).
    9. Animations : prefers-reduced-motion respecté ?
    10. ARIA : live regions pour toasts/notifs, role="dialog" pour modals avec focus trap ?
    11. Keyboard : navigation sans souris possible sur features critiques (depuis revue statique event handlers) ?
    12. Screen reader affordances : visually-hidden class, aria-describedby ?
  Contexte France : RGAA 4.1 critères applicables + déclaration d'accessibilité obligatoire (sites publics > seuils).
  Write report to `<PROJECT_ROOT>/.onboard-audit/a11y.md`.
  Note "STATIC MODE" si pas d'axe-core.
  Max 500 lignes. Cite fichier:ligne.
  """
)

Après tous les dispatches L3b

Vérification :

for f in .onboard-audit/{seo,geo,design,perf,a11y}.md; do
  [ -f "$f" ] && echo "OK $f ($(wc -l < "$f") lignes)" || echo "— $f (skipped, archétype n'a pas cet audit)"
done

STEP 7 — SYNTHÈSE dans `.claude/audits/`

À partir des rapports bruts dans .onboard-audit/, générer 4 fichiers structurés dans .claude/audits/.

Spawn un subagent synthétiseur (isolé, chargé uniquement du contenu de .onboard-audit/) :

Agent(
  subagent_type="general-purpose",
  description="Onboard — synthèse vers .claude/audits/",
  prompt="""
  Lire tous les fichiers de <PROJECT_ROOT>/.onboard-audit/ :
    - analyze.md, code-clean.md, cso.md, doc.md (toujours)
    - seo.md, geo.md, design.md, perf.md, a11y.md (si présents)
  Contexte : archetype=<archetype>, public=<bool>, stack=<stack>, brief_interview=<summary>.

  Produire 4 fichiers dans <PROJECT_ROOT>/.claude/audits/ :

  ═══ 1. .claude/audits/ONBOARD_REPORT.md — synthèse exécutive ═══
  Structure :
    # Onboard Report — <project_name>
    ## Profile
      - Archétype: <name> (<category>)
      - Stack: <lang+framework+db+hosting>
      - Public: <yes/no>
      - Taille: <lines of code / files count>
    ## Scores par domaine (0-100, calculés depuis le nombre d'issues par sévérité)
      | Domaine         | Score | Forces majeures | Problèmes majeurs |
      | analyze (dette) | 72    | bonne séparation MVC | god file src/foo.js |
      | code-clean      | ...   |
      | cso (sécu)      | ...
      | doc             | ...
      | seo (si public) | ...
      | geo (si public) | ...
      | design          | ...
      | perf            | ...
      | a11y            | ...
    ## Top 5 priorités (choisies depuis .claude/audits/AUDIT_ISSUES.md par score sévérité × impact projet)
      1. [P0 Critique] <titre> — <domaine> — <impact en 1 phrase>
      2. ...
    ## Prochaines étapes (pointeurs vers les 3 autres fichiers)

  ═══ 2. .claude/audits/AUDIT_GOOD.md — ce qui va ═══
  Inventaire positif par domaine. Ce qu'il faut PROTÉGER en modifiant le reste.
  Structure:
    # Audit — Ce qui va
    ## Dette technique
      - <pattern sain repéré> (ex: "services layer bien isolé de l'API")
    ## Sécurité
      - <forces>
    ## [domaine par domaine]

  ═══ 3. .claude/audits/AUDIT_ISSUES.md — ce qui ne va pas ═══
  Listing par sévérité descendante (Critique → Basse).
  Structure:
    # Audit — Ce qui ne va pas
    ## Critique
      ### [domaine] <titre>
      - Fichier(s): path:line
      - Preuve: <extrait ou description concrète>
      - Impact: <une phrase>
      - Référence: .onboard-audit/<source>.md
    ## Haute
    ## Moyenne
    ## Basse
  Ne pas inventer, ne citer QUE ce qui est dans .onboard-audit/.

  ═══ 4. .claude/audits/AUDIT_PROPOSALS.md — propositions ═══
  Pour CHAQUE issue Critique et Haute du fichier ISSUES : proposer au minimum 2 options,
  avec tradeoffs. Pour les issues Moyennes : 1 option suffit.
  Structure:
    # Audit — Propositions d'amélioration
    ## [P0 Critique] <titre issue>
      Contexte: <rappel court>
      Option A — <titre> :
        - Approche: <1-3 phrases>
        - Coût: <estimation S/M/L>
        - Risque: <faible/moyen/élevé>
        - Gain: <phrase>
      Option B — <titre> :
        ...
      Option C (optionnel) :
        ...
      **Recommandation**: Option <X> — <justification 1-2 phrases>
    ## [P1 Haute] ...
    ## [P2 Moyenne] ...

  Règles de qualité :
    - Chaque fichier max 800 lignes (split si dépasse, jamais tronquer le contenu crucial)
    - Citer TOUTES les sources .onboard-audit/ utilisées (preuve traçable)
    - Pas de conseil générique — toujours relier à une preuve concrète
    - Radical honesty : si un audit révèle une faille structurelle majeure (ex: SPA public),
      le dire clairement en P0 Critique, ne pas édulcorer
  """
)

Vérifier que les 4 fichiers .claude/audits/ONBOARD_REPORT.md, .claude/audits/AUDIT_GOOD.md, .claude/audits/AUDIT_ISSUES.md, .claude/audits/AUDIT_PROPOSALS.md existent et sont non vides.

STEP 8 — VALIDATION GATE ★ MANDATORY STOP

Afficher à l'utilisateur :

═══ ONBOARD — RAPPORT PRÊT ═══

Archétype: <name>
Stack: <stack>
Scores: dette:<X> · sécu:<X> · doc:<X>  [· seo:<X> · geo:<X> · design:<X> · perf:<X> · a11y:<X>]

📂 Fichiers produits dans .claude/audits/ :
  - ONBOARD_REPORT.md    (synthèse exécutive)
  - AUDIT_GOOD.md        (ce qui va)
  - AUDIT_ISSUES.md      (ce qui ne va pas, par sévérité)
  - AUDIT_PROPOSALS.md   (propositions avec options + tradeoffs)

TOP 5 PRIORITÉS :
  1. [P0 Critique] <titre>
  2. [P0 Critique] <titre>
  3. [P1 Haute]    <titre>
  4. [P1 Haute]    <titre>
  5. [P2 Moyenne]  <titre>

Prochaine étape : générer .claude/tasks/TODO.md depuis .claude/audits/AUDIT_PROPOSALS.md approuvé.

Options :
  A) Lire d'abord les 4 fichiers, je reviens te le dire (STOP)
  B) Tout est OK, génère .claude/tasks/TODO.md depuis toutes les propositions recommandées
  C) Je veux éditer .claude/audits/AUDIT_PROPOSALS.md avant de générer .claude/tasks/TODO.md (indiquer ce à changer)
  D) Réduire le scope — ne garder que P0 Critique dans .claude/tasks/TODO.md
  E) Abort — je n'utilise pas le backlog auto

Choix ? (A / B / C / D / E)

STOP. Attendre la réponse.

A → stop ici, l'utilisateur relira et reviendra avec /onboard continue.
B → continuer STEP 9 avec toutes les recommandations.
C → demander les changements spécifiques, les appliquer dans .claude/audits/AUDIT_PROPOSALS.md, puis re-présenter la gate.
D → continuer STEP 9 avec seulement les P0.
E → arrêter sans générer .claude/tasks/TODO.md, print "Onboard rapport figé dans .claude/audits/ — tu peux t'en servir à la main ensuite."

STEP 9 — BACKLOG → .claude/tasks/TODO.md

Lire .claude/audits/AUDIT_PROPOSALS.md (avec les "Recommandations" sélectionnées par l'utilisateur). Pour chaque proposition recommandée, générer une entrée dans .claude/tasks/TODO.md :

Format :

# TODO — onboard backlog (<date>)

<!-- Généré par /onboard — une entrée par proposition approuvée.
     Format: - [ ] [Priorité] [/skill] — description — fichiers estimés -->

## P0 — Critique
- [ ] [P0] [/hotfix] — <titre>
      Fichiers: <paths>
      Source: .claude/audits/AUDIT_PROPOSALS.md § "<titre>"
      Option recommandée: <A/B/C>
- [ ] [P0] [/bugfix] — <titre>
      Fichiers: ...

## P1 — Haute
- [ ] [P1] [/feat] — <titre>
- [ ] [P1] [/ship-feature] — <titre>

## P2 — Moyenne
- [ ] [P2] [/code-clean] — <titre>
- [ ] [P2] [/refactor] — <titre>

## P3 — Basse
- [ ] [P3] [...] — ...

## Post-MVP (non-priorisé, backlog)
- [ ] ...

Règles de sélection du skill recommandé :

Type de proposition	Skill
Typo, CSS, config, import manquant (1-2 fichiers, cause évidente)	`/hotfix`
Bug avec investigation (plusieurs fichiers)	`/bugfix`
Petite feature (1-5 fichiers)	`/feat`
Grosse feature (design, multi-fichiers, architecture)	`/ship-feature`
Dette technique (dead code, style, dupes)	`/code-clean`
Refactoring sans changement de comportement	`/refactor`
Audit SEO/GEO à re-lancer après corrections	`/seo` ou `/geo`
Audit docs à re-sync après changement	`/doc`

Ne PAS écraser .claude/tasks/TODO.md s'il contient déjà du contenu utilisateur : append avec un séparateur :

<contenu existant>

---
# Onboard backlog (généré le YYYY-MM-DD)

<nouveau contenu>

Print :

✅ .claude/tasks/TODO.md mis à jour — <N> tâches ajoutées (<P0>/<P1>/<P2>/<P3>)
Pour démarrer : lire .claude/tasks/TODO.md, choisir une tâche P0, lancer le /skill indiqué.

RULES

NO skipping STEP 0, 1, 2 — ils sont obligatoires.
NO audit agressif : chaque subagent doit recevoir "AUDIT-ONLY, no file modifications".
STEP 1 doit proposer un override force-archetype:<name> si l'utilisateur sait déjà.
Monorepo : toujours demander le mode (A/B/C) avant STEP 2.
Si CLAUDE.md existe : le lire, ne pas l'écraser sans fusion après STEP 3.
STEP 3 : ne redemande jamais ce qui est déjà dans README ou manifests.
STEP 3.5 : si ctx7 absent + fast-libs, WARN mais ne bloque pas.
STEP 4 : skip si complexity < 30% ou graph récent déjà présent.
STEP 5-6 : subagents isolés (Agent tool avec subagent_type spécifique) — pas de contexte partagé entre les audits. Chaque subagent écrit son rapport dans .onboard-audit/<name>.md.
STEP 6 dispatches parallélisables : regrouper dans un seul message Agent multi-calls.
.onboard-audit/ gitignoré automatiquement — ne jamais commiter.
Si un subagent échoue : proposer retry/skip/abort, ne pas auto-retry silencieusement.

FINAL OUTPUT

ONBOARD COMPLETE: <project name>
ARCHETYPE    : <name> (confiance: <niveau>)
STACK        : <stack>
CONFIG       : ✅ CLAUDE.md, settings.json, .claudeignore, .claude/{tasks,memory,audits}/
CTX7 CACHE   : ✅ [libs] | ⚠️ not installed | — N/A
GRAPHIFY     : ✅ graphify-out/ | ⚠️ not installed | — skipped (simple)
AUDITS       :
  ✅ dette technique     (.onboard-audit/analyze.md + code-clean.md)
  ✅ sécurité            (.onboard-audit/cso.md)
  ✅ docs drift          (.onboard-audit/doc.md)
  ✅ SEO + GEO           (.onboard-audit/seo.md + geo.md)       [si public]
  ✅ design UI/UX        (.onboard-audit/design.md)              [si frontend]
  ✅ performance         (.onboard-audit/perf.md)
  ✅ accessibilité       (.onboard-audit/a11y.md)                [si frontend]

SYNTHÈSE     :
  ✅ .claude/audits/ONBOARD_REPORT.md       (exécutif)
  ✅ .claude/audits/AUDIT_GOOD.md
  ✅ .claude/audits/AUDIT_ISSUES.md         (par sévérité)
  ✅ .claude/audits/AUDIT_PROPOSALS.md      (options + tradeoffs)
  ✅ .claude/tasks/TODO.md                  (backlog priorisé avec skill recommandé)

NEXT STEPS   :
  1. Ouvrir .claude/audits/ONBOARD_REPORT.md — overview complète
  2. Démarrer par la première tâche P0 de .claude/tasks/TODO.md avec le skill indiqué
  3. /onboard add gsd — générer ROADMAP.md pour multi-session si besoin
  4. .onboard-audit/ peut être supprimé (raw data consommée en synthèse)

SKILL.md 41 KB Riwayat Mentahan