Architecture — ulk

Reconstitue depuis le code source, les protocoles partages et les agents orchestrateurs.

1. Vue d’ensemble du monorepo

ulk/
├─ agents/              Source de verite des agents (.md)
│  ├─ _shared/          13 protocoles partages
│  ├─ orchestrators/    Bruce, Blackemperor, Lovecraft
│  ├─ docs/             Shuri, Friday
│  ├─ 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 stack (5)
│  ├─ deploy/           Agents deploy (5)
│  ├─ test/             Agents test (2)
│  ├─ frontend/         Agents frontend (7) + checklists
│  └─ vps/              Agents VPS (17+)
├─ commands/            Miroir installable (genere)
├─ skills/              12 skills CLI
├─ schemas/             11 JSON Schemas
├─ packages/
│  ├─ core/             @ulk/core (TypeScript)
│  ├─ status-board/     Dashboard CLI
│  └─ ulk-sdk/          SDK (futur)
├─ .claude/
│  ├─ agents/           8 subagents persistants
│  ├─ rules/            6 regles path-specific
│  └─ hooks-examples/   Hooks memory loop
├─ site/                GitHub Pages
├─ cheatheet/           Generateurs docs
├─ tools/               CLI registry + diagnostic
└─ install.sh           Installeur

2. Hierarchie d’orchestration

graph TD
    USER["Utilisateur"]
    BRUCE["Bruce (25)<br/>Orchestrateur PM"]
    BE["Blackemperor (18)<br/>5 modes"]
    LOVECRAFT["Lovecraft (47)<br/>Doc Obsidian"]
    FRONT_ORCH["Frontend Orch (15/00)"]

    USER --> BRUCE
    USER --> BE
    USER --> LOVECRAFT

    BRUCE --> GODSPEED["Godspeed (00)<br/>Diagnostic"]
    BRUCE --> SHURI["Shuri (01)<br/>Spec/Todo/Sync"]
    BRUCE --> TASKRUNNER["Task-runner (04)<br/>Execution"]
    BRUCE --> ROBOCOP["Robocop (11)<br/>Fix erreurs"]
    BRUCE --> BE
    BRUCE --> BRIGITTE["Brigitte (24)<br/>Sync ext."]

    BE --> SHURI
    BE --> VISION["Vision (05)<br/>Audit code"]
    BE --> PERF["Perf-auditor (07)"]
    BE --> A11Y["A11y-auditor (06)"]
    BE --> ROBOCOP

    LOVECRAFT --> SHURI
    LOVECRAFT --> STRANGE["Strange (16)<br/>Reverse doc"]
    LOVECRAFT --> FRIDAY["Friday (09)<br/>Docs manager"]
    LOVECRAFT --> OBSIDIAN["Obsidian-vault (39)"]

    FRONT_ORCH --> BRIQUE["Brique (15/01)"]
    FRONT_ORCH --> FQA["Frontend-QA (15/02)"]
    FRONT_ORCH --> VISUAL["Visual-auditor (15/03)"]
    FRONT_ORCH --> BACKOFFICE["Backoffice-auditor (15/04)"]

Niveaux d’orchestration

Niveau	Agents	Role
L0 — Entree	Bruce (25)	Point d’entree unique, routing intelligent
L1 — Orchestrateurs	Blackemperor (18), Lovecraft (47), Frontend-orch (15/00)	Pipelines multi-agents thematiques
L2 — Specialistes	Shuri, Vision, Robocop, Godspeed, etc.	Execution de taches focalisees
L3 — Utilitaires	Checklists, stack-detection, base-rules	Protocoles et references partages

3. Flux de donnees — Workflow “bruce go”

sequenceDiagram
    participant U as Utilisateur
    participant B as Bruce (25)
    participant G as Godspeed (00)
    participant S as Shuri (01)
    participant TR as Task-runner (04)

    U->>B: "bruce go"
    B->>G: Diagnostic projet
    G-->>B: Stack, etat, suggestions
    
    alt Projet vide
        B->>S: mode=spec (questions + generation)
        S-->>B: docs/spec.md
        B->>S: mode=todo (spec vers Kanban)
        S-->>B: docs/todo.md
    end

    B->>TR: Prochaine tache
    TR-->>B: Tache executee, todo.md mis a jour

4. Flux de donnees — Audit orchestre (Blackemperor)

sequenceDiagram
    participant U as Utilisateur
    participant BE as Blackemperor (18)
    participant S as Shuri (01)
    participant V as Vision (05)
    participant P as Perf-auditor (07)
    participant A as A11y-auditor (06)

    U->>BE: "audit-complet"
    BE->>S: mode=spec (contexte)
    S-->>BE: docs/spec.md + CONTEXTE PROJET

    par Audits paralleles
        BE->>V: Audit code + CONTEXTE PROJET
        BE->>P: Audit perf + CONTEXTE PROJET
        BE->>A: Audit a11y + CONTEXTE PROJET
    end

    V-->>BE: RESULTATS VISION
    P-->>BE: RESULTATS PERF
    A-->>BE: RESULTATS A11Y

    BE->>S: mode=todo (consolidation findings)
    S-->>BE: docs/todo.md enrichi
    BE-->>U: Rapport consolide + actions priorisees

Gains du context-protocol :

Les 3 agents paralleles recoivent le CONTEXTE PROJET: et sautent la Phase 1 (reconnaissance)
Economie : ~30K tokens (3 x 10K)
Temps : -40% (parallelisme)

