Plan Lego

Que fait Plan Lego ?

Transformer un changement arrêté en un DAG en couches allant des primitives simples à une fonctionnalité fonctionnelle. Planification uniquement. Puis s'arrêter.

Le graphe est une pyramide : des blocs indépendants à la base, des blocs composés au-dessus, un seul nœud final. Un pilote ultérieur peut exécuter les nœuds d'une même couche en parallèle, basculer status et redessiner ce graphe. Ce skill ne répartit pas de sous-agents. Il ne charge pas d'autres skills.

Quand l'utiliser

Charger lorsque le travail consiste à transformer un changement arrêté en une carte d'implémentation que le pilote peut suivre.

• Nécessité : ce qu'il faut construire est déjà choisi. Si une liste de fichiers à toucher ou un choix de chemin est déjà dans cette conversation, l'utiliser. Sinon, travailler à partir de l'intention arrêtée et du code. Ne pas inventer une deuxième carte système.
• Ignorer : fautes de frappe, commentaires, formatage, documentation sans code.
• Si l'intention est encore ouverte : s'arrêter. Demander jusqu'à ce que le changement soit arrêté. Ne pas empiler de blocs pour une fonctionnalité qui n'est pas choisie.

Un seul nœud est toujours un DAG. Émettre le contrat complet.

Barrières strictes

1. Planification uniquement. Ne pas écrire de code de production. Ne pas écrire de tests. Nommer la vérification dans done when. Ne pas l'implémenter ici.
2. S'arrêter après l'émission. DAG dans le chat plus le fichier scratch. Ne pas répartir. Ne pas charger le skill suivant.
3. Pas de cycles. Si un bloc dépend d'un bloc ultérieur, la division est erronée. Diviser à nouveau.
4. Ne pas attendre l'approbation. Montrer le DAG et s'arrêter. L'utilisateur interrompt si c'est faux.
5. Ne pas ouvrir le fichier scratch pour l'utilisateur. Ne pas écrire de plan sous docs/.

Granularité des nœuds

Nœud de graphe (unité parallèle) : une primitive indépendante et livrable qu'un sous-agent peut posséder sans attendre un autre nœud en cours.

Exemples : écrire fetchOrder, écrire OrderCard, câbler fetchOrder dans le loader.

Trop gros : implémenter l'authentification. Le diviser. Trop petit : renommer une variable. Le fondre dans le nœud qui en a besoin.

Parties (à l'intérieur d'un nœud) : les fonctions qui doivent atterrir ensemble pour que le nœud compile. Un seul sous-agent fait les parties dans l'ordre. Ne pas disperser les parties.

Exemple de nœud fetch-order :

• files : src/fetchOrder.ts, src/fetchOrder.test.ts
• parts : type Order, puis fetchOrder, puis écrire ou étendre src/fetchOrder.test.ts
• ces parties ne sont pas des nœuds de graphe séparés

Forme du graphe

