Doc Refonte Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Refonte complète de la documentation ulk — README vitrine + docs/ clean en 5 fichiers.

Architecture: README.md (root) = pitch + install + 5 commandes + liens. docs/ = guide.md + reference.md + adr.md + glossaire.md + README.md (index). Tous les fichiers stale supprimés.

Tech Stack: Markdown, Node.js (registry auto-généré), git

---

Task 1 : Supprimer les fichiers stale

Files:

• Delete: ulk-guide.md

• Delete: docs/README.md

• Delete: docs/00-index-2026-03-25.md

• Delete: docs/01-cahier-des-charges-2026-03-25.md

• Delete: docs/02-doc-technique-2026-03-25.md

• Delete: docs/03-doc-utilisateur-2026-03-25.md

• Delete: docs/04-user-stories-2026-03-25.md

• Delete: docs/05-glossaire-2026-03-25.md

• Delete: docs/06-architecture-2026-03-25.md

• Delete: docs/00-meta/conventions.md

• Delete: docs/00-meta/index.md

• Delete: docs/analysis/addyosmani-skills-eval-2026-04.md

• Delete: docs/analysis/update-ulk-2026-04.md

• Step 1 : Supprimer tous les fichiers stale

rm /Users/izo/Dev/Docs/Ulk/ulk-guide.md
rm /Users/izo/Dev/Docs/Ulk/docs/README.md
rm /Users/izo/Dev/Docs/Ulk/docs/00-index-2026-03-25.md
rm /Users/izo/Dev/Docs/Ulk/docs/01-cahier-des-charges-2026-03-25.md
rm /Users/izo/Dev/Docs/Ulk/docs/02-doc-technique-2026-03-25.md
rm /Users/izo/Dev/Docs/Ulk/docs/03-doc-utilisateur-2026-03-25.md
rm /Users/izo/Dev/Docs/Ulk/docs/04-user-stories-2026-03-25.md
rm /Users/izo/Dev/Docs/Ulk/docs/05-glossaire-2026-03-25.md
rm /Users/izo/Dev/Docs/Ulk/docs/06-architecture-2026-03-25.md
rm /Users/izo/Dev/Docs/Ulk/docs/00-meta/conventions.md
rm /Users/izo/Dev/Docs/Ulk/docs/00-meta/index.md
rm /Users/izo/Dev/Docs/Ulk/docs/analysis/addyosmani-skills-eval-2026-04.md
rm /Users/izo/Dev/Docs/Ulk/docs/analysis/update-ulk-2026-04.md
rmdir /Users/izo/Dev/Docs/Ulk/docs/00-meta 2>/dev/null
rmdir /Users/izo/Dev/Docs/Ulk/docs/analysis 2>/dev/null

• Step 2 : Vérifier que les suppressions sont propres

ls /Users/izo/Dev/Docs/Ulk/docs/

Expected : spec.md todo.md superpowers/ seulement.

• Step 3 : Commit

cd /Users/izo/Dev/Docs/Ulk
git add -A
git commit -m "chore(docs): supprimer fichiers stale et dossiers obsolètes"

---

Task 2 : Réécrire README.md (root)

Files:

• Modify: README.md

• Step 1 : Remplacer le contenu du README

Écrire le fichier suivant à /Users/izo/Dev/Docs/Ulk/README.md :

# ulk

AI Development Toolkit pour Claude Code.

