Développement Piloté par Subagents

Exécutez le plan en envoyant un subagent dédié par tâche, avec deux étapes de révision après chacune : d'abord la révision de conformité aux spécifications, puis la révision de qualité du code.

Pourquoi les subagents : Vous déléguez les tâches à des agents spécialisés avec un contexte isolé. En formulant précisément leurs instructions et leur contexte, vous vous assurez qu'ils restent concentrés et réussissent leur tâche. Ils ne doivent jamais hériter du contexte ou de l'historique de votre session — vous construisez exactement ce dont ils ont besoin. Cela préserve aussi votre propre contexte pour le travail de coordination.

Principe fondamental : Un subagent dédié par tâche + révision en deux étapes (spécifications puis qualité) = haute qualité, itération rapide

Quand utiliser

digraph when_to_use {
    "Have implementation plan?" [shape=diamond];
    "Tasks mostly independent?" [shape=diamond];
    "Stay in this session?" [shape=diamond];
    "subagent-driven-development" [shape=box];
    "executing-plans" [shape=box];
    "Manual execution or brainstorm first" [shape=box];

    "Have implementation plan?" -> "Tasks mostly independent?" [label="yes"];
    "Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"];
    "Tasks mostly independent?" -> "Stay in this session?" [label="yes"];
    "Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"];
    "Stay in this session?" -> "subagent-driven-development" [label="yes"];
    "Stay in this session?" -> "executing-plans" [label="no - parallel session"];
}

vs. Exécution de plans (session parallèle) :

Même session (pas de changement de contexte)
Un subagent dédié par tâche (pas de pollution du contexte)
Révision en deux étapes après chaque tâche : d'abord conformité aux spécifications, puis qualité du code
Itération plus rapide (pas d'humain dans la boucle entre les tâches)

Le processus

digraph process {
    rankdir=TB;

    subgraph cluster_per_task {
        label="Par tâche";
        "Dispatch implementer subagent (./implementer-prompt.md)" [shape=box];
        "Implementer subagent asks questions?" [shape=diamond];
        "Answer questions, provide context" [shape=box];
        "Implementer subagent implements, tests, commits, self-reviews" [shape=box];
        "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [shape=box];
        "Spec reviewer subagent confirms code matches spec?" [shape=diamond];
        "Implementer subagent fixes spec gaps" [shape=box];
        "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [shape=box];
        "Code quality reviewer subagent approves?" [shape=diamond];
        "Implementer subagent fixes quality issues" [shape=box];
        "Mark task complete in TodoWrite" [shape=box];
    }

    "Read plan, extract all tasks with full text, note context, create TodoWrite" [shape=box];
    "More tasks remain?" [shape=diamond];
    "Dispatch final code reviewer subagent for entire implementation" [shape=box];
    "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];

    "Read plan, extract all tasks with full text, note context, create TodoWrite" -> "Dispatch implementer subagent (./implementer-prompt.md)";
    "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer subagent asks questions?";
    "Implementer subagent asks questions?" -> "Answer questions, provide context" [label="yes"];
    "Answer questions, provide context" -> "Dispatch implementer subagent (./implementer-prompt.md)";
    "Implementer subagent asks questions?" -> "Implementer subagent implements, tests, commits, self-reviews" [label="no"];
    "Implementer subagent implements, tests, commits, self-reviews" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)";
    "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" -> "Spec reviewer subagent confirms code matches spec?";
    "Spec reviewer subagent confirms code matches spec?" -> "Implementer subagent fixes spec gaps" [label="no"];
    "Implementer subagent fixes spec gaps" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [label="re-review"];
    "Spec reviewer subagent confirms code matches spec?" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="yes"];
    "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" -> "Code quality reviewer subagent approves?";
    "Code quality reviewer subagent approves?" -> "Implementer subagent fixes quality issues" [label="no"];
    "Implementer subagent fixes quality issues" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="re-review"];
    "Code quality reviewer subagent approves?" -> "Mark task complete in TodoWrite" [label="yes"];
    "Mark task complete in TodoWrite" -> "More tasks remain?";
    "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
    "More tasks remain?" -> "Dispatch final code reviewer subagent for entire implementation" [label="no"];
    "Dispatch final code reviewer subagent for entire implementation" -> "Use superpowers:finishing-a-development-branch";
}

