Skill Proposal

Ce skill couvre l'étape Planning du workflow AI-DLC : créer des Proposals contenant des brouillons de documents (PRD, design technique) et des brouillons de tâches avec DAGs de dépendances, puis les soumettre pour examen Admin.

Espace de noms des outils : les outils Chorus sont exposés par le serveur MCP connecté sous un préfixe chorus__ sur OpenClaw (par ex. chorus__chorus_pm_create_proposal). Les noms simples sont utilisés ci-dessous par souci de lisibilité — préfixez avec chorus__ lors de l'invocation. Voir /chorus pour la règle complète.

Vue d'ensemble

Après que l'élaboration d'une Idea soit résolue (voir /idea), l'Agent PM crée une Proposal — un conteneur qui héberge les brouillons de documents et les brouillons de tâches. À l'approbation Admin, ces brouillons deviennent de véritables Documents et Tasks.

Elaboration resolved --> Create Proposal --> Add drafts --> Validate --> Submit --> Reviewer --> Admin /review

Outils

Gestion des Proposals :

Brouillons de documents :

Brouillons de tâches :

Post-approbation (tâches créées) :

Outils partagés (check-in, requête, commentaire, recherche, notifications) : voir /chorus

Flux de travail

Étape 1 : Créer une Proposal vide

Approche recommandée : créer d'abord le conteneur de proposal sans aucun brouillon, puis ajouter progressivement les brouillons de documents et de tâches un par un.

chorus_pm_create_proposal({
  projectUuid: "<project-uuid>",
  title: "Implement <feature name>",
  description: "Analysis and implementation plan for Idea #xxx",
  inputType: "idea",
  inputUuids: ["<idea-uuid>"]
})

Plusieurs Ideas : vous pouvez combiner plusieurs ideas en une seule proposal en passant plusieurs UUIDs dans inputUuids.

Étape 1.5 : Détecter le mode OpenSpec

Avant de rédiger les brouillons de documents, chargez le skill openspec-aware et exécutez sa §1 détection inline (trois vérifications — CHORUS_OPENSPEC_MODE != "off", un répertoire openspec/ à la racine du projet, et la CLI openspec dans PATH).

Note OpenClaw : il n'existe pas de hook Claude Code SessionStart pour pré-calculer CHORUS_OPENSPEC_ACTIVE. Vous devez exécuter vous-même les trois vérifications, inline, chaque fois que vous atteignez cette étape. Voir openspec-aware §1.

Branchez sur le résultat :

• OpenSpec actif (les trois vérifications réussissent) → suivez openspec-aware §3. Choisissez $SLUG, générez openspec/changes/<slug>/, rédigez proposal.md / design.md / specs/<capability>/spec.md localement, puis créez le conteneur de proposal (Étape 1 ci-dessus) avec la ligne littérale OpenSpec change slug: <slug> dans description, et reflétez chaque fichier local dans un brouillon de document.

  ⛔ Obligatoire en mode OpenSpec : les appels de mirroring passent par le wrapper chorus-api.sh avec content produit par json_encode_file — voir openspec-aware §3.6. Ne pas appeler chorus_pm_add_document_draft directement depuis le harnais MCP avec un champ content saisi à la main. Re-saisir des milliers de lignes via l'LLM consomme 20k+ tokens de contenu par proposal et casse l'égalité d'octet avec la source de vérité locale (openspec-aware §2 Rule 1 explique le raisonnement complet). Ignorez l'Étape 2 ci-dessous en mode OpenSpec — le flux basé sur le wrapper dans openspec-aware §3.6 la remplace pour les documents.

• OpenSpec inactif (une vérification échoue, ou CHORUS_OPENSPEC_MODE=off) → procédez à l'Étape 2 sans modifications. Rédigez les brouillons inline sous forme de Markdown libre via le MCP direct chorus_pm_add_document_draft.

Étape 2 : Ajouter les brouillons de documents

Ajoutez les brouillons de documents un par un :

# Add PRD
chorus_pm_add_document_draft({
  proposalUuid: "<proposal-uuid>",
  type: "prd",
  title: "PRD: <Feature Name>",
  content: "# PRD: <Feature Name>\n\n## Background\n...\n## Requirements\n..."
})

# Add Tech Design
chorus_pm_add_document_draft({
  proposalUuid: "<proposal-uuid>",
  type: "tech_design",
  title: "Tech Design: <Feature Name>",
  content: "# Technical Design\n\n## Architecture\n...\n## Implementation\n..."
})

Types de documents : prd, tech_design, adr, spec, guide

Étape 3 : Ajouter les brouillons de tâches

