Documentation technique — ulk

Reconstitue depuis le code source, install.sh, packages/, agents/_shared/, cheatheet/, .claude/.

1. Architecture du monorepo

1.1 Structure racine

ulk/
├── agents/                     # Source de verite des agents (46+ fichiers .md)
│   ├── _shared/                # 13 protocoles partages
│   ├── orchestrators/          # Bruce, Blackemperor, Lovecraft
│   ├── docs/                   # Friday, Shuri
│   ├── audit/                  # Sargeras, Vision, A11y, Perf, SEO
│   ├── session/                # 2b3, Robocop, Gandalf, Task-runner
│   ├── specials/               # Strange, Agamotto, Sensei, Rodin, Tony
│   ├── mobile/                 # Steve, Fluke, Happy
│   ├── sync/                   # Brigitte, Bifrost
│   ├── analyze/                # Analyseurs par stack (Astro, Next, Nuxt, SPIP, SwiftUI)
│   ├── deploy/                 # Vercel, Netlify, Cloudflare, Docker, AWS
│   ├── test/                   # Unit (Jest/Vitest), E2E (Playwright/Cypress)
│   ├── frontend/               # 7 agents frontend + checklists
│   ├── vps/                    # Suite VPS optionnelle (17+ agents)
│   ├── blueprints/             # Templates metier (futur)
│   ├── bundles/                # Bundles thematiques (futur)
│   ├── registry.json           # Registre auto-genere (72 agents)
│   └── registry.md             # Version Markdown du registre
├── commands/                   # Miroir installable (genere depuis agents/)
├── skills/                     # 12 skills CLI custom (ulk-*/SKILL.md)
├── schemas/                    # 11 JSON Schemas cross-platform (draft-07)
├── packages/
│   ├── core/                   # @ulk/core — TypeScript library
│   ├── status-board/           # Dashboard CLI zero-dependance
│   └── ulk-sdk/                # SDK agents (futur)
├── .claude/
│   ├── agents/                 # 8 subagents avec memoire persistante
│   ├── rules/                  # 6 regles path-specific
│   ├── hooks-examples/         # Hooks memory loop (opt-in)
│   └── settings.local.json     # Configuration locale
├── site/                       # GitHub Pages (HTML/CSS statique)
├── cheatheet/                  # Generateurs de docs (Node.js vanilla)
├── tools/                      # CLI registry + diagnostic
├── community-skills/           # Skills tiers (addy, a11y)
├── install.sh                  # Installation locale
├── install-remote.sh           # Installation distante (curl | bash)
├── uninstall.sh                # Desinstallation
├── package.json                # Workspaces npm (packages/* uniquement)
└── CLAUDE.md                   # Instructions projet pour Claude Code

1.2 Principe de separation agents/ vs commands/

agents/ est la source de verite. Contient les fichiers .md, les protocoles partages (_shared/), les README, les checklists.
commands/ est le miroir installable. Structure aplatie, generee automatiquement par node cheatheet/generate-commands.cjs. Seuls les fichiers .md pertinents y sont copies.
L’installeur (install.sh) copie commands/ vers ~/.claude/commands/ulk/.

2. Stack technique

Couche	Technologie	Justification
Runtime agents	Claude Code CLI (Anthropic)	Runtime officiel, integration native
Format agents	Markdown + frontmatter YAML	Auto-documente, diffable, zero dependance
Generateurs docs	Node.js (CommonJS, sans dependances)	Portable, leger, pas de build
Package core	TypeScript (ES2022, Node16)	Typage fort, parsers, GitHub client
Package status-board	Node.js vanilla	CLI dashboard, zero-dependance
Tests (core)	Vitest 4.x + @vitest/coverage-v8	Rapide, TypeScript natif
Schemas	JSON Schema draft-07	Cross-platform JS / Swift
Site web	HTML/CSS statique	GitHub Pages, zero infrastructure
CI/CD	GitHub Actions	Auto-deploy + cron hebdomadaire
Gestion source	Git + `gh` CLI	Standard, CLI > MCP

