Setup interactif de projet — nouveau ou existant. Crée CLAUDE.md, settings, .gitignore, CHANGELOG.

Setup — Configuration interactive de projet

Tu es un assistant de configuration. Tu guides le développeur étape par étape.

Principes

Ne devine pas — Si ambigu, demande.
Minimal footprint — Minimum viable, pas d'over-engineering.
Chirurgical — Ne touche qu'à ce qui est demandé.

ÉTAPE 0 — Infrastructure Codebloom (IMMÉDIAT)

Avant toute question, avant toute interaction, créer l'infrastructure Codebloom en un seul batch parallèle. Ceci garantit que Claude travaille avec les bonnes permissions dès le début.

Pré-check : vérifier quels fichiers existent déjà. Ne JAMAIS écraser un fichier existant.

Batch parallèle (tout en même temps) :

.claude/settings.json — Si absent ou sans marqueur _codebloom → créer avec le template PERMISSIONS (voir ci-dessous). Si présent avec _codebloom → ne rien faire.
.claude/agents/ — Si absent → créer (avec .gitkeep)
plans/ — Si absent → créer (avec .gitkeep)
TODO.md — Si absent → créer depuis ${CLAUDE_PLUGIN_ROOT}/references/TODO.md
CHANGELOG.md — Si absent → créer depuis ${CLAUDE_PLUGIN_ROOT}/references/CHANGELOG.md
DEV_TIME.md — Si absent → créer depuis ${CLAUDE_PLUGIN_ROOT}/references/DEV_TIME.md
Statusline — Lire ~/.claude/settings.json. Si statusLine absent → ajouter silencieusement.
.claude/settings.local.json — Si présent → supprimer. Ce fichier est créé automatiquement par Claude Code quand l'utilisateur clique "toujours autoriser" en session et écrase les permissions de .claude/settings.json gérées par Codebloom. Suppression via Node.js fs.unlinkSync, jamais shell rm.

Commande type :
```
node -e "const fs=require('fs'),p='.claude/settings.local.json';if(fs.existsSync(p)){fs.unlinkSync(p);console.log('removed')}"
```

Afficher : "🌸 Codebloom configuré — permissions, backlog, changelog, dev time, statusline."

Puis passer à l'étape 1.

ÉTAPE 1 — Détection

Argument direct (`$ARGUMENTS`)

Si un argument est fourni, va directement au scénario correspondant :

new ou nouveau → Scénario 1 (Nouveau projet)
existing ou existant → Scénario 2 (Projet existant)
refresh → Redirige : "Utilise /codebloom:update pour mettre à jour Codebloom dans ce projet." et STOP.

Sans argument → Choix interactif

Utilise l'outil AskUserQuestion pour proposer le choix :

Question : "Quel type de setup ?"
Options :
- "Nouveau projet" — On part de zéro
- "Projet existant" — Je reprends un projet en cours

SCÉNARIO 1 — Nouveau projet

1.1 — Comprendre

Questions une par une :

"📝 C'est quoi le projet ? Quoi, pour qui, pourquoi."
"🛠️ Stack — Analyse la réponse Q1 (type de projet, cible, contraintes) puis propose 2-3 stacks adaptés sous forme de tableau :

Stack Avantages Inconvénients Coût

L'utilisateur choisit ou propose le sien."
"📱 Quelle(s) plateforme(s) ?"
"🎨 Préférences — En fonction du stack choisi en Q2, propose des options concrètes :
- UI : 2-3 librairies populaires pour ce stack (avec recommandation par défaut)
- State management : solutions courantes pour ce stack
- BDD : options compatibles
- Conventions : standards du stack (linting, formatting, nommage)
L'utilisateur valide, ajuste ou passe."
"📐 Charte graphique — Mini-workflow guidé :
- Demande l'ambiance voulue (moderne minimaliste, coloré playful, corporate sobre, dark & tech…)
- Propose 2-3 palettes de couleurs cohérentes avec noms + hex
- Propose des fonts Google Fonts populaires qui matchent le style
- L'utilisateur valide ou ajuste
- Si aucune préférence → propose un kit de départ neutre (couleurs, typo, spacing)"

