La structure du framework ulk

ulk est un monorepo organisé autour d’un répertoire d’agents markdown, de packages partagés, et d’un installateur shell. Cet article cartographie ce qui se trouve où, et pourquoi.

Vue racine

ulk/
├─ framework/
│  ├─ agents/                # 86 agents (un fichier .md par agent)
│  ├─ packages/
│  │  ├─ core/               # lib TS partagée (parser, types, GitHub client)
│  │  └─ status-board/       # dashboard de suivi de projet
│  ├─ schemas/               # JSON Schemas (todo, spec, project, dashboard, recettage)
│  ├─ cheatheet/             # générateur de doc Node.js (zéro dép)
│  ├─ community-skills/      # skills tierces bundlées (Figma, Swift, Flutter, etc.)
│  └─ tools/                 # check-tools.sh, cli-registry.json
├─ site/                     # doc GitHub Pages (Astro)
├─ install.sh                # installateur (install / uninstall / check / verify)
├─ uninstall.sh
├─ CLAUDE.md                 # instructions du repo (chargé à chaque session Claude)
└─ package.json              # workspaces npm

Source : CLAUDE.md section “Project Overview”.

framework/agents/ — le cœur

C’est ici que vivent les 86 agents. Chaque agent est un fichier markdown autonome, sans dépendance.

Organisation par catégorie

framework/agents/
├─ orchestrators/    # Bruce, Tony, Lovecraft, project-decomposer, blackemperor
├─ docs/             # Shuri, Strange, Friday, obsidian-vault
├─ audit/            # Sargeras, Rodin, ED-209, Killbill, context-audit
├─ session/          # Godspeed, 2b3, Robocop, Xavier
├─ mobile/           # agents iOS / Swift / Flutter
├─ sync/             # synchronisation Linear, Notion, GitHub
├─ routines/         # cloud routines (Routine 53, CI Guard 54)
├─ analyze/          # analyse statique
├─ deploy/           # déploiement
├─ test/             # exécution tests
├─ frontend/         # design / composants / a11y
├─ vps/              # ops VPS (opt-in via --with-vps)
└─ specials/         # quarantaine (vide actuellement)

Source : CLAUDE.md section “Agent System” — « Agent folders : orchestrators/ · docs/ · audit/ … »

Numérotation

Chaque agent a un numéro global préservé. Le prochain disponible est 59 (Stark a pris le 58, ajouté en avril 2026). Le registre framework/agents/registry.json est auto-généré par node framework/cheatheet/generate-registry.cjs.

Phases (frontmatter phase:)

Chaque agent déclare sa phase dans son frontmatter :

Phase	Rôle
define	Cadrage, brief → spec
plan	Découpage, todo, archi
build	Implémentation
verify	Tests, lint, recettage
review	Audit, debug, doc reverse
ship	Commit, release, deploy
orchestrator	Coordination multi-agents

Grille complète : framework/agents/_shared/phase-grid.md.

Protocoles partagés

Le dossier framework/agents/_shared/ contient les protocoles transverses :

• base-rules.md — règles héritées par tous les agents.
• context-hygiene-protocol.md — les 4 règles obligatoires.
• memory-protocol.md — Knowledge Vault Loop Obsidian-compatible.
• plugins-protocol.md — délégation aux plugins officiels Anthropic.
• figma-protocol.md — workflow skills Figma.
• notion-protocol.md — Notion CLI-first, fallback MCP.
• routines-protocol.md — sessions autonomes sans machine locale.
• local-llm-protocol.md — délégation à apfel/ollama pour micro-tâches.

framework/packages/

Deux packages TypeScript partagés :

• core — parser markdown, types, client GitHub. Utilisé par les outils internes.
• status-board — dashboard projet (HTML + JS).

À la racine, package.json est un workspace npm. Les agents eux-mêmes restent markdown sans dépendance.

framework/schemas/

JSON Schemas partagés entre packages JS/TS :

• todo.schema.json — Monoboard Kanban.
• spec.schema.json — spec produit.
• project.schema.json — métadonnées projet.
• dashboard.schema.json — status-board.
• recettage.schema.json — checklists de recette.

Garantit la cohérence des fichiers générés par les agents.

framework/cheatheet/

