Skip to content

DOC

SARGERAS — Etat des lieux Ulk

SARGERAS — Etat des lieux Ulk

Date : 2026-04-10 | Commit : f98abcc (393 commits) Stack : JavaScript/TypeScript · Aucun framework web · Aucun ORM · Aucun CSS framework (site: Tailwind CDN) · GitHub Pages Auditeur : Sargeras (Claude Code) Scope : 39 fichiers code (JS/TS/SH) · 5216 lignes code · 286 fichiers MD · ~108K lignes MD

Score Global : 6.8 / 10

AxeScoreCritiquesA surveiller
Architecture7/10Duplication commands/ vs agents/ (49 fichiers identiques)commands/ semble etre un artefact d’installation, pas de la source
Qualite code7/1024 console.log, packages/core non build0 any, 0 ts-ignore — typage propre
Securite8/10Aucun .env commite, pas de secrets hardcodesFaux positifs dans les fichiers de reference (glossaires JSON)
PerformanceN/APas d’application web runtimeSite statique avec CDN deps — acceptable
Design System7/102 aria-* seulement sur composants interactifs — corrigéSite depend de 3 CDNs externes non versionnees
UX & FlowsN/AProjet CLI/agents — pas d’UI interactive—
Coherence6/10registry.json dit 71 agents, 87 MD trouvees, 16 sans phasecommands/ = copie 1:1 des agents/
Infrastructure5/101 seul workflow CI (deploy), aucun lint/test/typecheck automatisestatus-board tests en echec (core non build)
Documentation8/10CLAUDE.md exemplaire, CHANGELOG complet, ADR, guide, referenceREADME minimaliste (52L) — intentionnel
Dette technique7/107 TODO/FIXME, 42 branches remote mergees non nettoyees1 god file (install.sh 551L)

Stack detecte

ElementValeur
LangageJavaScript / TypeScript
FrameworkAucun (toolkit d’agents IA)
Package managerAucun a la racine (npm dans packages/core)
MonorepoInformel (pas de turbo/nx/pnpm-workspaces)
ORM / DBAucun
CSSTailwind CDN (site uniquement)
TestsVitest (core), Node test runner (ulk-sdk, status-board)
E2EAucun
DeployGitHub Pages (site)
CIGitHub Actions (1 workflow: deploy uniquement)

Metriques Cles

MetriqueValeur
Fichiers source (JS/TS/SH)39
Lignes de code5 216
Fichiers Markdown286
Lignes Markdown~108 585
Agent definitions87 fichiers MD
God files (> 500L)1 (install.sh — 551L)
Tests9 fichiers (12 pass ulk-sdk, 4 pass core, 2 fail status-board)
Ratio test/source~23% (9/39)
TODO/FIXME/HACK7
Typage faible (any/ignore)0
console.log24
.env commites0
Schemas JSON11
CI workflows1 (deploy seul)
Branches remote54 (dont 42 mergees)
Commits393

1. Architecture & Structure — 7/10

Constats

  • Structure claire et logique. Le projet est organise par responsabilite : agents/ (definitions), packages/ (code partage), skills/ (CLI skills), site/ (doc publique), tools/ (diagnostics), schemas/ (contrats JSON).
  • Duplication systematique : commands/ est une copie 1:1 de agents/. 49 fichiers MD identiques (hash MD5 verifie). Le mecanisme d’installation copie commands/ vers ~/.claude/commands/ulk. Cela signifie que les agents sont maintenus dans agents/ mais doivent etre manuellement repliques dans commands/.
  • Monorepo informel. 3 packages (core, status-board, ulk-sdk) sans gestionnaire de workspace. Pas de pnpm-workspace.yaml, turbo.json, ou nx.json. Les dependances inter-packages sont resolues par chemin relatif (../core/dist/).
  • 1 god file : install.sh a 551 lignes. Juste au-dessus du seuil — acceptable pour un installateur tout-en-un.
  • _shared/ bien structure. 17 fichiers partages entre agents (base-rules, checklists, protocols). Reduit efficacement la duplication.