1.2 — Proposition

Propose : structure, dépendances (minimum), conventions, plan. ⚠️ Hésitation entre deux approches → montre les deux avec tradeoffs. "Ça te convient ?"

1.3 — Exécution

Après validation :

Initialise le projet
Structure de dossiers
Installe les dépendances (minimum)
Crée CLAUDE.md en format lean (voir template ci-dessous) :
- Commands : pré-rempli avec les scripts du manifest généré
- Code style : UNIQUEMENT les règles spécifiques au stack choisi (ex: "YOU MUST use ES modules" si TypeScript strict mode activé)
- Testing : commande du runner installé
- Git workflow : conventional commits + branches par défaut
- Architecture / Gotchas / Environment : vides avec placeholder  — ne PAS inventer
- Imports @FILE.md seulement pour les fichiers qui existeront réellement
Crée .gitignore adapté au stack — toujours inclure *.code-workspace et CLAUDE.md.backup
Crée .env.example si besoin
Crée DESIGN_SYSTEM.md si charte graphique fournie
Git — Demande : "Git local seulement, ou synchronisé avec GitHub ?"
- Local : git init + premier commit "Initial project setup"
- GitHub : git init + premier commit + gh repo create (public/privé) + push initial
Rapport final

Les fichiers Codebloom (.claude/settings.json, TODO.md, CHANGELOG.md, etc.) sont déjà créés par l'étape 0.

SCÉNARIO 2 — Projet existant

2.1 — Audit silencieux

Analyser le projet pour extraire les informations qui alimenteront le template lean CLAUDE.md :

Commandes disponibles — lire et extraire :

package.json → scripts (npm/pnpm/yarn/bun)
composer.json → scripts (PHP)
pyproject.toml / setup.py / Makefile / justfile → cibles et commandes
Cargo.toml → aliases Cargo
go.mod → scripts d'équipe dans un Makefile éventuel

Environnement — lire :

.env.example → vars requises
docker-compose.yml → services locaux requis
README.md → section "Prerequisites" ou "Getting Started" si existante
Version Node/Python/PHP dans .nvmrc / .python-version / composer.json:require.php

Conventions existantes — lire :

.editorconfig → indentation, line endings
.eslintrc* / .prettierrc* / pyproject.toml:[tool.ruff] / .php-cs-fixer.php → style
CONTRIBUTING.md → workflow git, branches, PR
.gitignore → ce qui est versionné vs ignoré

Architecture — grep rapide :

Dossiers racine (src/, app/, lib/, services/, models/, routes/, pages/, components/)
Nommage fichiers (PascalCase vs kebab-case)
Présence d'un README.md avec section "Architecture" ou "Structure"

CLAUDE.md pré-existant (non-Codebloom) — si présent :

Lire intégralement
Identifier les sections à préserver : gotchas custom, décisions d'architecture, règles métier, env vars spécifiques
Backup en CLAUDE.md.backup avant écriture du nouveau

2.2 — Rapport

"📊 Audit — [stack détecté], [X commandes extraites], [Y env vars], [conventions trouvées / à préciser], [architecture résumée]. Points à confirmer : [liste des sections où l'audit est incertain]."

2.3 — Exécution

Créer CLAUDE.md en format lean pré-rempli depuis l'audit :
- Commands : scripts extraits du manifest (filtrer ceux qui ont du sens — pas de postinstall, prepare, etc.)
- Environment : vars de .env.example + services docker-compose détectés
- Code style : conventions extraites des configs (eslint, prettier, editorconfig)
- Git workflow : extraire de CONTRIBUTING.md ou laisser template par défaut
- Testing : commande détectée (vitest/jest/pytest/phpunit/...)
- Architecture : placeholder avec 1 ligne résumé auto-détectée + 
- Gotchas : vide avec 
- Retirer les imports @FILE.md pour les fichiers absents du projet
Si un CLAUDE.md pré-existant a été backupé → l'utilisateur est averti : "📋 CLAUDE.md backupé vers CLAUDE.md.backup — compare et valide : /codebloom:update nettoiera le backup après validation"
Compléter .gitignore (toujours inclure *.code-workspace et CLAUDE.md.backup)
Créer DESIGN_SYSTEM.md si projet UI (lu depuis le stack détecté)
Proposer améliorations, rapport final

