Design — Refonte complète de la documentation ulk

Date : 2026-04-09
Statut : Approuvé
Scope : README.md (root) + docs/ complet

---

Contexte

La documentation actuelle souffre de duplication (README + ulk-guide + dated strange files), de fichiers stale post-réorganisation agents/ (2026-03-25), et d’une absence de hiérarchie claire entre les 3 audiences cibles.

Audiences et hiérarchie

1. Externe / découverte GitHub → README.md (root)
2. Utilisateur régulier → docs/guide.md + docs/reference.md
3. Contributeur / interne → docs/spec.md + docs/adr.md + docs/todo.md

Fichiers supprimés

Fichier	Raison	Contenu récupéré vers
ulk-guide.md	Doublon README + docs/guide	docs/guide.md
docs/00-index-2026-03-25.md	Stale, index obsolète	—
docs/01-cahier-des-charges-2026-03-25.md	Stale	—
docs/02-doc-technique-2026-03-25.md	Stale	—
docs/03-doc-utilisateur-2026-03-25.md	Stale	docs/guide.md
docs/04-user-stories-2026-03-25.md	Stale	—
docs/05-glossaire-2026-03-25.md	Stale	docs/glossaire.md
docs/06-architecture-2026-03-25.md	Stale	docs/adr.md
docs/00-meta/conventions.md	Verbeux, absorbé	docs/spec.md
docs/00-meta/index.md	Remplacé	docs/README.md
docs/analysis/	Analyses temporelles	—
docs/README.md	Remplacé	docs/README.md (nouveau)

Nouvelle structure docs/

docs/
├── README.md        Index navigable (liens + 1 phrase par section)
├── guide.md         Démarrage + 3 workflows + FAQ + tips session
├── reference.md     Tous les agents par catégorie + invocations
├── adr.md           10 ADRs (pourquoi de chaque décision d'archi)
├── glossaire.md     ~50 termes consolidés et à jour
├── spec.md          Spec projet (inchangé, document vivant)
└── todo.md          Monoboard Kanban (inchangé)

README.md (root) — ~80 lignes

• Pitch ulk + histoire Bruce/Ulk (section existante à conserver)
• Badges (version, demo, GitHub)
• Install one-liner (curl ... | bash)
• 5 commandes d’entrée : bruce, godspeed, 2b3, sargeras, shuri
• Lien → docs/ pour tout le reste

Contenu par fichier

docs/README.md

Index avec une phrase par fichier, liens directs, navigation rapide.

docs/guide.md

1. Démarrage rapide (install → première commande)
2. Workflow : nouveau projet (bruce → shuri → task-runner)
3. Workflow : session de dev (godspeed → task-runner → 2b3)
4. Workflow : audit (sargeras / blackemperor)
5. Tips : règle des 50%, gandalf, /clear
6. FAQ : 5 questions fréquentes

docs/reference.md

Agents groupés par catégorie (orchestrators, docs, audit, session, mobile, specials, analyze, deploy, test, frontend, vps). Pour chaque agent : nom, modèle, phase, invocation, mission courte. Source : agents/registry.md (auto-généré).

docs/adr.md

10 ADRs extraits de 06-architecture-2026-03-25 :

• ADR-001 Zero dépendances npm
• ADR-002 Agents en Markdown
• ADR-003 Symlinks commands/
• ADR-004 Context Protocol (3-10K tokens saved)
• ADR-005 CLI > MCP priority
• ADR-006 Monoboard Kanban
• ADR-007 Registry auto-généré
• ADR-008 Model distribution (opus/sonnet)
• ADR-009 Numérotation globale agents
• ADR-010 Memory locale (.claude/agents/)

Format : ## ADR-NNN — Titre / Contexte / Décision / Conséquences

docs/glossaire.md

~50 termes : agents (nom + numéro + mission 1L), concepts (Monoboard, Context Protocol, CLI>MCP, Phase Grid, Worktree), abréviations (ulk, 2b3, ADR…). Mis à jour avec la structure thématique post-réorganisation.

Contraintes

• docs/spec.md et docs/todo.md : inchangés (documents vivants gérés par agents)
• CHANGELOG.md (root) : inchangé
• CLAUDE.md (root) : inchangé
• agents/registry.md : source de vérité pour reference.md (ne pas dupliquer manuellement)
• Nommage : tout en minuscules, pas de dates dans les noms