workflow-kit (wfk)

Un workflow agentisé pour Claude Code, installable en une commande. Objectif : du code de qualité, avec une consommation de tokens maîtrisée.

• 4 agents spécialisés (architecte, backend, frontend, relecteur) qui travaillent dans des contextes isolés
• 6 commandes de workflow (/prd, /feature, /fix, /verify, /ship, /init-workflow)
• 3 hooks de garde sans coût en tokens (push sur main, secrets en dur, erreurs TypeScript)
• 1 skill de pièges de stack, plus les skills officiels de ta stack, détectés et installés à la demande
• Zéro dépendance, Node 18+, Linux / macOS / Windows

Sommaire

1. Démarrage rapide
2. Pourquoi ça économise des tokens
3. Référence des commandes
4. Ce qui est installé et où
5. De l'idée au code : /prd puis /feature · Le workflow /feature pas à pas
6. Détection de la stack et skills
7. Les hooks
8. Sécurité et mises à jour
9. Personnaliser
10. Dépannage
11. Développement

Démarrage rapide

# 1. Installer l'outil (ou préfixer chaque commande par npx @aboudouzinsou01/workflow-kit)
npm i -g @aboudouzinsou01/workflow-kit

# 2. Dans un projet : scaffold + agents/commandes/hooks + skills de la stack
cd mon-projet
wfk init --install --skills

# 3. Vérifier
wfk doctor

Ouvre ensuite Claude Code dans le projet et lance par exemple :

/prd "un outil qui aide un développeur à définir son MVP"   # cadrer, puis valider docs/PRD.md
/feature "tranche 1 du PRD"

Pour installer pour tous tes projets plutôt que par projet : wfk install (dans ~/.claude).

Prérequis : Node 18+, Claude Code, git (utilisé par /feature, /fix, /ship).

Pourquoi ça économise des tokens

| Levier | Mécanisme | |---|---| | Contexte permanent minimal | wfk init génère un CLAUDE.md de moins de 80 lignes qui pointe vers docs/ ; le détail n'est lu que si la tâche l'exige. | | Sous-agents isolés | Exploration, implémentation et revue se font hors de la conversation principale ; seul un résumé court (≤ 15 lignes) remonte. | | Modèle adapté au rôle | Le relecteur tourne sur un modèle léger, en lecture seule. | | Vérifications déterministes | Typecheck, refus des secrets et du push sur main sont des scripts, pas des appels au modèle. | | Détection sans IA | wfk init et wfk skills lisent package.json : zéro token. | | Skills ciblés | Le registre est volontairement court : chaque skill installé ajoute sa description au contexte de chaque session. | | Pièges déjà connus | stack-gotchas évite de repayer des bugs déjà rencontrés (Base UI, Next 16, Prisma 7…). |

Référence des commandes

wfk install      Installe agents, commandes, skill et hooks
wfk init         Génère CLAUDE.md court, docs/INDEX.md, docs/ARCHITECTURE.md, .claude/settings.json
wfk skills       Détecte la stack et recommande les skills officiels (--install pour les installer)
wfk doctor       Vérifie l'installation (code de sortie 1 si problème bloquant)
wfk uninstall    Retire proprement ce que wfk a installé
wfk version

| Option | Commandes | Effet | |---|---|---| | --project | install | Cible <cwd>/.claude (partageable via git) au lieu de ~/.claude | | --dir <chemin> | install, uninstall, doctor | Cible un dossier .claude précis | | --pack <nom> | install | Ajoute un pack de pièges (africa) ; répétable | | --no-hooks | install | N'installe pas les hooks | | --install | init | Installe aussi agents/commandes/hooks dans le projet | | --install | skills | Installe réellement les skills recommandés | | --skills | init | Installe aussi les skills recommandés pour la stack | | --global | skills | Installe les skills au niveau utilisateur | | --dry-run | toutes | Affiche ce qui serait fait, n'écrit rien | | --force | install, init, uninstall | Remplace/supprime les fichiers modifiés localement (sauvegarde .bak) |

Variables d'environnement : CLAUDE_CONFIG_DIR (dossier global alternatif à ~/.claude), WFK_NPX (exécutable utilisé pour installer les skills, utile pour les tests).

Ce qui est installé et où

<.claude>/
├── agents/        architect.md · backend-dev.md · frontend-dev.md · reviewer.md
├── commands/      prd.md · feature.md · fix.md · verify.md · ship.md · init-workflow.md
├── skills/
│   └── stack-gotchas/SKILL.md
├── wfk/
│   ├── hooks/     guard-bash.mjs · guard-secrets.mjs · typecheck-ts.mjs
│   └── manifest.json        (versions et empreintes, pour doctor/uninstall)
└── settings.json  (hooks fusionnés, le reste est conservé)

