Guide ulk

Démarrage rapide

1. Installer

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

Bruce lance Godspeed → diagnostic
Shuri génère docs/spec.md (spécification) + docs/todo.md (backlog Kanban)
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.