Compétence Chorus 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 DAGs de dépendances, puis les soumettre pour examen par un Admin.

Vue d'ensemble

Une fois l'élaboration d'une Idea résolue (voir /chorus-idea), l'Agent PM crée une Proposal — un conteneur qui contient des brouillons de documents et des brouillons de tâches. Une fois approuvée par un Admin, ces brouillons deviennent de vrais Documents et Tasks.

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

Outils

Gestion des Proposals :

Brouillons de documents :

Brouillons de tâches :

Post-approbation (les tâches existent) :

Outils partagés (checkin, query, comment, search, notifications) : voir le doc de pilotage chorus.

Workflow

Étape 1 : Créer une Proposal vide

Approche recommandée : Créer d'abord le conteneur proposal sans aucun brouillon, puis ajouter progressivement des 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 ideas dans une seule proposal en passant plusieurs UUIDs dans inputUuids.

Un theme 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 theme et écrivez la proposal sur l'enfant à la place. (Voir la section theme-ideas de la compétence /chorus-idea.)

Étape 1.5 : Détecter le mode OpenSpec

Avant d'écrire les brouillons de documents, chargez la compétence /chorus-openspec-aware et exécutez son contrat de détection §1. Branchez selon le résultat :

• CHORUS_OPENSPEC_ACTIVE=1 → suivre /chorus-openspec-aware §3. Choisissez $SLUG, échafaudez openspec/changes/<slug>/, écrivez proposal.md / design.md / specs/<capability>/spec.md localement, puis créez le conteneur proposal (Étape 1 ci-dessus) avec la ligne littérale OpenSpec change slug: <slug> dans description, et miroir chaque fichier local dans un brouillon de document.

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

• CHORUS_OPENSPEC_ACTIVE=0 (CLI absent ou CHORUS_OPENSPEC_MODE=off) → procédez avec l'Étape 2 inchangée. Écrivez les brouillons en ligne en Markdown libre via chorus_pm_add_document_draft MCP direct.

Étape 2 : Ajouter des 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 des 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 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 éditer 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 passe :

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

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

Ajoutez un commentaire expliquant votre raisonnement :

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

Étape 6 : Gérer les retours

Après la soumission, le hook postToolUse de l'agent principal chorus vous pousse à générer le sous-agent chorus-proposal-reviewer, qui publie un commentaire VERDICT. Si le VERDICT est FAIL, ou un Admin rejette la proposal, vous devez la réviser et la réinserrer.

IMPORTANT : Une proposal avec le statut pending ne peut pas être éditée. Vous devez la rejeter d'abord pour la ramener au statut draft avant d'éditer les 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 du reviewer ou de la note de rejet.

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

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

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

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. Réinsérez :

   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 vrais Tasks (statut : open, prêts pour les développeurs)
• Le statut affiché de l'Idea est automatiquement dérivé de la progression de la Proposal et des Tasks — aucune mise à jour manuelle nécessaire

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

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

Créer des tâches en batch 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 des tâches à des Agents Développeur (Optionnel)

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

# Optional: pin the task to a specific (agent, host, cwd) AgentInstance
chorus_pm_assign_task({ taskUuid: "<task-uuid>", agentUuid: "<developer-agent-uuid>", instanceUuid: "<agent-instance-uuid>" })

• La tâche doit être open ou assigned
• L'agent cible doit avoir la permission task: ["write"]
• Passez instanceUuid pour épingler la tâche à une instance en ligne spécifique (assigne en tant que agent_instance) ; omettez-le pour une assignation agent classique qui hérite de l'instance épinglée de l'idea racine au moment du réveil

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 du design technique

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

Les bonnes tâches sont :

• Scoped au module — Un module fonctionnel cohésif par tâche, pas une simple fonction ou fichier
• 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 ; regroupez les vérifications liées en un seul critère mais listez la couverture clé, par 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 agent)
• Ordonnées — Utilisez dependsOnDraftUuids / dependsOnTaskUuids pour exprimer l'ordre d'exécution
• Descriptives — Incluez suffisamment de contexte pour qu'un agent développeur puisse commencer sans questions. Pour les tâches avec dépendances inter-modules, référencez Module Contracts du design technique dans les CA
• Points de contrôle d'intégration — Pour les DAGs avec 4+ tâches, incluez au moins une tâche de point de contrôle d'intégration à un point de convergence dont le CA exige l'exécution end-to-end des modules précédents ensemble
• Conscientes des hallucinations — Quand les tâches impliquent des dépendances externes, notez dans la description de la tâche que les développeurs doivent vérifier les détails spécifiques (signatures API, flags CLI, clés config, IDs de modèles, etc.) par rapport à la documentation officielle 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 simple fonction, fichier ou endpoint API. Évitez de diviser les fonctionnalités étroitement liées en tâches séparées ; les frais généraux du workflow Chorus par tâche (claim → implement → self-test → submit → verify) s'accumulent 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)

Conseils

• Gardez le PRD focalisé sur le quoi et le pourquoi ; le design technique focalisé sur le comment
• Divisez les grandes fonctionnalités en tâches scoped au module — mais évitez de sur-diviser les fonctionnalités liées en trop de petites tâches
• Ajoutez storyPoints pour aider à prioriser et estimer l'effort
• Gardez les critères d'acceptation cohésifs — regroupez les 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âches — 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éfinissez les contrats dans le design technique avant d'écrire les CA de tâches
• Quand vous combinez plusieurs ideas, expliquez comment elles se rapportent dans la description de la proposal

Ensuite

• Après la soumission, un Admin examinera en utilisant /chorus-review
• Après l'approbation, les Développeurs réclament des tâches en utilisant /chorus-develop
• Pour l'élaboration d'Idea, voir /chorus-idea
• Pour un aperçu de la plateforme, voir le doc de pilotage chorus.