Pipeline Spec Ops (Lead-Worker)

Que fait Pipeline Spec Ops (Lead-Worker) ?

SKILL_DIR = le répertoire contenant ce fichier.

Limites de rôle (non-négociables)

Rôle	Peut	Ne doit pas
Lead (vous)	Lire/rechercher du code, exécuter des tests/linters/compilations, rédiger des specs, des revues et l'état d'exécution (dans le répertoire d'exécution), gérer les worktrees via worktree.sh ; après l'accord explicite de l'utilisateur, exécuter migrate_to_bare.sh --apply ; une fois le point de contrôle approuvé, commiter le travail approuvé sur les branches sop/* (staged : également entre les étapes) et exécuter pr.sh open / pr.sh merge (fusion selon auto_merge_risk) ; selon auto_cleanup (ou avec le consentement de l'utilisateur) nettoyer après les PR fusionnées	Modifier, créer, supprimer ou déplacer un fichier applicatif — dans le dépôt principal ou un worktree de worker (seules exceptions : migrate_to_bare.sh --apply et le fast-forward de worktree.sh sync) ; résoudre les conflits de fusion manuellement ; fusionner une tâche qui n'a pas été APPROUVÉE, utiliser --admin, ou contourner la protection de branche
Worker (sous-agent)	Modifier les fichiers autorisés dans son worktree jusqu'à ce que la DoD soit satisfaite	Toucher des fichiers non autorisés, commiter/pousser, travailler en dehors de son worktree

Envie de "juste corriger" ? Écrivez un spec.

Attribution des modèles

Le runtime de la phase préliminaire donne les modèles par rôle (lead = phase 1, lead_phase2, worker, worker_light, scout) ; le relecteur s'exécute sur lead. Rôles, valeurs par défaut, surcharges, paliers : models.md. Si vous n'êtes pas sur le modèle Lead de la phase en cours, dites à l'utilisateur comment basculer (/model, /effort dans Claude Code) ; ne continuez pas silencieusement — sauf pour une exécution single, qui conserve le modèle Lead de la phase 1.

Sessions et contexte

• Phase 1 : étapes 0–2 sur le modèle Lead de la phase 1.
• Phase 2 : étapes 3–6. split : commence par Reprendre dans une nouvelle session sur le modèle Lead de la phase 2, en lisant uniquement le plan, l'état et les specs de l'étape en cours (autonomes). single : continue dans la même session.

session_split (env SOP_SESSION_SPLIT) : auto (défaut) = split pour toute tâche à risque élevé, trois tâches ou plus, ou mode staged, sinon single ; always → split ; never → single.

Le point de contrôle l'affiche ; l'utilisateur peut le modifier.

L'état d'exécution se trouve dans le répertoire d'exécution (run.run_dir, <git common dir>/sop-run/) : en dehors de toute arborescence de travail, partagé par toutes les arborescences de travail, conservé entre les sessions. N'utilisez jamais de bloc-notes de session.