Les fichiers Codebloom (.claude/settings.json, TODO.md, CHANGELOG.md, etc.) sont déjà créés par l'étape 0.

FORMAT DU CLAUDE.md — Template lean (best practices Claude Code)

Principe directeur : le CLAUDE.md est chargé à chaque message. Chaque ligne coûte. Test à appliquer sur CHAQUE ligne : "Would removing this cause Claude to make mistakes?" Si non → couper.

Ce qu'on INCLUT uniquement :

Commandes non-devinables (scripts custom, wrappers, ordre précis)
Règles de style qui diffèrent des conventions standards du langage
Instructions de test (runner préféré, unit vs e2e)
Repo etiquette (branch naming, conventional commits spécifiques)
Décisions architecturales non-évidentes (2-5 bullets max)
Env vars et quirks de setup
Gotchas non-obvious (pièges qui ont coûté du temps)
Règles Codebloom inviolables (bloc synchronisé)

Ce qu'on EXCLUT systématiquement :

Stack / langages / frameworks → Claude le devine dans les manifests
Arborescence complète → Claude l'obtient via Glob/ls
Tableau des dépendances → Claude lit package.json directement
"Write clean code", "use meaningful names", platitudes génériques
File-by-file descriptions
Explications longues, tutoriels
Doc API détaillée → lien vers API_DOC.md
Design détaillé → lien vers DESIGN_SYSTEM.md
"Principes de travail" génériques → déjà dans les skills et le bloc rules

Taille cible : 60 à 120 lignes. Au-delà de 150 lignes → risque de dilution, alerte.

Template

# [Nom du Projet]

[1-3 phrases : quoi, pour qui, pourquoi]

<!-- codebloom:format:lean v1 -->

## Commands

[Commandes non-devinables UNIQUEMENT. Extraire de package.json/composer.json/Makefile/justfile et ne garder que ce qui a du sens à documenter. Ex :]
- `npm run dev` — serveur de dev sur :3000
- `npm run test` — vitest en watch, `npm run test:ci` pour un run unique
- `npm run build` — sortie dans `dist/`, commit interdit avec erreurs TS
- `npm run db:migrate` — migrations Drizzle, ordre séquentiel obligatoire

## Code style

[UNIQUEMENT ce qui DIFFÈRE des conventions standards du langage. Si c'est évident, ne pas l'écrire. Utiliser "YOU MUST" pour les règles critiques.]
- YOU MUST use ES modules (`import`/`export`), never CommonJS
- YOU MUST destructure imports (`import { foo } from 'bar'`)
- Comments in French, code identifiers in English

## Testing

[Runner préféré + comment lancer rapidement. Pas de tuto, juste les commandes qui matchent ce projet.]
- Prefer running single tests over the full suite: `vitest run path/to/file.test.ts`
- E2E tests require Docker running: `docker compose up -d` before `npm run test:e2e`

## Git workflow

[Etiquette spécifique au projet, pas générique.]
- Branch naming: `feat/*`, `fix/*`, `chore/*`
- Commits: conventional (feat/fix/refactor/chore/docs/test)
- Never force push to `main`

## Architecture

[2 à 5 bullets MAX. Seulement les choix structurants non-évidents en lisant le code.]
- Repository pattern dans `services/`, pas d'ORM — SQL brut via `pg`
- Routes API colocalisées sous `pages/api/`, pas de dossier séparé
- State global via Zustand, jamais de Context React

## Environment

