Design — Intégration apfel dans les agents ulk

Date : 2026-04-14
Statut : approuvé
Auteur : Claude (brainstorming session)

Contexte

apfel (v1.0.1) est installé sur la machine mais n’est jamais réellement utilisé par les agents ulk. Les agents le mentionnent dans des commentaires suggestifs (> Optimisation apfel : ...) sans implémenter de branche conditionnelle réelle. Cette intégration complète le protocole existant (_shared/apfel-protocol.md).

Objectifs

Implémenter apfel dans tous les agents où c’est applicable (~10 agents)
Ajouter un rapport inline dans le rapport final de chaque agent
Maintenir un log cumulatif docs/apfel-report.md (markdown lisible + stats JSON embarquées)

Approche retenue : B — Protocole partagé + patch agents

Mettre à jour _shared/apfel-protocol.md avec le standard complet (pattern bash, format rapport)
Patcher chaque agent pour implémenter le check conditionnel réel
Un seul endroit à faire évoluer pour le format du rapport

Section 1 — Mise à jour `_shared/apfel-protocol.md`

Pattern standard d’invocation

Ajout d’un bloc “Pattern d’intégration standard” dans le protocole :

# Détection unique en début d'agent (Phase 0 ou Phase 1)
APFEL=$(command -v apfel >/dev/null 2>&1 && echo "yes" || echo "no")

# Invocation avec logging
# Usage : apfel_run "nom-tâche" "chemin/fichier" "prompt" "~tokens_estimés"
# - fichier peut être vide "" pour les prompts sans fichier

Pattern conditionnel dans chaque phase :

if [ "$APFEL" = "yes" ]; then
  result=$(apfel -q -f "$file" "prompt...")
  # Ajouter à APFEL_LOG : "tâche|fichier|~tokens"
else
  # Lire et analyser avec Claude directement
fi

Format rapport inline

Ajouté à la fin du rapport final de chaque agent :

🍏 Apfel — N invocations (~N tokens économisés)
  • tâche 1 (fichier)
  • tâche 2 (fichier)
  → Log : docs/apfel-report.md

Si apfel absent :

🍏 Apfel — non disponible (macOS 26+ requis)

Format log cumulatif `docs/apfel-report.md`

# Apfel Usage Report

<!-- apfel:stats
{
  "total_calls": 0,
  "total_tokens_saved": 0,
  "by_agent": {
    "godspeed": { "calls": 0, "tokens_saved": 0 },
    "2b3": { "calls": 0, "tokens_saved": 0 }
  }
}
-->

## YYYY-MM-DD

### agent-name (NN) — HH:MM
| Tâche | Fichier | Tokens économisés |
|-------|---------|-------------------|
| résumé spec | docs/spec.md | ~200 |
**Total session : ~200 tokens**

Règles du log :

Idempotent : append uniquement, jamais de réécriture complète
Section ## YYYY-MM-DD créée si absente, réutilisée si présente
Stats JSON mises à jour à chaque écriture (totaux cumulatifs)

Section 2 — Agents à patcher (10 agents + 2 fichiers)

Fichier	Tâches apfel	Phases concernées
`session/00-godspeed.md`	Résumé spec.md, classification stack, description structure	1.1, 1.2
`session/08-2b3.md`	TODOs/secrets/naming, commit message	1.4, 1.5, 5.2
`session/05-vision.md`	Extraction TODOs fichiers audités	Phase audit
`session/11-robocop.md`	Extraction contexte erreur	Phase 1
`docs/01-shuri.md`	Classification fichiers, extraction frontmatter	Phase 1
`docs/09-friday.md`	Résumé README/package.json/configs	Phase C1
`docs/16-strange.md`	Résumé docs pour reverse engineering	Phase 1
`orchestrators/47-lovecraft.md`	Inventaire docs (titre/statut/résumé)	Phase 1
`audit/45-sargeras.md`	Résumé fichiers pour 10 axes d’audit	Phase 1
`audit/52-ed209.md`	Détection secrets/tokens	Phase 1
`_shared/apfel-protocol.md`	Mise à jour avec standard complet	—
`docs/apfel-report.md`	Création du fichier log	—

Total : 12 fichiers.

Section 3 — Mécanique de logging

Chaque agent, à la fin de son exécution, appende au log :

Vérifier si docs/apfel-report.md existe, le créer si absent (avec structure initiale)
Chercher la section ## YYYY-MM-DD du jour, la créer si absente
Appender le sous-bloc agent avec le tableau des invocations
Mettre à jour le JSON stats en tête (incrémenter total_calls, total_tokens_saved, by_agent[agent])

Si apfel n’a pas été utilisé (absent ou aucune tâche déléguée) → ne rien écrire dans le log.

Contraintes respectées

Non bloquant : si apfel absent, fallback Claude transparent
Optionnel : aucun agent ne dépend d’apfel pour fonctionner
Scope fichier : apfel invoqué uniquement sur fichiers < 200 lignes
Pattern projet : suit _shared/cli-tools-protocol.md (CLI > MCP > fallback)
Idempotence : le log est append-only, pas de doublons

Gains estimés

Agent	Invocations/session	Tokens économisés
godspeed	2-3	~700
2b3	3-5	~1 500
friday	3-5	~2 000
lovecraft	5-20	~5 000
sargeras	10-30	~8 000
autres (5)	2-3 chacun	~3 000
Total session type		~20 000 tokens