# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this repo is

**Pas un repo de code applicatif.** Ce répertoire pilote uniquement le **suivi du projet ADVMFR** via le MCP Plane self-hosted Elevaseo. Aucun code source, pas de build, pas de tests, pas de lint.

- Workspace Plane : **`advmfr`**
- Instance Plane : **`https://projects.elevaseo.app`** (self-hosted **Community Edition**)
- Transport MCP : `stdio` via `uvx plane-mcp-server` (voir `.mcp.json`)

## Conventions de langue

- **Contenu Plane → anglais uniquement** : noms et descriptions de projets, titres/descriptions/commentaires de work items, labels, states, modules, cycles, milestones, pages. Pas de mix FR/EN.
- **Doc interne du repo → français** (`CLAUDE.md`, `docs/**`, `tasks/**`).
- **Dates** : ISO `YYYY-MM-DD` partout.

## État actuel du workspace Plane

### Membre

| User | Rôle | ID |
|---|---|---|
| Bastien Allain (`bastien@elevaseo.com`) | admin / project lead | `89af038d-f58e-47b9-a7cc-aefa7eb6ad12` |

### Projets

| Projet | Identifier | UUID | Scope |
|---|---|---|---|
| Website | `WEB` | `98d29603-01e9-43e1-8f3a-04c78b45f1da` | Refonte advmfr.com — site institutionnel, SEO technique, contenu, performance |
| Twenty CRM | `CRM` | `0aa23e65-1f70-48fe-adcc-f448ee22a71e` | Déploiement et paramétrage de Twenty CRM (open-source) pour le marketing |

Features activées sur les deux : **cycles, modules, work item types, intake, pages, issue views**. Time tracking **désactivé** (à activer projet par projet si besoin). Timezone : `Europe/Paris`.

### Substitut Initiatives (cross-projet)

Les Initiatives natives Plane **ne sont pas disponibles** sur cette instance self-hosted CE (endpoint workspace features 404 — Initiatives / Teams / Customers / Wiki / Project Grouping / PI sont des features Cloud Business/Enterprise uniquement). Workaround : **convention de labels** `init/<initiative-slug>` créée dans chaque projet contributeur.

| Label | Couleur | Projets | Rôle |
|---|---|---|---|
| `init/advmfr-2026` | `#6366f1` | WEB, CRM | Tague les work items qui contribuent à la vision ADVMFR 2026 cross-projet |

Pour "lister tout ce qui est dans l'initiative X" : filtrer chaque projet par le label `init/*` correspondant.

## Documentation locale (lire en premier)

Toute la doc opérationnelle est dans [`docs/plane-mcp/`](./docs/plane-mcp/) :

| Doc | Quand l'ouvrir |
|---|---|
| [`docs/plane-mcp/README.md`](./docs/plane-mcp/README.md) | Vue d'ensemble + liens sources officielles |
| [`docs/plane-mcp/setup.md`](./docs/plane-mcp/setup.md) | Problème de connexion MCP, troubleshooting, scopes |
| [`docs/plane-mcp/available-tools.md`](./docs/plane-mcp/available-tools.md) | Référence exhaustive des 116 outils `mcp__plane__*` + lesquels 404 sur cette instance |
| [`docs/plane-mcp/best-practices.md`](./docs/plane-mcp/best-practices.md) | Conventions ADVMFR : work items, cycles, modules, milestones, labels, states |

**Toujours relire `best-practices.md` avant toute écriture non triviale dans Plane.**

## Workflow type pour une demande utilisateur

1. **Identifier l'intent** : lecture (audit, recherche, listing) ou écriture (création/MAJ d'items, planning de cycle, etc.).
2. **Orientation MCP** (toujours libre, sans confirmation) :
   - `get_me` → identité (utile pour s'auto-assigner / filtrer).
   - `list_projects` → confirmer le `project_id` si pas déjà dans CLAUDE.md.
   - `list_states` + `list_labels` → connaître les valeurs valides avant `create_work_item`.
3. **Écritures** :
   - Mineures (`create_work_item`, `update_work_item`, `create_work_item_comment`, `add_work_items_to_cycle/module/milestone`) → annoncer brièvement puis exécuter.
   - **Destructives ou irréversibles** (`delete_*`, `archive_*`, `transfer_cycle_work_items`, `create_project`, `update_project` modifiant `identifier`, `update_workspace_features`) → **confirmation explicite obligatoire** avant d'appeler le tool.
4. **Batch** (>5 items) : dry-run en listant ce qui sera touché avant d'exécuter.

## Conventions ADVMFR — résumé express

- **Projets** : restreints. Ajouter un projet seulement si un chantier est vraiment autonome (livrables propres, cadence propre). Sinon préférer **module + label** dans un projet existant.
- **Work items** : titre impératif en anglais, description structurée (Context / Acceptance criteria / Links). Toujours définir `state`, `priority`, ≥1 `assignee`, labels pertinents. `start_date` + `target_date` dès l'entrée en cycle.
- **Cycles** : 1-2 semaines, nom `Sprint YYYY-WW — theme`, jamais chevauchants.
- **Modules** : groupement par chantier (non time-boxed). Un item peut être dans plusieurs modules.
- **Milestones** : pour les deadlines dures. Nom `<What> — <YYYY-MM-DD>`.
- **Initiatives** (Cloud) : indisponibles → label `init/<slug>` cross-projets.
- **States** : préférer `Cancelled` à `delete_work_item` pour conserver l'historique.

## Limitations connues self-hosted CE

Ces outils MCP renvoient HTTP 404 sur `projects.elevaseo.app` et **ne doivent pas être retentés** :

- `update_project_features` / `get_project_features` → utiliser `update_project` directement avec les flags (`cycle_view`, `module_view`, `is_issue_type_enabled`, `is_time_tracking_enabled`, …).
- `*_initiative*` → feature absente, substituer via labels.
- `get_workspace_features` / `update_workspace_features` → endpoint absent.
- Probablement aussi `*_team*`, `*_customer*`, wiki — non testés mais attendus absents.

Si un appel 404 inattendu : suspecter un gap CE/Cloud avant de conclure à un bug MCP.

## Configuration MCP (référence)

`.mcp.json` est versionné — rotation de l'API key uniquement via ce fichier. `.claude/settings.local.json` active explicitement le serveur Plane.

```bash
claude mcp list             # liste les serveurs configurés
claude mcp get plane        # détails du serveur Plane
claude --mcp-debug          # debug verbeux si /mcp ne voit pas Plane
```

## Anti-patterns à éviter

- Créer un nouveau projet Plane sans demander (identifier difficilement modifiable dès qu'il y a des items).
- Mettre `priority: urgent` par défaut → plus rien n'est urgent.
- Work items sans `assignee` ou sans `target_date` quand ils sont dans un cycle actif.
- Cycles à durée variable / chevauchants → casse le burn-down.
- Supprimer (`delete_*`) au lieu d'archiver ou de passer en `Cancelled`.
- Écrire du contenu Plane en français → casse la convention English-only.

## Memory & lessons

Mémoires longue durée gérées par l'auto-memory (système). Leçons spécifiques à la session : `tasks/lessons.md` (directive globale).