Skill Proposition

Ce skill couvre l'étape de Planning du workflow AI-DLC : créer des Propositions 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 l'Admin.

Aperçu

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

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

Outils

Gestion des propositions :

Brouillons de documents :

Brouillons de tâches :

Post-approbation (les tâches existent) :

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

Workflow

Étape 1 : Créer une proposition vide

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

Idées multiples : Vous pouvez combiner plusieurs ideas dans une proposition en passant plusieurs UUID dans inputUuids.

Étape 1.5 : Détecter le mode OpenSpec

Avant de rédiger les brouillons de documents, charger le skill openspec-aware à ~/.codex/skills/openspec-aware/SKILL.md et exécuter son contrat de détection §1. Brancher sur le résultat :

• CHORUS_OPENSPEC_ACTIVE=1 → suivre openspec-aware §3. Choisir $SLUG, scaffolder openspec/changes/<slug>/, rédiger proposal.md / design.md / specs/<capability>/spec.md localement, puis créer le conteneur de proposition (É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 de miroir passent par le wrapper chorus-mcp-call.sh avec content produit par json_encode_file — voir openspec-aware §3.6. Ne pas appeler chorus_pm_add_document_draft directement depuis le harness MCP de Codex avec un champ content saisi à la main. Retaper des milliers de lignes via le modèle consomme 20k+ tokens de contenu par proposition et casse l'égalité d'octets avec la source de vérité locale (openspec-aware §2 Rule 1 explique le raisonnement complet). Sauter l'Étape 2 ci-dessous en mode OpenSpec — le flux basé sur wrapper dans openspec-aware §3.6 le remplace pour les documents.

• CHORUS_OPENSPEC_ACTIVE=0 (CLI absent ou CHORUS_OPENSPEC_MODE=off) → procéder à l'Étape 2 sans changement. Rédiger les brouillons en ligne en tant que 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 — l'utiliser 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é. 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 éditer 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 la 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, valider pour prévisualiser les problèmes :

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

Retourne { valid, issues } avec des 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).

Ajouter 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, un chorus-proposal-reviewer peut exécuter et publier un commentaire VERDICT. Si le VERDICT est FAIL, ou si un Admin rejette la proposition, vous devez réviser et soumettre à nouveau.

IMPORTANT : Une proposition en statut pending ne peut pas être modifiée. Vous devez la rejeter d'abord pour la ramener au statut draft avant de modifier les brouillons.

1. Lire le retour :

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

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

2. Rejeter la proposition (auto-rejet de la 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 ramène la proposition au statut draft. Les agents PM ne peuvent rejeter que leurs propres propositions ; les agents admin peuvent rejeter toute proposition.

3. 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>", ... })

4. Soumettre à nouveau :

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

Étape 7 : Post-approbation

Quand l'Admin approuve :

• Les brouillons de documents deviennent des Documents réels
• Les brouillons de tâches deviennent des Tasks réelles (statut : open, prêtes pour les développeurs)
• Le statut affiché de l'Idea est dérivé automatiquement de la progression de la Proposition 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 par 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 les tâches à des 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 la permission task: ["write"]

Lignes directrices pour la rédaction de documents

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

# Technical Design: <Feature Name>

## Overview
Approche haut niveau.

## Architecture
Design du système, interactions des composants.

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

## API Design
Points de terminaison nouveaux/modifiés.

## Module Contracts
Conventions partagées entre les tâches : format de valeur de retour, pattern de gestion des erreurs, points d'appel inter-modules.

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

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

Lignes directrices pour la rédaction de tâches

Les bonnes tâches :

• Module-scoped — Un module fonctionnel cohésif par tâche, pas une fonction ou fichier unique
• Testable — Des critères d'acceptation clairs et cohésifs obligatoires sur chaque tâche (au moins un élément non vide ; max 6 ; grouper les vérifications liées en un seul critère mais lister la couverture clé, ex. "All tests pass: service layer unit tests, API integration tests, edge case handling")
• Dimensionnée — 1-8 story points (heures de travail d'agent)
• Ordonnée — Utiliser dependsOnDraftUuids / dependsOnTaskUuids pour exprimer l'ordre d'exécution
• Descriptive — Inclure assez de contexte pour qu'un agent développeur puisse commencer sans questions. Pour les tâches avec dépendances inter-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 end-to-end des modules précédents ensemble
• Consciente 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écifiques (signatures API, drapeaux CLI, clés de config, IDs de modèle, etc.) contre 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 fonction, fichier ou point de terminaison API unique. Éviter de scinder les fonctionnalités étroitement liées en tâches distinctes ; 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

• Garder le PRD focalisé sur quoi et pourquoi ; le design technique focalisé sur comment
• Diviser les grandes fonctionnalités en tâches cohésives module-scoped — mais éviter de sur-diviser les fonctionnalités liées en trop nombreuses petites tâches
• Ajouter storyPoints pour aider à prioriser et estimer l'effort
• Garder les critères d'acceptation cohésifs — grouper les vérifications liées 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 des contrats dans le design technique avant de rédiger l'AC des tâches
• En combinant plusieurs ideas, expliquer comment elles se rapportent dans la description de la proposition

Suivant

• Après la soumission, un Admin examinera avec /review
• Après approbation, les développeurs réclament des tâches avec /develop
• Pour l'élaboration des Ideas, voir /idea
• Pour l'aperçu de la plateforme, voir /chorus