DOC
Cahier des charges — ulk
Cahier des charges — ulk
Reconstitue depuis
docs/spec.md,CLAUDE.md,README.mdet le code source.
1. Contexte projet
1.1 Identite
- Nom : ulk (signifie “loup” en vieux norrois)
- Mascotte : Bruce, un Vallhund suedois (race de chien viking)
- Version actuelle : 4.0.1
- Licence : MIT
- Auteur : Mathieu Drouet (alias izo)
- Repository : github.com/izo/ulk
- Site : izo.github.io/ulk
1.2 Nature du projet
ulk est un AI Development Toolkit open-source qui etend Claude Code (CLI officiel d’Anthropic) avec un ecosysteme de 46+ agents IA specialises. Il couvre l’integralite du cycle de developpement logiciel — de la specification au deploiement, en passant par l’audit, le debogage, la documentation et la synchronisation.
Le projet se presente comme un monorepo leger, intentionnellement sans dependances npm a la racine, ou chaque agent est un fichier Markdown auto-descriptif avec frontmatter YAML.
1.3 Positionnement
ulk vise a devenir le standard pour le developpement assiste par IA avec Claude Code, en fournissant un compagnon intelligent, frugal en tokens et progressivement extensible.
2. Objectifs
| Objectif | Description | Indicateur |
|---|---|---|
| Automatisation IA | 46+ agents specialises couvrant tout le cycle dev | Nombre d’agents actifs |
| Frugalite contexte | CLI-first + context-protocol pour economiser les tokens LLM | -30% tokens via context-protocol |
| Installation legere | Une commande pour installer, zero configuration | curl | bash ou install.sh |
| Orchestration intelligente | Bruce + Blackemperor comme points d’entree uniques | Reduction du temps de demarrage |
| Memoire persistante | 8 subagents avec auto-memory inter-sessions | Sessions reprises sans perte de contexte |
| Extensibilite | Skills CLI, agents custom, blueprints metier | SDK agents en roadmap |
| Documentation vivante | Site GitHub Pages + generation automatique | Auto-deploy sur push main |
3. Perimetre
3.1 In scope (v4.x)
- 46+ agents specialises repartis en sous-dossiers thematiques
- 8 subagents persistants avec memoire locale
- 12+ skills CLI custom
- Installation locale (symlinks) et distante (curl | bash)
- Orchestrateurs Bruce (PM) et Blackemperor (5 modes)
- Pipeline documentaire Shuri (spec, todo, sync, convert, full)
- Protocoles partages (13 fichiers
_shared/) - Schemas JSON cross-platform (11 schemas)
- Site GitHub Pages avec reference des commandes
- Generateur de documentation (cheatheet/)
- Registre CLI (33+ outils, diagnostic automatique)
- Path-specific rules (6 fichiers
.claude/rules/) - Package TypeScript partage (
packages/core) - Dashboard de suivi projet (
packages/status-board) - Knowledge Vault Loop (memoire inter-sessions Obsidian-compatible)
- Agent Teams (experimental, activation manuelle)
3.2 Out of scope (v4.x)
- Interface web de gestion des agents
- Execution d’agents sans Claude Code (dependance au runtime Anthropic)
- Bridge JS / Swift finalise (schemas definis, bridge non implemente)
- Multi-utilisateur / partage en temps reel
- SDK officiel pour agents custom
4. Contraintes
| Contrainte | Description |
|---|---|
| Zero dependance npm (racine) | Pas de node_modules a la racine, agents distribues comme fichiers Markdown |
| CLI-first | Preferer les outils CLI (gh, vercel, neonctl) aux MCP pour reduire la consommation de contexte |
| Regle des 50% | Ne jamais depasser 50% du contexte LLM en session |
| Idempotence | install.sh re-executable sans effets de bord |
| Non-destructif | Les agents ne suppriment jamais de contenu utilisateur |
| Langue | Rapports, messages et documents generes en francais |
5. Utilisateurs cibles
| Profil | Description | Usage principal |
|---|---|---|
| Solo developer (primaire) | Mathieu Drouet, usage quotidien | Orchestration complete via Bruce |
| Developpeur Claude Code (secondaire) | Communaute CLI, early adopters | Installation d’agents specifiques |
| Equipe de developpement (futur) | Partage de conventions et workflows | Blueprints metier, Agent Teams |
6. Livrables
6.1 Livrables logiciels
| Livrable | Emplacement | Description |
|---|---|---|
| Agents | agents/ (source), commands/ (installable) | 46+ fichiers Markdown avec frontmatter YAML |
| Subagents persistants | .claude/agents/ | 8 agents avec memoire locale |
| Skills CLI | skills/ | 12 skills custom (SKILL.md par skill) |
| Package core | packages/core/ | Bibliothheque TypeScript (parsers, types, GitHub client) |
| Package status-board | packages/status-board/ | Dashboard CLI zero-dependance |
| Schemas JSON | schemas/ | 11 schemas cross-platform (JSON Schema draft-07) |
| Installeur | install.sh, install-remote.sh, uninstall.sh | Scripts d’installation locale et distante |
| Diagnostic | tools/check-tools.sh, tools/check-tools.py | Verification CLI et Skills |
| Site web | site/ | GitHub Pages avec reference des commandes |
6.2 Livrables documentaires
| Livrable | Emplacement | Description |
|---|---|---|
| Specification | docs/spec.md | Spec projet v4.0.0 |
| Kanban | docs/todo.md | Monoboard Kanban (backlog priorise) |
| Guide utilisateur | docs/guide.md | Demarrage, workflows, FAQ |
| Reference agents | docs/reference.md | 71+ agents par categorie |
| ADR | docs/adr.md | Decisions d’architecture |
| Glossaire | docs/glossaire.md | Terminologie ulk |
| Registre agents | agents/registry.json + registry.md | Auto-genere, 72 agents indexes |
7. Roadmap
Phase 1 — Consolidation (v4.x actuel)
- Finaliser
packages/core(TypeScript parser, types) - Finaliser
packages/status-board(dashboard local) - Completer la couverture de tests
- Optimiser CLAUDE.md (taille, specificite)
Phase 2 — Bundles et blueprints (v4.5)
- Bundles thematiques (Frontend, Backend, Mobile)
- Blueprints metier (SaaS, Mobile, Legacy Revival)
Phase 3 — SDK et ecosysteme (v5.0+)
- SDK pour agents custom compatibles ulk
- Bridge JS / Swift finalise
- Nested Agent Teams