ACP - Protocole de Collaboration entre Agents

Protocole de Collaboration entre Agents

ACP est un protocole de coordination basé sur un dossier partagé pour les agents qui ne peuvent pas se envoyer de messages directement. C'est une machine à états avec des événements JSONL structurés, une propriété de tour, des barrières de préparation et un livrable figé. Ce n'est pas une simple discussion en Markdown.

Tout agent compatible doit être capable de lire et écrire du Markdown/JSON, d'ajouter des événements JSONL, et d'exécuter ou reproduire exactement le comportement des scripts fournis. Ne vous fiez pas à l'état caché du thread, aux API spécifiques au fournisseur, ou à la mémoire de la conversation pour la correction du protocole.

Entrées Requises

Avant de commencer, exigez :

• collaboration_folder : chemin absolu ou relatif au dépôt du dossier partagé.
• objective : ce que la collaboration doit décider ou produire.
• objective_gates : barrières spécifiques à l'objectif. Le protocole génère automatiquement les barrières des livrables.
• participants : tous les identifiants des participants, tels que server, reader, reviewer, ou agent-a.
• participant_id : l'identité de l'agent actuel.
• primary_deliverable_type : l'un des adr, design-spec, implementation-plan, decision-memo, review-report, test-plan, ou custom.
• primary_deliverable_file : optionnel pour les types intégrés, requis pour custom ; doit être en Markdown.
• primary_deliverable_checklist : requis pour custom.
• deliverables_mode : optionnel, par défaut internal ; external nécessite repoRoot.
• deliverables_dir : optionnel, par défaut deliverables.

Si une entrée requise est manquante, demandez avant de créer des fichiers ou d'écrire des événements. N'inventez pas de barrières d'objectif.

Fichiers

Les dossiers du schéma ACP v2 utilisent ces fichiers de protocole :

• protocol.json : protocol: "acp", schemaVersion: 2, objectif, participants, barrières générées et d'objectif, déclaration de livrable, phase actuelle, propriétaire de la proposition, participants en attente, et horodatages.
• events.jsonl : journal d'événements en ajout seul. Chaque ligne est un objet JSON compact.
• proposal.md : proposition actuelle / résumé des modifications.
• review.md : avis structurés des participants.
• decisions.md : index concis des décisions acceptées avec des identifiants stables.
• readiness.md : classification des questions ouvertes, barrières d'objectif, barrières générées des livrables, instantané du livrable, blocages, et résultat de préparation.
• conclusion.md : accusé de réception final du protocole. Ce n'est pas le livrable principal.
• deliverables/ : livrables Markdown réels et pièces jointes optionnelles.

Ne créez pas et n'utilisez pas state.log, discussion.md, ou opinions.md. Ce ne sont pas des fichiers de protocole et ils ne doivent pas apparaître dans les barrières ou les instructions.

Livrables

ACP sépare l'état du protocole des artefacts du livrable :

• Chaque collaboration achevable nécessite un livrable Markdown principal déclaré.
• conclusion.md est l'accusé de réception final ; il référence le livrable figé et le résultat de la préparation.
• Les types de livrables intégrés sont adr, design-spec, implementation-plan, decision-memo, review-report, et test-plan.
• custom nécessite un fichier Markdown explicite et une liste de vérification.
• Les livrables secondaires sont en Markdown. Les pièces jointes peuvent être des fichiers non Markdown dans le répertoire deliverables.
• Le mode internal stocke les livrables à l'intérieur du dossier de collaboration.
• Le mode external stocke les livrables dans un répertoire relatif à la racine du dépôt et utilise des références external:<fichier> dans les événements, la préparation et la conclusion.
• Un livrable doit inclure Status: Draft, Status: In Review, ou Status: Frozen.
• Le propriétaire de la proposition fige le livrable principal avec deliverable_frozen ; le gel est strict et n'a pas de chemin de dégel/regel.

Initialisation

Préférez le script fourni :

python3 <skill>/scripts/init_collaboration.py \
  --folder <dossier_collaboration> \
  --participant <id_participant> \
  --participant <id_autre_participant> \
  --objective "<objectif>" \
  --primary-deliverable-type design-spec \
  --completion "<barrière_objectif>" \
  --completion "<autre_barrière_objectif>"

Pour les livrables externes :

python3 <skill>/scripts/init_collaboration.py \
  --folder <depot>/.acp/<execution> \
  --participant <id_participant> \
  --participant <id_autre_participant> \
  --objective "<objectif>" \
  --primary-deliverable-type adr \
  --deliverables-mode external \
  --repo-root ../.. \
  --deliverables-dir docs/architecture \
  --completion "<barrière_objectif>"

L'initialiseur crée des modèles pour les fichiers de protocole et le livrable principal. Il échoue si protocol.json existe déjà, sauf si --resume est fourni.

Événements

Utilisez scripts/append_event.py ou reproduisez exactement son comportement. Champs d'événement requis :

• seq : entier continu dans events.jsonl.
• from : identifiant du participant listé dans protocol.json.
• event : nom d'événement autorisé.
• at : horodatage ISO-8601 UTC.
• summary : une phrase courte.

Événements autorisés :

• initialized
• deliverable_drafted
• deliverable_revised
• deliverable_frozen
• proposal_submitted
• review_submitted
• proposal_revised
• question_classified
• decision_proposed
• decision_accepted
• readiness_passed
• completed
• blocked