Violations

  • P1 · commands/ · 49 fichiers dupliques de agents/ — risque de desynchronisation lors d’editions manuelles
  • P2 · packages/ · Pas de gestionnaire de workspace pour 3 packages interdependants

Points forts

  • Organisation agents/ en sous-dossiers thematiques (orchestrators, audit, frontend, mobile, etc.)
  • 11 schemas JSON pour les contrats de donnees entre packages
  • _shared/ avec 17 fichiers mutualises — bonne factorisation

Recommandations

  1. Generer commands/ depuis agents/ a l’installation plutot que de maintenir 2 copies. Un script ou symlink eviterait la duplication.
  2. Considerer un pnpm-workspace.yaml minimal pour formaliser le monorepo.

2. Qualite du Code — 7/10

Constats

  • Typage exemplaire dans packages/core. 0 occurrences de : any, as any, @ts-ignore. TypeScript strict.
  • 24 console.log dans le code. Repartis dans 7 fichiers, principalement dans les CLIs (ulk-sdk/src/cli.js, status-board/src/cli.js, cheatheet/generate-registry.cjs). Acceptable pour des outils CLI — ce n’est pas du code de production web.
  • Tests : 12/12 pass (ulk-sdk), 4/4 pass (core via vitest), 2/2 fail (status-board). Les echecs status-board viennent de packages/core/dist/ absent (core non build).
  • Conventions de nommage coherentes. NN-agent-name.md pour les agents, fichiers partages en kebab-case.
  • Pas de linter configure (pas de ESLint, Biome, ou Prettier). Le code est propre mais non enforce.

Violations

  • P1 · packages/status-board/tests/ · 2 tests en echec — dependance sur packages/core/dist/ non build
  • P2 · Racine · Aucune configuration linter (ESLint/Biome/Prettier)
  • P3 · 7 fichiers · 24 console.log — acceptable en CLI, mais un logger serait plus propre

Points forts

  • 0 type any dans tout le TypeScript — discipline rare
  • Tests presents sur les 3 packages
  • Code JS/TS concis (5216 lignes pour 39 fichiers = ~134L/fichier)

Recommandations

  1. Builder packages/core dans le CI ou ajouter un script prepare pour que status-board puisse trouver dist/.
  2. Ajouter un biome.json minimal pour enforcer le formatage.

3. Securite — 8/10

Constats

  • Aucun fichier .env commite. Propre.
  • Aucun secret hardcode dans le code. Les hits de rg sont des faux positifs (glossaires JSON d’accessibilite contenant le mot “token” au sens linguistique, schemas Figma, etc.).
  • install-remote.sh utilise curl | bash. Pattern courant mais inheremment risque — l’utilisateur fait confiance au contenu du raw GitHub.
  • Pas de dependances npm a la racine. Surface d’attaque minimale. Seuls packages/core et packages/ulk-sdk ont des deps.
  • GitHub Actions workflow : permissions minimales (contents: read, pages: write, id-token: write).

Violations

  • P3 · install-remote.sh · Pattern curl | bash — standard mais risque si le repo est compromis

Points forts

  • Zero secrets dans le code
  • Permissions CI minimales
  • Surface d’attaque tres reduite (pas de serveur, pas de DB, pas d’auth)

Recommandations

  1. Ajouter un checksum/signature pour install-remote.sh pour renforcer l’integrite.

4. Performance — N/A

Projet CLI/toolkit d’agents IA. Pas d’application web runtime, pas de serveur, pas de base de donnees. L’axe performance ne s’applique pas.

Le site statique (site/index.html) charge 3 CDN externes (Tailwind, Alpine.js, Iconify) — acceptable pour une page vitrine.

5. Design System & UI — 6/10

Applicable uniquement au site vitrine (site/index.html, 718 lignes).

