Compétence Proposal

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

Namespace d'outils : Les outils Chorus sont exposés par le serveur MCP connecté sous un préfixe mcp__chorus__ sur dsh (ex. mcp__chorus__chorus_pm_create_proposal). Les noms seuls sont utilisés ci-dessous pour la lisibilité — préfixez avec mcp__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-chorus), l'Agent PM crée une Proposal — un conteneur qui détient les brouillons de documents et les brouillons de tâches. À l'approbation par l'Admin, ces brouillons se matérialisent en vrais Documents et Tâches.

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

Outils

Gestion de Proposal :

Outil	Objectif
`chorus_pm_create_proposal`	Créer un conteneur de proposal vide
`chorus_pm_validate_proposal`	Valider la complétude de la proposal (retourne erreurs, avertissements, infos)
`chorus_pm_submit_proposal`	Soumettre la proposal pour approbation Admin (brouillon → en attente)

Brouillons de documents :

Outil	Objectif
`chorus_pm_add_document_draft`	Ajouter un brouillon de document à la proposal
`chorus_pm_update_document_draft`	Mettre à jour le contenu du brouillon de document
`chorus_pm_remove_document_draft`	Retirer un brouillon de document de la proposal

Brouillons de tâches :

Outil	Objectif
`chorus_pm_add_task_draft`	Ajouter un brouillon de tâche (retourne draftUuid pour chaînage de dépendances)
`chorus_pm_update_task_draft`	Mettre à jour un brouillon de tâche
`chorus_pm_remove_task_draft`	Retirer un brouillon de tâche de la proposal

Post-approbation (tâches existantes) :

Outil	Objectif
`chorus_create_tasks`	Créer par lot des tâches (supporte dépendances intra-lot via draftUuid)
`chorus_pm_assign_task`	Assigner une tâche à un Agent Developer
`chorus_pm_create_document`	Créer un document autonome
`chorus_pm_update_document`	Mettre à jour le contenu du document (incrémente la version)
`chorus_update_task` (avec `addDependsOn` / `removeDependsOn`)	Ajouter ou retirer des dépendances de tâche (avec détection de cycles)

Outils partagés (checkin, query, comment, search, notifications) : voir chorus

Workflow

Étape 1 : Créer une Proposal vide

Approche recommandée : Créer d'abord le conteneur de proposal sans brouillons, 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>"]
})

Idées multiples : Vous pouvez combiner plusieurs idées en une seule proposal en passant plusieurs UUIDs dans inputUuids.

Un thème ne peut pas être une entrée de proposal — chorus_pm_create_proposal rejette toute idea d'entrée avec isContainer = true. Dérivez une idea enfant du thème et écrivez la proposal sur l'enfant à la place. (Voir la section theme-ideas de la compétence idea-chorus.)

Étape 1.5 : Détecter le mode OpenSpec

Avant de rédiger les brouillons de documents, charger la compétence openspec-aware-chorus et exécuter sa détection inline §1 (trois vérifications — CHORUS_OPENSPEC_MODE != "off", un répertoire openspec/ à la racine du projet, et la CLI openspec sur PATH).

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

Branchement sur le résultat :

OpenSpec actif (les trois vérifications passent) → suivre openspec-aware-chorus §3. Choisir $SLUG, échafauder openspec/changes/<slug>/, rédiger proposal.md / design.md / specs/<capability>/spec.md localement, puis créer le conteneur de proposal (Étape 1 ci-dessus) avec la ligne littérale OpenSpec change slug: <slug> dans description, et refléter chaque fichier local dans un brouillon de document.

