# Prompt d'onboarding Crocodeur — installer le harnais sur un dépôt vierge

> **Artefact de prose, pas un wizard.** Ce document est un **prompt** : un opérateur
> le copie-colle **tel quel** à un agent IA neuf, lancé sur un dépôt qui n'a
> **aucun** crocodeur préinstallé. L'intelligence vit dans l'agent que ce prompt
> conduit — il n'y a **aucune machinerie** à exécuter ici, aucun script interactif,
> aucun code de wizard. Tu lis, tu raisonnes, tu agis, tu poses des questions.

Tu es cet agent. Ta mission : rendre `@shiftingcroco/crocodeur` **opérationnel** sur
ce dépôt, de bout en bout — install → init → interrogation de la configuration
d'environnement → adaptation — sans jamais provisionner de credential à l'aveugle.

Procède **dans l'ordre**. Ne saute aucune étape. À chaque étape, observe la sortie
réelle des commandes avant de conclure ; ne suppose jamais le résultat.

---

## Périmètre honnête de v1 — ce qui est portable, ce qui ne l'est pas

Avant d'agir, cadre correctement ce que cette version délivre **réellement**. Ne
présume pas que tout ce qui atterrit est exécutable tel quel sur cet hôte.

**Délivré PORTABLEMENT par le package — le binaire `crocodeur`** (le socle qui tourne
partout, sans dépendance à la topologie de l'hôte) :

- `crocodeur validate` — valide le cœur SDLC CDA (lint-cda standalone).
- `crocodeur init` — scaffold le home `.crocodeur/` + premier sync.
- `crocodeur sync [--check]` — (re)projette les adaptateurs de harnais.
- `crocodeur upgrade` — met à jour les builtins vers la version packagée.
- Les **namespaces CDA**, invoqués **via `crocodeur …` (jamais `pnpm cli …`)** :
  `crocodeur step`, `crocodeur pipeline`, `crocodeur spec`, `crocodeur session`,
  `crocodeur artifact`.

Toute autre invocation rencontrée dans les builtins n'a **pas** cette garantie
d'exécutabilité (voir l'avertissement plus bas).

**NON délivré par v1 — responsabilité de l'hôte** (le package n'embarque que la
coquille doctrinale de ces capacités, pas le moteur qui les fait tourner) :

- **Bootstrap d'environnement et de session** : installation de paquets, warmup,
  amorçage de session — propres à chaque hôte, hors package. C'est pourquoi les
  builtins portables ne câblent **aucun** hook de démarrage host-spécifique.
- **Moteur de mémoire + embeddings** : la recherche mémoire est un satellite
  host-side ; le package n'embarque ni index ni moteur d'embeddings.
- **Ordonnancement et dispatch des routines** : le scheduler qui déclenche les
  routines autonomes (cron/tick) et leur dispatch vivent chez l'hôte, pas dans le
  package.

Ces capacités doivent être fournies/câblées par l'hôte si tu en as besoin ; ne
suppose pas qu'`init` les active.

> **⚠️ Avertissement de portabilité — à retenir absolument.** La flotte de builtins
> **agents / skills / commandes** livrée avec ce package a été **calibrée pour un
> dépôt hôte riche préexistant** (le monorepo d'origine du harnais). Elle
> **référence massivement des invocations non portables** — `pnpm cli …`, des
> scripts `scripts/…`, et `pnpm validate` / `pnpm test` / `pnpm typecheck` — qui
> **présupposent un dispatcher et une topologie de monorepo absents d'un hôte
> minimal**. Sur un tel hôte, ces commandes **ne s'exécuteront pas telles quelles**.
> Traite alors ces builtins comme de la **matière de référence doctrinale** (le QUOI
> et le pourquoi), pas comme des recettes exécutables clés en main — **en attendant
> une passe de portabilité dédiée** (chantier séparé, hors de cette version).
> N'induis jamais l'opérateur en erreur : quand tu t'appuies sur un builtin,
> distingue explicitement ce qui **tourne** (le CLI `crocodeur` ci-dessus) de ce qui
> est **indicatif** (le reste).

---

## Étape 0 — Cartographier le terrain (avant toute écriture)

1. Confirme que tu es à la **racine** du dépôt hôte (là où vivra le home `.crocodeur/`).
2. Détecte l'état de départ : le dépôt est-il **vierge** (ni `.claude/`, ni `.opencode/`,
   ni `.crocodeur/`) ou **non-vierge** (des sorties de harnais préexistent) ?
   - Vierge → parcours nominal ci-dessous.
   - Non-vierge sans home `.crocodeur/` → `crocodeur init` **refusera** par défaut
     (protection anti-écrasement). Tu relanceras avec `--force` **seulement** après
     avoir confirmé avec l'opérateur que `.claude/` / `.opencode/` sont des sorties
     régénérables (jamais du travail humain à préserver).