Ajoutez les brouillons de tâches un par un. La réponse retourne le draftUuid du nouveau brouillon — utilisez-le directement pour dependsOnDraftUuids dans les brouillons suivants.

acceptanceCriteriaItems est obligatoire — chaque brouillon de tâche doit inclure au moins un élément avec une description non vide, sinon l'appel est rejeté. Utilisez le tableau structuré acceptanceCriteriaItems (la chaîne Markdown acceptanceCriteria héritée ne satisfait pas l'exigence).

# First task -> response includes { draftUuid, draftTitle }
chorus_pm_add_task_draft({
  proposalUuid: "<proposal-uuid>",
  title: "Implement <component>",
  description: "Detailed description of what to build...",
  priority: "high",
  storyPoints: 3,
  acceptanceCriteriaItems: [
    { description: "Criteria 1", required: true },
    { description: "Criteria 2", required: true }
  ]
})

# Second task — depends on first
chorus_pm_add_task_draft({
  proposalUuid: "<proposal-uuid>",
  title: "Write tests for <component>",
  description: "Unit and integration tests...",
  priority: "medium",
  storyPoints: 2,
  acceptanceCriteriaItems: [
    { description: "Test coverage > 80%", required: true }
  ],
  dependsOnDraftUuids: ["<draftUuid-from-first-task>"]
})

Pour modifier les critères d'un brouillon plus tard via chorus_pm_update_task_draft, passez un acceptanceCriteriaItems non vide pour les remplacer ; omettez le champ pour les laisser inchangés. Le champ ne peut pas être utilisé pour effacer les critères.

Priorité de tâche : low, medium, high

Étape 4 : Examiner et affiner les brouillons

# Review current state. chorus_get_proposal defaults to section:"basic"
# (metadata + a lightweight draft index, no bodies). Use section:"full" to
# see every draft's content, or section:"documents"/"tasks" for one kind.
chorus_get_proposal({ proposalUuid: "<proposal-uuid>", section: "full" })

# Update a document draft
chorus_pm_update_document_draft({
  proposalUuid: "<proposal-uuid>",
  draftUuid: "<draft-uuid>",
  content: "Updated content..."
})

# Update a task draft
chorus_pm_update_task_draft({
  proposalUuid: "<proposal-uuid>",
  draftUuid: "<draft-uuid>",
  description: "Updated description...",
  dependsOnDraftUuids: ["<other-draft-uuid>"]
})

# Remove a draft
chorus_pm_remove_task_draft({
  proposalUuid: "<proposal-uuid>",
  draftUuid: "<draft-uuid>"
})

Étape 5 : Valider et soumettre

Avant de soumettre, validez pour prévisualiser les problèmes :

chorus_pm_validate_proposal({ proposalUuid: "<proposal-uuid>" })

Retourne { valid, issues } avec niveaux erreur, avertissement et info. Corrigez les erreurs avant de soumettre.

Quand la validation réussit :

chorus_pm_submit_proposal({ proposalUuid: "<proposal-uuid>" })

Cela change le statut de draft à pending. Un Admin l'examinera (voir /review).

Ajoutez un commentaire expliquant votre raisonnement :

chorus_add_comment({
  targetType: "proposal",
  targetUuid: "<proposal-uuid>",
  content: "This proposal covers... Key decisions: ..."
})

Étape 5.5 : Exécuter l'examinateur de Proposal (inline — pas de hook sur OpenClaw)

Différence OpenClaw : le plugin Claude Code s'appuie sur un hook PostToolUse pour injecter un rappel « spawner l'examinateur » après chorus_pm_submit_proposal. OpenClaw n'a pas ce hook. Exécutez l'étape d'examinateur inline, ici même, immédiatement après soumission. N'attendez pas un rappel injecté — il ne viendra jamais.

Obtenez un VERDICT indépendant avant de considérer la proposal prête pour approbation Admin :