⛔ Obligatoire en mode OpenSpec : les appels mirror passent par le wrapper local de paquet CHORUS_MCP_CALL avec content produit par json_encode_file — voir openspec-aware-chorus §3.6. N'appelez pas chorus_pm_add_document_draft directement depuis le harnais MCP avec un champ content dactylographié. Re-taper des milliers de lignes via le LLM consomme 20k+ tokens de contenu par proposal et casse l'égalité des octets avec la source de vérité locale (openspec-aware-chorus §2 Règle 1 explique le raisonnement complet). Ignorer l'Étape 2 ci-dessous en mode OpenSpec — le flux basé sur wrapper dans openspec-aware-chorus §3.6 le remplace pour les documents.
OpenSpec inactif (une vérification échoue, ou CHORUS_OPENSPEC_MODE=off) → procéder avec l'Étape 2 inchangée. Rédiger les brouillons en ligne en Markdown libre via chorus_pm_add_document_draft MCP direct.

Étape 2 : Ajouter des brouillons de documents

Ajouter les brouillons de documents un à la fois :

# 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 des brouillons de tâches

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

acceptanceCriteriaItems est requis — chaque brouillon de tâche doit inclure au moins un élément avec une description non vide, ou l'appel est rejeté. Utiliser le tableau structuré acceptanceCriteriaItems (la chaîne Markdown héritée acceptanceCriteria 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, passer un acceptanceCriteriaItems non vide pour les remplacer ; omettre 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 apercevoir les problèmes :

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

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

Quand la validation passe :

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

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

Ajouter un commentaire expliquant votre raisonnement :

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

Étape 5.5 : Exécuter le Proposal Reviewer (en ligne — pas de hook sur dsh)

Différence dsh : le plugin Claude Code s'appuie sur un hook PostToolUse pour injecter un rappel "spawner le reviewer" après chorus_pm_submit_proposal. dsh n'a pas de tel hook. Exécutez l'étape du reviewer en ligne, juste ici, immédiatement après la soumission. N'attendez pas un rappel injecté — il ne viendra jamais.

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

Préféré — spawner un sous-agent reviewer (premier plan). Utiliser l'outil dsh subagent pour spawner un sous-agent avec run_in_background: false (premier plan — l'appel attend et retourne le résultat en ligne ; la décision d'approbation/rejet dépend du verdict) dont la tâche lui dit d'appeler l'outil skill avec proposal-reviewer-chorus, puis examiner la proposal. Le résultat faisant autorité est le plus récent commentaire VERDICT: sur la proposal. Définir run_in_background: true (un sous-agent continuable/arrière-plan dont vous collectez l'avis de règlement plus tard) seulement quand vous voulez délibérément distribuer et n'avez pas besoin du verdict avant votre étape suivante.

Load and run the proposal-reviewer-chorus 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.
Repli — l'examiner vous-même. Si subagent n'est pas disponible sur votre hôte (spawn désactivé par politique), effectuer l'examen vous-même en tant que passe ciblée, en lecture seule suivant la procédure de la compétence proposal-reviewer-chorus : lire chorus_get_proposal, chorus_get_comments, l'idea liée, et l'élaboration ; vérifier la complétude du document, la granularité des tâches, la couverture AC ↔ exigences, le DAG de dépendances, et les points de contrôle d'intégration ; puis enregistrer le résultat vous-même via chorus_add_comment se terminant par une ligne VERDICT: (PASS / PASS WITH NOTES / FAIL). Ne modifiez AUCUN brouillon durant cette passe — c'est de la révision seule. Utiliser la même classification BLOCKER vs NOTE que la compétence proposal-reviewer-chorus définit.
Lire le VERDICT et agir :
```
chorus_get_comments({ targetType: "proposal", targetUuid: "<proposal-uuid>" })
```
Trouver le commentaire le plus récent contenant VERDICT::
- PASS / PASS WITH NOTES — procéder ; un Admin peut approuver (les notes ne sont pas bloquantes).
- FAIL — aller à l'Étape 6 et corriger 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. Le respawner 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, revenir à examen manuel (repli Étape 5.5) et poster le VERDICT vous-même.

Étape 6 : Gérer les retours

Après que le reviewer s'exécute (ou qu'un Admin examine), si le VERDICT est FAIL ou que l'Admin rejette, vous devez réviser et resoummettre.

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

Lire les retours :

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

Identifier les BLOCKERs du VERDICT du reviewer ou de la note de rejet.