Les agents

| Agent | Rôle | Outils | Modèle | |---|---|---|---| | architect | Brief de ≤ 40 lignes : fichiers, contrats, réutilisation, risques, vérification. Ne code pas. | lecture | sonnet | | backend-dev | Implémente le lot backend (Convex/Prisma/Server Actions…), validation aux frontières, pas de SQL brut. | lecture + écriture | sonnet | | frontend-dev | Implémente le lot UI (Next/Tailwind/shadcn). Détecte Base UI vs Radix avant d'écrire. | lecture + écriture | sonnet | | reviewer | Relit le diff contre une checklist ; sortie 🔴🟡🟢 fichier:ligne — problème — correctif + verdict. | lecture seule | haiku |

Les commandes

| Commande | Rôle | |---|---| | /prd <idée> | Cadre le produit avant de coder : pose les 4 questions en un seul message (problème, utilisateur, « terminé », hors périmètre), puis écrit docs/PRD.md (≤ 120 lignes) : parcours, fonctionnalités Must/Should/Could/Won't, ligne MVP, écrans, tranches de construction prêtes à coller dans /feature. Marque ? / [hypothèse] ce qui est incertain. | | /feature <desc> | Pipeline complet d'une fonctionnalité (voir ci-dessous). | | /fix <bug> | Reproduire → cause racine → correctif minimal → test de non-régression → commit. | | /verify | Typecheck + lint + tests ciblés ; ne remonte que les erreurs. | | /ship | Relecture finale puis push + PR — demande confirmation avant l'envoi. | | /init-workflow | À lancer dans Claude Code : remplit docs/ARCHITECTURE.md à partir du code réel. |

De l'idée au code : /prd puis /feature