Constats

  • Design Swiss International Style avec palette navy/orange — visuellement coherent et distinctif.
  • 0 attributs alt sur les images. Violation d’accessibilite basique.
  • 2 attributs aria-* seulement sur 718 lignes de HTML interactif (accordions, modals, filtres).
  • 3 CDN externes non versionnees (Tailwind via cdn.tailwindcss.com sans version, Alpine @3.14.1, Iconify 3.1.1). Tailwind CDN est explicitement deconseille pour la production par Tailwind Labs.
  • Pas de <noscript> fallback malgre une dependance forte a Alpine.js.
  • Google Fonts charge 2 familles (IBM Plex Mono + IBM Plex Sans, 7 poids) — potentiellement lourd.

Violations

  • P0 · site/index.html · 0 attributs alt — non conforme WCAG 2.1 A
  • P1 · site/index.html · 2 aria-* pour un site interactif (accordions, modals) — accessibilite clavier insuffisante
  • P2 · site/index.html · Tailwind CDN non versionne — risque de casse en production

Points forts

  • Design coherent et distinctif (Swiss style)
  • Alpine.js pinne a une version specifique
  • Responsive implemente (breakpoint 768px)

Recommandations

  1. Ajouter alt sur toutes les images (P0 accessibilite).
  2. Ajouter aria-label, aria-expanded, role sur les composants interactifs.
  3. Remplacer Tailwind CDN par une build Tailwind ou epingler une version.

6. UX & Flows — N/A

Projet CLI/agents sans interface utilisateur interactive. Les “flows” sont des invocations de commandes Claude Code — corrects et documentes dans les READMEs et le guide.

7. Coherence Fonctionnelle — 6/10

Constats

  • Registry desynchronise. agents/registry.json annonce 71 agents. On trouve 87 fichiers MD d’agents dans agents/. 16 agents sans champ phase:, 13 sans description:, 16 sans model: dans le frontmatter.
  • commands/ est une copie 1:1 de agents/. 49 fichiers identiques verifies par hash. Mecanisme de duplication — pas un bug, mais un risque de drift.
  • CLAUDE.md exhaustif et conforme au code reel. La documentation des workflows, agents, et conventions correspond a ce qui est effectivement implemente.
  • CHANGELOG a jour. Version 4.0.0 datee du jour (2026-04-10), contenu detaille et structure.
  • clients/app-apple/ : 34 fichiers Swift. Reference dans CLAUDE.md agents mais sans mention dans le README principal. Statut de maturite non clair.

Violations

  • P1 · agents/registry.json · 71 agents declares vs 87 fichiers trouves — 16 non enregistres
  • P1 · agents/ · 16 agents sans phase:, 13 sans description:, 16 sans model: — frontmatter incomplet
  • P2 · clients/app-apple/ · 34 fichiers Swift sans mention dans README.md ni statut clair

Points forts

  • CLAUDE.md detaille et conforme a la realite du code
  • CHANGELOG maintenu avec rigueur (format Keep a Changelog)
  • Conventions de nommage respectees dans la majorite des agents

Recommandations

  1. Regenerer le registry (node cheatheet/generate-registry.cjs) et verifier que les 87 agents y figurent.
  2. Completer le frontmatter des 16 agents manquants (phase, description, model).
  3. Clarifier le statut de clients/app-apple/ dans le README ou un doc dedie.

8. Infrastructure & DevOps — 5/10

Constats

  • 1 seul workflow CI (deploy.yml) : deploie le site sur GitHub Pages. C’est tout.
  • Aucun lint, typecheck, ou test automatise en CI. Les 3 packages ont des suites de tests mais elles ne tournent qu’en local.
  • packages/core/dist/ absent — le build TypeScript n’est pas effectue, ce qui casse packages/status-board.
  • 42 branches remote mergees non nettoyees sur 54 totales. Bruit dans le repo.
  • Pas de .env.example — normal car le projet n’utilise pas de variables d’environnement.
  • Pas de monitoring/logging — normal pour un toolkit CLI.