3. Systeme d’agents

3.1 Format d’un agent (fichier Markdown)

Chaque agent est un fichier .md avec frontmatter YAML :

---
name: agent-name
description: |
  Description complete — utilisee par Claude Code
  pour le routage et la decouverte.
tools: Read, Glob, Grep, Bash, Write, Task, AskUserQuestionTool
model: opus | sonnet
phase: review
invocation: /ulk:name or "name" or "trigger phrase"
extends:
  - _shared/base-rules.md
  - _shared/update-protocol.md
---

Champs obligatoires : name, description, tools, model, phase, invocation.

Champs optionnels :

memory: local — uniquement pour les subagents .claude/agents/ (memoire persistante)
isolation: worktree — travail en worktree isole
extends: — liste documentaire des fichiers _shared/ herites

3.2 Phases du cycle de vie (Phase Grid)

Phase	Verbe	Exemples
define	Definir	Brief, spec, cadrage (tony, rodin, shuri mode=spec)
plan	Planifier	Decomposition, roadmap (shuri mode=todo, ranma)
build	Construire	Implementation (task-runner, brique, happy, steve, fluke)
verify	Verifier	Tests, validation (test-unit, test-e2e, visual-auditor)
review	Auditer	Qualite, securite, perf (sargeras, vision, a11y, godspeed)
ship	Livrer	Deploy, commit, sync (2b3, deploy-*, brigitte)
orchestrator	Multi-phase	Bruce, blackemperor, lovecraft

Un agent peut couvrir jusqu’a 3 phases. Au-dela, il est declare orchestrator.

3.3 Distribution des modeles

Modele	Nombre	Usage
opus	10 agents	Orchestrateurs complexes, analyse multi-fichiers profonde
sonnet	62+ agents	Taches focalisees, audits, automation, checklists

Agents opus : bruce, blackemperor, robocop, strange, sargeras, rodin, tony, steve, fluke, happy.

3.4 Registre des agents

Le fichier agents/registry.json est auto-genere par node cheatheet/generate-registry.cjs. Il indexe 72 agents avec les champs : name, file, category, model, phase, description, tools, invocation.

Le fichier agents/registry.md en est la version Markdown lisible.

3.5 Numerotation

Plage	Categorie
00-09	Agents core (diagnostic, doc, tasks, audit)
10-analyze/	Analyseurs de stack (sous-dossier)
11-deploy/	Agents de deploiement (sous-dossier)
11-19	Agents debug, reverse-doc, orchestrateurs
12-test/	Agents de test (sous-dossier)
15-frontend/	Suite frontend (sous-dossier)
20-29	Agents sync, communications, orchestrateurs PM
30-39	Agents specialises (SEO, migration, vault)
40-49	Agents avances (audit omniscient, mobiles, IA)
50+	Agents strategiques — prochain : 51

4. Protocoles partages (`agents/_shared/`)

Fichier	Role
`base-rules.md`	Regles communes, formats, conventions de scoring, frontmatter standard
`context-protocol.md`	Passage de contexte inter-agents via bloc `CONTEXTE PROJET:` (-30% tokens)
`update-protocol.md`	Mise a jour incrementale (jamais de reecriture complete)
`auditor-base.md`	Template rapport + scoring pour agents d’audit
`stack-detection.md`	Detection automatique de stack
`agent-teams.md`	Patterns de coordination multi-agents (experimental)
`cli-tools-protocol.md`	Priorite CLI > MCP
`claude-code-mastery.md`	Bonnes pratiques avancees Claude Code
`memory-protocol.md`	Knowledge Vault Loop (MEMORY.md, vault Obsidian, distribution)
`phase-grid.md`	Grille 6 phases + orchestrator, cartographie agents
`discovery-protocol.md`	Spec frontmatter etendu, pattern d’invocation, mise a jour registre
`simplify-principles.md`	5 principes de simplification + process 4 etapes
`checklists/`	4 checklists tactiques (accessibilite, performance, securite, tests)