Sortie de commande — exécutez chaque commande de lint/test/compilation/DoD via bash SKILL_DIR/scripts/run_logged.sh <run dir>/logs/<slug>-<step>-<n>.log '<commande>' (affiche exit=<rc> lines=<n> log=<chemin> + les 40 dernières lignes en cas d'échec). Lisez plus du journal uniquement lorsque la fin n'explique pas un échec. Ne mettez jamais le résultat complet des tests dans le chat.

Workflow

0. Phase préliminaire

bash SKILL_DIR/scripts/preflight.sh --agent <claude|gemini|codex> --fetch (votre propre environnement d'exécution ; --fetch met d'abord à jour un default_base distant) imprime une ligne JSON : runtime (noter worker, session_split), config (noter source_worktree, default_base, provision, max_parallel, auto_merge_risk, merge_method, auto_cleanup ; layout), leftovers, run, pr, baseline, base_check, docker_pool. Dans une disposition bare, exécutez les commandes Lead git/test dans source_worktree. Agissez sur :

1. run.has_state: true (exécution en cours) : demandez à l'utilisateur s'il souhaite reprendre, nettoyer (si toutes les tâches ont des PR en attente de l'utilisateur), ou archiver (worktree.sh rundir --archive) et recommencer.
2. leftovers (tâches d'exécutions précédentes) : mentionnez-les.
3. config.offer_bare_migration: true : exécutez bash SKILL_DIR/scripts/migrate_to_bare.sh (essai à sec), demandez à l'utilisateur s'il souhaite convertir vers la disposition bare-repo worktree, formatée selon bare-layout.md. Uniquement sur un oui explicite : migrate_to_bare.sh --apply, réexécutez preflight.sh, relisez les docs de l'agent depuis le nouveau source_worktree. Bloqué ou refusé → disposition standard.
4. pr.ok: false : l'exécution ne commit que localement ; le point de contrôle le dit. Notez pr.into. Règles de fusion : execution-plan.md.
5. base_check.match: false, fetch_error ou error : mettez-vous d'accord sur la base avec l'utilisateur d'abord.
6. docker_pool.error : dites à l'utilisateur que la capacité est inconnue ; sinon docker: false : passez ; sinon free < config.max_parallel : avertissez (l'étape 3 revérifie).
7. baseline = sortie de git status --porcelain=v1 && git diff HEAD | sha256sum, déjà exécutée dans source_worktree. Conservez-la pour state.json.

1. Audit (lecture seule)

• Établissez le périmètre avec l'utilisateur (chemins ; sécurité / performances / dette / lacunes de spec).
• Scannez statiquement ; pour un périmètre étendu, faites d'abord un premier balayage avec des scouts parallèles en lecture seule (scout.md) et vérifiez leurs pistes. Exécutez les commandes de lint/test/typage existantes du projet pour établir la vérité terrain via run_logged.sh (journaux audit-<n>.log) ; n'installez pas d'outils et ne modifiez pas la configuration.
• Produisez un rapport de lacunes : observations numérotées avec fichier:ligne, gravité, preuve, correctif proposé. Regroupez-les en tâches de taille Worker avec des listes blanches petites et non chevauchantes.
• Avec plusieurs tâches, rédigez le plan d'exécution selon execution-plan.md : pas de dépendances → independent (tous en parallèle) ; liées → staged (étapes ordonnées par dépendance, parallèles au sein d'une étape, chacune construite sur le résultat intégré de l'étape précédente).

2. Spec (point de contrôle)

• Pour chaque tâche, remplissez worker-spec-template.md et choisissez son palier Worker (models.md). Remplissez les Règles du dépôt à partir des docs de l'agent (AGENTS.md, CLAUDE.md, également dans les répertoires touchés par la liste blanche) : commandes de test/lint, drapeaux, règles de langage ; ajoutez les pièges du dépôt de votre mémoire et les éventuels worker_notes. Les Workers ne peuvent pas voir votre contexte. Écrivez les commandes DoD comme ces règles l'exigent.
• Enregistrez dans le répertoire d'exécution, jamais dans un worktree : gap-report.md, plan.md, spec-<slug>.md, <slug>.wl.
• Vérification de chevauchement par étape : bash SKILL_DIR/scripts/check_scope.sh --overlap <source_worktree> <slug>.wl... ; OVERLAP → redécoupez ou ré-étagez ; vérifiez chaque POSSIBLE manuellement.
• Essai à sec de la DoD : exécutez chaque commande DoD des tâches independent / de l'étape 1 dans source_worktree via run_logged.sh (journaux <slug>-dry-<n>.log), notez sa classe dans le spec, corrigez celles BROKEN (détails) ; étape 2+ à l'étape 3.
• Critique du plan : avec 2+ tâches, mode staged, une tâche à risque élevé, ou sur demande : un critique en lecture seule (modèle lead uniquement si une tâche est à risque élevé, sinon lead_phase2) ; décidez pour chaque observation selon plan-critic.md. Un tour.
• Affichez le rapport du point de contrôle et attendez l'approbation avant l'étape 3, au format de execution-plan.md §3. L'approbation doit explicitement couvrir : en mode staged les commits et fusions locales inter-étapes ; toujours le commit automatique, le push, la PR et — selon la colonne Fusion — la fusion après APPROUVER ; avec auto_cleanup le nettoyage après chaque fusion ; et, lorsque la ligne du pool Docker dit prune: ask, worktree.sh pool --prune. Formulation au §3.
• Frontière de phase : après l'approbation, écrivez <run dir>/state.json (§7) avec phase: 2 et la session convenue, puis :

  • split, dites à l'utilisateur :

    Plan approuvé et enregistré dans <run dir>. Exécutez /clear, passez au Lead de la phase 2 (/model <lead_phase2.model>, /effort <lead_phase2.effort>), puis invoquez cette compétence avec resume.

    (Codex / Antigravity : démarrez une nouvelle session sur lead_phase2.)

  • single : dites à l'utilisateur que le plan est enregistré dans <run dir> et que l'exécution continue ici ; passez à l'étape 3 sans changer de modèle (resume fonctionne toujours).

Reprendre (phase 2)

Sur resume : entrypoints.md.

Nettoyage (après que l'utilisateur a fusionné)

Sur cleanup : entrypoints.md.

Les étapes 3–5 s'exécutent une fois par étape (independent = une seule étape), dans l'ordre du plan. Tenez state.json à jour : mettez à jour le statut d'une tâche lors de l'envoi, de chaque tour de revue, de l'approbation ou du report, et de l'étape lors de l'intégration.

3. Worktree + envoi

1. Avant de créer les worktrees de l'étape : bash SKILL_DIR/scripts/worktree.sh pool. docker: false → passez ; error → dites à l'utilisateur, demandez d'abord. Sinon si free < le nombre de tâches de l'étape, exécutez worktree.sh pool --prune uniquement si l'approbation le couvre (cela supprime tous les réseaux Compose inutilisés des projets ; ils sont recréés), sinon demandez à l'utilisateur.
2. Pour chaque tâche : bash SKILL_DIR/scripts/worktree.sh create <slug> [--base <ref>] (étape 1 : omettez --base ; étape 2+ : --base sop-stage/<n-1> ; worktree.sh path <slug> prévisualise). Vérifiez provisioned dans la sortie ; arrêtez si une entrée attendue manque. Étape 2+ : exécutez à sec la DoD de chaque tâche dans son nouveau worktree via run_logged.sh avant l'envoi (corrections de chemin/drapeau uniquement ; sinon demandez).
3. Insérez le chemin et la base du worktree dans chaque spec, puis envoyez tous les Workers de l'étape en parallèle selon dispatch.md, chacun sur le modèle de son worker_tier (worker / worker_light ; limitez max_parallel).

4. Vérification (par tâche)

1. bash SKILL_DIR/scripts/check_scope.sh <worktree> <fichier-liste-blanche> doit sortir avec le code 0 ; en cas de violations, le Worker les annule (compte comme un tour de revue).
2. Réexécutez vous-même chaque commande DoD dans le worktree via run_logged.sh (journaux <slug>-gate-r<round>-<n>.log) ; toutes doivent sortir avec le code 0.

5. Revue (par tâche) + barrière d'étape

Suivez review-checklist.md : le diff est revu sur le modèle lead (split : sous-agent relecteur en lecture seule, vous vérifiez ses observations ; single : vous) par rapport à la base enregistrée. Émettez APPROUVER ou DEMANDER_MODIFICATIONS avec des observations numérotées fichier:ligne ; bouclez avec le Worker au maximum 3 tours, puis remontez à l'utilisateur. Les tâches bouclent indépendamment. Une tâche light échouant au tour 1 est ré-envoyée sur le modèle worker (models.md).

• independent : sur APPROUVER, commitez, poussez, ouvrez la PR avec pr.sh et fusionnez-la lorsque les règles de fusion automatique le permettent, sans poser de question (§4a).
• staged : lorsque chaque tâche de l'étape est APPROUVÉE, commitez chacune localement, exécutez worktree.sh integrate <n> --base <base de l'étape> sop/<slug>..., et passez la vérification d'intégration (toutes les DoD de l'étape dans le worktree de l'étape) avant l'étape suivante ; conflits, échecs d'intégration et remontées : execution-plan.md. S'il reste des étapes, définissez current_stage sur la suivante dans state.json et continuez dans la même session. Proposez une nouvelle session (/clear, puis resume) uniquement lorsque le contexte est devenu volumineux (deux étapes se sont déroulées, ou de nombreux tours de revue) ; c'est sûr ici.

6. Clôture

1. Réexécutez la commande de référence de l'étape 0 ; elle doit correspondre, sinon signalez exactement ce qui a changé dans le dépôt principal — ne le "corrigez" pas vous-même.
2. PR : les PR independent existent déjà (§5) ; listez chacune comme merged, open (raison) ou locale uniquement. staged : ouvrez la PR unique à partir du dernier sop-stage/<n> avec pr.sh (fusion selon auto_merge_risk, §6).
3. Nettoyage des worktrees et branches des PR fusionnées, worktree.sh sync, et — une fois chaque tâche nettoyée — worktree.sh rundir --archive. Pas de question uniquement avec auto_cleanup dans l'approbation, sinon demandez d'abord. Jamais --force.
4. Résumé final : observations traitées, reportées (et dépendants bloqués), branches/PR avec état, ce qui a été nettoyé et ce qui reste. Si des PR attendent l'utilisateur, terminez par : après les avoir fusionnées, invoquez cette compétence avec cleanup.

Scripts et disposition

Utilisation, codes de sortie, chemins des worktrees, provisionnement, surcharges de configuration : scripts-and-layout.md.