Metadata-Version: 2.5
Name: devflow-cli
Version: 8.2.0
Summary: Spec-Driven Development workflow CLI
Project-URL: Homepage, https://github.com/sopequenoteck/devflow
Project-URL: Repository, https://github.com/sopequenoteck/devflow
Author-email: sopequenoteck <sopequeno.tech@gmail.com>
License: MIT
License-File: LICENSE
Keywords: claude-code,cli,codex,development,spec-driven,workflow
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: jsonschema>=4.23
Requires-Dist: pyyaml>=6
Requires-Dist: rich>=13
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: hatchling>=1.27; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# 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](docs/pipeline-reference.generated.md).

## Installation

```bash
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](CHANGELOG.md).

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

## Parcours quotidien

```bash
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 deux voies de réouverture
(`implement` si le code est en cause, `prepare` ou `plan` si la validation l'est).

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.

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 :

```bash
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](docs/releases/8.0.0.md).

## 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](docs/adr/0003-v7-guardrails-rupture.md) et les
[notes de version 7.0.0](docs/releases/7.0.0.md).

## 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](docs/adr/0002-v5-rupture-and-provenance.md).

`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](docs/cli-reference.md#synchronisation-linear).

## Documentation

- [Workflow adaptatif](docs/pipeline.md)
- [Référence CLI](docs/cli-reference.md)
- [Contrats d’activité](docs/activity-contracts.md)
- [Façade Claude Code](docs/commands-reference.md)
- [Guide Cursor](docs/cursor-guide.md)

## Développement

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