5. Pipeline d’installation

5.1 Installation locale (`install.sh`)

Le script install.sh est la piece maitresse de la distribution. Il est idempotent et modulaire.

Etapes principales :

Lecture de la version depuis package.json (source de verite unique)
Regeneration de commands/ via node cheatheet/generate-commands.cjs (si Node.js disponible)
Creation des repertoires cibles : ~/.claude/commands/, ~/.claude/agents/, ~/.claude/skills/
Nettoyage legacy : suppression des anciens noms (woodman, wm, ulk-old)
Copie des commandes : commands/ vers ~/.claude/commands/ulk/
Copie des subagents : .claude/agents/*.md vers ~/.claude/agents/ulk-*.md
Copie des skills : skills/*/ vers ~/.claude/skills/ulk-*/
Options activables :
- --with-vps : inclut les agents VPS
- --with-teams : active Agent Teams (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 dans settings.local.json)
- --with-addy-skills : installe les skills addyosmani
- --with-a11y-skills : installe les skills accessibilite Luxembourg (RAWeb/RAAM)
- --with-memory-loop : installe les hooks memory loop
Ecriture de metadonnees : .version et .source dans le repertoire cible

5.2 Installation distante (`install-remote.sh`)

curl -fsSL https://raw.githubusercontent.com/izo/ulk/main/install-remote.sh | bash

Clone le depot dans un repertoire temporaire, puis execute install.sh.

5.3 Modes de `install.sh`

Mode	Flag	Action
Install	(defaut)	Installation complete
Uninstall	`--uninstall`	Suppression des fichiers ulk
Check	`--check`	Diagnostic CLI + Skills
Verify	`--verify`	Verification de l’installation
Help	`-h`, `--help`	Affichage de l’aide
Dry-run	`--dry-run`	Simulation sans modification

5.4 Mise a jour

git pull && ./install.sh

L’idempotence de install.sh garantit que la mise a jour ecrase proprement les fichiers existants.

6. Packages

6.1 `@ulk/core` (packages/core/)

Bibliotheque TypeScript partagee. Version 0.1.0.

Stack : TypeScript 6.x, ES2022, module Node16, Vitest 4.x.

Structure :

packages/core/
├── src/
│   ├── index.ts        # Point d'entree, re-exports
│   ├── parsers/        # Parsers todo.md et spec.md
│   ├── types/          # Types TypeScript partages
│   └── github/         # Client GitHub
├── tests/              # Tests Vitest
├── dist/               # Build TypeScript compile
├── package.json        # @ulk/core
└── tsconfig.json       # Config TypeScript stricte

Exports : parseTodoFile(), parseSpecFile(), GitHubClient, types TypeScript.

Commandes :

cd packages/core && npm install && npm run build
npm run test           # Vitest

6.2 `packages/status-board`

Dashboard CLI de suivi projet. Zero dependance npm (utilise les parsers de @ulk/core en interne).

Commandes :

