Project Kickoff — on ne code rien tant que le tableau n'est pas vert

Problème résolu. En vibe coding, les projets ratent pour les mêmes raisons :

• le besoin est flou ;
• la stack est choisie au hasard ;
• Claude oublie les conventions d'une session à l'autre ;
• sans tests ni CI, les régressions passent inaperçues ;
• les secrets se retrouvent dans Git ;
• sans plan, on avance de patch en patch.

Ce skill produit un socle vérifiable, adapté à la personne et au type de projet. Il le résume dans un tableau de préparation que le script scripts/check.mjs vérifie réellement.

Fichiers du skill (lis seulement ce qui sert)

Règles de conduite

• Avance phase par phase. À la fin de chaque phase, relance le script et montre le tableau, puis attends le « ok » de l'utilisateur.
• Ne marque jamais une ligne ✅ à la main. Seul le script décide. Une ligne ne devient ➖ que par na dans docs/kickoff.json, avec une raison acceptée par l'utilisateur. Les lignes bloquantes ne peuvent pas être écartées, sauf par le mode express.
• Pose les questions par lots de 3 à 4 (AskUserQuestion), avec une réponse recommandée. Ne demande jamais ce que le profil, le pack ou le code disent déjà.
• Adapte le ton, la quantité de questions et le vocabulaire au niveau (tableau dans references/profil.md).
• Demande toujours une confirmation explicite avant toute action visible de l'extérieur : créer un repo, faire un push, créer des issues, déployer, acheter.
• Les fichiers sont la source de vérité, pas la conversation.

Étape A — Profil de l'utilisateur

Lis ~/.claude/kickoff-profile.md.

• S'il est absent : pose les 6 questions de references/profil.md et écris le fichier.
• S'il existe : résume-le en 3 lignes et demande « Toujours vrai ? ». Applique ses Leçons : chacune devient une question ou une vérification en plus.

Étape B — Situation, pack et mode

1. Projet existant ? Si le dossier contient du code, suis references/reprise.md : audit d'abord, puis seulement les phases nécessaires.
2. Pack : déduis le type de projet de la description et confirme-le (vitrine, saas, ecommerce, mobile, outil-interne, ecole, odoo). Lis ce pack. Si aucun ne colle, utilise saas et adapte.
3. Mode (propose celui que le pack conseille) :

Données de santé, de paiement, biométriques ou de mineurs : le mode complet est obligatoire.

4. Initialiser le tableau. Crée docs/kickoff.json depuis templates/kickoff.json (projet, mode, niveau, pack, pays, gestionnaire de paquets, currentMilestone: "Cadrage"). Copie scripts/check.mjs vers scripts/kickoff-check.mjs, ajoute .claude/kickoff-state.json au .gitignore, puis lance node scripts/kickoff-check.mjs. Montre ce premier tableau, presque entièrement ❌ : c'est le point de départ.

Phase 0 — Machine

git --version; node --version; npm --version; pnpm --version; bun --version; gh --version; gh auth status; docker --version

Ajoute les outils propres au pack (Python, ruff et Docker pour Odoo ; EAS CLI pour mobile).

• Gestionnaire de paquets : un gestionnaire déjà installé (préférence du profil, sinon pnpm, puis bun, puis npm). Il remplace <pm> dans tous les modèles. Note-le dans kickoff.json et dans le profil.
• Windows : git config core.longpaths true dans le repo, et un .gitattributes avec * text=auto eol=lf.

Phase 1 — Comprendre le projet → docs/PRD.md