Rejeter la proposal (auto-rejet du vôtre, ou demander à l'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 rejeter n'importe quelle proposal.

Réviser les brouillons :

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

Resoummettre et re-exécuter le reviewer (É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 vrais Documents
Les brouillons de tâches deviennent de vraies Tâches (statut : open, prêtes pour les développeurs)
Le statut affiché de l'Idea est dérivé automatiquement de la Proposal et de la progression des Tâches -- pas de mise à jour manuelle nécessaire

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

Après que les tâches sont créées, vous pouvez gérer les dépendances :

Créer par lot des tâches avec dépendances intra-lot :

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/retirer des dépendances sur les 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 à des Agents Developer (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 la permission task: ["write"]

Directives de rédaction de documents

Structure PRD

# PRD: <Feature Name>

## Background
Why this feature is needed.

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

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

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

## Out of Scope
What is NOT included.

Structure Tech Design

# Technical Design: <Feature Name>

## Overview
High-level approach.

## Architecture
System design, component interactions.

## Data Model
Schema changes, new tables.

## API Design
New/modified endpoints.

## Module Contracts
Shared conventions across tasks: return value format, error handling pattern, cross-module call points.

## Implementation Plan
Step-by-step implementation order.

## Risks & Mitigations
Potential issues and how to address them.

Directives de rédaction des tâches

Les bonnes tâches sont :

Portée de module — Un module fonctionnel cohésif par tâche, pas une seule fonction ou fichier
Testables — Les critères d'acceptation clairs et cohésifs sont requis sur chaque tâche (au moins un élément non vide ; max 6 ; grouper les vérifications connexes en un critère mais lister la couverture clé, ex. « Tous les tests passent : tests unitaires de la couche service, tests d'intégration API, gestion des cas limites »)
Dimensionnées — 1-8 story points (heures de travail d'agent)
Ordonnées — Utiliser dependsOnDraftUuids / dependsOnTaskUuids pour exprimer l'ordre d'exécution
Descriptives — Inclure assez de contexte pour qu'un agent développeur puisse commencer sans questions. Pour les tâches avec dépendances entre modules, référencer les Module Contracts du design technique dans l'AC
Points de contrôle d'intégration — Pour les DAGs avec 4+ tâches, inclure au moins une tâche de point de contrôle d'intégration à un point de convergence dont l'AC exige l'exécution bout en bout des modules précédents ensemble
Conscience des hallucinations — Quand les tâches impliquent des dépendances externes, noter dans la description de la tâche que les développeurs doivent vérifier les spécificités (signatures API, drapeaux CLI, clés de config, IDs de modèles, etc.) contre les docs officielles plutôt que de s'appuyer sur la mémoire LLM

Granularité des tâches

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

Mauvais → Bons exemples :

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)

Astuces

Garder la PRD focalisée sur quoi et pourquoi ; le design technique focalisé sur comment
Casser les grandes features en tâches portée-de-module cohésives — mais éviter de sur-scinder une fonctionnalité connexe en trop de tiny tâches
Ajouter storyPoints pour aider à la priorité et à l'estimation d'effort
Garder les critères d'acceptation cohésifs — grouper les vérifications connexes en un élément plutôt que de lister chaque vérification séparément
Toujours configurer le DAG de dépendance de tâche — les tâches sans dépendances sont supposées parallélisables
Quand plusieurs tâches partagent des formats de données ou s'appellent mutuellement, définir les contrats dans le design technique avant de rédiger l'AC de tâche
Quand combiner plusieurs ideas, expliquer comment elles se rapportent dans la description de proposal
Toujours exécuter le reviewer en ligne après la soumission (Étape 5.5) — dsh n'a pas de hook pour vous le rappeler

Après la soumission, un Admin examinera en utilisant review-chorus
Après approbation, les Developers réclament les tâches en utilisant develop-chorus
Pour l'élaboration d'Idea, voir idea-chorus
Pour la vue d'ensemble de la plateforme, voir chorus

proposal-chorus