Générateur de doc Node.js, zéro dépendance externe :

• generate-registry.cjs — produit agents/registry.json + agents/registry.md à partir des frontmatters.
• generate-commands.cjs — produit commands/ à partir de agents/ (auto-exécuté par install.sh).

framework/tests/

Tests de régression. Ajouté en avril 2026 (Epic ULK-181→183).

• agents-golden.test.mjs — runner Node natif (node --test).
• agents/<agent>.golden.md — fixtures golden, une par agent. Chaque golden valide : frontmatter requis, sections H2 critiques, patterns d’invocation.
• generate-golden-files.cjs — auto-génération calibrée (sections H2, min_table_rows à 50 %).
• cheatheet.test.mjs — tests du générateur de doc.
• install.bats — tests bats pour install.sh.

Portée : structurel, déterministe, gratuit. Limite : ne teste pas le comportement à l’exécution d’un agent.

framework/community-skills/

Skills tierces bundlées par défaut, copiées dans ~/.claude/skills/ à l’install :

Famille	Nombre	Exemples
Figma	7	figma-use, figma-implement-design, figma-code-connect
Swift	7	SwiftUI Pro, SwiftData Pro, Concurrency Pro
Flutter	2	Flutter Tester, OWASP Mobile Security
Nothing design	1	dominikmartn (opt-in)
context-audit	1	health score 0-100
cwb-app-icon	1	AppIcon natif iOS/macOS (opt-in)

Source : CLAUDE.md section “Community Skills”.

install.sh

Script bash qui :

1. Compile les packages.
2. Copie les agents dans ~/.claude/agents/.
3. Génère les commandes dans ~/.claude/commands/.
4. Copie les skills dans ~/.claude/skills/.
5. Optionnellement installe MCP Figma, hooks mémoire, telemetry CLI.

Modes : --check, --verify, --uninstall, --dry-run + une vingtaine d’options --with-*.

site/

Documentation publique en Astro, déployée sur GitHub Pages. URL : https://izo.github.io/ulk/.

CLAUDE.md (racine)

Fichier d’instructions du repo, chargé automatiquement à chaque session Claude Code. Contient :

• Vue d’ensemble du projet.
• Commandes essentielles.
• Liste des agents clés.
• Les 4 règles d’hygiène de contexte.
• Liens vers les protocoles partagés.

C’est l’unique fichier obligatoire à connaître pour collaborer avec ulk.

.claude/rules/

Règles spécifiques par dossier (path-specific) :

• agents-authoring.md — comment créer un nouvel agent.
• frontend-agents.md — règles agents frontend.
• cheatheet.md — règles du générateur de doc.
• packages.md — build & test commands.
• native-features.md — /batch, auto memory, /schedule.
• session-practices.md — les 4 règles d’hygiène.

CLI Go — en cours depuis v4.3

La CLI native ulk est en développement actif dans framework/cli/. Les phases 0-2 sont livrées (ULK-265-267) :

• Phase 0 — interface Installable + 6 types de modules typés (refactoring modules.go, ULK-265).
• Phase 1 — 6 skills manquantes intégrées au catalogue (ULK-266).
• Phase 2 — 5 hooks unifiés + base RTK + fix cli-telemetry (ULK-267).

Phases suivantes prévues :

• Phase 3 — TUI : sélecteur de modules bubbletea, barre de progression lipgloss.
• Phase 4 — distribution : brew install izo/tap/ulk.
• Phase 5 — app macOS Wails (P3) : .app + Dashboard.

install.sh reste valide et deviendra un wrapper mince une fois la phase 4 livrée.

Construire localement :

cd framework/cli
make build    # → ./bin/ulk
make test     # 75+ tests unitaires

Comment lire le repo en 5 minutes

1. Lire CLAUDE.md (racine).
2. Ouvrir framework/agents/registry.json (liste exhaustive).
3. Ouvrir framework/agents/_shared/phase-grid.md pour comprendre les phases.
4. Lire .claude/rules/session-practices.md pour les règles d’hygiène.
5. Tester ./install.sh --dry-run pour voir ce qui serait installé.

Suite

Billet #4 : zoom sur les 10 agents majeurs (rôle, invocation, exemple de sortie).