Écrire un worker arka-deck

Un worker est un processus LLM headless à appel unique (1-shot). Il reçoit un JSON structuré, produit un JSON structuré, et s’arrête. Pas de chat, pas de multi-tour, pas d’interface utilisateur directe.

---

Principe

Les workers traitent des tâches qui nécessitent un LLM mais pas d’interaction : analyser un contexte projet, rédiger une note, proposer une composition d’équipe.

Le cycle d’un worker :

1. Le système d’arka-deck l’invoque avec un payload JSON (via le port for-workers.ts)
2. Le worker appelle le LLM configuré avec son prompt + le payload
3. Il retourne un JSON structuré
4. L’addon parent reçoit le résultat et l’exploite

Les workers existants et leur addon parent :

Worker	Addon parent	Statut	Rôle
cortex-favorites-suggester	cortex-actions	active	Propose 5-15 artefacts Cortex pertinents pour un projet
memory-note-writer	memory-local	active	Rédige une note mémoire L1-L5 depuis un transcript de session
governance-policy-designer	gouvernance-lite	active	Assiste la conception d’une politique de gouvernance projet
squad-creator	squad-leader	active	Propose une composition de squad depuis une mission

---

Structure d’un worker

Un worker est déclaré par un manifest.json. L’implémentation runtime (invocation LLM, parsing JSON) est gérée par arka-deck — le worker lui-même ne contient que sa déclaration et son prompt.

workers/<name>/
├── manifest.json      # obligatoire
├── prompt.json        # si le prompt est local (optionnel — sinon via Cortex)
└──           # description du worker

---

manifest.json

{
  "name": "mon-worker",
  "version": "1.0.0",
  "description": "Ce que fait le worker en une phrase.",
  "status": "active",
  "input": "Description du payload JSON attendu en entrée.",
  "output": "Description du JSON produit en sortie.",
  "addon_parent": "mon-addon",
  "runtime": "claude-headless",
  "model": "haiku",
  "service": {
    "famille_cortex": "SERVICE",
    "sous_famille_cortex": "service/service/mon_worker",
    "tool_name": "mon_worker_template",
    "prompt_source": "cortex://atoms/mon_worker_prompt",
    "prompt_atom_id": "atom:mon_worker_prompt",
    "preferred_model": "haiku",
    "model_override_via": "Paramètres > Services (config user)"
  }
}

Champs obligatoires

Champ	Type	Description
name	string	Identifiant kebab-case — doit correspondre au nom du dossier
version	string	Semver
description	string	Ce que fait le worker
status	string	"active" / "draft"
input	string	Description du JSON d’entrée (format prose ou pseudo-schéma)
output	string	Description du JSON de sortie
addon_parent	string	Nom de l’addon qui possède ce worker (null si worker autonome)
runtime	string	Voir runtimes disponibles ci-dessous
service.prompt_source	string	Source du prompt — voir formats ci-dessous

Runtimes disponibles

Runtime	Description
claude-headless	Appel Claude via SDK Anthropic — idéal pour tâches d’analyse courtes
llm-json	Appel LLM multi-provider en mode JSON strict — retourne un objet JSON parsé

Sources de prompt

Format	Exemple	Description
cortex://atoms/<id>	cortex://atoms/notewriter_note_prompt	Atome Cortex public — récupéré au runtime
Chemin local	workers/squad-creator/prompt.json	Fichier JSON local dans le dépôt

Le format Cortex est préférable pour les workers actifs : le prompt est versionné dans le Cortex et peut être mis à jour sans modifier le dépôt.

---

Exemples de workers existants

cortex-favorites-suggester

{
  "name": "cortex-favorites-suggester",
  "runtime": "claude-headless",
  "model": "haiku",
  "input": "JSON : { project: { name, description }, agents: [{label, sourceId}], recentSessions: [{summary, agentLabel}], memorySummary?: string, libraryTree: { modes, blocs: { types: { skill, expertise, tool, methode, scope } } } }",
  "output": "JSON : { suggestions: [{ ref: { type: 'atome'|'bloc', id, label }, justification }] } — 5 à 15 items"
}

memory-note-writer

{
  "name": "memory-note-writer",
  "runtime": "llm-json",
  "model": "service-assigned",
  "input": "JSON : { projectPath, sessionId, agentId?, agentLabel?, transcript, recentNotes, profileMemory, projectMemory }",
  "output": "JSON : { level: 'L1'|'L2'|'L3'|'L4'|'L5', title, summary?, content, tags?, actions?, decisions? }"
}

squad-creator

{
  "name": "squad-creator",
  "runtime": "llm-json",
  "model": "gemini-2.5-flash",
  "addon_parent": "squad-leader",
  "input": "Mission en texte libre, contraintes optionnelles, catalogue de profils disponibles",
  "output": "Liste d'agents recommandés (profil + justification), leader désigné, résumé stratégie"
}

---

Intégration avec un addon

Un worker doit être déclaré dans le manifest.json de son addon parent :

{
  "name": "mon-addon",
  "workers": ["mon-worker"]
}

L’addon invoque le worker via le port for-workers.ts (côté use-case) :

const result = await deps.workers.invoke('mon-worker', {
  projectPath,
  // ... payload JSON selon le manifest du worker
});

Le résultat JSON est directement exploitable par l’addon.

---

Choix du modèle

Le manifest déclare un model préférentiel. L’utilisateur peut le surcharger depuis Paramètres → Services.

Cas	Modèle recommandé
Analyse courte, tâche de classement	haiku
Rédaction structurée, extraction	gemini-2.5-flash ou haiku
Tâche complexe, raisonnement	sonnet

Règle pratique : commencez par haiku — le worker est 1-shot, le coût est proportionnel au modèle choisi.

---

Limites

• Un worker ne peut pas initier une conversation multi-tour
• Un worker ne peut pas appeler un autre worker directement
• Un worker ne peut pas écrire dans .arka-deck/ — c’est l’addon parent qui persiste le résultat
• Les workers draft peuvent évoluer sans préavis