Sélection du modèle

Utilisez le modèle le moins puissant capable de gérer chaque rôle pour économiser les coûts et augmenter la vitesse.

Tâches d'implémentation mécanique (fonctions isolées, spécifications claires, 1-2 fichiers) : utilisez un modèle rapide et bon marché. La plupart des tâches d'implémentation sont mécaniques quand le plan est bien spécifié.

Tâches d'intégration et de jugement (coordination multi-fichiers, correspondance de motifs, débogage) : utilisez un modèle standard.

Tâches d'architecture, de conception et de révision : utilisez le modèle le plus capable disponible.

Signaux de complexité des tâches :

Touche 1-2 fichiers avec une spécification complète → modèle bon marché
Touche plusieurs fichiers avec des préoccupations d'intégration → modèle standard
Nécessite un jugement de conception ou une compréhension large de la base de code → modèle le plus capable

Gestion du statut de l'Implementer

Les subagents implementer rapportent l'un de quatre statuts. Gérez chacun de manière appropriée :

DONE : Passez à la révision de conformité aux spécifications.

DONE_WITH_CONCERNS : L'implementer a terminé le travail mais a signalé des doutes. Lisez les préoccupations avant de continuer. Si les préoccupations portent sur la justesse ou le périmètre, adressez-les avant la révision. Si ce sont des observations (par exemple, « ce fichier devient trop volumineux »), notez-les et passez à la révision.

NEEDS_CONTEXT : L'implementer a besoin d'informations qui n'ont pas été fournies. Fournissez le contexte manquant et renvoyez-le.

BLOCKED : L'implementer ne peut pas terminer la tâche. Évaluez le blocage :

Si c'est un problème de contexte, fournissez plus de contexte et renvoyez avec le même modèle
Si la tâche nécessite plus de raisonnement, renvoyez avec un modèle plus capable
Si la tâche est trop grande, divisez-la en morceaux plus petits
Si le plan lui-même est mauvais, escaladez vers l'humain

Ne jamais ignorer une escalade ou forcer le même modèle à réessayer sans changements. Si l'implementer a dit que c'est bloqué, quelque chose doit changer.

Modèles de prompts

./implementer-prompt.md - Envoyer le subagent implementer
./spec-reviewer-prompt.md - Envoyer le subagent de révision de conformité aux spécifications
./code-quality-reviewer-prompt.md - Envoyer le subagent de révision de qualité du code

Exemple de flux de travail

You: I'm using Subagent-Driven Development to execute this plan.

[Read plan file once: docs/superpowers/plans/feature-plan.md]
[Extract all 5 tasks with full text and context]
[Create TodoWrite with all tasks]

Task 1: Hook installation script

[Get Task 1 text and context (already extracted)]
[Dispatch implementation subagent with full task text + context]

Implementer: "Before I begin - should the hook be installed at user or system level?"

You: "User level (~/.config/superpowers/hooks/)"

Implementer: "Got it. Implementing now..."
[Later] Implementer:
  - Implemented install-hook command
  - Added tests, 5/5 passing
  - Self-review: Found I missed --force flag, added it
  - Committed

[Dispatch spec compliance reviewer]
Spec reviewer: ✅ Spec compliant - all requirements met, nothing extra

[Get git SHAs, dispatch code quality reviewer]
Code reviewer: Strengths: Good test coverage, clean. Issues: None. Approved.

[Mark Task 1 complete]

Task 2: Recovery modes

[Get Task 2 text and context (already extracted)]
[Dispatch implementation subagent with full task text + context]

Implementer: [No questions, proceeds]
Implementer:
  - Added verify/repair modes
  - 8/8 tests passing
  - Self-review: All good
  - Committed

[Dispatch spec compliance reviewer]
Spec reviewer: ❌ Issues:
  - Missing: Progress reporting (spec says "report every 100 items")
  - Extra: Added --json flag (not requested)