/prd "un outil qui fait X pour Y"
  └─ 4 questions en un message (seul arrêt) → docs/PRD.md
     (parcours · Must/Should/Could/Won't · ligne MVP · tranches)
valider le PRD, puis pour chaque tranche :
/feature "<le prompt de la tranche>"

L'agent architect lit docs/PRD.md en premier : le quoi et le hors périmètre sont déjà décidés, il ne fait que le comment.

Le workflow /feature pas à pas

/feature "ajouter les codes promo"
  1. branche feat/<slug> si on est sur main
  2. architect → brief court          ← seul arrêt prévu : une vraie décision produit
  3. backend-dev ∥ frontend-dev       ← en parallèle si les contrats sont figés
  4. /verify                           ← corrige jusqu'à vert (3 itérations max)
  5. reviewer                          ← corrige les 🔴 et 🟡 pertinents
  6. commit conventionnel              ← jamais de push
  7. compte-rendu ≤ 12 lignes
/ship → confirmation → push + PR

Principe d'autonomie : le workflow s'arrête uniquement pour (1) une action difficile à annuler (push, déploiement, suppression de données, migration), (2) une action externe/publique, (3) une vraie décision produit/business. Tout le reste s'enchaîne.

Détection de la stack et skills

wfk init lit package.json et adapte le CLAUDE.md généré : gestionnaire de paquets (pnpm/yarn/bun/npm), scripts disponibles, Next (et sa version), Convex, Prisma, Better Auth, Tailwind, shadcn Base UI ou Radix, Zod. Les pièges pertinents (ex. middleware.ts → proxy.ts en Next 16, pas d'asChild en Base UI) sont rappelés en deux lignes.

wfk skills (et wfk init) détecte ensuite les technologies présentes et recommande les skills publiés par leurs éditeurs :

| Technologie détectée (dépendance) | Source | Skills | |---|---|---| | React / Next.js (next, react) | vercel-labs/agent-skills | vercel-react-best-practices, web-design-guidelines | | React Native / Expo | vercel-labs/agent-skills | vercel-react-native-skills | | Convex (convex) | get-convex/agent-skills | convex | | Prisma (prisma, @prisma/client) | prisma/skills | prisma-client-api, prisma-cli | | Supabase (@supabase/supabase-js, @supabase/ssr) | supabase/agent-skills | supabase, supabase-postgres-best-practices | | SDK Anthropic (@anthropic-ai/sdk) | anthropics/skills | claude-api |

wfk skills                  # liste ce qui est détecté et ce qui manque (n'installe rien)
wfk skills --install        # installe dans <projet>/.claude/skills
wfk skills --install --global --dry-run   # simule une installation utilisateur
wfk init --install --skills # tout d'un coup pour un nouveau projet

Sous le capot : npx skills add <source> -s <skill…> -a claude-code -y (le Skills CLI). Les skills déjà présents (projet ou global) sont ignorés, donc la commande est rejouable.

Choix de conception

• Rien n'est installé sans consentement explicite (--install / --skills). Par défaut, wfk recommande seulement.
• Registre curaté, pas de recherche libre : seuls les skills de ce tableau (publiés par l'éditeur de la techno) sont installables automatiquement. Un skill est du texte qui oriente l'agent : n'installer que des sources de confiance est une mesure de sécurité.
• Un échec réseau n'interrompt pas le reste ; la commande de repli est affichée.

Les hooks

Scripts Node (pas de jq, pas de bash), branchés dans settings.json. Ils s'exécutent sans appeler le modèle : 0 token.

| Hook | Événement | Comportement | |---|---|---| | guard-bash | PreToolUse · Bash | Refuse git push vers main/master (explicite, ou implicite quand on est sur cette branche). Le message renvoyé à Claude lui indique de passer par une branche et /ship. | | guard-secrets | PreToolUse · Write|Edit | Refuse l'écriture de clés en dur (sk_live_…, sk-ant-…, AKIA…, ghp_…, whsec_…, clés privées PEM, password = "…"). Exempte .env*, *.md, *.example, .claude/. | | typecheck-ts | PostToolUse · Write|Edit | Après l'édition d'un .ts/.tsx, lance tsc --noEmit --incremental et ne remonte que les erreurs du fichier édité (10 lignes max, timeout 60 s). Inactif si TypeScript n'est pas installé dans le projet. |

En portée projet, les chemins utilisent $CLAUDE_PROJECT_DIR : le dossier .claude/ peut être commité et partagé avec l'équipe.

Sécurité et mises à jour

• Jamais d'écrasement silencieux : un fichier que tu as modifié est conservé ; --force le remplace après avoir écrit une copie .bak.
• settings.json est fusionné, pas remplacé : tes hooks, permissions et réglages restent, une sauvegarde .bak est écrite. Un settings.json invalide arrête l'opération au lieu d'être écrasé.
• Idempotent : relancer wfk install ne duplique ni fichiers ni hooks ; il met à jour ce qui a changé dans l'outil.
• Désinstallation propre : wfk uninstall ne supprime que les fichiers non modifiés et nos hooks, et nettoie les dossiers vides.
• Mises à jour : npm i -g @aboudouzinsou01/workflow-kit@latest puis wfk install (global) ou wfk install --project. wfk doctor signale une version installée plus ancienne que l'outil.
• wfk init ne remplace jamais un CLAUDE.md ou un doc existant sans --force, et ne touche pas à un .claude/settings.json existant.

Personnaliser

Les fichiers installés sont du Markdown ordinaire : édite .claude/agents/*.md, commands/*.md, skills/stack-gotchas/SKILL.md. Tes modifications sont respectées aux mises à jour.

Idées courantes :

• changer le modèle d'un agent (champ model: dans le frontmatter) ;
• ajouter tes propres pièges dans stack-gotchas (une section par bug déjà payé) ;
• ajouter une règle à la checklist du reviewer ;
• ajouter un pack (templates/packs/<nom>/, enregistré dans PACKS de src/install.mjs) ou une technologie au registre de skills (REGISTRY dans src/skills.mjs — vérifier les noms avec npx skills add <source> --list).

Pack fourni : africa — pièges des paiements Mobile Money (signature des webhooks, idempotence, comptes sandbox/live) et règle « pays, devises, indicatifs : bibliothèques, jamais de tables maison ».

Les gabarits sont rédigés en français.

Dépannage

| Symptôme | Cause / solution | |---|---| | Les agents ou commandes n'apparaissent pas | Redémarre Claude Code après une installation globale. | | doctor : « hooks branchés 0/3 » | Un autre outil a réécrit settings.json. Relance wfk install. | | Le hook de typecheck ne fait rien | TypeScript n'est pas dans node_modules du projet, ou pas de tsconfig.json. | | wfk skills --install échoue | Pas de réseau, ou dépôt source indisponible : relance la commande affichée à la main. | | « JSON invalide : …/settings.json » | Corrige le fichier à la main ; wfk refuse de l'écraser. | | Un push légitime est refusé | guard-bash bloque main/master. Passe par une branche, ou retire le hook avec wfk install --no-hooks / édite settings.json. | | Faux positif du hook secrets | Place la valeur dans .env.local et lis-la via process.env. |

Développement

npm test      # 22 tests (node:test), aucune dépendance
npm pack      # produit l'archive

Arborescence : bin/wfk.mjs (CLI) · src/ (install, init, skills, doctor) · templates/ (agents, commandes, skill, hooks, packs) · test/.

Licence

MIT © 2026 François Mawutô Aboudou ZINSOU