• Couche 0 : nœuds avec depends on: none. Le pilote peut tous les exécuter en parallèle.
• Couche N : nœuds dont toutes les dépendances sont dans des couches antérieures.
• Dernière couche : un nœud (ou un ensemble serré) qui signifie que la fonctionnalité fonctionne de bout en bout.
• Deux nœuds qui ne dépendent pas l'un de l'autre doivent partager une couche (ou se trouver dans des couches qui ne s'attendent pas mutuellement).
• depends on liste des IDs de nœuds, jamais des noms de fichiers.

Même fichier : si deux nœuds créent ou modifient le même chemin, ils ne doivent pas partager une couche. Les fusionner, ou ajouter une arête depends on pour que l'un attende. Ne pas diviser un fichier seulement pour l'exécuter en parallèle. Deux nœuds qui ne font que lire un chemin peuvent partager une couche. files liste uniquement les chemins créés ou modifiés. La règle du même fichier inclut les fichiers de test.

Champs des nœuds

Chaque nœud possède les sept champs suivants :

1. id : kebab-case, unique dans ce plan, stable (un pilote ultérieur marque cet id comme terminé).
2. name : nom court en anglais.
3. depends on : autres IDs, ou none.
4. files : créer ou modifier (chemins). Inclure le chemin de test de done when.
5. parts : liste ordonnée en C. Dernière partie : écrire ou étendre ce test. Si done when est une vérification manuelle et qu'il n'y a pas de fichier de test, la dernière partie est cette vérification et files n'a pas de chemin de test.
6. done when : un fichier de test ou une commande que le pilote peut exécuter avant de démarrer les dépendants.
7. status : ce skill écrit toujours pending. Un pilote ultérieur peut définir in-progress ou done. Ce skill n'écrit jamais ces deux-là.

Ne pas mettre le code source complet dans le plan.

Tableau de bord en direct

Chemin : <dépôt>/.agent/scratch/lego-plan.json

Même JSON que la clôture de code du chat. Les agents suivent ce fichier. Le produit visible par l'utilisateur est l'image dans le chat.

• Créer .agent/scratch/ si nécessaire.
• Toujours écraser. Ne pas demander, même si des nœuds existants sont in-progress ou done.
• Si le dépôt a git, s'assurer que .gitignore contient .agent/scratch/. Si .gitignore existe et que la ligne est manquante, l'ajouter. Si .gitignore est manquant, le créer avec cette seule ligne.
• Ne pas ouvrir le fichier. Ne pas le vider comme deuxième copie dans le chat. La clôture JSON est la copie que l'utilisateur voit.

Procédures

Procédure 1 : Confirmer un changement arrêté

1. Si le changement est clair, continuer.
2. Si l'utilisateur choisit encore ce qu'il veut, s'arrêter. Demander. Revenir ici une fois que c'est arrêté.

Procédure 2 : Collecter les entrées déjà dans la session

1. Si cette conversation contient déjà une liste de fichiers à toucher, des parties ou un choix de chemin, les utiliser comme ensemble de départ.
2. Sinon, dériver les blocs de l'intention arrêtée et du code que vous devez lire pour nommer les fichiers. Ne pas parcourir tout le dépôt.

Procédure 3 : Diviser en nœuds et parties

1. Lister les primitives candidates (granularité B).
2. Pour chaque primitive, lister les parties C qui doivent compiler ensemble. Terminer par l'écriture ou l'extension du test (ou la vérification manuelle).
3. Dessiner depends on : un nœud dépend d'un autre seulement s'il appelle ou intègre le résultat de ce nœud.
4. Assigner les couches à partir des dépendances. Nœuds indépendants → même couche.
5. Si deux nœuds créent ou modifient le même chemin et partagent une couche, les fusionner ou ajouter une arête. Puis recalculer les couches.
6. Si un cycle apparaît, diviser le mauvais nœud et répéter cette procédure.

Procédure 4 : Remplir chaque nœud

Remplir les sept champs. status est pending sur chaque nœud.

Procédure 5 : Afficher le DAG dans le chat

Afficher, dans cet ordre :

1. Couches : couche 0 à dernière. Sous chaque couche, les nœuds de cette couche.
2. Nœuds : les sept champs pour chaque ID.
3. Mermaid : toujours. Un flowchart (ou graph TD). Les IDs des nœuds dans le diagramme doivent correspondre aux IDs du plan. Pas de classDef. Pas de couleurs de statut. Chaque nœud est en attente.
4. Clôture JSON : un bloc json avec l'objet du tableau de bord en direct. Source de vérité pour les IDs, dépendances, fichiers, parties, doneWhen et status. Les couches sont dérivées de depends. Ne pas stocker de champ layer.

Puis Procédure 6.

Forme Mermaid :

flowchart TD
  fetch-order[fetch-order]
  order-card[order-card]
  wire-loader[wire-loader]
  fetch-order --> wire-loader
  order-card --> wire-loader

Les nœuds d'une même couche n'ont pas d'arête entre eux.

Forme JSON :

{
  "version": 1,
  "nodes": [
    {
      "id": "fetch-order",
      "name": "fetch order",
      "depends": [],
      "files": ["src/fetchOrder.ts", "src/fetchOrder.test.ts"],
      "parts": ["Order type", "fetchOrder", "write or extend src/fetchOrder.test.ts"],
      "doneWhen": "pnpm test src/fetchOrder.test.ts",
      "status": "pending"
    }
  ]
}

depends est un tableau d'IDs. Vide signifie aucun.

Procédure 6 : Écrire le tableau de bord en direct

1. Écrire le même JSON dans .agent/scratch/lego-plan.json (écrasement).
2. S'assurer que .gitignore ignore .agent/scratch/ comme dans « Tableau de bord en direct ».
3. Ne pas ouvrir le fichier.

Procédure 7 : S'arrêter

Après la Procédure 6, s'arrêter. Ne pas écrire de code. Ne pas répartir. Ne pas charger un autre skill.

Arbre de décision

• Intention non arrêtée → Procédure 1.
• Changement arrêté, besoin d'une carte d'implémentation → Procédure 2 → 3 → 4 → 5 → 6 → 7.
• Un seul nœud → quand même Procédure 2 → 7 (contrat complet).
• Faute de frappe / formatage / documentation uniquement → ce skill ne s'applique pas.
• Cycle dans les dépendances → Procédure 3 étape 6.
• Même chemin sur deux nœuds de même couche → Procédure 3 étape 5.
• Nœud « implémenter toute la fonctionnalité » → diviser (Procédure 3).

Signaux d'alarme

Signal	Ce que cela signifie	Faire à la place
Écrire la fonction fetch dans ce skill	Le plan est devenu implémentation	Procédure 7. S'arrêter.
Une seule liste linéaire sans couches	Impossible de répartir	Mettre les nœuds indépendants dans la même couche.
Répartir des sous-agents depuis ici	La feuille est devenue le pilote	Procédure 7. S'arrêter.
IDs Mermaid différents des IDs des nœuds	Le pilote ne peut pas marquer comme terminé	Même ID kebab-case aux deux endroits.
Clôture JSON différente du fichier scratch	Deux sources de vérité	Écrire un seul objet. Le copier aux deux endroits.
Cycle (a → b → a)	La division est erronée	Diviser et recalculer les couches.
Deux nœuds de même couche modifient order.ts	Conflit d'écriture parallèle	Fusionner ou ajouter une arête depends on.
Diviser un fichier pour que deux nœuds puissent s'exécuter en parallèle	Conception non demandée	Garder le fichier. Séquencer les nœuds.
Chemin de test manquant dans files / dernière partie	Le nœud n'est pas livrable	Procédure 3 étape 2.
classDef ou couleurs de statut sur le Mermaid du plan	Ce skill peint la progression	Sans style. Tout en attente.
Parties d'un nœud divisées en nœuds parallèles qui ne peuvent pas compiler seuls	Partie C traitée comme B	Garder ces parties à l'intérieur d'un nœud.
« Implémenter l'authentification » comme un seul nœud	Trop gros	Diviser en primitives.
Attendre « ça a l'air bon ? »	Barrière est de montrer et s'arrêter	Émettre et s'arrêter.
Demander avant d'écraser le fichier scratch	Le tableau de bord en direct est un seul emplacement	Procédure 6. Écraser.
Ouvrir .agent/scratch/lego-plan.json	Supplémentaire pour l'utilisateur	Chat uniquement. Le fichier est pour les agents.
Écrire docs/lego-plan.md	Artefact supplémentaire	Chat plus scratch. Pas de fichier de plan docs.

Gestion des erreurs

• Aucun fichier à toucher dans la session : dériver de l'intention et des lectures ciblées. Si vous ne pouvez pas nommer les fichiers, s'arrêter et dire ce qui manque. Ne pas inventer de chemins.
• Cycle : signaler le cycle par ID. Diviser. Relancer la Procédure 3. Ne pas montrer un Mermaid cyclique comme plan.
• La dernière couche ne signifie pas que la fonctionnalité fonctionne : ajouter un nœud final qui dépend des pièces composées (le câblage), ou dire pourquoi la dernière couche actuelle est déjà le chemin de bout en bout.
• L'utilisateur interrompt en disant qu'un nœud est faux : modifier ce nœud et toute arête depends on qui pointait vers lui. Garder les IDs stables si le nœud existe toujours. Si vous supprimez un nœud, le retirer du Mermaid et du JSON également. Écraser le fichier scratch. Montrer le DAG à nouveau. S'arrêter.
• done when est vague (« ça marche ») : remplacer par une commande ou un chemin de test. Si le projet n'a pas encore de commande de test, nommer la vérification manuelle en une ligne. La dernière partie est cette vérification.
• Pas un dépôt git : écrire quand même .agent/scratch/lego-plan.json sous l'espace de travail si accessible en écriture. Ignorer l'étape gitignore. Le dire en une ligne dans le chat.
• Échec d'écriture scratch (permissions, disque) : montrer quand même le DAG du chat et la clôture JSON. Dire que le tableau de bord en direct n'a pas été écrit. Ne pas faire comme si le fichier existait.
• JSON scratch existant invalide ou en cours d'exécution : écraser. Ne pas fusionner. Ne pas demander.