Tous les événements après initialized nécessitent reply_to pointant vers un événement antérieur. Les références doc sont relatives au dossier de collaboration en mode interne, ou external:<fichier> en mode externe.

Tous les événements deliverable_* nécessitent :

• doc : la référence résolue du livrable.
• role : primary ou supporting.

deliverable_frozen nécessite également un sha256 de premier niveau, un hachage SHA-256 hexadécimal minuscule de 64 caractères du fichier référencé. Une fois figé, le contenu du fichier doit correspondre au hachage.

Phases

Les agents doivent agir selon protocol.json.currentPhase et protocol.json.waitingFor :

• drafting : le propriétaire de la proposition rédige le livrable principal, ajoute deliverable_drafted, met à jour proposal.md, puis ajoute proposal_submitted.
• reviewing : les réviseurs listés examinent à la fois proposal.md et le livrable principal, ajoutent des avis structurés à review.md, puis ajoutent review_submitted.
• revising : le propriétaire de la proposition met à jour proposal.md et les livrables si nécessaire, ajoute deliverable_revised si un livrable a changé, puis ajoute proposal_revised.
• decision_review : le propriétaire de la proposition classe toutes les questions ouvertes dans readiness.md et ajoute question_classified ; les participants acceptent ensuite les entrées explicites de decisions.md avec decision_accepted.
• readiness_check : le propriétaire de la proposition fige les livrables requis, enregistre les instantanés dans readiness.md, exécute la validation, puis ajoute readiness_passed.
• completed : arrêtez-vous, sauf si l'utilisateur démarre explicitement un nouveau cycle.
• blocked : arrêtez-vous jusqu'à ce que le blocage soit résolu ou qu'un nouveau cycle commence.

completed n'est valide qu'après readiness_passed et doit référencer conclusion.md.

Format de Révision

Chaque événement review_submitted doit avoir un en-tête review.md correspondant dont le seq est égal au seq de cet événement :

## <ISO-8601 UTC> - <id_participant> - seq <seq_événement review_submitted>

Contexte :
- Lecture de `proposal.md` après l'événement seq `<seq>`.
- Livrable principal examiné : `<chemin résolu>`
- Livrables secondaires examinés : `<chemins ou aucun>`

Portée de la révision :
- Cohérence de la proposition
- Complétude du livrable principal
- Traçabilité des décisions acceptées
- Préparation à l'implémentation

Position :
- ...

Préoccupations :
- ...

Modifications requises :
- ...

Questions :
- ...

Décisions

decisions.md est un index de décisions acceptées, pas le livrable. Chaque décision acceptée doit utiliser un ID stable :

### D1. <titre court>

- Décision : ...
- Justification : ...
- Reflété dans : `deliverables/design-spec.md#section`

Les ID doivent être séquentiels (D1, D2, ...). Reflected in: doit pointer vers un livrable principal ou secondaire déclaré.

Barrière de Préparation

Avant readiness_passed ou completed :

• Chaque question ouverte est [resolved], [deferred_nonblocking], ou [blocking].
• Chaque élément [deferred_nonblocking] inclut Reason: ....
• Aucun élément [blocking] ou [unresolved] ne subsiste.
• Les barrières d'objectif sont vérifiées.
• Les barrières générées des livrables sont vérifiées.
• Le livrable principal a Status: Frozen.
• L'instantané SHA-256 du livrable principal est enregistré.
• Ready to implement est cochée.
• validate_collaboration.py réussit.

Les éléments de préparation bloquants ou non résolus empêchent également decision_accepted.

Conclusion Finale

Avant completed, écrivez conclusion.md comme accusé de réception final. Il doit inclure :

• Résultat de la décision : exactement un parmi [proceed], [do_not_proceed], ou [defer].
• Justification.
• Reçu du livrable : chemin principal, type, SHA-256, livrables secondaires, et pièces jointes.
• Résumé des décisions acceptées.
• Résultat de la préparation.
• Hypothèses.
• Suivis différés.
• Blocages d'implémentation.
• Prochaine action.

blocked est une phase/événement, pas un résultat achevable.

Interrogation et Surveillants

Les participants doivent rester actifs pour la boucle de collaboration jusqu'à ce que la phase soit completed, blocked, ou qu'une échéance explicite du coordinateur soit atteinte.

S'il n'y a pas de surveillant, utilisez :

python3 <skill>/scripts/next_action.py \
  --folder <dossier_collaboration> \
  --participant <id_participant>

Pour les participants autonomes, préférez :

python3 <skill>/scripts/wait_for_turn.py \
  --folder <dossier_collaboration> \
  --participant <id_participant>

wait_for_turn.py renvoie lorsque le participant est listé dans waitingFor, ou lorsque la collaboration devient completed ou blocked. Par défaut, un délai d'attente de 30 minutes est utilisé ; utilisez --timeout 0 uniquement lorsqu'un superviseur externe gère l'annulation.

Validation

Exécutez :

python3 <skill>/scripts/validate_collaboration.py --folder <dossier_collaboration>

Le validateur vérifie les fichiers de protocole requis, les champs du schéma v2, les déclarations de livrables, la sécurité des chemins, la forme des événements, les rôles et hachages des livrables, les transitions de phase, les en-têtes de révision, les ID de décision, les barrières de préparation, le contenu figé du livrable, l'accusé de réception de conclusion et l'ordre d'achèvement.

Codes de sortie :

• 0 : validation réussie.
• 1 : validation réussie avec avertissements.
• 2 : validation échouée.