5. Flux de donnees — Knowledge Vault Loop

sequenceDiagram
    participant C as Claude (session)
    participant M as MEMORY.md
    participant L as Lovecraft (47)
    participant OV as Obsidian-vault (39)
    participant S as Shuri (01)
    participant CMD as CLAUDE.md

    C->>M: Ecrit learnings pendant la session
    
    Note over C,M: Fin de session (2b3 ou hook Stop)
    
    C->>L: lovecraft memory capture
    L->>OV: Parse MEMORY.md
    OV->>OV: Cree entrees dans docs/_memory/<cat>/
    OV-->>L: Entrees creees
    L->>L: Archive MEMORY.md

    L->>S: lovecraft memory distribute
    S->>S: Filtre par pertinence projet
    S->>CMD: Injecte bloc vault:begin/end
    
    Note over C,CMD: Session suivante
    
    C->>L: lovecraft memory surface
    L-->>C: Resume des entrees pertinentes

6. Pipeline install → compile → run

flowchart LR
    subgraph SOURCE ["Source (repo)"]
        A[agents/*.md]
        SH[_shared/*.md]
        SK[skills/*/SKILL.md]
        SA[.claude/agents/*.md]
    end

    subgraph GENERATE ["Generation"]
        GC[generate-commands.cjs]
        GR[generate-registry.cjs]
    end

    subgraph OUTPUT ["Genere"]
        CMD[commands/]
        REG[registry.json]
    end

    subgraph INSTALL ["Installation (~/.claude/)"]
        UC[commands/ulk/]
        UA[agents/ulk-*.md]
        US[skills/ulk-*/]
    end

    A --> GC --> CMD
    A --> GR --> REG
    CMD -->|install.sh copie| UC
    SA -->|install.sh copie| UA
    SK -->|install.sh copie| US

    subgraph RUNTIME ["Runtime Claude Code"]
        CC[Claude Code CLI]
        CC -->|lit| UC
        CC -->|lit| UA
        CC -->|lit| US
    end

Etapes du pipeline :

Source : agents/ contient les fichiers .md (source de verite)
Generation : cheatheet/generate-commands.cjs aplatit la structure vers commands/
Installation : install.sh copie vers ~/.claude/ (commands, agents, skills)
Runtime : Claude Code lit les fichiers depuis ~/.claude/ et les rend disponibles comme commandes

7. Dependances entre packages

graph TD
    ROOT["package.json (racine)<br/>workspaces: packages/*"]
    CORE["@ulk/core<br/>TypeScript: parsers, types, GitHub"]
    SB["status-board<br/>Dashboard CLI"]
    SDK["ulk-sdk<br/>(futur)"]
    SCHEMAS["schemas/<br/>JSON Schema draft-07"]

    ROOT --> CORE
    ROOT --> SB
    ROOT --> SDK

    SB -.->|utilise parsers| CORE
    CORE -.->|valide contre| SCHEMAS
    SDK -.->|importera| CORE

Contrat cross-platform (schemas/)

Les schemas JSON servent de contrat entre les differentes couches :

Schema	Producteur	Consommateur
`todo.schema.json`	Shuri (01), Task-runner (04)	@ulk/core (`parseTodoFile`), status-board
`spec.schema.json`	Shuri (01)	@ulk/core (`parseSpecFile`)
`dashboard.schema.json`	status-board	Future app macOS
`cli-registry.schema.json`	Editeur humain	tools-checker (43), install.sh

8. Ecosysteme mobile

flowchart TD
    WEB["Projet web existant"]
    HAPPY["Happy (49)<br/>API Architect"]
    API["docs/api/<br/>OpenAPI 3.1"]
    STEVE["Steve (27)<br/>Apple"]
    FLUKE["Fluke (48)<br/>Android"]
    IOS["docs/apple-starter-kit/<br/>SwiftUI"]
    ANDROID["docs/android-starter-kit/<br/>Kotlin/Flutter"]

    WEB --> HAPPY
    HAPPY --> API
    API --> STEVE --> IOS
    API --> FLUKE --> ANDROID

Happy est le prerequis obligatoire : il audite le projet web, concoit l’API complete et genere la documentation OpenAPI. Steve et Fluke consomment cette spec pour generer les starter kits natifs.

9. Modes Agent Teams vs Subagents

                    ┌─────────────────────────┐
                    │    ORCHESTRATEUR         │
                    │  (bruce / blackemperor)  │
                    └─────────┬───────────────┘
                              │
              ┌───────────────┴───────────────┐
              │                               │
    ┌─────────▼──────────┐        ┌──────────▼──────────┐
    │    SUBAGENTS        │        │    AGENT TEAMS       │
    │  (mode par defaut)  │        │  (experimental)      │
    ├─────────────────────┤        ├──────────────────────┤
    │ Contexte propre     │        │ Contexte propre      │
    │ Resultat → caller   │        │ Communication entre  │
    │ Coordination par    │        │   teammates          │
    │   l'orchestrateur   │        │ Task list partagee   │
    │ Cout tokens: bas    │        │ Cout tokens: eleve   │
    │ Ideal: taches       │        │ Ideal: collaboration │
    │   focalisees        │        │   multi-angles       │
    └─────────────────────┘        └──────────────────────┘

Choix de mode :

Subagents : taches independantes, budget tokens limite
Agent Teams : debug adversarial, multi-layer (front + back + tests), review multi-angles