devflow

Toolkit de Spec-Driven Development pour Codex, Claude Code et Cursor. Chaque feature passe par un pipeline structuré avec des parcours adaptatifs et des gates de preuve avant d'atteindre le code.

Inspiré de spec-kit.

Qu'est-ce que devflow ?

devflow impose un workflow séquentiel où chaque feature est spécifiée, planifiée et reviewée avant toute ligne de code. Le pipeline complet :

constitution → spec → clarify → review-spec → research → plan → contracts → tasks → review-tasks → implement → review-impl → docs → done

Les gates de review (review-spec, review-tasks, review-impl) sont bloquantes : aucune progression sans verdict PASS.

Deux interfaces complémentaires :

• CLI Python (devflow) — moteur d'état, orchestration, branches, hooks et installation
• Contrats adaptatifs (devflow adaptive) — activités portables exécutables avec Codex
• Commandes slash (/devflow.*) — interface historique de production et review dans Claude Code

Prérequis

• Python 3.11+
• Codex, Claude Code ou Cursor
• git

Installation

uv tool install devflow-cli

Ou avec pip :

pip install devflow-cli

Pour vérifier l'installation :

devflow check --ai codex

Pour l'installation en mode développeur, voir CONTRIBUTING.md.

Quick Start

1. Initialiser devflow dans votre projet

devflow init --ai codex

En mode Codex, cela initialise .specify/ sans installer de fichiers dans ~/.claude/. Pour l'interface historique Claude Code, utilisez simplement devflow init.

Vérifiez ensuite l'environnement choisi :

devflow check --ai codex

2. Créer une feature

devflow feature KS-123 --short-name "user-auth"

Crée la branche et le dossier de specs associé.

3. Exécuter le pipeline

Depuis le terminal :

devflow run KS-123

Avant de lancer le pipeline, assess peut recommander un niveau de rigueur sans modifier la progression existante :

devflow assess KS-123 --scope local --ambiguity low --risk low

La commande écrit .specify/specs/<feature>/assessment.json. Les profils possibles sont quick, standard, deep et critical. Les quatre profils disposent d'une machine d'état exécutable :

devflow adaptive start KS-123
devflow adaptive complete KS-123 implement
devflow adaptive evidence KS-123 targeted-check --report "test ciblé réussi"
devflow adaptive evidence KS-123 diff-inspection --report "diff relu"
devflow adaptive complete KS-123 verify
devflow adaptive complete KS-123 done

Le parcours adaptatif utilise workflow-state.json et ne modifie pas le state.json du pipeline historique.

Tous les profils peuvent exécuter leur activité courante avec Codex :

devflow adaptive run KS-123 --agent codex

Une validation planifiée échouée à cause d'une baseline connue peut recevoir une dérogation auditée, sans réécrire le plan ou la preuve historique :

devflow adaptive waive KS-123 V-05 --reason "Baseline connue et hors diff"

Si une vérification révèle qu'il faut corriger l'implémentation, le retour est explicite et audité :

devflow adaptive reopen KS-123 implement \
  --reason "La vérification a révélé un défaut à corriger"
devflow adaptive run KS-123 --agent codex

La tentative précédente est archivée sous attempts/, reopen-log.json conserve le motif et l'auteur, et le résultat suivant garde le périmètre cumulé des fichiers d'implémentation.

Chaque invocation traite une seule activité. prepare (standard) analyse le dépôt en lecture seule. Deep produit spec.md, plan.md et tasks.md, puis réalise une revue indépendante après les preuves. Critical ajoute l'analyse des risques, la recherche, les contrats, une preuve sensible non dérogeable, une revue indépendante et un contrôle explicite du rollback. implement utilise Codex avec un résultat JSON structuré ; verify est exécutée localement par Devflow, qui sélectionne une commande sûre, produit les preuves et contrôle le diff réel. Pour une preuve sensible Critical, un code de sortie nul ne suffit pas : une suite Maven dont tous les tests sont ignorés est enregistrée en échec.

Un worklog.md compact est créé et actualisé automatiquement pendant le parcours. Il résume l'objectif, l'évaluation, les fichiers modifiés, les validations et les risques, tout en préservant une section de notes manuelles.

Le pipeline historique devflow run enchaîne les sessions de l'agent choisi et relit state.json. Le parcours quotidien recommandé avec Codex utilise devflow adaptive run, une activité et une gate à la fois.

Pour travailler étape par étape dans Claude Code, lancez les commandes slash dans l'ordre :

/devflow.spec "Description de la feature"
/devflow.clarify
/devflow.plan
/devflow.tasks
/devflow.implement

Chaque commande produit un artefact (spec.md, plan.md, tasks.md, etc.) et fait avancer la feature dans le pipeline.

4. Suivre la progression

devflow status

Documentation

Consultez la documentation complète pour :

• Pipeline détaillé — les 13 étapes expliquées
• Commandes CLI — référence des commandes terminal
• Commandes slash — référence des 23 commandes Claude Code
• Guides par type de projet — brownfield, greenfield, microservices

Contribuer

Les contributions sont les bienvenues. Consultez le guide de contribution pour les prérequis, l'installation dev et les conventions.

English Summary

devflow is a Spec-Driven Development toolkit for Codex, Claude Code, and Cursor. It provides adaptive quick, standard, deep, and critical workflows with evidence-based gates.

The full pipeline: constitution → spec → clarify → review-spec → research → plan → contracts → tasks → review-tasks → implement → review-impl → docs → done.

Install: uv tool install devflow-cli (or pip install devflow-cli). Requires Python 3.11+, Codex, Claude Code or Cursor, and git.

Quick start:

1. devflow init --ai codex — set up an agent-independent project for Codex
2. devflow feature KS-123 — create a feature branch
3. devflow assess KS-123 ... → devflow adaptive start KS-123 → devflow adaptive run KS-123 --agent codex

For full documentation, see docs/index.md. To contribute, see CONTRIBUTING.md.