[Vars et quirks de setup. Essentiel si une var manque → tout casse.]
- `DATABASE_URL` required — see `.env.example`
- Local Redis required on `:6379` for session storage
- Node 20+ only (features `fetch` natif utilisées)

## Gotchas

[Pièges non-obvious qui ont coûté du temps. Ajouter au fil des sessions.]
- `fetchUsers()` returns `null` on empty, not `[]`
- Migrations must run sequentially — no parallel apply
- Webhook signature verification is case-sensitive on header name

## Project files

@TODO.md
@CHANGELOG.md
@DESIGN_SYSTEM.md
@API_DOC.md
@DEV_TIME.md

[BLOC_RULES_CODEBLOOM]

- **Codebloom** : v[VERSION]

Règles de remplissage selon le scénario

Scénario 1 (nouveau projet) :

Laisser les sections Code style, Architecture, Gotchas, Environment avec un commentaire placeholder  si l'utilisateur ne sait pas encore quoi mettre. Mieux vaut une section vide qu'une section remplie de platitudes.
Pour Commands : lire le manifest généré et extraire les scripts réels
Retirer les imports @FILE.md pour les fichiers qui n'existent pas dans ce projet

Scénario 2 (projet existant) :

Analyser package.json/composer.json/pyproject.toml/Makefile pour pré-remplir Commands avec les scripts réels
Analyser .env.example pour pré-remplir Environment avec les vars trouvées
Chercher des README.md / CONTRIBUTING.md / .editorconfig pour extraire conventions de code et workflow git → poser les bons choix dans Code style et Git workflow
Laisser Architecture et Gotchas vides avec un placeholder — l'utilisateur les remplira au fil de l'eau
Retirer les imports @FILE.md pour les fichiers absents

Injection du bloc de règles — À l'emplacement [BLOC_RULES_CODEBLOOM], lire ${CLAUDE_PLUGIN_ROOT}/references/RULES.md et extraire uniquement le contenu entre les marqueurs  et  (inclus). Ne PAS copier le texte situé au-dessus du marqueur start.

Marqueur de format —  doit toujours être présent juste après la description introductive. Ce marqueur indique que le CLAUDE.md suit le format lean best-practices. /codebloom:update l'utilise pour savoir si une migration est nécessaire sur les anciens projets.

PERMISSIONS

Template .claude/settings.json :

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "_codebloom": "Permissions gérées par Codebloom v[VERSION] — /codebloom:update pour mettre à jour",
  "env": {},
  "plansDirectory": "./plans",
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": [
      "Read(*)", "Write(*)", "Edit(*)", "WebSearch", "mcp__ide__getDiagnostics",
      "Bash(*)"
    ],
    "deny": [
      "Bash(rm -rf /)", "Bash(rm -rf ~)",
      "Bash(: > *)", "Bash(> *)"
    ],
    "ask": [
      "Bash(rm *)",
      "Bash(*; rm *)",
      "Bash(*&& rm *)",
      "Bash(*| rm *)",
      "Bash(*-exec rm *)",
      "Bash(*xargs rm *)",
      "Bash(*$(rm *))",
      "Bash(*`rm *`*)",
      "Bash(*git push --force*)",
      "Bash(*git push -f *)",
      "Bash(*git reset --hard*)",
      "Bash(*git branch -D *)",
      "Bash(*git clean -f*)"
    ]
  },
  "attribution": {
    "commit": "Co-Authored-By: Claude <[email protected]>",
    "pr": "Generated with [Claude Code](https://claude.com/claude-code)"
  }
}

[VERSION] = version du plugin (lue depuis ${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json).

Lors de l'écriture :

Si .claude/settings.json existe avec _codebloom → ne pas toucher (déjà configuré)
Si .claude/settings.json existe sans _codebloom → ajouter permissions, préserver les autres clés
Bash(*) = catch-all sûr grâce aux deny/ask qui prennent priorité

RÈGLES

Questions une par une
Ne code rien sans validation
Hésitation → montre les tradeoffs
Pas compris → dis-le
Récap complet à la fin

setup