amElnagdy/delegate-skills

Pi Délégation

Vous êtes l'orchestrateur. Déléguez une tâche de codage bien délimitée à un implémenteur séparé - l'agent CLI Pi - puis examinez ce qu'il a produit et validez vous-même. Vous rédigez le brief et possédez le jugement ; l'implémenteur effectue les modifications dans sa propre session ; vous vérifiez et commitez.

La boucle nécessite seulement une commande shell et un accès aux fichiers, donc tout orchestrateur comparable peut la piloter.

Quand NE PAS utiliser cette compétence

• La tâche est assez petite pour être faite en ligne ; le coût de délégation n'en vaut pas la peine.
• L'interface CLI pi n'est pas installée ou authentifiée.
• Vous avez besoin d'un implémenteur cloisonné. Pi n'a pas de cloisonnement ni de modes de permissions ; --read-only restreint la surface d'outils, mais une exécution avec capacité d'écriture s'effectue sans invites de confirmation.

Prérequis (vérifier une fois)

1. Installez pi avec npm install -g @earendil-works/pi-coding-agent.
2. Authentifiez-vous : /login dans pi pour un fournisseur par abonnement, ou une variable d'environnement avec clé API / un fichier d'authentification de pi pour un fournisseur par clé API.
3. Confirmez que pi --version fonctionne.
4. Travaillez dans, ou pointez --cd vers, le dépôt git cible.

Choisir le modèle (optionnel)

Omettre --model pour utiliser le modèle par défaut configuré de pi. Pour en choisir un autre, sélectionnez-en un depuis pi --list-models et passez un identifiant explicite ou un motif comme <fournisseur>/<id-du-modèle> ou sonnet:high. Le relais accepte uniquement lettres, chiffres et . _ : / - (la valeur atteint un shell sur Windows), donc les motifs glob avec * ne sont pas transmis.

La boucle

Exécutez ces cinq étapes par tâche. Les étapes 1, 4 et 5 nécessitent du jugement ; les 2 et 3 sont mécaniques.

1. Rédiger le brief

Pi ne voit que le texte que vous envoyez plus ce qu'il peut inspecter dans l'espace de travail - aucun historique de chat ni contexte partagé. Incluez l'objectif, l'état actuel, ce qui doit changer, ce qui doit rester intact, les véritables contraintes du projet, et un contrat de rapport. Dites à pi de ne pas commiter. Gardez une tâche par brief. Pi charge automatiquement les fichiers de contexte AGENTS.md/CLAUDE.md de l'espace de travail et de ses parents, donc les instructions du dépôt lui parviennent sans être intégrées en ligne. Voir references/writing-the-brief.md.

2. Expédier

Utilisez le relais intégré. Il transmet le brief à pi --mode json sur l'entrée standard, capture le flux d'événements JSON, et écrit result.json. (<skill-dir> est le dossier installé contenant ce SKILL.md.)

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /chemin/vers/depot
# choisir un modèle :                          ajouter --model <id depuis pi --list-models>
# choisir un fournisseur :                     ajouter --provider <nom>
# exécution en lecture seule (révision/diagnostic) : ajouter --read-only
# faire confiance aux ressources .pi du projet : ajouter --approve
# reprendre la session la plus récente :        ajouter --resume-last  (brief delta uniquement)
# reprendre une session spécifique :            ajouter --session <id> (brief delta uniquement)
# limite de temps stricte (gardien) :          ajouter --timeout 2h  (la valeur par défaut de 30 minutes convient pour les exécutions courtes ; les briefs d'implémentation ont généralement besoin de 1 à 2 heures)
# voir toutes les options :                    node .../relay.mjs --help

Le répertoire de travail courant du processus enfant fixe l'espace de travail. Le relais écrit les artefacts sous le répertoire temporaire système par défaut et ne commit jamais. Voir references/dispatch-and-poll.md.

3. Attendre la fin

Le relais bloque jusqu'à ce que pi se termine. Exécutez-le avec la fonctionnalité de commande d'arrière-plan de l'orchestrateur, ou mettez-le en arrière-plan dans le shell et interrogez la présence de result.json. Une erreur d'utilisation avant exécution se termine avec le code 2 et n'écrit aucun résultat ; une absence de pi se termine avec le code 127 et écrit status: "pi_unavailable".

Fiez-vous à l'état du processus et à l'arbre de travail plutôt qu'à un affichage de progression. La fin signifie que le processus s'est terminé et que result.json existe. Le rapport complet de pi est le champ finalMessage dans result.json (également imprimé en entier sur la sortie standard entre les marqueurs de rapport).

4. Réviser - ne pas faire confiance à l'auto-rapport

Traitez le message final de pi et ses affirmations de contraintes comme des déclarations :

• Réexécutez vous-même les contraintes du projet.
• Lisez le diff par rapport au brief, en commençant par touchedFiles.
• Exécutez les compétences de garde pertinentes si installées.
• Vérifiez les migrations et recherchez les références orphelines après des suppressions ou des renommages.

Voir references/review-and-land.md.

5. Valider

L'implémenteur modifie l'arbre de travail ; l'orchestrateur commit. Ne commitez qu'après que les contraintes passent et que le diff tienne. Si des reprises sont nécessaires, envoyez un brief delta avec --resume-last ou --session <id>, puis réexaminez.

Autonomie et permissions

Pi n'a pas de cloisonnement ni de modes de permissions. Une exécution par défaut sans tête lit, écrit, édite et exécute des commandes shell sans invites de confirmation - les contrôles sont :

1. --read-only restreint les outils appelables de pi à --tools read,grep,find,ls à travers les outils intégrés, d'extension et personnalisés. Le code d'extension installé s'exécute toujours avec les permissions de l'hôte de l'utilisateur.
2. Le relais passe --no-approve par défaut, donc les paramètres .pi, extensions et compétences du projet restent non fiables. --approve est l'option explicite pour un dépôt auquel l'utilisateur fait confiance.
3. touchedFiles et le diff sont l'enregistrement de ce qui a changé. Inspectez-les après chaque exécution.

Modèle d'autorisation

La délégation est quelque chose que l'humain choisit. Une fois qu'il a accepté ("exécute cette file d'attente", "procède"), valider un travail vérifié respectant les contraintes est le contrat convenu. Deux limites demeurent : montrer, ne pas absorber (rapportez les décisions de conception de pi, les tournants défendables mais non demandés, et les critiques non bloquantes) et arrêter pour changements de périmètre (si la complétion correcte nécessite d'aller au-delà du brief, demandez plutôt que d'étendre le mandat). Voir references/review-and-land.md.

Références

• references/writing-the-brief.md - structure, contrat de rapport, contraintes réelles, livraison par entrée standard, et briefs delta.
• references/dispatch-and-poll.md - drapeaux, artefacts, result.json, interrogation, et reprise après échec.
• references/review-and-land.md - liste de contrôle de révision, limite de commit, et reprise via les sessions pi.
• references/multi-task-queues.md - files d'attente séquentielles, report de contraintes, suivi de progression, et passage final de cohérence.