# Plane MCP — Best practices ADVMFR Conventions pour structurer le suivi du projet ADVMFR dans Plane (self-hosted CE). ## Hiérarchie des concepts Plane (disponibles en CE) ``` Workspace (advmfr) └── Project ← Website, Twenty CRM, … ├── Epic ← gros chantier ("SEO technical audit") │ └── Work Item (task / bug / story) │ └── Sub-work item ├── Cycle ← time-box 1-2 semaines (sprint) ├── Module ← groupement par feature / thème ├── Milestone ← deadline dure ("v2 launch — 2026-06-30") └── Label / State (workflow) ``` Un work item peut appartenir à **0 ou 1 cycle**, **0..N modules**, **0..N milestones**. > **Les Initiatives natives sont indisponibles sur cette instance CE.** Substituer via une convention de labels workspace `init/` créée dans chaque projet concerné. Actif : `init/advmfr-2026`. ## Convention de langue - **Contenu Plane → anglais uniquement** : project names/descriptions, work item titles/descriptions/comments, labels, states, modules, cycles, milestones, pages. - **Doc interne du repo → français** (`CLAUDE.md`, `docs/**`). - **Dates** : ISO `YYYY-MM-DD`. ## Projets actuels | Projet | Identifier | UUID | Lead | |---|---|---|---| | Website | `WEB` | `98d29603-01e9-43e1-8f3a-04c78b45f1da` | Bastien | | Twenty CRM | `CRM` | `0aa23e65-1f70-48fe-adcc-f448ee22a71e` | Bastien | Ajouter un projet uniquement si un chantier est vraiment autonome (livrables propres, cadence propre). Sinon préférer **module + label** dans un projet existant. ## Work items — règles de création ### Titre (anglais, impératif) - **Action concrète** : `Fix duplicate H1 on /services/grinding` - Pas de placeholder vague : `SEO stuff to do` → mauvais. - Préfixe visuel optionnel : `[Tech]`, `[Content]`, `[Backlink]`. ### Description (markdown, anglais) Structure minimale : ```markdown ## Context Why this task exists. ## Acceptance criteria - [ ] Measurable criterion 1 - [ ] Measurable criterion 2 ## Links - Source (GSC, Ahrefs, Screaming Frog…) ``` ### Propriétés à toujours renseigner | Property | Valeur | |---|---| | `state` | Toujours défini (défaut = `Backlog`) | | `priority` | `urgent` / `high` / `medium` / `low` / `none` | | `assignees` | Au moins un — sinon ça flotte | | `labels` | Catégoriser (`seo-tech`, `content`, `bug`, `quick-win`, `init/advmfr-2026`…) | | `start_date` / `target_date` | Dès qu'un item entre en cycle | | `estimate` | Optionnel mais utile pour le burn-down | | `cycle` / `module` | Affecter dès le triage | ### Types Utiliser les types par défaut et en créer des custom seulement si nécessaire : - **Task** — unité de travail standard - **Bug** — régression / défaut - **Story** — fonctionnalité user-facing - **Epic** — conteneur agrégeant plusieurs work items ### Sub-work items Découper dès qu'une tâche dépasse ~1 jour. Une parent task complétée doit signifier que tous ses sub-items le sont. ## Cycles (sprints) - **Durée** : 1 à 2 semaines. Tenir cette règle. - **Nom** (anglais) : `Sprint YYYY-WW` ou `Sprint NN — theme` (ex. `Sprint 12 — Core Web Vitals optimization`). - **Dates** : non chevauchantes par défaut. Aligner sur les semaines ISO. - **Contenu** : 5 à 15 work items selon taille. Mieux vaut **finir le cycle** que de le surcharger. - **À la clôture** : transférer les items non terminés (`transfer_cycle_work_items`) vers le cycle suivant et archiver l'ancien. - **Burn-down** : checker en milieu de cycle pour anticiper. ## Modules (groupement par thème) Modules ≠ cycles : pas strictement time-boxed, ils regroupent par feature/chantier. - **Nom** (anglais) : descriptif du périmètre (`Services pages redesign`, `Internal linking 2026`, `Grinding topic cluster`). - **Lead** : un owner désigné. - **States** : `Backlog` → `Planned` → `In Progress` → `Paused` → `Completed` / `Cancelled`. - Un work item peut appartenir à plusieurs modules. - Archiver à la complétion pour garder une vue propre. ## Milestones (deadlines dures) Pour les **dates non négociables** (release, lancement, deadline client, kickoff campagne). - **Nom** (anglais) : ` — ` (ex. `v2 launch — 2026-06-30`). - Rattacher work items, cycles, modules contributeurs. ## Substitut Initiatives (cross-projet, CE-friendly) Puisque les Initiatives natives ne sont pas disponibles en CE, simuler via **labels** : - Pattern de slug : `init/` (ex. `init/advmfr-2026`). - Créer le même label dans chaque projet contributeur (`create_label` par projet). - Appliquer aux work items stratégiques. - Pour une vue cross-projet : filtrer chaque projet par le label `init/*` correspondant. - Documenter le périmètre de l'initiative dans une workspace page (long-form) ou dans ce repo. Actuellement actif : **`init/advmfr-2026`** sur `WEB` + `CRM`. ## Epics Epic = work item élargi contenant d'autres work items. À utiliser quand un chantier : - dépasse ~2 semaines, - est trop petit pour mériter un projet à part, - doit être groupé sous un même owner. Exemple : `Epic: Q2 2026 technical SEO audit` contenant 20+ tasks (crawl, log analysis, robots.txt fix, sitemap…). ## Labels — taxonomie ADVMFR | Catégorie | Labels (anglais) | |---|---| | Domain | `seo-tech`, `seo-content`, `seo-netlinking`, `seo-local`, `dev`, `design`, `analytics`, `crm-config`, `crm-data` | | Effort | `quick-win`, `deep-work`, `recurring`, `research` | | Source | `from-gsc`, `from-ahrefs`, `from-audit`, `from-client` | | Statut transverse | `blocked`, `needs-info`, `waiting-on-client` | | Initiatives | `init/advmfr-2026`, … | Créer les labels via `create_label` une fois par projet, puis réutiliser systématiquement. ## States — workflow par défaut | Group | State suggéré (anglais) | |---|---| | `backlog` | Backlog | | `unstarted` | Todo | | `started` | In Progress, In Review | | `completed` | Done | | `cancelled` | Cancelled | Pour SEO content spécifiquement on peut ajouter : `Brief`, `Drafting`, `Editing`, `Published` (groups `started` / `completed`). ## Intake Utiliser l'Intake comme **boîte de triage** pour les demandes brutes (idée, demande client, opportunité keyword Ahrefs) avant qu'elles deviennent des work items propres. Triage hebdo : promouvoir, refuser, ou compléter. ## Comments - Markdown supporté. - Mentionner un work item en collant son identifier (ex. `WEB-42`). - Logger les décisions clés en commentaire plutôt que dans une doc externe — c'est searchable. ## Work logs (time tracking) Optionnel. Activer projet par projet via `update_project` avec `is_time_tracking_enabled: true`. Utile pour : - justifier le temps passé sur un audit, - comparer estimate vs réel sur les types de tâches récurrentes. ## Pages Pour les docs longues (stratégie SEO Q2, briefs rédactionnels, audit complet, runbook). - Workspace pages : transverses (editorial charter, personas, tone of voice). - Project pages : spécifiques à un projet (ADVMFR 2026 SEO strategy). ## Règles d'écriture via MCP — Claude Code 1. **Lectures** (`list_*`, `retrieve_*`, `search_work_items`, `get_*`) → toujours OK sans confirmation. 2. **Écritures mineures** (`create_work_item`, `update_work_item`, `create_work_item_comment`, `add_work_items_to_*`) → annoncer puis exécuter. 3. **Écritures sensibles / irréversibles** (`delete_*`, `archive_*`, `transfer_cycle_work_items`, `update_workspace_features`, `update_project` modifiant `identifier`) → **confirmation explicite obligatoire** avant l'appel. 4. **Création de projet** (`create_project`) → confirmation obligatoire ; identifier difficilement modifiable dès qu'il y a des items. 5. **Batch** (>5 items) : dry-run en listant ce qui sera touché avant. ## Anti-patterns à éviter - Créer 5 projets pour 1 chantier → fragmentation, préférer modules/labels. - Cycles à durée variable / chevauchants → casse le burn-down. - Work items sans assignee ou sans priority → ils dorment. - Tout en `priority: urgent` → plus rien n'est urgent. - Description vide ou = titre → impossible de reprendre l'item plus tard. - `delete_work_item` au lieu de `state: Cancelled` → perte d'historique d'activité. - Mélanger français et anglais dans le contenu Plane → casse la convention English-only et la searchabilité.