proposal

Par chorus-aidlc · chorus

Workflow de proposition Chorus — créez des propositions avec des ébauches de documents et de tâches, gérez le DAG de dépendances, validez et soumettez pour révision.

npx skills add https://github.com/chorus-aidlc/chorus --skill proposal

Skill Proposal

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

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 tient les brouillons de documents et les brouillons de tâches. À l'approbation Admin, ces brouillons se matérialisent en vrais Documents et Tâches.

Elaboration resolved --> Create Proposal --> Add drafts --> Validate --> Submit --> 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 Document :

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 Supprimer un brouillon de document de la proposal

Brouillons de Tâche :

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 Supprimer un brouillon de tâche de la proposal

Post-Approbation (tâches existantes) :

Outil Objectif
chorus_create_tasks Créer des tâches en lot (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 supprimer des dépendances de tâches (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 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 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 rédigez la proposal sur l'enfant à la place. (Voir la section theme-ideas du skill /idea.)

Étape 1.5 : Détecter le mode OpenSpec

Avant de rédiger les brouillons de documents, charger le skill openspec-aware à 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, é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 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 avec un champ content tapé à la main. Retaper des milliers de lignes par l'LLM consume 20k+ tokens de contenu par proposal et casse l'équivalence d'octets avec la source de vérité locale (openspec-aware §2 Rule 1 explique le raisonnement complet). Ignorer l'Étape 2 ci-dessous quand en mode OpenSpec — le flux basé wrapper dans openspec-aware §3.6 la remplace pour les documents.

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

Étape 2 : Ajouter des Brouillons de Document

Ajouter les brouillons de document 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 document : prd, tech_design, adr, spec, guide

Étape 3 : Ajouter des Brouillons de Tâche

Ajouter les brouillons de tâche un à la fois. La réponse retourne le draftUuid du nouveau brouillon — l'utiliser 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, 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 tâche : low, medium, high

Étape 4 : Réviser 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 soumission, un chorus-proposal-reviewer peut s'exécuter et poster un commentaire VERDICT. Si le VERDICT est FAIL, ou un Admin rejette la proposal, vous devez la réviser et la soumettre à nouveau.

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 les brouillons.

  1. 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.

  2. Rejeter la proposal (auto-rejet du vôtre, ou demander à l'admin de rejeter celui 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.

  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 document deviennent de vrais Documents
  • Les brouillons de tâche deviennent de vraies Tâches (statut : open, prêtes pour les développeurs)
  • Le statut affiché de l'Idea est automatiquement dérivé de la progress de Proposal et Tâche — 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 lot 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/supprimer 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 des Tâches aux Agents Developer (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"]
  • Passer instanceUuid pour épingler la tâche à une instance spécifique en ligne (assigne comme agent_instance) ; l'omettre pour une assignation agent simple qui hérite de l'instance épinglée de l'idea racine au moment du réveil

Directives de Rédaction de Document

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 de Tâche

Les bonnes tâches sont :

  • Module-scoped — Un module fonctionnel cohérent par tâche, pas une simple fonction ou fichier
  • Testables — Des critères d'acceptation clairs et cohérents sont requis 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é, par ex. « Tous les tests passent : tests unitaires de la couche service, tests d'intégration API, gestion des cas extrêmes »)
  • 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 inter-modules, référencer le Module Contracts du tech design dans la CA
  • 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 la CA exige l'exécution bout en bout des modules précédents ensemble
  • Conscientes 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 d'API, drapeaux CLI, clés de config, IDs de modèle, etc.) par rapport aux docs officiels plutôt que de se fier à la mémoire de l'LLM

Granularité de Tâche

Chaque tâche doit correspondre à un module fonctionnel indépendamment exécutable et testable — pas une simple fonction, fichier ou endpoint API. Éviter de fractionner les fonctionnalités étroitement liées en tâches séparées ; le coût du workflow Chorus par tâche (claim → implement → self-test → submit → verify) s'accumule rapidement.

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

  • Garder la PRD focalisée sur quoi et pourquoi ; tech design focalisé sur comment
  • Casser les grandes fonctionnalités en tâches module-scoped cohérentes — mais éviter de sur-fractionner les fonctionnalités liées en trop de 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 seul élément plutôt que de lister chaque vérification séparément
  • Toujours mettre en place un DAG de dépendance 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éfinir les contrats dans le tech design avant de rédiger la CA de tâche
  • Quand combiner plusieurs ideas, expliquer comment elles se rapportent dans la description de proposal

Suivant

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

Skills similaires

chorus
chorus-aidlc / chorus

Orchestrer la collaboration multi-agents et humains sur la plateforme Chorus.

1 105
yolo-chorus
chorus-aidlc / chorus

Piloter automatiquement tout le cycle de vie d'un DLC IA, de l'idée à la livraison.

1 105
chorus
chorus-aidlc / chorus

Orchestrer la collaboration multi-agents sur la plateforme Chorus via un workflow AI-DLC structuré.

1 105
chorus
chorus-aidlc / chorus

Orchestrer la collaboration multi-agents sur des projets selon un cycle de développement IA structuré.

1 105
review-chorus
chorus-aidlc / chorus

Approuver, rejeter et vérifier les livrables des agents IA dans un workflow de projet.

1 105