Specs projet sop-writer (plugin Claude Code)

Contexte

Plugin à embarquer dans la marketplace pham-claude-plugins (à côté de humanizer + doc-generator). Inspiré du pattern de cristallisation d'expérience de GenericAgent (memory/ + SOPs markdown), mais générique et domain-agnostic — pas un catalogue hardcodé.

Objectif

Cristalliser des sessions Claude Code en skills réutilisables (SKILL.md + scripts), pour tout domaine : déploiement Laravel, ressources Terraform, dev mobile, idéation, écriture d'articles, triage emails, etc.

Architecture

plugins/sop-writer/
├── .claude-plugin/plugin.json
├── skills/sop-writer/SKILL.md       # comportement quand invoqué
├── commands/sop.md                   # /sop : cristallise maintenant (manuel)
├── commands/sop-review.md            # /sop-review : force un review immédiat
├── commands/sop-snooze.md            # /sop-snooze N : fait taire l'auto-detector N turns
├── commands/sop-update.md            # /sop-update : met à jour skill existant (opt-in)
├── hooks/checkpoint-review.sh        # appelle Opus 4.7 aux checkpoints
└── prompts/detector.md               # prompt LLM-detector (le cerveau)

Principe clé : un slash = une action, pas de dispatcher LLM (déterminisme + tokens).

Mécanisme de détection

LLM-as-detector (Opus 4.7), pas catalogue hardcodé.

Quand ça déclenche :

• Manuel : /sop ou /sop-review
• Auto : aux checkpoints naturels (PreCompact, SessionEnd, ou tous les K turns avec K élevé ~30)

Ce que le LLM regarde :

1. Résumé d'activité de la session récente
2. Liste des SKILL.md existants (~/.claude/skills/ + .claude/skills/ projet)
3. Question unique : « Y a-t-il une séquence finie et reproductible qui mériterait d'être un skill, ET qui n'est pas déjà couverte ? »

Réponse : 0 ou N propositions, chacune avec name, description, pourquoi, existing_overlap (null ou id).

Anti-doublon

Par défaut silencieux si un skill couvre déjà le pattern. /sop-update manuel pour proposer une mise à jour explicitement.

Snooze

Si user dit non à une proposition, snooze auto pendant N turns (10 par défaut). /sop-snooze N pour forcer.

Récurrence (extension)

À la cristallisation, sop-writer demande si le skill est récurrent :

• Non, à la demande uniquement
• Proposition à chaque ouverture matinale
• Proposition à chaque ouverture sur projet X
• Schedulé via routine Claude Code (cron) — délègue au skill schedule natif

Métadonnée stockée dans frontmatter SKILL.md :

recurrence:
  type: session-start-hint  # ou scheduled
  when: morning             # ou cron expression
  scope: global             # ou project:nom

Hook SessionStart lit ces frontmatters et propose les skills matchant le contexte (heure, jour, projet) — non-intrusif, juste suggestion.

Format SKILL.md produit

---
name: <nom-court>
description: Use when <triggers FR/EN>
recurrence: ...  # optionnel
---

## Variables
- VARIABLES_EXTRAITES (DOMAIN, DB_NAME, etc.)

## Pré-requis
- outils, versions, accès

## Étapes
1. commandes exactes

## Vérifications
- comment savoir que ça a marché

## Pièges rencontrés
- ce qui a foiré pendant la session

Exemple use case validé

Jour 1 : « scanne mes emails et planifie ma journée » → exécution → cristallisation → user choisit récurrence « ouverture matinale » → SKILL.md créé.

Jour 2 matin, ouverture Claude Code : « Bonjour. Je peux relancer morning-email-triage (planning du matin) ? » → user dit oui d'1 mot, pas besoin de se souvenir du nom.

Au checkpoint Jour 2 : detector voit activité similaire MAIS skill existe déjà → silence (pas de doublon).

Coût

1 appel Opus 4.7 par checkpoint (~2-3K tokens d'entrée). Déclenchement parcimonieux donc coût total OK pour usage power-user.

Style

Bilingue FR/EN cohérent avec humanizer + doc-generator de la marketplace.

Localisation prévue

/home/pham/work/projects/claude-plugins/plugins/sop-writer/