[![Live Demo](https://img.shields.io/badge/demo-live-blue)](https://izo.github.io/ulk/)
[![GitHub](https://img.shields.io/github/stars/izo/ulk?style=social)](https://github.com/izo/ulk)
[![Version](https://img.shields.io/badge/version-3.5.0-purple)](https://github.com/izo/ulk/releases)

## Pourquoi "ulk" ?

**Bruce**, de son vrai nom **Ulk**, est un Vallhund suédois — une race de chien viking millénaire, trapue et intrépide, surnommée "le chien des Vikings".

Comme son ancêtre qui accompagnait les drakkars à travers les mers nordiques, Ulk accompagne les développeurs à travers les océans de code. Petit mais costaud, il ne recule devant aucun défi.

> Le nom "ulk" signifie "loup" en vieux norrois.

## Installation

```bash
curl -fsSL https://raw.githubusercontent.com/izo/ulk/main/install-remote.sh | bash

Ou depuis le dépôt cloné :

./install.sh                          # Installation de base
./install.sh --with-vps               # + agents VPS
./install.sh --with-addy-skills       # + checklists addyosmani

Mise à jour : git pull && ./install.sh — Désinstallation : ./uninstall.sh

Par où commencer

Commande	Ce que ça fait
/ulk:bruce	Point d’entrée principal — détecte l’état du projet et orchestre tout
/ulk:godspeed	Diagnostic rapide : stack, état, prochaine action suggérée
/ulk:shuri	Pipeline doc : spec → todo Kanban → sync
/ulk:sargeras	Audit omniscient 10 axes avec score et verdict
/ulk:2b3	Checkpoint fin de session : lint → docs → commit

Documentation

• Guide — Démarrage, workflows, FAQ
• Référence des agents — Les 71+ agents par catégorie
• ADR — Décisions d’architecture et leurs raisons
• Glossaire — Terminologie ulk
• Spec projet — État et roadmap du projet

- [ ] **Step 2 : Vérifier le rendu**

```bash
wc -l /Users/izo/Dev/Docs/Ulk/README.md

Expected : environ 55-65 lignes.

• Step 3 : Commit

cd /Users/izo/Dev/Docs/Ulk
git add README.md
git commit -m "docs(readme): refonte — vitrine concise avec liens vers docs/"

---

Task 3 : Créer docs/README.md (index)

Files:

• Create: docs/README.md

• Step 1 : Créer l’index de docs/

Écrire le fichier suivant à /Users/izo/Dev/Docs/Ulk/docs/README.md :

# Documentation ulk

| Fichier | Pour qui | Contenu |
|---------|----------|---------|
| [guide.md](guide.md) | Utilisateurs | Démarrage rapide, workflows types, FAQ |
| [reference.md](reference.md) | Utilisateurs | Tous les agents par catégorie + invocations |
| [adr.md](adr.md) | Contributeurs | 10 décisions d'architecture avec rationale |
| [glossaire.md](glossaire.md) | Tous | Terminologie, concepts, abréviations |
| [spec.md](spec.md) | Contributeurs | Spec du projet, état, roadmap |
| [todo.md](todo.md) | Contributeurs | Backlog Monoboard Kanban |

---

*Registry agents auto-généré : [`agents/registry.md`](../agents/registry.md) via `node cheatheet/generate-registry.cjs`*

• Step 2 : Commit

cd /Users/izo/Dev/Docs/Ulk
git add docs/README.md
git commit -m "docs: ajouter index docs/README.md"

---

Task 4 : Créer docs/guide.md

Files:

• Create: docs/guide.md

• Step 1 : Créer le guide utilisateur

Écrire le fichier suivant à /Users/izo/Dev/Docs/Ulk/docs/guide.md :

# Guide ulk

## Démarrage rapide

### 1. Installer

```bash
curl -fsSL https://raw.githubusercontent.com/izo/ulk/main/install-remote.sh | bash

2. Première commande

Dans n’importe quel projet, taper dans Claude Code :

/ulk:bruce go

Bruce analyse le projet et propose l’action la plus logique. Sur un projet vide, il génère spec + todo. Sur un projet en cours, il reprend la prochaine tâche.

3. Vérifier l’installation

/ulk:godspeed

Diagnostic instantané : stack détectée, état, CLI installés, prochaine action.

---

Les 3 workflows essentiels

Workflow 1 — Nouveau projet

/ulk:bruce go

1. Bruce lance Godspeed → diagnostic
2. Shuri génère docs/spec.md (spécification) + docs/todo.md (backlog Kanban)
3. Task Runner prend la première tâche et commence

Résultat : spec structurée + backlog priorisé en une commande.

Workflow 2 — Session de développement

/ulk:bruce next     ← prend et exécute la prochaine tâche
/ulk:bruce next     ← tâche suivante
/ulk:2b3            ← fin de session : lint → docs → commit

Task Runner suit la vélocité et affine ses estimations. 2b3 fait le checkpoint final et commit proprement.

Workflow 3 — Audit / pré-release

/ulk:sargeras       ← audit omniscient 10 axes

ou en mode ciblé :

/ulk:vision         ← qualité du code (8 dimensions)
/ulk:perf-auditor   ← Core Web Vitals + bundle + DB
/ulk:a11y-auditor   ← WCAG 2.1/2.2

ou tout en parallèle via l’orchestrateur :

/ulk:blackemperor   ← mode audit : 4 audits simultanés + rapport consolidé

---

Le système en 4 couches

Couche 1 — L’orchestrateur

Bruce (/ulk:bruce) est le seul point d’entrée à connaître. Il comprend 9 commandes naturelles :

Vous tapez	Ce qui se passe
go	Détecte et lance l’action la plus logique
status	Diagnostic complet du projet
next	Prend et exécute la prochaine tâche
fix	Cherche et corrige les erreurs
audit	Audit qualité du code
audit all	4 audits en parallèle (code, perf, a11y, SEO)
review	Revue de complétude avant livraison
ship	Vérifications pré-release
sync	Synchronise avec Notion/Linear

Bruce a une mémoire persistante inter-sessions : il se souvient du projet, de la stack, des préférences.

Couche 2 — Le diagnostic

Godspeed scanne le projet en quelques secondes et cache le résultat 30 minutes. Gandalf surveille la consommation de contexte et alerte au-delà de 40%.

Couche 3 — Les agents de travail

• Documentation : Shuri (spec + todo + sync), Friday (snapshots), Strange (reverse doc)
• Exécution : Task Runner (tâches depuis todo.md), Robocop (fix erreurs)
• Qualité : Vision (8 dimensions), Perf Auditor, A11y Auditor, SEO Auditor, Sargeras (10 axes)
• Fin de session : 2b3 (lint → tests → simplification → commit)

Couche 4 — Les spécialistes

Activés selon le contexte : Frontend (8 agents), Stack Analyzers (5), Deploy (5), Tests (2), VPS (16+), Mobile (Happy → Steve + Fluke), Notion/Linear (Bifrost, Brigitte).

---

Comment les agents communiquent

Bloc CONTEXTE PROJET — quand Bruce appelle un agent, il lui passe un résumé structuré du projet. L’agent ne re-scanne pas. Économie : 3 000 à 10 000 tokens par appel.

Mémoire persistante — 8 agents gardent un état entre sessions :

Agent	Ce qu’il retient
Bruce	Projet, stack, préférences
Godspeed	Dernier diagnostic (expire au prochain commit)
Gandalf	Zone de contexte, alertes
Task Runner	Vélocité par catégorie
2b3	Problèmes récurrents
Steve	Décisions API mobile
Fluke	Stack Android, form factors
Tony	Stacks préférées, historique projets

CLI > MCP — les outils CLI (gh, vercel, neonctl) consomment 0 token. Les MCP sont réservés aux outils sans CLI viable (Figma, Notion, Linear).

---

Tips session

• Règle des 50% : ne jamais dépasser 50% de contexte. Au-delà → /clear après avoir commité.
• /ulk:gandalf : vérifie la santé de la session avant de continuer.
• /ulk:godspeed : à lancer en début de session pour récupérer le contexte projet en 30 secondes.
• Une tâche par session : ne pas chaîner des sujets non liés. Commit → /clear → nouvelle session.

---

FAQ

Q : Je dois connaître les 71 agents ? Non. Bruce les sélectionne pour vous. /ulk:bruce go suffit dans 80% des cas.

Q : Comment mettre à jour ulk ?

git pull && ./install.sh

Le script désinstalle et réinstalle proprement. Pas de migration manuelle.

Q : Ça fonctionne sur n’importe quel projet ? Oui. Les agents détectent la stack automatiquement (Next.js, Nuxt, Astro, SPIP, Swift, Python, Go, Rust, Laravel, WordPress…).

Q : Qu’est-ce que le Monoboard Kanban ? Le format de docs/todo.md utilisé par Task Runner et Shuri. Colonnes : Backlog → Todo → In Progress → Blocked → Done. Compatible avec le plugin Kanban d’Obsidian.

Q : Comment ajouter un agent custom ? Créer agents/NN-nom.md avec le frontmatter YAML requis (name, type, description, tools, model, phase, invocation). Voir .claude/rules/agents-authoring.md.

- [ ] **Step 2 : Vérifier le fichier**

```bash
wc -l /Users/izo/Dev/Docs/Ulk/docs/guide.md

Expected : environ 130-150 lignes.

• Step 3 : Commit

cd /Users/izo/Dev/Docs/Ulk
git add docs/guide.md
git commit -m "docs: créer guide.md — workflows, couches système, tips, FAQ"

---

Task 5 : Créer docs/reference.md

Files:

• Create: docs/reference.md

• Read: agents/registry.md (source auto-générée)

• Step 1 : Régénérer le registry pour avoir les données à jour

cd /Users/izo/Dev/Docs/Ulk
node cheatheet/generate-registry.cjs

Expected : ✓ agents/registry.json — 71 agents + ✓ agents/registry.md

• Step 2 : Créer docs/reference.md

Écrire le fichier suivant à /Users/izo/Dev/Docs/Ulk/docs/reference.md :

# Référence des agents ulk

> **71 agents** organisés par catégorie. Source machine-readable : [`agents/registry.json`](../agents/registry.json)
> Régénérer : `node cheatheet/generate-registry.cjs`

## Invocation

Tous les agents s'invoquent via le pattern Claude Code :

/ulk:

Ou via le pattern générique pour les orchestrateurs :

Task → “Read agents/.md then follow its instructions.”

---

## Orchestrateurs

Agents multi-phase qui coordonnent d'autres agents.

| Agent | Modèle | Invocation | Mission |
|-------|--------|-----------|---------|
| bruce | opus | `/ulk:bruce` | Point d'entrée principal — détecte l'état et orchestre tout |
| blackemperor | opus | `/ulk:blackemperor` | 5 modes : audit, legacy, release, review, ship |
| lovecraft | opus | `/ulk:lovecraft` | Super agent documentation Obsidian |

## Session Workflow

Agents du cycle de travail quotidien.

| Agent | Modèle | Invocation | Mission |
|-------|--------|-----------|---------|
| godspeed | sonnet | `/ulk:godspeed` | Diagnostic : stack, état, prochaine action |
| task-runner | sonnet | `/ulk:task-runner` | Exécute les tâches de docs/todo.md |
| 2b3 | sonnet | `/ulk:2b3` | Checkpoint fin de session |
| robocop | opus | `/ulk:robocop` | Détecte et corrige toutes les erreurs |
| gandalf | sonnet | `/ulk:gandalf` | Surveillance contexte et hygiène session |

## Documentation

Agents qui génèrent et maintiennent la documentation.

| Agent | Modèle | Invocation | Mission |
|-------|--------|-----------|---------|
| shuri | sonnet | `/ulk:shuri` | spec.md → todo.md → sync CLAUDE.md |
| friday | sonnet | `/ulk:friday` | Snapshots contexte + organisation /docs |
| strange | opus | `/ulk:strange` | Reverse doc : reconstitue la doc depuis le code |
| obsidian-vault | sonnet | `/ulk:obsidian-vault` | Transforme /docs en vault Obsidian |

## Audit & Qualité

| Agent | Modèle | Invocation | Mission |
|-------|--------|-----------|---------|
| sargeras | opus | `/ulk:sargeras` | Audit omniscient 10 axes, score, verdict |
| vision | sonnet | `/ulk:vision` | Audit code 8 dimensions + simplification |
| perf-auditor | sonnet | `/ulk:perf-auditor` | Core Web Vitals, bundle, DB |
| a11y-auditor | sonnet | `/ulk:a11y-auditor` | WCAG 2.1/2.2 |
| seo-auditor | sonnet | `/ulk:seo-auditor` | SEO technique + GEO (citations IA) |
| amiral | sonnet | `/ulk:amiral` | Audit généralisabilité (open-source readiness) |
| claude-md-optimizer | sonnet | `/ulk:claude-md-optimizer` | Optimise CLAUDE.md |
| tools-checker | sonnet | `/ulk:tools-checker` | Diagnostic CLI + Skills installés |

## Mobile (iOS / Android)

| Agent | Modèle | Invocation | Mission |
|-------|--------|-----------|---------|
| happy | opus | `/ulk:happy` | Architecte API : audit web → OpenAPI 3.1 → docs/api/ |
| steve | opus | `/ulk:steve` | Orchestrateur Apple : docs/api/ → SwiftUI starter kit |
| fluke | opus | `/ulk:fluke` | Orchestrateur Android : docs/api/ → Kotlin/Flutter starter kit |

Workflow mobile : `happy` → `steve` et/ou `fluke` → `task-runner`

## Sync & Intégrations

| Agent | Modèle | Invocation | Mission |
|-------|--------|-----------|---------|
| bifrost | sonnet | `/ulk:bifrost` | Notion bridge : import/export bidirectionnel |
| brigitte | sonnet | `/ulk:brigitte` | Communications + sync Notion/Linear |

## Spécialistes

| Agent | Modèle | Invocation | Mission |
|-------|--------|-----------|---------|
| tony | opus | `/ulk:tony` | Engineer-in-chief : brief → stack + archi + timing |
| rodin | opus | `/ulk:rodin` | Interlocuteur socratique, anti-chambre d'écho |
| ranma | sonnet | `/ulk:ranma` | Planificateur de migration entre stacks |
| picsou | sonnet | `/ulk:picsou` | Estimation coûts hébergement multi-providers |
| sensei | sonnet | `/ulk:sensei` | Mode apprentissage : explications, diagrammes |
| agamotto | opus | `/ulk:agamotto` | Reverse design system depuis Figma/Pencil |
| astride | sonnet | `/ulk:astride` | Code review sarcastique et pragmatique |

## Stack Analyzers (analyze/)

Analyse approfondie par framework.

| Agent | Invocation | Stack |
|-------|-----------|-------|
| analyze-astro | `/ulk:analyze:astro` | Astro 3-5 |
| analyze-next | `/ulk:analyze:next` | Next.js 13-15 |
| analyze-nuxt | `/ulk:analyze:nuxt` | Nuxt 3-4 |
| analyze-spip | `/ulk:analyze:spip` | SPIP 3-5 |
| analyze-swiftui | `/ulk:analyze:swiftui` | SwiftUI |

## Deploy (deploy/)

Déploiement automatisé multi-providers.

| Agent | Invocation | Plateforme |
|-------|-----------|-----------|
| deploy-vercel | `/ulk:deploy:vercel` | Vercel |
| deploy-netlify | `/ulk:deploy:netlify` | Netlify |
| deploy-cloudflare | `/ulk:deploy:cloudflare` | Cloudflare Pages/Workers |
| deploy-docker | `/ulk:deploy:docker` | Docker |
| deploy-aws | `/ulk:deploy:aws` | AWS (S3, ECS, Lambda) |

## Tests (test/)

| Agent | Invocation | Framework |
|-------|-----------|----------|
| test-unit | `/ulk:test:unit` | Jest, Vitest |
| test-e2e | `/ulk:test:e2e` | Playwright, Cypress |

## Frontend (frontend/)

| Agent | Invocation | Mission |
|-------|-----------|---------|
| frontend-orchestrateur | `/ulk:frontend:orchestrateur` | Coordonne tous les agents frontend |
| brique | `/ulk:frontend:brique` | Figma/HTML → composants shadcn/ui |
| frontend-qa | `/ulk:frontend:frontend-qa` | Audit QA frontend unifié |
| visual-auditor | `/ulk:frontend:visual-auditor` | Audit visuel via Chrome DevTools |
| backoffice-auditor | `/ulk:frontend:backoffice-auditor` | Audit cohérence backoffice |
| svg-analyzer | `/ulk:frontend:svg-analyzer` | Inventaire pages + maquettes SVG |
| pencil-generator | `/ulk:frontend:pencil-generator` | Next.js → fichiers .pen (Pencil) |

## VPS (vps/)

Suite de 16+ agents pour la gestion infrastructure VPS : orchestrateur, audit sécurité, réseau, Docker, CI/CD, monitoring, backups, incidents, migration, compliance. Invocation : `/ulk:vps:<nom>`.

---

*Référence générée depuis [`agents/registry.json`](../agents/registry.json). Pour tout voir : `cat agents/registry.md`*

• Step 3 : Commit

cd /Users/izo/Dev/Docs/Ulk
git add docs/reference.md
git commit -m "docs: créer reference.md — tous les agents par catégorie"

---

Task 6 : Créer docs/adr.md

Files:

• Create: docs/adr.md

• Step 1 : Créer le fichier ADR

Écrire le fichier suivant à /Users/izo/Dev/Docs/Ulk/docs/adr.md :

# Architecture Decision Records — ulk

Décisions architecturales documentées : pourquoi chaque choix structurant a été fait.

---

## ADR-001 — Zéro dépendances npm

**Statut :** Adopté

**Contexte :** ulk est un toolkit d'agents pour Claude Code, pas une application Node.js. Les agents sont des fichiers Markdown.

**Décision :** Aucune dépendance npm. Pas de `package.json` à la racine. Les scripts utilitaires (génération de docs) sont en Node.js vanilla.

**Conséquences :** Distribution simplifiée — pas de `node_modules`, installation par curl ou clone + symlink. Surface d'attaque supply-chain réduite à zéro.

---

## ADR-002 — Agents comme fichiers Markdown

**Statut :** Adopté

**Contexte :** Les agents doivent être portables, lisibles, éditables sans IDE, et versionnés avec git.

**Décision :** Chaque agent est un fichier `.md` avec frontmatter YAML (`name`, `type`, `model`, `tools`, `phase`, `invocation`) suivi d'instructions en Markdown.

**Conséquences :** Portabilité maximale, pas de runtime, diff lisible, contribution facilitée. Le frontmatter sert de metadata machine-readable pour le registry auto-généré.

---

## ADR-003 — Symlinks pour le développement local

**Statut :** Adopté

**Contexte :** En développement, les modifications dans `agents/` doivent être immédiatement disponibles dans Claude Code sans réinstallation.

**Décision :** `install.sh` crée des symlinks de `commands/` vers `~/.claude/commands/ulk/` et de `skills/` vers `~/.claude/skills/ulk-*/`.

**Conséquences :** Synchronisation automatique — toute modification dans le repo est instantanément effective. Risque : si le repo est déplacé, les symlinks cassent.

---

## ADR-004 — Séparation agents/ vs commands/

**Statut :** Adopté

**Contexte :** Les agents sources contiennent des fichiers supplémentaires (README, shared, checklists) qui ne doivent pas être installés comme commandes.

**Décision :** `agents/` est la source de vérité. `commands/` est la version installable — structure aplatie pour Claude Code, symlinks uniquement. L'installeur itère `commands/`.

**Conséquences :** Séparation claire source/distribution. Les sous-dossiers de `agents/` (`_shared/`, `blueprints/`) ne polluent pas les commandes installées.

---

## ADR-005 — Subagents avec mémoire persistante

**Statut :** Adopté

**Contexte :** Certains agents bénéficient de persistence inter-sessions (état du projet, métriques, alertes récurrentes).

**Décision :** 8 agents définis dans `.claude/agents/` avec `memory: local`. Mémoire stockée dans `~/.claude/agent-memory-local/<nom>/`. L'installeur les copie (pas symlink) dans `~/.claude/agents/`.

**Agents concernés :** bruce, godspeed, gandalf, task-runner, 2b3, steve, fluke, tony.

**Conséquences :** Ces agents conservent leur état entre sessions. Les autres agents (commandes) sont stateless par design.

---

## ADR-006 — CLI > MCP (économie de tokens)

**Statut :** Adopté

**Contexte :** Les appels MCP consomment des tokens de contexte (requête + réponse dans la fenêtre). Les CLI s'exécutent hors contexte.

**Décision :** Quand un CLI équivalent existe (`gh`, `vercel`, `neonctl`), l'utiliser au lieu du MCP. Registre : `tools/cli-registry.json`.

**Conséquences :** Économie significative de tokens. Les MCP sont réservés aux outils sans CLI viable (Figma, Notion, Linear).

---

## ADR-007 — Orchestration hybride (séquentiel + parallèle)

**Statut :** Adopté

**Contexte :** Certaines tâches d'audit sont indépendantes (code, perf, a11y) mais d'autres ont des dépendances (diagnostic avant audit).

**Décision :** Les orchestrateurs (bruce, blackemperor) exécutent séquentiellement les tâches dépendantes et en parallèle les tâches indépendantes. Le bloc `CONTEXTE PROJET:` transmet le contexte sans re-scan.

**Conséquences :** Économie : 1 scan + 3 × 1K tokens au lieu de 4 scans × 10K = 40K tokens (économie ~67%). Avec Agent Teams, le parallélisme devient réel (multi-instance).

---

## ADR-008 — Registry auto-généré

**Statut :** Adopté (ULK-044, 2026-04-09)

**Contexte :** Avec 71+ agents, maintenir un registre manuel est source d'erreurs et de drift.

**Décision :** `cheatheet/generate-registry.cjs` parse le frontmatter YAML de tous les agents et génère `agents/registry.json` (machine-readable) + `agents/registry.md` (human-readable). La règle d'or : le frontmatter *est* la documentation.

**Conséquences :** Registre toujours à jour. Bruce et les orchestrateurs peuvent découvrir les agents dynamiquement. Bruce réduit de 1302 à 848 lignes (-35%) en référençant le registry.

---

## ADR-009 — Site statique GitHub Pages

**Statut :** Adopté

**Contexte :** La documentation publique doit être accessible sans infrastructure.

**Décision :** Site statique dans `site/` déployé via GitHub Pages. Workflow GitHub Actions sur push à `main`. Fichier `.nojekyll` pour désactiver Jekyll.

**Conséquences :** Zéro coût d'hébergement, déploiement automatique, pas de backend. URL : `https://izo.github.io/ulk/`.

---

## ADR-010 — Numérotation globale des agents

**Statut :** Adopté

**Contexte :** Les agents doivent être identifiés de manière unique et ordonnée. Les sous-familles thématiques créent un risque de collision.

**Décision :** Format `NN-nom.md` avec numéros globaux préservés, même dans les sous-dossiers thématiques (`orchestrators/25-bruce.md`, `session/08-2b3.md`). Les numéros ne sont jamais réutilisés. Prochain disponible : **51**.

**Gaps historiques** (ne pas réutiliser) : 02-03, 13-14, 19-20, 22-23, 28-30, 33, 37.

**Conséquences :** Historique implicite dans la numérotation. Références inter-agents par nom, pas par numéro.

• Step 2 : Commit

cd /Users/izo/Dev/Docs/Ulk
git add docs/adr.md
git commit -m "docs: créer adr.md — 10 décisions architecturales avec rationale"

---

Task 7 : Créer docs/glossaire.md

Files:

• Create: docs/glossaire.md

• Step 1 : Créer le glossaire

Écrire le fichier suivant à /Users/izo/Dev/Docs/Ulk/docs/glossaire.md :

# Glossaire ulk

## Agents principaux

| Agent | N° | Modèle | Mission |
|-------|-----|--------|---------|
| **bruce** | 25 | opus | Orchestrateur principal. Mémoire persistante. Détecte l'état du projet via Godspeed et dispatche les agents. |
| **godspeed** | 00 | sonnet | Diagnostic. Scanne stack, fichiers, config. Cache 30 min. Premier agent invoqué par Bruce. |
| **shuri** | 01 | sonnet | Pipeline doc. Modes : spec → todo → sync → convert → full. |
| **task-runner** | 04 | sonnet | Exécute les tâches de docs/todo.md. Mesure la vélocité. Mémoire persistante. |
| **vision** | 05 | sonnet | Audit code 8 dimensions + mode simplify. |
| **a11y-auditor** | 06 | sonnet | Accessibilité WCAG 2.1/2.2. |
| **perf-auditor** | 07 | sonnet | Performance : Core Web Vitals, bundle, DB. |
| **2b3** | 08 | sonnet | Checkpoint fin de session : verify → CLAUDE.md → docs → todo → simplify → commit. |
| **friday** | 09 | sonnet | Docs manager : context.md snapshot + organisation /docs. |
| **robocop** | 11 | opus | Détective et fixeur d'erreurs runtime, compilation, tests, linting. |
| **strange** | 16 | opus | Reverse doc : reconstitue 6 documents depuis le code source → docs/rewrite/. |
| **agamotto** | 17 | opus | Reverse design system depuis Figma/Pencil/Penpot → docs/design-system/. |
| **blackemperor** | 18 | opus | Orchestrateur unifié 5 modes : audit, legacy, release, review, ship. |
| **bifrost** | 21 | sonnet | Pont Notion : import (Notion → local) + export (Markdown → Notion QA). |
| **brigitte** | 24 | sonnet | Communications + sync Notion/Linear. |
| **picsou** | 26 | sonnet | Estimation coûts hébergement multi-providers. |
| **steve** | 27 | opus | Orchestrateur Apple : docs/api/ → SwiftUI starter kit. Mémoire persistante. |
| **ranma** | 31 | sonnet | Migration planner (WP→SPIP, Next→Nuxt, etc.). |
| **seo-auditor** | 32 | sonnet | SEO technique + GEO (citations IA). |
| **gandalf** | 34 | sonnet | Context guardian. Hygiène session, alertes, règle des 50%. Mémoire persistante. |
| **sensei** | 38 | sonnet | Apprentissage : explications, diagrammes ASCII, visualisations HTML. |
| **obsidian-vault** | 39 | sonnet | Convertit /docs en vault Obsidian + todos → Kanban boards. |
| **astride** | 40 | sonnet | Code review sarcastique et pragmatique. |
| **amiral** | 41 | sonnet | Audit généralisabilité (open-source readiness). |
| **claude-md-optimizer** | 42 | sonnet | Optimise CLAUDE.md. |
| **tools-checker** | 43 | sonnet | Diagnostic CLI + Skills installés. |
| **sargeras** | 45 | opus | Audit omniscient 10 axes, métriques quantitatives, verdict production-ready. |
| **rodin** | 46 | opus | Interlocuteur socratique anti-chambre d'écho. |
| **lovecraft** | 47 | opus | Super agent doc Obsidian : orchestre shuri, strange, friday, obsidian-vault. |
| **fluke** | 48 | opus | Orchestrateur Android : docs/api/ → Kotlin/Compose ou Flutter starter. Mémoire persistante. |
| **happy** | 49 | opus | Architecte API : audit web → OpenAPI 3.1 → docs/api/. Prérequis steve + fluke. |
| **tony** | 50 | opus | Engineer-in-chief : brief → stack + archi + timing. Mémoire préférences techniques. |

---

## Concepts ulk

| Terme | Définition |
|-------|------------|
| **ulk** | Nom du projet. "Loup" en vieux norrois. Aussi le vrai nom de Bruce, Vallhund suédois. |
| **Monoboard** | Format Kanban de docs/todo.md. Colonnes : Backlog → Todo → In Progress → Blocked → Done. Compatible plugin Obsidian Kanban. |
| **Context Protocol** | Bloc `CONTEXTE PROJET:` transmis par l'orchestrateur aux sous-agents. Évite le re-scan. Économie : 3-10K tokens par agent. |
| **Agent Teams** | Feature expérimentale Claude Code. Multi-instance avec communication directe entre agents. Activé via `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`. |
| **Hybrid Execution** | Pattern orchestration : séquentiel pour les tâches avec dépendances, parallèle pour les tâches indépendantes. |
| **CLI > MCP** | Principe architectural. CLI = 0 token de contexte. MCP réservé aux outils sans CLI viable (Figma, Notion, Linear). |
| **Phase Grid** | Grille des 7 phases du cycle : define → plan → build → verify → review → ship → orchestrator. Champ `phase:` dans le frontmatter. |
| **Registry** | agents/registry.json auto-généré par `node cheatheet/generate-registry.cjs`. Source de vérité machine-readable pour 71 agents. |

---

## Termes techniques

| Terme | Définition |
|-------|------------|
| **Claude Code** | CLI officiel d'Anthropic. Environnement d'exécution des agents ulk. |
| **Custom Command** | Fichier Markdown dans `~/.claude/commands/`. Invoqué par `/prefix:nom`. |
| **Subagent** | Agent avec mémoire persistante dans `.claude/agents/`. Stockage dans `~/.claude/agent-memory-local/<nom>/`. |
| **Skill** | Fichier `SKILL.md` dans `~/.claude/skills/`. Chargé automatiquement quand le contexte matche. |
| **MCP** | Model Context Protocol. Serveurs d'extension LLM (Figma, Notion, Linear). |
| **Frontmatter** | Bloc YAML en tête de fichier Markdown, délimité par `---`. Metadata machine-readable de l'agent. |
| **Context Rot** | Dégradation de la qualité du contexte en session longue. Surveillé par Gandalf. |
| **Symlink** | Lien symbolique Unix. Mécanisme de synchronisation install.sh : agents/ → ~/.claude/commands/ulk/. |
| **Worktree** | Git worktree isolé. Certains agents l'utilisent pour travailler sans affecter la branche courante. |

---

## Abréviations

| Abréviation | Signification |
|-------------|---------------|
| **ADR** | Architecture Decision Record |
| **CWV** | Core Web Vitals (LCP, FID, CLS) |
| **GEO** | Generative Engine Optimization |
| **MOC** | Map of Content (fichier _HOME.md Obsidian) |
| **CLI** | Command Line Interface |
| **MCP** | Model Context Protocol |
| **VPS** | Virtual Private Server |
| **QA** | Quality Assurance |
| **DRY** | Don't Repeat Yourself |
| **WCAG** | Web Content Accessibility Guidelines |
| **CRO** | Conversion Rate Optimization |
| **SPIP** | Système de Publication pour l'Internet Partagé |

---

## Conventions de nommage

| Pattern | Exemple | Signification |
|---------|---------|---------------|
| `NN-nom.md` | `25-bruce.md` | Agent numéro NN (numéros globaux, jamais réutilisés) |
| `dossier/NN-nom.md` | `orchestrators/25-bruce.md` | Agent dans sous-dossier thématique |
| `ulk-*` | `ulk-deploy-vercel` | Skill custom dans ~/.claude/skills/ |
| `/ulk:nom` | `/ulk:bruce` | Invocation agent via custom command |
| `/ulk:cat:nom` | `/ulk:deploy:vercel` | Invocation agent dans une catégorie |
| `mode=xxx` | `mode=audit` | Mode d'exécution d'un agent multi-mode |

• Step 2 : Commit

cd /Users/izo/Dev/Docs/Ulk
git add docs/glossaire.md
git commit -m "docs: créer glossaire.md — agents, concepts, termes, abréviations"

---

Task 8 : Vérification finale

• Step 1 : Vérifier la structure finale de docs/

ls -la /Users/izo/Dev/Docs/Ulk/docs/

Expected :

README.md
adr.md
glossaire.md
guide.md
reference.md
spec.md
superpowers/
todo.md

• Step 2 : Vérifier qu’aucun ancien fichier ne traîne

ls /Users/izo/Dev/Docs/Ulk/docs/*-2026-03-25.md 2>/dev/null && echo "PROBLÈME : fichiers datés restants" || echo "OK"
ls /Users/izo/Dev/Docs/Ulk/ulk-guide.md 2>/dev/null && echo "PROBLÈME : ulk-guide.md encore présent" || echo "OK"

Expected : OK sur les deux lignes.

• Step 3 : Vérifier les liens du README root

head -60 /Users/izo/Dev/Docs/Ulk/README.md

Vérifier que les 5 liens docs/*.md pointent vers des fichiers existants.

• Step 4 : Commit final

cd /Users/izo/Dev/Docs/Ulk
git add -A
git status  # Vérifier qu'il ne reste rien de non commité
git log --oneline -8

Expected : 7-8 commits propres depuis le début de cette refonte.