devflow

Devflow est un moteur de développement adaptatif pour Codex, Claude Code et Cursor. Il choisit un niveau de rigueur à partir de signaux explicites, produit des contrats d’activité portables et bloque les transitions tant que les preuves attendues ne sont pas présentes.

Profils

Le profil fixe la route documentaire :

• quick : changement local, clair et peu risqué, sans revue.
• standard : plusieurs composants ou risque modéré ; préparation puis revue systématique (implementation-review).
• deep : changement transversal, ambigu ou contractuel ; spec, plan, tasks, plus contracts quand --contract-change est déclaré.

Un bloc de garde-fous s'y ajoute quand --data-security est déclaré ou que --risk high : risk-assessment après l'évaluation, validation bloquante de sécurité ou de données dans le plan de validation (une validation protégée non bloquante est refusée dès prepare ou plan), preuve security-or-data-check produite par verify, revue independent-review, puis rollback-check avec rollback-plan. Un bloc actif impose au minimum le profil standard, ne se désactive par aucune option et interdit les dérogations.

Les routes exactes et leurs preuves sont générées dans docs/pipeline-reference.generated.md.

Installation

uv tool install --refresh devflow-cli==X.Y.Z   # version publiée, voir CHANGELOG.md
devflow init --ai codex

Après chaque mise à jour de la CLI, lancer devflow upgrade : il met à jour les commandes /devflow installées dans ~/.claude, que l'installation de la CLI ne touche pas. --refresh évite qu'uv ignore une version tout juste publiée. Juste après une publication, l'installation peut échouer pendant une à quatre minutes, le temps que l'index se propage : réessayer. Tant que les commandes installées diffèrent de la CLI, devflow status affiche un avertissement avec cette commande ; rien n'est modifié sans vous.

Installer toujours depuis PyPI, à une version précise, jamais depuis le dossier du dépôt. Les versions publiées sont listées dans CHANGELOG.md.

Python 3.11+ et Git sont requis. --ai accepte codex, claude-code ou cursor.

Parcours quotidien

devflow feature KS-123 --short-name user-auth
# Décrire le besoin dans need.md, dans le dossier de la feature créé
devflow assess KS-123 --scope multiple --ambiguity medium --risk medium
devflow adaptive start KS-123
devflow adaptive run KS-123 --agent codex
devflow adaptive status KS-123