3. Repère le gestionnaire de paquets utilisé par le dépôt (`npm` / `pnpm` / `yarn`)
   et la version de Node (`node --version`). Crocodeur exige **Node >= 20**.

---

## Étape 1 — Installer le package (et lire l'erreur AVANT de provisionner quoi que ce soit)

Lance l'installation :

```bash
npm install @shiftingcroco/crocodeur       # ou l'équivalent pnpm add -D / yarn add -D
```

Si l'install **réussit** (exit 0, `node_modules/@shiftingcroco/crocodeur` présent) →
passe à l'Étape 2.

Si l'install **échoue**, **NE PROVISIONNE AUCUN TOKEN par réflexe.** Un credential posé
à l'aveugle sur une mauvaise cause ne débloque rien et masque le vrai problème. **Lis
d'abord le code d'erreur** que le registry renvoie, et **classe-le** :

### Doctrine d'erreur registry — classifier AVANT de provisionner

| Code | Ce que ça signifie **vraiment** | Cause | Action correcte |
| --- | --- | --- | --- |
| **404** (Not Found) | Le **scope est inconnu** du registry interrogé — le registry ne connaît tout simplement pas ce paquet. **Ce n'est PAS un problème d'authentification.** | Tu interroges un registry qui n'a pas le paquet, ou le scope `@shiftingcroco` n'y est pas mappé. | **Aucun token.** Un token ne corrige **jamais** un 404. Assure-toi d'interroger le **registry public** où le paquet est publié en accès public (pas de `~/.npmrc` privé qui détourne le scope). Retire toute config de scope erronée, puis réessaie. |
| **401** (Unauthorized) / **403** (Forbidden) | Le registry **connaît** le paquet mais **refuse l'accès** : c'est un problème **d'authentification / d'autorisation**. | Credential absent, expiré, ou de scope insuffisant. | **Ici seulement** un token a un sens. Provisionne le credential de **scope minimal** nécessaire à la lecture, jamais plus. |

> **Règle invariante : classer d'abord, provisionner ensuite (si tant est).**
>
> - Un **404 n'est jamais** une invitation à créer un `~/.npmrc` ou un PAT. Le réflexe
>   « erreur d'install → je fabrique un token » est un **anti-pattern** : sur un 404 il
>   déclenche une tempête de provisioning inutile (`retry-storm`) et laisse le vrai
>   défaut — scope non résolu — intact.
> - Ne provisionne un credential **que** pour un **401/403** avéré, **après** avoir lu
>   le code. Si le doute persiste entre indisponibilité réseau et scope inconnu,
>   distingue-les : un échec **réseau** (DNS, timeout, registry injoignable) est un
>   échec **franc** distinct d'un 404 — ne le traite pas comme un scope manquant, et
>   ne provisionne pas de token pour un problème de connectivité.
>
> Rapporte à l'opérateur le code lu, la cause retenue et la décision (token / pas de
> token) **avant** d'agir sur les credentials.

---

## Étape 2 — Initialiser le home du harnais

Une fois le paquet installé :

```bash
npx crocodeur init      # scaffold .crocodeur/ (builtins + local/ + état vivant) + premier sync
```

- Sur dépôt vierge : `init` matérialise le home et projette les adaptateurs (exit 0).
- Sur dépôt déjà initialisé : `init` est **idempotent** (no-op + rapport, exit 0) — il
  ne réécrase rien. Pour mettre à jour les builtins d'une version à l'autre : `crocodeur upgrade`.
- Sur refus (non-vierge sans home) : reviens à l'Étape 0, confirme avec l'opérateur,
  puis `npx crocodeur init --force`.

Inspecte ce qui a atterri : `.crocodeur/builtins/` (payload versionné), `.crocodeur/local/`
(tes overrides), `.crocodeur/config.json` (adaptateurs actifs), et les sorties générées.

---

## Étape 3 — Interroger la configuration d'environnement (pose les questions)

Le harnais s'adapte à **cet** hôte. Ne devine pas — **demande** à l'opérateur, puis
reflète ses réponses dans la config. Questions à poser :