1. Préféré — spawner un sous-agent examinateur. Utilisez l'outil OpenClaw sessions_spawn pour spawner un sous-agent dont la task lui dit d'invoquer le skill /proposal-reviewer (fourni avec ce plugin) contre la proposal, puis attendez-le (scrutez l'outil subagents ou utilisez sessions_yield — ne détachez PAS ; vous avez besoin de son VERDICT avant de continuer). Le sous-agent hérite des skills du plugin, donc /proposal-reviewer lui est disponible ; ce skill est en lecture seule et poste un commentaire VERDICT: sur la proposal. Exemple de prompt de tâche :

   Run the /proposal-reviewer skill to review proposalUuid <uuid>. Read the proposal, its documents, the idea, and the elaboration; classify findings BLOCKER/NOTE; post your VERDICT comment on the proposal when done.

2. Secours — l'examiner vous-même. Si sessions_spawn n'est pas disponible sur votre hôte (spawning désactivé par politique), effectuez l'examen vous-même comme une passe focalisée, en lecture seule suivant la procédure du skill /proposal-reviewer : lisez chorus_get_proposal, chorus_get_comments, l'idea liée, et l'élaboration ; vérifiez l'exhaustivité des documents, la granularité des tâches, couverture AC ↔ exigences, le DAG de dépendances, et les points de contrôle d'intégration ; puis enregistrez le résultat via chorus_add_comment se terminant par une ligne VERDICT: (PASS / PASS WITH NOTES / FAIL). Ne modifiez AUCUN brouillon pendant cette passe — c'est en lecture seule. Utilisez la même classification BLOCKER vs NOTE que le skill /proposal-reviewer définit.

3. Lisez le VERDICT et agissez :

   chorus_get_comments({ targetType: "proposal", targetUuid: "<proposal-uuid>" })

   Trouvez le commentaire le plus récent contenant VERDICT: :

   • PASS / PASS WITH NOTES — continuez ; un Admin peut approuver (les notes ne sont pas bloquantes).
   • FAIL — allez à l'Étape 6 et corrigez les BLOCKERs avant de resoummettre.

Si vous avez spawné un sous-agent et aucun nouveau commentaire VERDICT: n'apparaît après son retour, il a probablement épuisé son budget de tours. Respawnez-le UNE FOIS avec un indice de budget concis : "Stay within turn budget. Skip deep verification. Fetch proposal + comments + idea only, skim for obvious BLOCKERs, and post your VERDICT within the first 10 turns." Si toujours pas de VERDICT, revenez à examen manuel (secours Étape 5.5) et postez le VERDICT vous-même.

Étape 6 : Gérer les retours

Après l'exécution de l'examinateur (ou examen Admin), si le VERDICT est FAIL ou l'Admin rejette, vous devez réviser et resoummettre.

IMPORTANT : une proposal en statut pending ne peut pas être modifiée. Vous devez la rejeter d'abord pour la retourner au statut draft avant de modifier des brouillons.

1. Lisez les retours :

   chorus_get_proposal({ proposalUuid: "<proposal-uuid>", section: "full" })
   chorus_get_comments({ targetType: "proposal", targetUuid: "<proposal-uuid>" })

   Identifiez les BLOCKERs du VERDICT d'examinateur ou de la note de rejet.

2. Rejeter la proposal (auto-rejet de la vôtre, ou demander à admin de rejeter celle de quelqu'un d'autre) :

   chorus_pm_reject_proposal({
     proposalUuid: "<proposal-uuid>",
     reviewNote: "Reviewer FAIL. Fixing BLOCKERs: <list>"
   })

   Cela retourne la proposal au statut draft. Les agents PM ne peuvent rejeter que leurs propres proposals ; les agents admin peuvent en rejeter n'importe quelle.

3. Révisez les brouillons :

   chorus_pm_update_document_draft({ proposalUuid: "<proposal-uuid>", draftUuid: "<uuid>", content: "..." })
   chorus_pm_update_task_draft({ proposalUuid: "<proposal-uuid>", draftUuid: "<uuid>", ... })

4. Resoumettez et ré-exécutez l'examinateur (Étape 5 → Étape 5.5 à nouveau) :

   chorus_pm_submit_proposal({ proposalUuid: "<proposal-uuid>" })

Étape 7 : Post-approbation

Quand l'Admin approuve :

• Les brouillons de documents deviennent de véritables Documents
• Les brouillons de tâches deviennent de véritables Tasks (statut : open, prêtes pour les développeurs)
• Le statut affiché de l'Idea est automatiquement dérivé du progrès Proposal et Task — aucune mise à jour manuelle nécessaire

Étape 8 : Gérer les dépendances de tâches (Optionnel)

Après création des tâches, vous pouvez gérer les dépendances :

Créer en masse des tâches avec dépendances intra-batch :

chorus_create_tasks({
  projectUuid: "<project-uuid>",
  tasks: [
    { draftUuid: "draft-db", title: "Create database schema", priority: "high", storyPoints: 2 },
    { draftUuid: "draft-api", title: "Implement API endpoints", priority: "high", storyPoints: 4, dependsOnDraftUuids: ["draft-db"] },
    { title: "Write integration tests", priority: "medium", storyPoints: 2, dependsOnDraftUuids: ["draft-api"] }
  ]
})

Ajouter/supprimer des dépendances sur des tâches existantes :

chorus_update_task({ taskUuid: "<task-B-uuid>", addDependsOn: ["<task-A-uuid>"] })
chorus_update_task({ taskUuid: "<task-B-uuid>", removeDependsOn: ["<task-A-uuid>"] })

Les dépendances sont validées : même projet, pas d'auto-dépendance, pas de cycles (détection DFS).

Étape 9 : Assigner les tâches aux agents développeurs (Optionnel)

chorus_pm_assign_task({ taskUuid: "<task-uuid>", agentUuid: "<developer-agent-uuid>" })

• La tâche doit être open ou assigned
• L'agent cible doit avoir permission task: ["write"]

Directives pour la rédaction de documents

Structure PRD

# PRD: <Feature Name>

## Background
Pourquoi cette fonctionnalité est nécessaire.

## Requirements
### Functional Requirements
- FR-1: ...

### Non-Functional Requirements
- NFR-1: ...

## User Stories
- As a <role>, I want <action>, so that <benefit>

## Out of Scope
Ce qui N'est PAS inclus.

Structure Tech Design

# Technical Design: <Feature Name>

## Overview
Approche haut niveau.

## Architecture
Conception du système, interactions entre composants.

## Data Model
Changements de schéma, nouvelles tables.

## API Design
Endpoints nouveaux/modifiés.

## Module Contracts
Conventions partagées entre tâches : format de valeur retournée, motif de traitement d'erreur, points d'appel cross-module.

## Implementation Plan
Ordre d'implémentation étape par étape.

## Risks & Mitigations
Problèmes potentiels et comment les adresser.

Directives pour la rédaction de tâches

Les bonnes tâches sont :

• Module-scoped — Un module fonctionnel cohésif par tâche, pas une fonction ou fichier unique
• Testables — Des critères d'acceptation clairs et cohésifs sont obligatoires sur chaque tâche (au moins un élément non vide ; max 6 ; groupez vérifications liées en un critère mais listez couverture clé, ex. « All tests pass: service layer unit tests, API integration tests, edge case handling »)
• Sized — 1-8 story points (heures de travail agent)
• Ordonnées — Utilisez dependsOnDraftUuids / dependsOnTaskUuids pour exprimer l'ordre d'exécution
• Descriptives — Incluez assez de contexte pour un agent développeur pour démarrer sans questions. Pour tâches avec dépendances cross-module, référencez les Module Contracts du tech design dans l'AC
• Points de contrôle d'intégration — Pour DAGs avec 4+ tâches, incluez au moins une tâche point de contrôle d'intégration à un point de convergence dont l'AC exige exécution bout-en-bout des modules précédents ensemble
• Conscience des hallucinations — Quand tâches impliquent dépendances externes, notez dans la description de tâche que les développeurs doivent vérifier les spécifiques (signatures API, flags CLI, clés config, IDs modèles, etc.) contre docs officielles plutôt que de se fier à la mémoire LLM

Granularité des tâches

Chaque tâche doit correspondre à un module fonctionnel indépendamment exécutable et testable — pas une fonction, fichier, ou endpoint API unique. Évitez de scinder fonctionnalités étroitement liées en tâches séparées ; la surcharge du workflow Chorus par tâche (claim → implement → self-test → submit → verify) s'accumule vite.

Exemples Mauvais → Bon :

• Mauvais : Book Search + Book CRUD (2 tâches) → Bon : Book Management (1 tâche couvrant CRUD + Search pour la même entité)
• Mauvais : Chart Rendering + Statistics Calculation (2 tâches) → Bon : Data Analytics (1 tâche couvrant stats + visualization comme un module)

Conseils

• Gardez PRD focalisée sur quoi et pourquoi ; tech design focalisé sur comment
• Divisez grandes fonctionnalités en tâches module-scoped cohésives — mais évitez sur-division de fonctionnalité liée en trop nombreuses petites tâches
• Ajoutez storyPoints pour aider prioriser et estimer effort
• Gardez critères d'acceptation cohésifs — groupez vérifications liées en un élément plutôt que de lister chaque vérification séparément
• Configurez toujours le DAG de dépendances de tâche — tâches sans dépendances sont supposées parallélisables
• Quand plusieurs tâches partagent formats de données ou s'appellent, définissez contrats dans le tech design avant de rédiger l'AC de tâche
• Quand combinant plusieurs ideas, expliquez comment elles se rapportent dans la description de proposal
• Exécutez toujours l'examinateur inline après soumission (Étape 5.5) — OpenClaw n'a pas de hook pour vous le rappeler

Suivant

• Après soumission, un Admin examinera en utilisant /review
• Après approbation, Développeurs claimant des tâches utilisant /develop
• Pour l'élaboration d'Idea, voir /idea
• Pour vue d'ensemble plateforme, voir /chorus