Questions générales (un débutant n'a que les n° 1, 2, 3, 4, 5, 7, 10 et 12 ; le reste reçoit une valeur par défaut notée en Hypothèses) :

1. Quel problème, pour qui ? Persona principal et secondaire.
2. Quelle action unique l'utilisateur doit-il pouvoir faire au jour 1 ?
3. Les 5 à 10 fonctionnalités du MVP, en MoSCoW.
4. Hors périmètre v1.
5. Rôles et authentification.
6. Données : entités, relations, données personnelles, fichiers.
7. Paiement, notifications, temps réel ?
8. Langues, SEO, accessibilité, mobile d'abord.
9. Contraintes : budget, échéance, compétences, hébergeur imposé.
10. Références visuelles et identité de marque.
11. Mesure du succès.
12. Cas limites : actions simultanées, double clic, action dans le passé, suppression d'un élément lié, fuseau horaire, devise, réseau coupé. Chaque garantie d'intégrité est imposée en base.

Ajoute ensuite les questions du pack et celles qui viennent du pays (pays.md : droit des données, paiement, canaux de notification, réseau). Structure du PRD : Vision · Utilisateurs · User stories avec critères d'acceptation testables · MVP (MoSCoW) · Hors périmètre · Exigences non fonctionnelles · Hypothèses · Questions ouvertes · Mesure du succès.

Phase 1b — Avocat du diable (standard et complet)

Suis references/avocat-du-diable.md : un sous-agent sans contexte relit le PRD et écrit docs/REVIEW.md. Corrige le PRD avec l'utilisateur jusqu'à ce qu'aucun point [Bloquant] ne reste ouvert.

Phase 2 — Stack → docs/ARCHITECTURE.md + docs/adr/

Ordre de priorité : stack imposée > préférences du profil (si elles conviennent au besoin) > stack du pack. Une préférence inadaptée doit être signalée honnêtement dans l'ADR, avec les alternatives écartées. Socle transverse si pertinent : Zod, react-hook-form, Vitest + Playwright, Biome, Resend, Sentry, Plausible ou PostHog. ARCHITECTURE.md contient : un schéma Mermaid du flux, le modèle de données (erDiagram), l'arborescence, la liste des variables d'environnement, et la stratégie d'authentification et d'autorisation. Pour un niveau débutant, une seule recommandation, expliquée simplement. Pour un expert, un tableau comparatif.

Phase 2b — Estimation (standard et complet) → docs/ESTIMATION.md

Suis references/estimation.md. Les prix sont vérifiés en ligne, jamais donnés de mémoire. Compare le résultat au budget et à l'échéance. S'ils sont dépassés, réduis le MVP avec l'utilisateur.

Phase 3 — Design → docs/DESIGN.md

Tokens (couleurs clair et sombre, typo, espacements, rayons), composants de base, chaque écran avec ses états chargement, vide et erreur, et le parcours critique. Utilise les skills de design installés (frontend-design, design-system-creation, tailwind-v4-shadcn, responsive-web-design). En mode express, les tokens vont dans CLAUDE.md.

Phase 4 — Repo GitHub

Après confirmation : git init, puis gh repo create <nom> --private --source=. --remote=origin.

• .gitignore (inclut .env* sauf l'exemple, et .claude/kickoff-state.json), .gitattributes, .env.example documenté (ou odoo.conf.example : dans ce cas, renseigne envExample dans kickoff.json), README.md et LICENSE si le projet est public.
• .github/workflows/ci.yml : install → lint → typecheck → test → build avec <pm> (bun : oven-sh/setup-bun@v2 ; pnpm : pnpm/action-setup). Pour Odoo, utilise la CI du pack. La CI reste rouge jusqu'à ce que J0 crée les scripts.
• .github/dependabot.yml, modèles d'issue et de PR (la checklist reprend la Definition of Done).
• Donne à l'utilisateur le lien des réglages GitHub pour activer la protection de main, le secret scanning et la push protection.

Phase 5 — Configurer Claude Code

1. CLAUDE.md depuis templates/CLAUDE.md, entièrement rempli. Le script signale tout <…> restant. Ajoute les Leçons du profil qui concernent ce projet.
2. .claude/settings.json depuis templates/settings.json (remplace <pm>), et .claude/hooks/format.mjs :
   • permissions : interdit la lecture des vrais .env (pas de l'exemple), le push --force et le rm -rf ;
   • hook PostToolUse : formate chaque fichier modifié avec Biome, Prettier ou ruff ;
   • hook SessionStart : à chaque nouvelle session, Claude reçoit le jalon en cours et les lignes non vertes du tableau.
3. .claude/commands/kickoff-status.md : la commande /kickoff-status.
4. MCP de projet (après accord), enregistrés dans .mcp.json pour être partagés et vérifiables :

   claude mcp add --scope project context7 -- npx -y @upstash/context7-mcp
   claude mcp add --scope project playwright -- npx @playwright/mcp@latest

   Ajoute aussi les MCP propres à la stack : GitHub, Supabase, Vercel ou Cloudflare.
5. Skills : liste ceux qui sont installés et propose ceux qui manquent pour la stack. Sources fiables : anthropics/skills (officiel) et obra/superpowers. Lis toujours un skill tiers avant de l'installer.

Phase 6 — Plan → docs/PLAN.md

Des jalons en tranches verticales (de la base de données à l'écran, avec le test), en partant des jalons types du pack. J0 : squelette, CI verte et preview en ligne dès le premier jour. Chaque jalon a un critère « terminé quand ». Tailles et durées viennent de l'estimation.

Phase 6b — Issues GitHub (standard et complet)

Suis references/issues-github.md : un milestone par jalon, une issue par story avec ses critères en cases à cocher. Montre la liste et attends l'accord avant de créer quoi que ce soit.

Phase 7 — Definition of Done (dans CLAUDE.md)

Une tâche est terminée seulement si :

• ses critères sont vérifiés dans un vrai navigateur ;
• les tests sont ajoutés et la CI est verte ;
• les états chargement, vide et erreur sont gérés et le rendu mobile est vérifié ;
• il n'y a aucun secret dans le code et les entrées sont validées côté serveur ;
• la documentation est à jour.

Phase 8 — Production

Hébergeur et environnements · domaine · variables d'environnement chez l'hébergeur · Sentry · analytics · sauvegardes (testées en mode complet) · rate limiting · en-têtes de sécurité · pages légales selon le pays (pays.md) · robots.txt, sitemap et Open Graph.

La porte de sortie : le tableau de préparation

Lance node scripts/kickoff-check.mjs (en ligne). Le script :

• vérifie réellement chaque ligne : sections du PRD, ADR, placeholders du CLAUDE.md, hook exécuté, .env ignoré, variables utilisées mais non documentées, secret suivi par Git, dernière CI, issues, preview qui répond ;
• écrit docs/KICKOFF.md avec les colonnes Statut (✅ ⚠️ ❌ ➖), Preuve, Type (bloquant, recommandé, après J0, info) et Risque si sauté ;
• calcule le score et le verdict : ✅ Prêt · ⚠️ Prêt avec réserves · ❌ Pas prêt ;
• liste les régressions depuis la dernière vérification.

Montre le tableau en entier.

• ❌ Pas prêt : propose de traiter les lignes bloquantes.
• ⚠️ Réserves : demande à l'utilisateur s'il les accepte explicitement.
• ✅ Prêt, ou réserves acceptées : passe currentMilestone à "J0" et propose de démarrer.

Après le kickoff

• /kickoff-status à tout moment : tableau à jour, régressions expliquées, 3 prochaines actions.
• À chaque jalon terminé : mets à jour currentMilestone dans docs/kickoff.json et previewUrl dès que la preview existe.
• Fin de projet ou « rétro » : references/retrospective.md. Les leçons enrichissent le profil, donc le prochain kickoff.

Modifier ce skill

Après toute modification, lance node evals/check.test.mjs (tests du script) et rejoue au moins un scénario de evals/scenarios/ selon evals/README.md.