DOC
Architecture Decision Records — ulk
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.