[Implementer fixes issues]
Implementer: Removed --json flag, added progress reporting

[Spec reviewer reviews again]
Spec reviewer: ✅ Spec compliant now

[Dispatch code quality reviewer]
Code reviewer: Strengths: Solid. Issues (Important): Magic number (100)

[Implementer fixes]
Implementer: Extracted PROGRESS_INTERVAL constant

[Code reviewer reviews again]
Code reviewer: ✅ Approved

[Mark Task 2 complete]

...

[After all tasks]
[Dispatch final code-reviewer]
Final reviewer: All requirements met, ready to merge

Done!

Avantages

vs. Exécution manuelle :

Les subagents suivent TDD naturellement
Contexte dédié par tâche (pas de confusion)
Sûr pour le parallélisme (les subagents n'interfèrent pas)
Le subagent peut poser des questions (avant ET pendant le travail)

vs. Exécution de plans :

Même session (pas de transfert)
Progression continue (pas d'attente)
Points de révision automatiques

Gains d'efficacité :

Pas de frais de lecture de fichiers (le contrôleur fournit le texte complet)
Le contrôleur sélectionne exactement le contexte nécessaire
Le subagent reçoit les informations complètes dès le départ
Les questions remontées avant le travail (pas après)

Portes de qualité :

L'auto-révision détecte les problèmes avant le transfert
Révision en deux étapes : conformité aux spécifications, puis qualité du code
Les boucles de révision garantissent que les corrections fonctionnent réellement
La conformité aux spécifications prévient le sur-développement ou sous-développement
La qualité du code garantit que l'implémentation est bien construite

Coût :

Plus d'invocations de subagents (implementer + 2 réviseurs par tâche)
Le contrôleur effectue plus de préparation (extraction de toutes les tâches à l'avance)
Les boucles de révision ajoutent des itérations
Mais détecte les problèmes tôt (moins cher que déboguer plus tard)

Drapeaux rouges

Ne jamais :

Commencer l'implémentation sur la branche main/master sans consentement explicite de l'utilisateur
Ignorer les révisions (conformité aux spécifications OU qualité du code)
Continuer avec des problèmes non résolus
Envoyer plusieurs subagents implémenteurs en parallèle (conflits)
Faire lire le fichier plan au subagent (fournir le texte complet à la place)
Ignorer le contexte de mise en place de scène (le subagent doit comprendre où la tâche s'intègre)
Ignorer les questions du subagent (répondez avant de le laisser procéder)
Accepter « c'est assez proche » sur la conformité aux spécifications (le réviseur a trouvé des problèmes = pas terminé)
Ignorer les boucles de révision (le réviseur a trouvé des problèmes = l'implementer les corrige = révision à nouveau)
Laisser l'auto-révision de l'implementer remplacer la révision réelle (les deux sont nécessaires)
Commencer la révision de qualité du code avant que la conformité aux spécifications soit ✅ (mauvais ordre)
Passer à la tâche suivante tant qu'une révision a des problèmes ouverts

Si le subagent pose des questions :

Répondez clairement et complètement
Fournissez du contexte supplémentaire si nécessaire
Ne les pressez pas d'implémenter

Si le réviseur trouve des problèmes :

L'implementer (même subagent) les corrige
Le réviseur révise à nouveau
Répétez jusqu'à approbation
Ne sautez pas la révision à nouveau

Si le subagent échoue la tâche :

Envoyez un subagent correctif avec des instructions spécifiques
Ne pas essayer de corriger manuellement (pollution du contexte)

Intégration

Compétences de flux de travail requises :

superpowers:using-git-worktrees - REQUIS : Configurer un espace de travail isolé avant de commencer
superpowers:writing-plans - Crée le plan que cette compétence exécute
superpowers:requesting-code-review - Modèle de révision de code pour les subagents réviseurs
superpowers:finishing-a-development-branch - Terminer le développement après toutes les tâches

Les subagents doivent utiliser :

superpowers:test-driven-development - Les subagents suivent TDD pour chaque tâche

Flux de travail alternatif :

superpowers:executing-plans - Utiliser pour une session parallèle au lieu d'une exécution dans la même session