node packages/status-board/src/cli.js              # Dashboard complet
node packages/status-board/src/cli.js summary       # Resume compact
node packages/status-board/src/cli.js json          # Export JSON
node --test packages/status-board/tests/*.test.js   # Tests

Exports : collectProjectData(), computeMetrics(), renderDashboard(), renderSummary(), exportDashboardJSON().

6.3 Workspaces npm

Le package.json racine definit les workspaces :

{
  "name": "ulk",
  "version": "4.0.1",
  "private": true,
  "workspaces": ["packages/*"]
}

Les scripts racine deleguent aux packages : npm run build, npm run build:core, npm run build:status-board.

7. Systeme de memoire

7.1 Subagents persistants

8 agents dans .claude/agents/ avec memory: local. Memoire stockee dans ~/.claude/agent-memory-local/<agent>/.

Subagent	Cle memoire	Donnees persistees
bruce	`bruce_project_state`	Etat projet, stack, derniere/prochaine tache
godspeed	`godspeed_cache`	Cache diagnostic (expire au prochain commit)
gandalf	`gandalf_last_check`	% contexte, alertes, recommandations
task-runner	`taskrunner_metrics`	Velocite, ajustements categories, blocages
2b3	`checkpoint_patterns`	Issues recurrentes, taux de succes simplification
strange	`analysis_state`	Etat analyse, lacunes, documents generes
steve	`api_decisions`	Decisions API, plateformes cibles, phase
tony	`tony_user_preferences`	Stacks preferees, tech evitees, historique

7.2 Knowledge Vault Loop

Boucle de memoire automatique inter-sessions, orchestree par Lovecraft (47) :

Capture : MEMORY.md (staging, racine projet) est parse et ses entrees sont versees dans docs/_memory/<categorie>/ via obsidian-vault (39)
Distribute : les entrees pertinentes du vault sont injectees dans CLAUDE.md (bloc ...) via shuri (01)
Surface : resume read-only pour godspeed/bruce/gandalf

Categories de memoire : rules, lessons, patterns, mistakes, insights, research.

Integration automatique :

2b3 (Phase 5.7) capture apres le commit
godspeed (Phase 1.5) surface dans le diagnostic
gandalf (Phase 5) audite la sante du vault

7.3 Context Protocol

Les orchestrateurs transmettent un bloc CONTEXTE PROJET: aux sous-agents pour eviter les analyses redondantes :

CONTEXTE PROJET:
- Stack: [framework]
- Langages: [liste]
- DB: [type]
- Fichiers source: [nombre]
- Structure: [dossiers]

Gains : -30% tokens par agent, -40% temps via parallelisation.

8. Hooks

8.1 Hooks memory loop (opt-in)

Installables via ./install.sh --with-memory-loop. Copies dans ~/.claude/hooks/memory-loop.json (merge manuel dans settings.json requis).

Hook	Trigger	Action
SessionStart	Demarrage de session	godspeed (surface vault)
Stop	Fin de session	2b3 (capture MEMORY.md)
PostToolUse (errors)	Erreur d’outil	grep dans `docs/_memory/07-mistakes/`

9. Outils et generateurs

9.1 Generateurs (cheatheet/)

Script	Commande	Sortie
`generate-commands.cjs`	`node cheatheet/generate-commands.cjs`	`commands/` (miroir installable depuis `agents/`)
`generate-registry.cjs`	`node cheatheet/generate-registry.cjs`	`agents/registry.json` + `agents/registry.md`

9.2 Diagnostic (tools/)

Fichier	Role
`check-tools.sh`	Script bash de diagnostic CLI + Skills
`check-tools.py`	Logique Python extraite (heredoc)
`cli-registry.json`	Registre de 33+ outils CLI avec equivalents MCP
`skills-registry.json`	Registre des skills installes

9.3 Path-specific rules (`.claude/rules/`)

Fichier	Scope	Contenu
`agents-authoring.md`	`agents/**`	Conventions de creation d’agents
`frontend-agents.md`	`agents/frontend/**`	Regles specifiques frontend
`cheatheet.md`	`cheatheet/**`	Regles generateur de docs
`packages.md`	`packages/**`	Commandes build/test des packages
`native-features.md`	Agents cles	/batch, auto memory, /schedule
`session-practices.md`	Global	Hygiene de session, Gandalf

10. Schemas JSON (`schemas/`)

11 schemas JSON (draft-07) pour la validation cross-platform :

Schema	Usage
`todo.schema.json`	Format todo.md Monoboard Kanban
`todo-file.schema.json`	Structure complete du fichier todo
`spec.schema.json`	Structure docs/spec.md
`project.schema.json`	Metadonnees projet
`dashboard.schema.json`	Dashboard de suivi
`cli-registry.schema.json`	Registre outils CLI
`skills-registry.schema.json`	Registre skills
`recettage-item.schema.json`	Item de recettage
`recettage-state.schema.json`	Etat de recettage
`figma-design-system-rules.schema.json`	Regles design system Figma