Creating a Spec.fr

Créer une spec

Tout projet WorkPilot AI démarre par une spec : un dossier auto-contenu qui décrit ce qu'il faut faire, pour qui, comment, et comment valider que c'est fait.

---

🎯 Qu'est-ce qu'une spec ?

Une spec (spécification) est à la fois :

• Un document lisible par un humain (spec.md)
• Un contrat structuré (JSON) lu par les agents
• Un répertoire persistant qui survit aux redémarrages

Emplacement : .workpilot/specs/XXX-nom-fonctionnalite/ à la racine de votre projet (gitignoré par défaut).

Contenu typique

001-add-health-endpoint/
├── spec.md                   # résumé humainement lisible
├── requirements.json         # critères d'acceptation structurés
├── context.json              # fichiers pertinents à charger
├── implementation_plan.json  # découpage en phases
├── qa_report.md              # résultats de revue QA
└── QA_FIX_REQUEST.md         # demande(s) de correction

---

🚀 Méthodes de création

Via l'application de bureau (recommandé)

1. Dans le Kanban Board, cliquez sur « Nouvelle tâche »
2. Décrivez votre objectif en langage naturel
3. (Optionnel) Ajoutez des critères d'acceptation explicites
4. Cliquez sur « Générer la spec »
5. Une fois la spec affichée en colonne Spec Review, relisez puis Approuvez

Via la CLI

cd apps/backend

# Spec interactive
python runners/spec_runner.py --interactive

# Spec depuis une description
python runners/spec_runner.py --task "Ajoute un endpoint /api/health"

# Forcer un tier de complexité
python runners/spec_runner.py --task "Fix typo dans le README" --complexity simple

# Reprendre une spec interrompue
python runners/spec_runner.py --continue 001-nom-spec

---

🧭 Les 3 tiers de complexité

L'agent complexity_assessor évalue automatiquement la demande. Selon le tier, le pipeline comporte plus ou moins de phases.

Tier	Phases	Exemples
SIMPLE	3	Correction de typo, changement de label, bouton couleur
STANDARD	6	Ajout d'un endpoint + test, refactor d'un composant, petit bug
COMPLEX	8	Intégration OAuth, migration framework, refonte d'architecture

Vous pouvez forcer un tier si l'évaluation auto vous semble inadaptée.

---

📝 Anatomie de spec.md

Le fichier spec.md est généré par un pipeline de 4 agents :

1. spec_gatherer — clarifie le besoin avec des questions (interactives ou déduites du contexte)
2. spec_researcher — explore le codebase pour trouver les fichiers pertinents
3. spec_writer — rédige la spec
4. spec_critic — relit et propose des améliorations

Structure typique :

# 001 - Ajouter un endpoint /api/health

## Contexte
Pourquoi cette feature, dans quel module.

## Objectifs
- Exposer un endpoint GET /api/health
- Retourner { status, uptime_seconds }

## Critères d'acceptation
- [ ] GET /api/health retourne 200
- [ ] La réponse contient `status: "ok"`
- [ ] Un test d'intégration couvre le cas nominal
- [ ] Un test couvre le cas d'erreur 500

## Fichiers concernés
- src/api/routes.ts (modifié)
- src/api/health.ts (nouveau)
- tests/api/health.test.ts (nouveau)

## Plan d'implémentation
Phase 1 — Créer le handler
Phase 2 — Câbler la route
Phase 3 — Écrire les tests

---

✅ Les critères d'acceptation

C'est la partie la plus importante : ce sont les conditions vérifiées par le QA Reviewer.

Règles d'or

• Observable — vérifiable par un humain ou un test (« l'utilisateur voit X »)
• Mesurable — pas de « fonctionne bien » mais « temps de réponse < 200 ms »
• Indépendant — chaque critère ne dépend pas des autres
• Atomique — un seul fait par critère

Exemples ✅

• GET /api/health retourne 200 en moins de 100 ms
• Les tests existants passent tous
• Aucun warning eslint ou biome sur les fichiers modifiés

Contre-exemples ❌

• Le code est propre (subjectif)
• Ajoute des tests (pas de seuil)
• Améliore la performance (pas de mesure)

---

🧩 Le contexte (context.json)

Liste des fichiers, modules et symboles pertinents pour la tâche. Construit par l'agent spec_researcher qui :

• Utilise la recherche sémantique (grepai)
• Suit le graphe d'imports
• Analyse les imports inverses (qui appelle ce fichier ?)
• Identifie les tests liés

Plus le contexte est ciblé, plus les agents sont efficaces et économes en tokens.

---

📋 Le plan d'implémentation (implementation_plan.json)

Découpage en phases ordonnées. Chaque phase :

• A un objectif précis
• Contient une liste d'actions (créer fichier, modifier fonction…)
• A un modèle assigné (ex : Opus pour la phase critique, Sonnet pour les autres)
• A un budget de réflexion

Le plan est exécuté par le Coder phase par phase, avec checkpoints entre chaque phase.

---

🔁 Contrôles interactifs pendant l'exécution

Vous pouvez intervenir à tout moment :

Via l'UI

• Bouton Pause sur la carte Kanban
• Bouton Add Instruction pour injecter une note à l'agent
• Bouton Abort pour annuler

Via la CLI / fichiers

# Pause après la session en cours
touch .workpilot/specs/001-name/PAUSE

# Ajouter une instruction humaine
echo "Focus sur le bug de login d'abord" > .workpilot/specs/001-name/HUMAN_INPUT.md

# Reprendre
python run.py --spec 001 --continue

Raccourcis clavier terminal

• Ctrl+C une fois → pause et prompt d'instruction
• Ctrl+C deux fois → exit immédiat

---

🧪 Valider une spec avant exécution

Pour vérifier que votre spec est bien formée :

python validate_spec.py --spec-dir .workpilot/specs/001-feature --checkpoint all

Checks effectués :

• Critères d'acceptation mesurables
• Fichiers référencés existent
• Plan cohérent avec les critères
• Pas de conflits avec d'autres specs actives

---

🧠 Bonnes pratiques

• Commencez petit — une spec de 3-5 critères est plus facile à piloter qu'une spec monolithique
• Découpez les grosses features en plusieurs specs ordonnées
• Relisez la spec avant d'approuver — c'est votre dernier point de contrôle humain avant que les agents codent
• Enrichissez le contexte si vous constatez que l'agent oublie un fichier important
• Utilisez la mémoire — Graphiti retient les décisions des specs précédentes

---

Prochaine étape

➡️ Comprendre le pipeline multi-agents