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, 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. 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.

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