Best Version — ai-layer-kit/USAGE.md

Score: 12/12 Iteration: #1 Date: 2026-05-26 Snapshot of the version that achieved the highest score against eval-criteria.md.

How to use the AI-Layer Starter Kit

Two audiences: (A) the production line worker integrating the kit, (B) the talent owner / client running the delivered product.

A. Production line integration (Pablo, during assembly)

Add these steps to assembly Phase D Template Library and Phase G Documentation (see assembly-checklist-template.md).

Phase D — Embed the kit

Copy production-lines/digital-talent/templates/ai-layer-kit/ → {client-repo}/.claude/ai-layer/.
Move CLAUDE-root.md to the repo root as CLAUDE.md. Fill the {placeholders}.
For each role/domain in the talent, copy CLAUDE-domain-template.md to .claude/CLAUDE-{domain}.md.
Install the stop-hook:
- Copy hooks/stop-self-improve.sh → {repo}/.claude/hooks/stop-self-improve.sh
- Merge this block into {repo}/.claude/settings.json (the full source is hooks/stop-self-improve.json):
```
"hooks": {
  "Stop": [{
    "matcher": "*",
    "hooks": [{
      "type": "command",
      "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/stop-self-improve.sh"
    }]
  }]
}
```
For each skill in .claude/commands/*.md, add a paths: line to its frontmatter. Convention in 4 lines (full spec in skills/SCOPING.md):
- Domain-specific skill → list 1–3 globs where it's relevant (e.g., content-in/legal/**)
- Cross-cutting skill (e.g., /ci, session-close) → omit paths: (intentional global load)
- Never use paths: ['**'] — equivalent to global, defeats the purpose
- Smoke-test: open a file outside scope, verify the skill is unavailable
Copy agents/explorer.md → {repo}/.claude/agents/explorer.md.
If the talent benefits from AST search, install codebase-search MCP:
- ⚠ Sync with RD-0031 BEFORE starting this step. The toolkit-catalog distribution covers most of this gap; doing custom work here will likely be superseded.
- Destination: only one file is added to the client repo — {repo}/.mcp.json (the entry block, see mcp/codebase-search/README.md for the snippet). The reference doc itself stays in .claude/ai-layer/mcp/.
- Document install steps in the talent's README.

Phase G — Document the kit for the client

Add a section « Qu'est-ce qui tourne dans votre talent ? » (or English equivalent) to the user guide. Use the template client-facing-overview.md (Section B below).

Acceptance — assembly QA (Quinn, Stage 5)

Fresh-generated talent has all 5 components without manual fix-up
Client can git clone and run autonomously (no factory dependency)
Stop-hook captures at least one lesson in a smoke-test session
Scoped skills don't load outside their paths: (test by opening a file outside scope and verifying skill is unavailable)
Explorer subagent cannot write (negative test — attempt a Write call, must be refused)
User guide contains the 5-component overview from USAGE.md Section B verbatim (or translated to the talent's language) — verify by diff

B. Client-facing overview (template — ship with every talent)

Drop this in the talent's user-guide.md under « Qu'est-ce qui tourne dans votre talent ? » (translate to talent language).

Votre digital talent ne tourne pas sur un seul prompt magique. Il embarque un harnais standard (le « AI-Layer kit ») qui le rend stable, traçable et auto-améliorant. Voici les cinq pièces, en clair :

Mémoire en couches — Le talent garde un fichier d'instructions lean au sommet, et un par domaine métier (juridique, finance, opérations…). Quand vous travaillez sur un sujet, seul le bon contexte est chargé. Conséquence : réponses plus précises, moins de bruit, factures de tokens plus basses.

Apprentissage en fin de session — À la fin de chaque session, le talent écrit ce qu'il a appris dans sa mémoire (un journal automatique sous memory/lessons/). La fois suivante, il s'en souvient. Aucun ré-entraînement, aucune commande manuelle.

Compétences ciblées par dossier — Chaque compétence ne se déclenche que dans les dossiers où elle est pertinente. Vous ne recevez plus de suggestions de skill « rédaction d'email » quand vous éditez un fichier de configuration.

Explorer en lecture seule (un sous-agent est une instance auxiliaire du talent, dédiée à une tâche bornée) — Pour comprendre un grand répertoire, le talent envoie un sous-agent qui peut lire mais ne peut rien écrire. Aucun risque de modification accidentelle.

Recherche par structure de code (via un connecteur MCP — un protocole standard qui permet au talent d'utiliser des outils externes en sécurité) — Pour les talents touchant à du code : « où est défini X ? », « qui appelle Y ? », « donne-moi le plan de ce fichier ». Recherche structurée, pas du grep aveugle.

Ce harnais est notre propriété, copié à l'identique dans chaque talent. Vous l'exécutez chez vous, en autonomie, sans dépendance à notre infrastructure. Si vous voulez en changer un composant (par exemple, pointer le stop-hook vers votre propre journal d'apprentissage), tout est en clair dans .claude/ai-layer/.

C. Quick reference — file map after assembly

{client-repo}/
├── CLAUDE.md                              ← lean root (filled from CLAUDE-root.md)
├── .claude/
│   ├── CLAUDE-{domain-1}.md               ← per-role/domain (from CLAUDE-domain-template.md)
│   ├── CLAUDE-{domain-2}.md
│   ├── ai-layer/                          ← full kit copy — reference, never edit live
│   │   ├── README.md
│   │   ├── USAGE.md
│   │   ├── CLAUDE-root.md                 ← original template (for re-init)
│   │   ├── CLAUDE-domain-template.md
│   │   ├── hooks/
│   │   │   ├── README.md
│   │   │   ├── stop-self-improve.sh
│   │   │   └── stop-self-improve.json
│   │   ├── skills/
│   │   │   ├── SCOPING.md                 ← paths: convention
│   │   │   └── example-scoped-skill.md
│   │   ├── agents/
│   │   │   └── explorer.md
│   │   └── mcp/
│   │       └── codebase-search/README.md  ← wiring spec (sync with RD-0031)
│   ├── hooks/
│   │   └── stop-self-improve.sh           ← live copy (executed by Claude Code)
│   ├── agents/
│   │   └── explorer.md                    ← live copy
│   ├── commands/                          ← skills, each with paths: frontmatter
│   └── settings.json                      ← references the hook
├── .mcp.json                              ← codebase-search entry (only if installed)
└── memory/
    └── lessons/                           ← stop-hook appends YYYY-MM.md here