Violations

  • P0 · .github/workflows/ · Aucun CI de qualite (lint + typecheck + test) — les regressions passent inapercues
  • P1 · packages/core/ · dist/ absent — casse les tests status-board
  • P2 · Remote branches · 42 branches mergees non supprimees

Points forts

  • Deploy GitHub Pages automatise et propre
  • Permissions CI minimales (principe du moindre privilege)
  • Concurrency group pour eviter les deployments paralleles

Recommandations

  1. Ajouter un workflow CI test.yml : npm run build (core) + npm test (core) + node --test (ulk-sdk, status-board).
  2. Nettoyer les branches mergees : git branch -r --merged main | grep -v main | xargs git push origin --delete.
  3. Ajouter un job typecheck dans le CI pour packages/core.

9. Documentation — 8/10

Constats

  • CLAUDE.md : reference. 676 lignes dans agents/CLAUDE.md, couvrant l’architecture, les workflows, les conventions, les agents, et les patterns. Probablement un des meilleurs CLAUDE.md de projet open-source.
  • Documentation structuree dans docs/ : spec.md (676L), guide.md (162L), reference.md (146L), adr.md (127L), glossaire.md, todo.md (70L).
  • CHANGELOG exemplaire : 594 lignes, format Keep a Changelog, versionne semantiquement.
  • README minimaliste (52 lignes) — intentionnel, renvoie vers la doc complete. Efficace.
  • 6 rules dans .claude/rules/ : agents-authoring, cheatheet, frontend-agents, native-features, packages, session-practices.
  • ADR documentees : 10 decisions d’architecture avec leurs raisons.
  • Pas de JSDoc/docstrings dans le code TypeScript. Les types font office de documentation.

Violations

  • P3 · packages/core/src/ · Pas de JSDoc sur les exports publics (parseTodoFile, parseSpecFile, GitHubClient)

Points forts

  • CLAUDE.md exhaustif et structure
  • CHANGELOG maintenu avec rigueur
  • 10 ADR documentees
  • 6 rules contextuelles
  • Guide utilisateur avec 3 workflows

Recommandations

  1. Ajouter des JSDoc minimaux sur les 3 exports publics de @ulk/core.
  2. Documenter clients/app-apple/ dans un README dedie ou la doc de reference.

10. Dette Technique — 7/10

Constats

  • 7 TODO/FIXME/HACK dans le code. Bien en dessous du seuil de 10. La plupart sont des placeholders dans les tests ou templates.
  • 42 branches remote mergees non nettoyees — dette organisationnelle, pas technique.
  • commands/ duplique agents/ — 49 fichiers a maintenir en double. Dette architecturale.
  • Pas de linter enforce — le code est propre mais rien n’empeche une regression de style.
  • packages/core non build (dist/ absent) — empeche le fonctionnement de status-board.
  • 1 god file (install.sh 551L) — juste au seuil, structure interne correcte.
  • Dependances a jour : TypeScript 6.0, Vitest 4.0, Node 24/25 — stack moderne.

Violations

  • P1 · commands/ · 49 fichiers dupliques — dette de maintenance active
  • P2 · Remote · 42 branches mergees a supprimer
  • P3 · install.sh · 551 lignes — candidat au split si d’autres features s’ajoutent

Points forts

  • Seulement 7 TODO/FIXME dans tout le code
  • Dependances modernes et a jour
  • 0 code deprecie ou workaround documente

Recommandations

  1. Automatiser la generation de commands/ depuis agents/ pour eliminer la duplication.
  2. Nettoyer les 42 branches mergees.

Top 20 Actions Prioritaires