adaptive status --json fournit un état exploitable par la CI. Les échecs distinguent explicitement blocage métier, contrat invalide, panne agent, validation échouée et conflit concurrent ; chaque refus affiche la commande de reprise recommandée. Après un refus de verify, cette reprise dépend du motif : approbations à donner, environnement à corriger, ou trois voies après un contrôle échoué (rouvrir implement si le code est en cause, rouvrir prepare ou plan si la validation l'est, relancer verify après un échec passager). En quick, un lot purement documentaire (README.md, Markdown sous docs/) sans contrôle détecté franchit verify sur l'inspection du diff.

Un plan de prepare ou de plan refusé par les validateurs se corrige sans relancer l'agent : devflow adaptive reconcile KS-123 --result FICHIER.json --reason MOTIF rejoue les mêmes validateurs et trace la correction. Les validations qui attendent une approbation (devflow adaptive approve-command) sont listées en une fois à la fin du plan et au début de verify. Pendant qu'un agent travaille, les commandes humaines qui modifieraient l'état sont refusées sans effet, et un fichier d'exécution modifié par l'agent est remis dans son état d'avant l'agent.

L'agent Claude d'une activité est lancé avec CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 : il peut déléguer à des sous-agents, mais au premier plan seulement. Effet de bord : il ne peut plus lancer de commande shell en arrière-plan (serveur de test, par exemple). Tous les contrats demandent en plus que la sortie structurée soit le dernier message de l'agent. Si un agent termine sans erreur mais sans sortie structurée, adaptive run nomme la cause (structured-output-missing) et propose devflow adaptive reconcile KS-123 --result MODELE --reason MOTIF avec un modèle de résultat prérempli, écrit dans ~/.devflow/reconcile/ et à compléter.

need.md peut être amendé en cours de parcours. Avant une activité documentaire, l'amendement est accepté avec un avertissement qui nomme les activités déjà closes, à rouvrir si leur résultat en dépend ; avant prepare, il est accepté sans cet avertissement ; pendant l'exécution d'un agent, il est refusé ; avant implement, il périme la preuve de pré-vol ; après implement, il périme une revue déjà faite. Pour arbitrer après un blocage d'implement : amender need.md, puis devflow adaptive reopen KS-123 preflight-evidence --reason MOTIF, refaire le pré-vol et relancer implement. Un refus d'artefact (artifact-files-mismatch) nomme chaque fichier en trop et sa cause : retirer ou remettre en état le fichier, puis devflow adaptive reconcile KS-123 ; la relance à l'identique n'est plus proposée. Pour une entrée du besoin modifiée par un agent, la relance est refusée avant le lancement de l'agent : remettre l'entrée en état, ou devflow adaptive discard-attempt KS-123 --reason MOTIF, puis devflow adaptive run KS-123.

Chaque invocation de adaptive run traite une activité. La politique est dans assessment.json; la progression et les preuves sont dans workflow-state.json. Les résultats agent sont validés par schéma et les preuves d’exécution sensibles sont produites localement par Devflow.

Chaque profil exécute preflight-evidence avant implement. Cette activité archive des faits externes reproductibles dans preflight-evidence.md, sans secret ni donnée utilisateur.

Les trois adaptateurs acceptent les mêmes contrats structurés :

devflow adaptive run KS-123 --agent codex
devflow adaptive run KS-123 --agent claude
devflow adaptive run KS-123 --agent cursor

Features créées avant devflow 8

Devflow 8 refuse, sans migration, un workflow-state.json (schéma 5) produit par devflow 7.x. Terminez les parcours en cours avec devflow 7.x, ou gardez la CLI épinglée : uv tool install 'devflow-cli<8'. Voir les notes de version 8.0.0.

Features créées avant devflow 7

Devflow 7 refuse, sans migration, un assessment.json (schéma 3) ou un workflow-state.json (schéma 4) produit par devflow 6.x, avec un message qui nomme le fichier. Avant la mise à jour, terminez les parcours en cours avec devflow 6.x, ou gardez la CLI épinglée : uv tool install 'devflow-cli<7'. Voir ADR-0003 et les notes de version 7.0.0.

Features créées avant devflow 5

Devflow 5 ne lit que ses propres schémas et ne fournit aucune migration : un assessment.json, un workflow-state.json ou un state.json créé par une version antérieure est refusé. Terminez ces features avec devflow 4.x avant la mise à jour. Voir ADR-0002.

devflow init et devflow upgrade déplacent également les anciennes commandes Claude connues vers ~/.claude/.devflow-legacy-backup/ sans toucher aux commandes personnalisées.

Synchronisation Linear

Si LINEAR_API_KEY contient une clé d'API personnelle Linear, la CLI met à jour le statut de l'issue du parcours au démarrage de chaque activité (adaptive run, y compris avec --until, et clôture done). L'équipe Linear doit avoir les statuts Backlog, Design, In Progress, Review et Done. Un statut n'est jamais ramené en arrière ; un statut hors de cette liste (Canceled, Duplicate) n'est jamais modifié.

Sans clé, ou si Linear échoue (issue inconnue, statut absent, erreur réseau ou délai de 5 s dépassé), la CLI affiche un avertissement et le parcours continue à l'identique. La clé est retirée de l'environnement de tout processus lancé par Devflow (agents, commandes de validation, hooks, commandes git) ; elle reste lisible par un agent si elle est définie dans un fichier que son shell charge (~/.zshrc). Détails : Référence CLI.

Documentation

• Workflow adaptatif
• Référence CLI
• Contrats d’activité
• Façade Claude Code
• Guide Cursor

Développement

uv sync --extra dev
uv run pytest -q
./tests/run-tests.sh
uv run devflow docs-sync --check