Concepts arka-deck
Ce document explique les termes du produit dans l’ordre logique : du plus concret (votre machine, vos fichiers) au plus abstrait (l’orchestration multi-agents).
Un projet est un dossier local sur votre machine. Vous le pointez dans arka-deck, qui crée un sous-dossier .arka-deck/ à l’intérieur pour stocker ses données de travail (mémoire, sessions, logs, configuration).
Vos fichiers ne bougent pas. arka-deck ne lit que ce dont il a besoin.
Workspace
Section intitulée « Workspace »Un workspace est un conteneur logique qui regroupe plusieurs projets. Il n’existe pas sur le disque — c’est un label d’organisation interne à arka-deck.
Exemple : un workspace “Client A” peut contenir les projets “audit-2026” et “refonte-api”.
Provider
Section intitulée « Provider »Un provider est le moteur LLM que vous configurez pour faire tourner les agents. arka-deck supporte plusieurs providers :
| Provider | Statut | Notes |
|---|---|---|
| Claude Code (Anthropic) | beta | SDK officiel @anthropic-ai/claude-agent-sdk |
| Google Gemini | beta | Generative Language API |
| Codex CLI (OpenAI) | beta | Runtime Codex CLI |
Chaque provider conserve ses capacités natives. arka-deck n’efface pas les spécificités — il ajoute une couche de pilotage au-dessus.
Profil (HYOS)
Section intitulée « Profil (HYOS) »Un profil est un agent spécialisé : un ensemble de règles, de capacités, de flowmaps et d’atomes qui définissent comment l’agent doit travailler dans un domaine donné.
Le Cortex public propose plusieurs dizaines de profils prêts à l’emploi (architecte, juriste, QA, data scientist, etc.). Vous installez un profil sur un projet pour recruter cet agent.
Un profil n’est pas un prompt système écrit à la main. C’est une entité versionnée, récupérée du Cortex et injectée dans le contexte au moment voulu.
Un atome est une unité de connaissance atomique : une règle, un pattern, une contrainte ou une capacité isolée, identifiée par un identifiant stable.
Les atomes composent les profils et les blocs.
Un bloc est une règle ou capacité exécutable — une instruction structurée que l’agent peut recevoir pour cadrer son comportement : méthode, expertise, outil autorisé, scope, contrainte.
Les blocs sont organisés en plusieurs types (skill, expertise, tool, methode, scope).
L’addon cortex-actions permet de sélectionner un bloc avant un tour de chat pour l’injecter dans le contexte de l’agent.
Une flowmap est une séquence d’exécution agentique : un enchaînement d’étapes, de décisions et de transitions que l’agent suit pour traiter une mission structurée.
Les flowmaps viennent du Cortex. Elles donnent à l’agent un cadre de progression explicite plutôt qu’une improvisation libre.
Une session est un échange de chat avec un agent sur un projet. Elle contient la timeline complète : messages, blocs thinking, appels d’outils, résultats. Tout reste local.
Une session a un cycle de vie : started → ended (normal) ou aborted ou error.
Tour (turn)
Section intitulée « Tour (turn) »Un tour est un échange unitaire dans une session : un message utilisateur suivi de la réponse de l’agent. Les événements chat.turn.started et chat.turn.ended bornent chaque tour.
La mémoire est un système de persistance active par projet. Après une session, les éléments importants (décisions, apprentissages, méthodes) peuvent être capturés sous forme d’entrées mémoire et réinjectés dans les sessions suivantes.
Les entrées ont un niveau d’importance allant de L1 (note courte) à L5 (synthèse élaborée). Stockage local dans <projet>/.arka-deck/memory/.
La mémoire n’est pas un historique de chat. C’est une extraction sémantique de ce qui mérite d’être réutilisé.
Un addon est un module autonome qui étend les capacités d’arka-deck. Il s’abonne au bus d’événements et peut augmenter le contexte d’un tour, écrire des logs, ou exposer ses propres fonctionnalités.
Les addons préinstallés (first-party) :
| Addon | Rôle | Statut |
|---|---|---|
cortex-actions | Panneau d’artefacts Cortex dans le chat | beta |
cortex-lite | Runtime Cortex local en sidecar | stable |
memory-local | Mémoire agentique par projet | beta |
mission-guardian | Mission Control, guardian packs, gates leader et QA, preuves | beta |
squad-leader | Composition et coordination de squads | beta |
squad-orchestration | Orchestration multi-agents LangGraph | beta |
notion-connect | Connecteur Notion | beta |
gmail | Connecteur Gmail géré par l’utilisateur | beta |
google-drive | Connecteur Google Drive géré par l’utilisateur | beta |
@arkalabs/addon-expert-panel | Infrastructure Expert Panel pour futurs Packs Métier | non exposé en release |
Gmail et Google Drive sont des connecteurs gérés par l’utilisateur : arka-deck ne fournit pas d’app OAuth Google globale. L’utilisateur apporte le token API/gateway et peut rattacher un endpoint MCP géré par lui à la même installation connecteur.
Le contrat addon est stabilisé pour permettre, à terme, des extensions externes. Pour l’instant, tous les addons sont câblés explicitement dans arka-deck.
MCP projet
Section intitulée « MCP projet »Un MCP projet est un serveur MCP externe rendu disponible uniquement aux agents d’un projet donné. Il se configure depuis Sources externes → MCP projet.
Deux chemins existent :
- rattacher une installation connecteur déjà configurée qui expose un endpoint MCP, par exemple Gmail, Google Drive ou Notion si l’installation porte un endpoint ;
- ajouter un endpoint HTTP/SSE custom, avec un nom runtime stable
connector_*.
arka-deck ne copie pas de secret dans la configuration MCP projet. Les credentials restent dans l’installation connecteur ou dans une politique de secret dédiée. Les endpoints distants doivent utiliser HTTPS ; le HTTP est accepté uniquement sur loopback pour un serveur local.
Quand un MCP projet est configuré et testé, les agents du projet le reçoivent dans leur runtime provider. Un autre projet ne le reçoit pas.
Un worker est un processus LLM headless à appel unique. Il reçoit un JSON en entrée, produit un JSON en sortie, et s’arrête. Pas de chat, pas de multi-tour.
Les workers sont déclarés dans un manifest.json et rattachés à un addon parent. Exemples :
squad-creator— propose une composition de squad pour une missioncortex-favorites-suggester— propose des artefacts Cortex pertinents pour le projetmemory-note-writer— rédige une note mémoire à partir d’une session
Un squad est une équipe d’agents spécialisés recrutés pour travailler ensemble sur une mission. Chaque agent a son profil et son rôle. Un leader coordonne.
L’addon squad-leader gère la composition et l’activation des squads sur un projet. L’addon squad-orchestration gère l’exécution de missions multi-agents avec un graphe d’état LangGraph.
Une mission est une unité de travail confiée à un squad. Elle comporte un objectif, des phases, des preuves attendues et un verdict QA.
L’addon mission-guardian suit l’état de la mission (phases, gates franchis, preuves capturées) et empêche un agent de passer à l’étape suivante tant que les gates ne sont pas validés. Mission Control est la vue runtime du même flux : flowmap active, mode courant, blocages et prochains documents attendus.
Mission Control
Section intitulée « Mission Control »Mission Control regroupe les règles, permissions et traces qui encadrent le travail des agents. Dans arka-deck, ces règles runtime sont portées par le guardian pack actif et matérialisées via Cortex Lite pour le projet.
Guardian pack
Section intitulée « Guardian pack »Un guardian pack est un pack de gouvernance appliqué à un projet. Il contient les modes, transitions, règles, mini-rules, règles par mode, flowmap, event policy, tool policy, templates de cards UI, prompt layers et documents requis.
Le pack actif est matérialisé dans Cortex Lite. Mission Guardian l’administre et le runtime l’exécute ; le core ne doit pas choisir une gouvernance à sa place.
Deck Guardian est le guardian pack first-party par défaut pour un projet arka-deck standard. Un futur Pack Métier devra apporter son propre guardian pack dédié avant d’être publié.
Le Cortex est un référentiel de connaissance structuré. Il stocke profils, atomes, blocs, flowmaps et documents sous forme de graphe.
- Cortex public (
public.arkalabs.app) — lecture seule, sans authentification. Fournit le catalogue de départ. Vos projets n’y sont jamais envoyés. - Cortex dédié — instance privée pour une équipe ou une organisation. Permet de stocker les profils internes, décisions, traces et mémoire opérationnelle (offre à venir).
Cortex Lite
Section intitulée « Cortex Lite »Cortex Lite est le runtime Cortex local d’arka-deck. Il s’appuie sur SurrealDB et un modèle graphe local.
Son rôle n’est pas de stocker des fichiers. Cortex Lite matérialise les relations utiles au runtime : projet, documents ArkaDoc, mémoire, profils, méthodes, règles, events et artefacts de module. Les agents ne lisent pas un dossier brut ; ils résolvent un contexte structuré et scopé au projet via les routes HTTP et le serveur MCP arka_runtime.
Quand un futur pack métier validé sera activé sur un projet, Cortex Lite reliera ce pack au projet dans le graphe local. Les méthodes, règles et eventmaps du pack deviendront disponibles uniquement dans ce contexte projet. Aucun pack métier first-party n’est publié dans cette release.
Un ArkaDoc est un document métier rattaché à un projet : compte-rendu, brief, spec, tâche, décision, verdict QA. Il persiste sur disque dans <projet>/.arka-deck/arkadoc/ et est consultable depuis l’UI (liste, timeline, kanban, arbre).
Pour le dispatch, l’id du document ArkaDoc est l’id runtime stable. Les agents peuvent voir un task_id métier dans le payload du document, mais les commandes de dispatch doivent utiliser l’id ArkaDoc exposé comme dispatch_task_id.
Documentation projet
Section intitulée « Documentation projet »La Documentation projet est la vue lisible des livrables ArkaDoc : CR, specs, décisions, verdicts QA, briefs et documents métier. Elle n’est plus un mock UI : elle lit les documents réels du projet via les routes documentation.
Chaque document est exposé avec un index de consultation : résumé, tags, estimation de tokens, blocs et relations. Les agents peuvent naviguer par index, lire un bloc précis, explorer les voisins du document ou ouvrir le contenu complet quand c’est nécessaire. L’objectif est d’éviter la relecture brute de tous les documents et de garder un graphe de livrables exploitable par Cortex Lite.