#AxeSeveriteActionFichier(s)Effort
1Design SystemP0Ajouter attributs alt sur toutes les imagessite/index.htmlXS
2InfrastructureP0Creer workflow CI test.yml (build + test + typecheck).github/workflows/S
3Qualite codeP1Builder packages/core (ou ajouter script prepare)packages/core/XS
4CoherenceP1Regenerer registry.json pour inclure les 87 agentsagents/registry.jsonXS
5CoherenceP1Completer frontmatter manquant (16 agents sans phase/model)agents/frontend/, agents/test/, agents/deploy/S
6ArchitectureP1Generer commands/ depuis agents/ dans install.shcommands/, install.shM
7Design SystemP1Ajouter aria-* sur composants interactifs (accordion, modal)site/index.htmlS
8InfrastructureP1Fixer les 2 tests status-board en echecpackages/status-board/tests/XS
9Design SystemP2Remplacer Tailwind CDN par build ou version epingleesite/index.htmlS
10ArchitectureP2Ajouter pnpm-workspace.yaml pour formaliser le monorepoRacineS
11Qualite codeP2Ajouter config linter (Biome ou ESLint)RacineS
12InfrastructureP2Nettoyer 42 branches remote mergeesRemoteXS
13CoherenceP2Documenter statut clients/app-apple/clients/app-apple/README.mdXS
14DocumentationP3Ajouter JSDoc sur exports publics @ulk/corepackages/core/src/S
15SecuriteP3Ajouter checksum pour install-remote.shinstall-remote.shS
16Design SystemP3Ajouter <noscript> fallbacksite/index.htmlXS
17Design SystemP3Optimiser Google Fonts (reduire les poids charges)site/index.htmlXS
18DetteP3Surveiller install.sh (551L) — splitter si > 600Linstall.shM
19InfrastructureP3Ajouter schedule de nettoyage branches dans CI.github/workflows/S
20CoherenceP3Verifier coherence site/data/commands.json vs registrysite/data/commands.jsonXS

Ce qui fonctionne bien

  • CLAUDE.md de reference — documentation agent exhaustive, structuree, conforme au code reel
  • Typage exemplaire — 0 any, 0 ts-ignore dans tout le TypeScript
  • Architecture agent solide — 87 agents organises par theme, protocols partages (_shared/), frontmatter structure
  • CHANGELOG maintenu — 594 lignes, format Keep a Changelog, versionne semantiquement
  • 10 ADR documentees — decisions d’architecture tracees et justifiees
  • Suite de tests presente sur les 3 packages (meme si CI manque)
  • Securite propre — zero secrets, zero .env commite, permissions CI minimales
  • install.sh unifie — installateur pur bash, zero dependances, multi-options
  • 11 schemas JSON — contrats de donnees formalises entre packages
  • Dependances modernes — TypeScript 6, Vitest 4, Node 24+
  • Conventions coherentes — nommage NN-agent-name.md, _shared/ mutualise, rules/ contextuelles

Verdict

  1. Le projet est-il pret pour la production / le prochain jalon ?

    Oui, avec reserves. Ulk v4.0.0 est un toolkit fonctionnel et bien documente. Les agents s’installent et s’executent correctement. La dette technique est faible (7 TODO, code propre). Cependant, l’absence totale de CI de qualite (aucun test automatise) est le principal risque pour la fiabilite a mesure que le projet grandit. Le second risque est la duplication commands/ qui finira par generer des incoherences.

  2. Les 3 risques majeurs.

    • Aucun CI de qualite — les regressions passent en silence (seul le deploy est automatise)
    • Duplication commands/agents — 49 fichiers identiques maintenus manuellement, drift inevitable
    • Registry desynchronise — 71 declares vs 87 reels, frontmatter incomplet sur 16 agents

  3. Les 3 atouts majeurs.

    • Documentation exceptionnelle — CLAUDE.md, CHANGELOG, ADR, guide, reference, glossaire — rare a ce niveau
    • Architecture agent coherente — 87 agents structures, protocols partages, detection de stack, orchestration multi-agents
    • Code propre et minimal — 0 type any, 7 TODO, dependances modernes, pas de code mort significatif