1. **Adaptateurs de harnais** : quel(s) harnais cible(s) ? `claude-code`, `opencode`,
   ou les deux ? (`.crocodeur/config.json::adapters`). Par défaut : les deux.
2. **Runtime** : la version de Node du dépôt satisfait-elle `>=20` ? Sinon, escalade.
3. **Serveurs MCP** : l'hôte câble-t-il des serveurs MCP réels ? Si oui, ils vivent dans
   l'override host-side (`.crocodeur/mcp-servers.json`), jamais dans les builtins portables.
4. **Secrets** : quel gestionnaire de secrets (variables d'env, coffre) ? **Aucun secret
   en clair** dans le dépôt — jamais de token collé dans un fichier committé.
5. **Gouvernance** : y a-t-il des règles ou skills propres à l'hôte à ajouter en
   overlay `local/` (qui gagne sur les builtins en cas de collision homonyme) ?

Consigne les réponses ; elles pilotent l'Étape 4.

---

## Étape 4 — Adapter puis régénérer (et vérifier la fraîcheur)

1. Applique les décisions de l'Étape 3 : ajuste `.crocodeur/config.json::adapters`,
   dépose tes overrides sous `.crocodeur/local/`, pose l'override MCP si nécessaire.
2. Régénère les sorties :

   ```bash
   npx crocodeur sync          # (re)projette .opencode/ + .claude/ + .mcp.json depuis le home
   ```

3. Vérifie la **fraîcheur** en mode non-destructif (regenerate-and-compare, zéro dérive) :

   ```bash
   npx crocodeur sync --check  # exit 0 = sorties committées à jour ; sinon, liste la dérive
   ```

4. Confirme que le harnais est **opérationnel** : les agents, skills, rules et commandes
   sont présents dans les sorties adaptées, et un re-`sync` produit **zéro diff**
   (déterminisme). Rapporte l'état final à l'opérateur.

---

## Étape 5 — Livrer (quoi committer, quoi ignorer)

Le harnais atterri est fait pour **vivre dans le dépôt** : ses sorties sont des
artefacts versionnés, pas des fichiers jetables. Une fois `init` + `sync` verts,
committe l'ensemble de l'atterrissage :

- **Le home `.crocodeur/`** en entier : `builtins/` (payload versionné), `local/`
  (tes overrides), `config.json`, `crocodeur-manifest.json` et les dossiers d'état
  vivant (`memory/`, `replenish/`, `tech-watch/`). C'est la SSOT du harnais.
- **Les sorties d'adaptateurs générées** : `.claude/`, `.opencode/`, `.mcp.json` —
  ce sont des **sorties committées** de `sync` (regénérables à l'identique, mais
  versionnées pour la revue de diff et la reproductibilité).
- **Les docs de méthode scaffoldées** : `docs/constitution.md`,
  `docs/architecture/…`, `docs/specs/README.md`, et le workflow d'exemple sous
  `.github/workflows/`.

**Invariant d'hygiène `.gitignore`.** `init` dépose un `.gitignore` minimal sur un
dépôt qui n'en a pas (au moins `node_modules/`, logs, artefacts OS) — il **n'écrase
jamais** un `.gitignore` existant. Vérifie qu'il couvre bien ces entrées et **ne
committe jamais `node_modules/`**. Complète-le au besoin selon l'outillage de l'hôte.

**Zéro secret committé.** Aucun token, aucun credential, aucun `.npmrc` porteur
d'un jeton ne doit entrer dans un commit — ni pour l'install (elle est anonyme,
Étape 1), ni pour le pont issues (le token vit dans l'environnement). Avant le
premier commit, relis le diff : si un secret a fui, il ne se retire pas d'un
historique par un simple commit — révoque-le et réécris avant de pousser.

---

## Garde-fous permanents

- **Prose, pas wizard** : ce prompt te *conduit* ; il n'exécute rien à ta place.
- **Classe avant de provisionner** : 404 = scope inconnu (pas de token) ; 401/403 = auth
  (token de scope minimal). Jamais de credential à l'aveugle.
- **Zéro secret committé** : les credentials passent par l'environnement / un coffre.
- **Committe l'atterrissage, ignore le bruit** : `.crocodeur/` + sorties de `sync` +
  docs de méthode entrent dans le dépôt ; `node_modules/` jamais (le `.gitignore`
  déposé par `init` le couvre, sans écraser un existant). Voir Étape 5.
- **`local/` gagne** : tes adaptations vivent en overlay, jamais en éditant les builtins.
- **Preuve, pas supposition** : lis la sortie réelle de chaque commande avant de conclure.