Skill Proposal

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

Overview

Après la résolution de l'élaboration d'une Idea (voir /idea), l'Agent PM crée une Proposal — un conteneur qui contient 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

Tools

Proposal Management:

Tool	Purpose
`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 (draft -> pending)

Document Drafts:

Tool	Purpose
`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

Task Drafts:

Tool	Purpose
`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 le brouillon de tâche
`chorus_pm_remove_task_draft`	Supprimer un brouillon de tâche de la proposal

Post-Approval (tasks exist):

Tool	Purpose
`chorus_create_tasks`	Créer en batch des tâches (supporte les dépendances intra-batch 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âche (avec détection de cycles)

Shared tools (checkin, query, comment, search, notifications): voir /chorus

Workflow

Step 1: Create an Empty Proposal

Recommended approach: 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>"]
})

Multiple Ideas: Vous pouvez combiner plusieurs ideas dans une seule proposal en passant plusieurs UUIDs dans inputUuids.

Step 1.5: Detect OpenSpec mode

Avant de rédiger les brouillons de documents, charger le skill openspec-aware à .claude/skills/openspec-aware/SKILL.md et exécuter son contrat de détection §1. Branch 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 proposal (Step 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.

⛔ Mandatory in OpenSpec mode: les appels de mirror 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 harness MCP avec un champ content saisi à la main. Re-typer des milliers de lignes à travers le LLM consomme 20k+ content tokens par proposal et casse l'égalité des bytes avec la source de vérité locale (openspec-aware §2 Rule 1 explique le raisonnement complet). Sauter Step 2 ci-dessous en mode OpenSpec — le flux basé wrapper dans openspec-aware §3.6 le remplace pour les documents.
CHORUS_OPENSPEC_ACTIVE=0 (CLI absent ou CHORUS_OPENSPEC_MODE=off) → procéder avec Step 2 inchangé. Rédiger les brouillons inline sous forme de Markdown libre via direct MCP chorus_pm_add_document_draft.

Step 2: Add Document Drafts

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

Document types: prd, tech_design, adr, spec, guide

Step 3: Add Task Drafts

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 required — chaque brouillon de tâche doit inclure au moins un item avec une description non-vide, sinon l'appel est rejeté. Utiliser le tableau structuré acceptanceCriteriaItems (la chaîne Markdown legacy acceptanceCriteria ne satisfait pas le requirement).

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

Task priority: low, medium, high

Step 4: Review and Refine Drafts

# 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>"
})

Step 5: Validate and Submit

Avant de soumettre, valider pour apercevoir les problèmes :

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

Retourne { valid, issues } avec niveaux error, warning, 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: ..."
})

Step 6: Handle Feedback

Après la soumission, un chorus:proposal-reviewer peut s'exécuter et poster un commentaire VERDICT. Si le VERDICT est FAIL, ou qu'un Admin rejette la proposal, vous devez réviser et resubmitter.

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.

Read feedback:

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.

Reject the proposal (auto-reject la vôtre, ou demander à un 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 peuvent seulement rejeter leurs propres proposals ; les agents admin peuvent rejeter n'importe quelle proposal.

Revise the drafts:

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

Resubmit:

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

Step 7: Post-Approval

Quand l'Admin approuve :

Les brouillons de documents deviennent de vrais Documents
Les brouillons de tâches deviennent de vrais Tasks (status: open, prêts pour les développeurs)
Le statut affiché de l'Idea est automatiquement dérivé de la progression de Proposal et Task — aucune mise à jour manuelle nécessaire

Step 8: Manage Task Dependencies (Optional)

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

Batch créer 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).

Step 9: Assign Tasks to Developer Agents (Optional)

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"]

Document Writing Guidelines

PRD Structure

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

Tech Design Structure

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

Task Writing Guidelines

Les bonnes tâches sont :

Module-scoped — Un module fonctionnel cohésif par tâche, pas une fonction ou un fichier unique
Testable — Des critères d'acceptation clairs et cohésifs sont required sur chaque tâche (au moins un item non-vide ; max 6 ; grouper les vérifications liées en un critère mais lister la couverture clé, p.ex. "All tests pass: service layer unit tests, API integration tests, edge case handling")
Sized — 1-8 story points (heures de travail agent)
Ordered — Utiliser dependsOnDraftUuids / dependsOnTaskUuids pour exprimer l'ordre d'exécution
Descriptive — Inclure assez de contexte pour qu'un agent developer puisse commencer sans questions. Pour les tâches avec dépendances cross-module, référencer les Module Contracts du tech design dans l'AC
Integration checkpoints — Pour les DAGs avec 4+ tâches, inclure au moins une tâche d'integration checkpoint à un point de convergence dont l'AC requiert l'exécution end-to-end des modules précédents ensemble
Hallucination-aware — 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, flags CLI, clés config, model IDs, etc.) contre la doc officielle plutôt que de s'appuyer sur la mémoire LLM

Task Granularity

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

Bad → Good examples:

Bad: Book Search + Book CRUD (2 tasks) → Good: Book Management (1 task covering CRUD + Search for the same entity)
Bad: Chart Rendering + Statistics Calculation (2 tasks) → Good: Data Analytics (1 task covering stats + visualization as one module)

Tips

Garder le PRD focalisé sur what et why ; tech design focalisé sur how
Casser les grandes features en tâches module-scoped cohésives — mais éviter sur-scinder une fonctionnalité liée 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 item plutôt que de lister chaque vérification séparément
Toujours mettre en place un DAG de dépendances 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 tech design avant d'écrire l'AC des tâches
Quand on combine plusieurs ideas, expliquer comment elles se rapportent dans la description de la proposal

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

proposal