Metadata-Version: 2.5
Name: devflow-cli
Version: 10.1.1
Summary: Workflow adaptatif pour Claude Code : profils, preuves et contrats d'activité
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: adaptive,claude-code,cli,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 workflow adaptatif pour Claude Code. Il s'adresse au développeur
qui fait travailler Claude Code sur ses projets et veut une rigueur
proportionnée au risque : la CLI choisit un profil à partir de signaux
explicites, confie chaque activité à un agent sous un contrat écrit et ne
franchit une étape que sur des preuves qu'elle produit elle-même.

Un parcours produit une branche Git et un dossier de feature, un besoin écrit
(`need.md`), les résultats de chaque activité, des preuves exécutées
localement (tests, inspection du diff, revue) et un journal des retours
d'usage (frictions et bilan).

## Installer

Prérequis : Python 3.11+, Git et la CLI `claude` (Claude Code).

```bash
uv tool install --refresh devflow-cli==X.Y.Z   # version publiée sur PyPI
devflow init
devflow check
```

`devflow init` installe les commandes `/devflow` et `/devflow.status` dans
`~/.claude` ; `devflow check` vérifie les prérequis. Installer toujours depuis
PyPI, à une version précise.

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. Tant qu'elles diffèrent de la CLI, `devflow status` affiche
un avertissement avec cette commande ; rien n'est modifié sans vous.
`--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.

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

Une version majeure refuse, sans migration, les parcours démarrés avec une
version majeure antérieure : terminez-les avant la mise à jour, voir les notes
de version du dépôt.

## Premier parcours

Une feature avec un identifiant d'issue passe par Devflow ; un correctif
ponctuel ou une tâche hors feature, non.

Avec Claude Code :

```text
/devflow KS-123
```

La commande crée la feature, rédige `need.md`, demande les signaux de
l'évaluation puis enchaîne les activités jusqu'à `done`.

À la main :

```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
devflow adaptive status KS-123
```

Chaque invocation de `adaptive run` traite une activité. `adaptive status`
affiche la progression, les preuves et la prochaine commande ; `--json` en
donne une forme exploitable par la CI.

## Décrire le besoin

`need.md` est l'entrée de tout parcours et fait foi pour chaque activité. Le
besoin dit :

1. les constats observés, avec leur origine ;
2. les décisions prises, non rediscutables pendant le parcours ;
3. l'attendu et les tests ;
4. la livraison (version, fichiers de version) ;
5. le hors périmètre ;
6. les contraintes d'exécution.

## Lire un refus

Chaque refus affiche son motif et la commande de reprise recommandée.

- Refus justifié (le travail de l'agent ne satisfait pas l'étape) : corriger
  le travail, puis reprendre par la commande proposée.
- Échec de Devflow (refus à tort, message trompeur, reprise inadaptée,
  prérequis non documenté) : le consigner aussitôt avec
  `devflow feedback add --type friction`.
- En fin de parcours, terminé ou abandonné : un bilan avec
  `devflow feedback add --type bilan`.

## Profils et garde-fous

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.
- `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` : évaluation du risque, contrôle bloquant de sécurité ou de
données à `verify`, revue indépendante, puis vérification du retour arrière
avant `done`. Un bloc actif impose au minimum le profil `standard`, ne se
désactive par aucune option et interdit les dérogations.

La référence complète (routes, preuves, commandes, contrats d'activité) est
livrée dans le dépôt, sous `docs/`.

## 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, commandes git) ; elle reste
lisible par un agent si elle est définie dans un fichier que son shell charge
(`~/.zshrc`).

## Développement

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