Epic Harness
Un harnais d'agent de codage IA auto-evolutif — 3 commandes, 26 skills, 1 pipeline autonome, apprend de vos echecs.
Moins a memoriser. Plus d'intelligence par frappe. Devient plus intelligent a chaque session.
English | 日本語 | 한국어 | Deutsch | Français | 简体中文 | 繁體中文 | Português | Español | हिन्दी
Un plugin Claude Code qui **consolide plus de 30 commandes en 3 commandes + 26 skills a declenchement automatique**, et **genere de nouvelles competences** a partir de vos propres schemas d'echec.
---
### Tableau de bord web — se lance automatiquement au demarrage de la session
10 ecrans de metriques en temps reel pour les scores eval, les statistiques d'outils, les pipelines orbit, les competences evoluees et l'etat des hooks. S'ouvre automatiquement lors de la premiere session Claude Code — aucune configuration manuelle necessaire.
```bash
# Se lance automatiquement lors de la premiere session (par defaut : http://localhost:7700)
# Configurez le port ou desactivez dans ~/.harness/config.toml :
[dashboard]
port = 7700 # mettre a 0 pour desactiver le lancement automatique
auto_open = true # ouvrir le navigateur lors de la premiere session
```
Ecrans : **Dashboard** · Pipeline /orbit · Commandes (3) · Competences (26) · Agents en direct · Eval & Evolve · Hooks (6) · Integrations (6) · harness-mem · Parametres
---
## Ce qu'il fait
Une seule commande livre une fonctionnalite de bout en bout. Les competences se declenchent sans que vous les demandiez. L'agent devient plus intelligent apres chaque session.
```bash
$ /orbit "Add JWT auth to the login API"
→ spec approved → go (TDD subagents) → check (PASS) → ship (PR + CI) → evolve
```
Ou invoquer les skills du pipeline directement :
```bash
/spec "Add JWT auth to the login API" # clarifie les exigences → SPEC-*.md
/go # planification automatique → sous-agents TDD → 4 min
/check # revue parallele + securite + tests → PASS
/ship # test isole → PR → CI vert
```
Les competences se declenchent automatiquement en arriere-plan — aucune commande supplementaire :
```
Vous ecrivez une fonctionnalite ? → tdd se declenche (Red→Green→Refactor applique)
Un test echoue ? → debug se declenche (cause racine d'abord, pas de corrections au hasard)
Vous touchez a l'auth ou la BDD ? → secure se declenche (liste de controle OWASP, pas de raccourcis)
Un fichier depasse 200 lignes ? → simplify se declenche (extraire, renommer, reduire)
```
Apres la fin de la session, la **boucle evolve** analyse ce qui a echoue, genere des competences ciblees et les charge lors de la prochaine session. L'agent qui a eu des difficultes avec les echecs de build TypeScript aura une competence `evo-ts-care` la prochaine fois.
---
## Installation
> **Premiere fois ?** Lisez le [Guide de demarrage rapide (5 min)](../../docs/quickstart.md).
epic-harness est distribué en tant que **plugin** — les skills, hooks et le serveur MCP `harness-mem` sont chargés directement depuis la disposition du plugin (`skills/`, `hooks.json`, `mcp_config.json`). Il n'y a pas de sous-commande `install` ; chaque outil lit le plugin depuis le disque.
### Claude Code (recommande)
```
/plugin marketplace add epicsagas/plugins
/plugin install epic@epicsagas
```
Installe automatiquement le binaire, les skills, les hooks et le serveur MCP `harness-mem` en une seule étape.
### Codex CLI
```bash
codex plugin marketplace add epicsagas/plugins
```
Les skills et agents sont disponibles immédiatement — aucune étape supplémentaire nécessaire.
### agy (Antigravity CLI)
```bash
agy plugin install .
```
Les 27 skills, les hooks et le serveur MCP `harness-mem` sont découverts automatiquement depuis `plugin.json` + `skills/` + `hooks.json` + `mcp_config.json` du plugin.
### Binaire uniquement (sans hôte de plugin)
```bash
brew install epicsagas/tap/epic-harness # macOS / Linux (Homebrew)
cargo binstall epic-harness # binaire précompilé (Rust)
cargo install epic-harness # compilation depuis les sources
```
Pas de Homebrew ? Utilisez le script d'installation :
```bash
curl --proto '=https' --tlsv1.2 -LsSf \
https://github.com/epicsagas/epic-harness/releases/latest/download/install.sh | sh
```
Windows:
```powershell
irm https://github.com/epicsagas/epic-harness/releases/latest/download/install.ps1 | iex
```
Le binaire crée automatiquement `~/.harness/config.toml` et `HARNESS.md` lors de la première exécution du hook — sans assistant de configuration ni étape `install`.
> `epic-harness --version` pour vérifier. Mettez à jour avec `brew upgrade epic-harness` ou ré-exécutez le script d'installation.
Prérequis : **Git**. Les installations depuis les sources/binaires nécessitent également la [chaîne d'outils Rust](https://rustup.rs).
### Vérifier
```bash
epic --version # Binaire installé
ls ~/.harness/ # Répertoire de données (créé automatiquement à la première session)
```
Dans une session Claude Code : `/evolve status`
> **Télémétrie** : les rapports d'utilisation sont activés par défaut (opt-out). Basculez avec `epic-harness telemetry status|on|off`.
---
## Télémétrie
epic-harness collecte une télémétrie d'utilisation **anonyme** par défaut (opt-out) pour améliorer la fiabilité des hooks et l'évolution des skills. Les événements sont envoyés à Posthog.
**Ce que nous collectons :** nom de la commande, durée, résultat (succès/échec), classe d'échec et événements de blocage/échec des hooks — plus `product`, `product_version`, `os` et un `install_id` aléatoire (UUID généré au premier lancement, stocké dans `~/.config/epic-harness/install-id`).
**Ce que nous ne collectons jamais :** code source, contenu de fichiers, chemins de fichiers, variables d'environnement, secrets ou toute information personnelle.
**Contrôle :**
```bash
epic-harness telemetry status # afficher le consentement actuel
epic-harness telemetry off # désactiver (arrête tout envoi)
epic-harness telemetry on # réactiver
```
Le consentement est stocké dans `~/.config/epic-harness/telemetry-consent`. Lorsque off, aucune télémétrie n'est envoyée.
---
## Commandes
| Commande | Ce qu'elle fait |
|----------|----------------|
| `/orbit` | **Pipeline autonome complet** : spec → go → check → ship → evolve en une seule execution |
| `/team` | Parcourir les bibliotheques d'organisation, recruter des equipes existantes ou en concevoir de nouvelles (3–6 agents, synchronises vers `.claude/agents/`) |
| `/evolve` | Declencheur d'evolution manuelle — analyser les sessions, voir le tableau de bord, inspecter l'efficacite des competences, restaurer |
Les etapes du pipeline (`/spec`, `/go`, `/check`, `/ship`, `/discover`) sont maintenant des **skills** — declenchees automatiquement selon le contexte ou appelables par nom. Les anciens noms de commandes fonctionnent toujours via le routage par alias.
---
## /orbit — Pipeline autonome
`/orbit` encapsule l'ensemble du pipeline en une seule execution autonome. Choisissez un mode — tout le reste est automatique jusqu'a la PR.
```mermaid
flowchart TD
START(["/orbit"]) --> MODE{"requirement?"}:::human
MODE -->|"unclear"| WAIT["Interactive\n/discover → /spec\nthen 'orbit go'"]:::human
MODE -->|"clear + complex"| COUNCIL["Council\n4-voice auto-spec"]:::auto
MODE -->|"clear + simple"| DIRECT["Direct\nauto-spec"]:::auto
WAIT --> SPEC_LOAD["Load spec"]
COUNCIL --> SPEC_LOAD
DIRECT --> SPEC_LOAD
SPEC_LOAD --> GO["Go\nplan → TDD → integrate"]:::auto
GO --> CHECK["Check\nreview + audit + test"]:::auto
CHECK -->|"PASS / WARN"| SHIP["Ship\nisolated test → PR → CI"]:::auto
CHECK -->|FAIL| RETRY{"retry < 3?"}
RETRY -->|yes| GO
RETRY -->|no| PAUSE["Pause\nuser decides"]:::human
PAUSE -->|continue| GO
PAUSE -->|abort| ABORT(["Abort"])
SHIP --> EVOLVE["Evolve\nauto-analyze session"]:::auto
EVOLVE --> DONE(["Orbit Complete\nconsolidated report"]):::auto
classDef human fill:#4a4a6a,stroke:#9b9bcc,color:#fff
classDef auto fill:#1a5c3a,stroke:#4caf7d,color:#fff
```
**Violet** — etapes humaines : selection du mode (flou → interactif), pause apres 3 echecs de check.
**Vert** — clair + complexe → auto-spec en conseil ; clair + simple → construction directe ; les deux entierement autonomes.
Etat persiste dans `$HARNESS_DIR/orbit/PIPELINE-{timestamp}.json` — survit a la compaction du contexte.
> **Reserves** : L'agent peut contourner le pipeline lorsqu'il modifie orbit lui-meme ou lorsqu'il modifie uniquement de la documentation. Voir [Problemes connus (Jugement de l'agent)](#known-issues-agent-judgment).
---
## Competences automatiques (Ring 2)
Les competences se declenchent automatiquement en fonction du contexte. Vous ne les invoquez pas.
| Competence | Se declenche quand |
|-----------|-------------------|
| **spec** | Besoin de definir les exigences — convertit en document R + AC numerote |
| **go** | Phase de build — planification auto → sous-agents TDD → execution parallele → verification AC |
| **check** | Phase de review — revue de code parallele + audit de securite + tests avec extras par scope |
| **ship** | Phase de livraison — test isole → PR avec rapport complet → surveillance CI + auto-fix |
| **audit** | Audit complet — revue parallele de la qualite du code + securite + tests avec dedoublonnage semantique |
| **eval** | Evaluation de regression qualitative avec comparaison de base — correction, perf, qualite |
| **tdd** | Implementation d'une nouvelle fonctionnalite ou correction de bug |
| **debug** | Echec de test ou erreur d'execution |
| **discover** | Demande vague, solution sans probleme, plainte imprecise |
| **secure** | Code d'auth / BDD / API / secrets modifie |
| **threat-model** | Cadrage de securite — enumeration des frontieres de confiance, acteurs de menace, scenarios → THREAT_MODEL.md |
| **vuln-scan** | Scan systematique des vulnerabilites — injection, auth, exposition de donnees, dependances → VULN-FINDINGS.json |
| **triage** | Validation adversariale — ajustement de severite, analyse de chainage, regroupement par cause racine → TRIAGE.json |
| **perf** | Boucles, requetes, rendu, operations par lot |
| **simplify** | Fichier > 200 lignes ou complexite cyclomatique elevee |
| **document** | API publique ajoutee ou signature modifiee |
| **verify** | Avant de completer `/go` ou `/ship` |
| **context** | Fenetre de contexte > 70 % |
| **council** | Decisions architecturales ou de conception ambigues |
| **orchestrate** | Statut d'orchestration multi-agent et controle des agents en direct |
| **agent-introspection** | 3+ echecs consecutifs ou schema de reessai circulaire |
| **reflect** | A la demande : utilisez-vous l'IA comme amplificateur de pensee ? Auto-evaluation basee sur des preuves froides |
| **commit** | Generation Conventional Commits — cree automatiquement depuis git diff |
> **Note sur le budget de tokens :** Claude Code charge les descriptions de competences dans chaque contexte de session. Les 26 skills d'epic s'inscrivent dans le `skillListingBudgetFraction: 0.01` par defaut (1 %). Si vous installez des competences supplementaires (par ex. episteme, alcove, obscura), le total combine peut depasser le budget et declencher un avertissement « descriptions dropped ». Ajoutez ceci a `~/.claude/settings.json` pour corriger :
>
> ```json
> "skillListingBudgetFraction": 0.02
> ```
>
> Utilisez `0.03` si vous avez 20+ competences installees.
---
## Evolve (Ring 3)
Le harnais observe chaque appel d'outil, l'evaluate sur 3 axes, detecte les schemas d'echec et genere des competences ciblees — automatiquement, en fin de session.
### Notation
```
composite = 0.5 × tool_success + 0.3 × output_quality + 0.2 × execution_cost
```
Classification des echecs (9 types) : `type_error` · `syntax_error` · `test_fail` · `lint_fail` · `build_fail` · `permission_denied` · `timeout` · `not_found` · `runtime_error`
### Detection de schemas
| Schema | Detecte | Seuil par defaut |
|--------|---------|------------------|
| `repeated_same_error` | Meme erreur N+ fois | 3 |
| `fix_then_break` | Succes d'edition → echec de build/test | 3 en retrospective, 2 cycles |
| `long_debug_loop` | Bloque sur le meme fichier | 5 operations |
| `thrashing` | Alternance Edition↔Erreur | 3 editions, 3 erreurs |
### Flux d'evolution
```
Observe (PostToolUse — notation sur 3 axes)
↓ obs/session_{id}.jsonl
Analyze (SessionEnd)
↓ scores par outil, par extension + schemas
Propose (Solver — gradue par score : ≥0.90 ignorer, ≥0.70 modere, <0.70 complet)
↓ SkillProposal[] avec confiance
Curate (Accepter/Fusionner/Ignorer, retour masque au solveur)
↓ evolved/{skill}/SKILL.md + meta.json
Gate (verification de format, dedoublonnage, plafond 10, promotion controlee ≥ 3 sessions)
↓ evolved_backup/ (meilleur point de controle)
Instinct (schemas a fort taux de succes → noeuds memory.db inter-projets)
↓
Reload (prochaine session — resume charge les competences evoluees)
```
Seeding de competences : outil faible (succes <60 %, min 5 obs), type de fichier faible (succes <50 %, min 3 obs), erreur frequente (5+ occurrences).
Stagnation : 3 sessions sans 5 % d'amelioration → retour automatique au meilleur point de controle.
### Optimisation inspiree de SkillOpt
Trois techniques inspirees de l'apprentissage profond adaptees de [SkillOpt](https://arxiv.org/abs/2605.23904) :
| Technique | Comment ca fonctionne |
|-----------|----------------------|
| **Tampon de retour negatif** | Les propositions rejetees sont stockees avec une expiration basee sur un TTL ; les propositions futures sont verifiees par rapport au tampon avant generation |
| **Reflexion par mini-lots** | Les observations sont decomposees en lots de taille fixe pour l'extraction de schemas structurels ; reutilisable quand l'erreur dominante ≥60 % + ≥2 fichiers distincts |
| **Mise a jour lente/meta** | Une regression lineaire sur les 5 dernieres sessions classifie les epoques comme Improving / Regressing / PersistentFailure / StableSuccess ; supprime automatiquement les competences sous-performantes |
### Auto-reglage des prompts
Les competences evoluees sous-performantes recoivent des conseils de reglage cibles ajoutes apres le delimiteur ``. Le contenu original n'est jamais modifie. 3 sessions consecutives en baisse → retour automatique du reglage, historique efface.
### Efficacite des competences
Chaque competence evoluee est suivie avec une attribution A/B :
```
/evolve history → Efficacite des competences
| Competence | Avec | Sans | Delta |
|--------------------|------|-------|-------|
| evo-ts-care | 0.87 | 0.72 | +15% |
| evo-bash-discipline| 0.65 | 0.68 | -3% |
```
Delta positif = efficace. Negatif = envisager la suppression via `/evolve rollback`.
### Presets de demarrage a froid
Lors de la premiere session, des competences preset adaptees a la pile s'appliquent automatiquement :
| Pile | Presets |
|------|---------|
| Node.js/TypeScript | `evo-ts-care`, `evo-fix-build-fail` |
| Go | `evo-go-care` |
| Python | `evo-py-care` |
| Rust | `evo-rs-care` |
### Apprentissage par instinct
Les schemas a fort taux de succes sont extraits et promus entre projets :
```
observe (100 % confirme) → extract_instincts() → noeud instinct (confiance ≥ 0.8)
→ promu au niveau global quand observe dans ≥ 2 projets
```
```bash
/evolve # Executer maintenant
/evolve status # Tableau de bord : scores, tendances, schemas, competences
/evolve history # Historique complet + efficacite des competences
/evolve cross-project # Analyse de schemas inter-projets
/evolve rollback # Restaurer le meilleur precedent
/evolve reset # Effacer toutes les donnees d'evolution
```
---
## Pipeline de securite
Pipeline d'evaluation des vulnerabilites en trois etapes porte depuis [defending-code](https://github.com/anthropics/defending-code-reference-harness) :
```bash
/threat-model # 1. Frontieres de confiance, acteurs de menace, scenarios → THREAT_MODEL.md
/vuln-scan # 2. Scanner en 4 dimensions (injection, auth, exposition de donnees, deps) → VULN-FINDINGS.json
/triage # 3. Validation adversariale, ajustement de severite, chainage → TRIAGE.json
```
### Mode audit `--strict`
Pour les audits de securite, le mode `--strict` impose l'independance entre les modes d'audit :
- Les revues de code, securite et tests recoivent uniquement le diff + spec — aucun contexte du builder
- Independance croisee : les modes s'executent a l'aveugle jusqu'a la synthese
- Notation a l'aveugle pour eviter le biais d'ancrage
Contexte d'audit optionnel via `.harness/engagement.md` a la racine du projet (autorisation, portee, contraintes, exclusions). Voir `docs/references/engagement.md` pour le modele.
---
## Hooks (Ring 0)
S'executent de maniere invisible a chaque session. Binaire Rust unique (`epic-harness`) avec des sous-commandes.
| Hook | Quand | Fait |
|------|-------|------|
| **resume** | Debut de session | Restaurer le contexte, charger la memoire, detecter la pile |
| **guard** | Avant Bash | Bloquer force-push-to-main, `rm -rf /`, DROP prod |
| **polish** | Apres Edit | Formatage automatique (Biome/Prettier/ruff/gofmt) + verification de types |
| **observe** | Chaque utilisation d'outil | Journaliser vers `~/.harness/projects/{slug}/obs/` pour l'evolution |
| **snapshot** | Avant compactage | Sauvegarder l'etat vers `~/.harness/projects/{slug}/sessions/` |
| **reflect** | Fin de session | Analyser les echecs, seeding des competences evoluees, controle, extraire les instincts |
Polish alimente observe : echec de formatage → `lint_fail`, erreur TypeScript → `build_fail`. Le va-et-vient Edition→Erreur est detecte meme lorsque les erreurs proviennent de polish.
Chaque session ecrit son propre `session_{date}_{pid}_{random}.jsonl` — des sessions concurrentes multiples ne corrompront pas les donnees des autres.
### Profils de hook
Via `~/.harness/config.toml` ou la variable d'environnement `EPIC_HOOK_PROFILE` :
| Profil | Hooks actifs |
|---------|-------------|
| `minimal` | guard, observe, resume |
| `standard` (par defaut) | ci-dessus + polish, reflect, snapshot |
| `strict` | tous les hooks + controles stricts futurs |
### Regles de garde personnalisees
Ajoutez des regles specifiques au projet via `.harness/guard-rules.yaml` a la racine de votre projet :
```yaml
blocked:
- pattern: kubectl\s+delete\s+namespace | msg: Suppression de namespace bloquee
warned:
- pattern: docker\s+system\s+prune | msg: Nettoyage Docker — verifiez d'abord
```
---
## Team (`epic team`)
Les equipes sont au **niveau organisation**, pas liees a un projet. Executer `/team` dans n'importe quel projet enrichit un pool partage de definitions d'agents — ne remplace jamais silencieusement.
```bash
epic team # Interactif : scan → conception → ecriture → synchronisation
epic team sync backend # Repartir les agents → .claude/agents/backend/
epic team link backend # Repartir + enregistrer le projet dans la config d'equipe
epic team list # Toutes les equipes de l'organisation actuelle
epic team list --org netflix # Equipes dans une organisation nommee
epic team show backend --playbook # Config + playbook complet
epic team delete backend # Retirer du projet actuel uniquement
epic team delete backend --global # Supprimer definitivement du store d'organisation
```
Apres synchronisation, les agents sont disponibles dans la prochaine session : `@domain-expert`, `@reviewer`, `@tester`, etc.
| Type | Mot-cle | Agents par defaut |
|------|----------|-------------------|
| Aligne sur le flux | `stream` | domain-expert, reviewer, tester |
| Plateforme | `platform` | api-designer, infra-specialist, dx-agent |
| Facilitateur | `enabling` | specialist |
| Sous-systeme complexe | `subsystem` | domain-specialist, integration-tester |
Multi-organisation : `epic team --org netflix` — topologie separee par organisation.
Strategie de fusion : les agents modifies invitent (par defaut : conserver l'existant, sauvegarder dans `.history/`). Le playbook est toujours ajoute.
---
## Support multi-outils
Tous les outils partagent le meme repertoire de donnees `~/.harness/projects/{slug}/`.
| Outil | Hooks Ring 0 | Commandes | Competences | Agents |
|-------|-------------|-----------|-------------|--------|
| **Claude Code** | ✓ Complet | ✓ 3 commandes (incl. /orbit) | ✓ 26 competences | Live |
| **Codex CLI** | ✓ Complet¹ | ✓ 3 prompts (incl. /orbit) | ✓ 26 | — |
| **Antigravity** | ✓ Partiel² | ✓ 3 commandes (incl. /orbit) | ✓ 26 | — |
¹ `plugin_hooks = true` dans `~/.codex/config.toml` · ² PreInvocation/PostInvocation uniquement — pas de PreToolUse (guard/polish indisponible)
---
## Architecture : Modele 4-Ring
```mermaid
flowchart TB
subgraph R0["Ring 0 — Pilote automatique (hooks, invisible)"]
direction LR
h1(resume) --- h2(guard) --- h3(polish) --- h4(observe) --- h5(snapshot) --- h6(reflect)
end
subgraph R1["Ring 1 — Commandes (vous les appelez)"]
direction TB
subgraph orbit_wrap[" /orbit "]
direction LR
c1("spec") --> c2("go") --> c3("check") --> c4("ship") --> c5("evolve")
end
c6("/team")
c7("/evolve (manuel)")
end
subgraph R2["Ring 2 — Competences automatiques (declenchement contextuel)"]
direction LR
s1(spec) --- s2(go) --- s3(check) --- s4(ship) --- s5(tdd) --- s6(debug) --- s7(secure) --- s8(perf) --- s9(simplify) --- s10(verify) --- s11(audit) --- s12(eval) --- s13(threat-model) --- s14(vuln-scan) --- s15(triage)
end
subgraph R3["Ring 3 — Evolve (auto-amelioration)"]
direction LR
e1(observe) --> e2(analyze) --> e3(seed) --> e4(gate) --> e5(reload)
end
R0 -->|"observe chaque appel d'outil"| R3
R3 -.->|"competences evoluees"| R2
R1 -->|"declenchement auto des competences"| R2
R0 -->|"resume : restaurer le contexte"| R1
```
---
## Apprentissage inter-projets
Activez le partage de schemas d'echec entre projets :
```bash
touch ~/.harness/projects/{slug}/.cross-project-enabled
```
Fin de session → exporte les schemas anonymises vers `~/.harness/global_patterns.jsonl`. Debut de session → affiche des indices provenant des zones faibles d'autres projets.
---
## Memoire unifiee
Tous les agents partagent un graphe de connaissances dans `~/.harness/memory.db` (SQLite avec recherche en texte integral). Aucun runtime externe.
```
score = recence(25%) + importance(35%) + frequence_acces(15%) + correspondance_FTS(25%)
```
### CLI
```bash
epic mem recall "auth refactor" --project my-project # Rappel intelligent
epic mem add --title "JWT rotation" --type decision # Ajouter un noeud
epic mem search "JWT" # Recherche FTS5
epic mem list --type decision --project my-project # Filtrer
epic mem context --project my-project # Contexte projet
epic mem serve # Interface Web → :7700 ou port personnalise avec --port 8800
epic mem mcp-install # Enregistrer le serveur MCP
epic mem export --out ./docs/memory # Exporter en Markdown
```
### Outils MCP (6)
| Outil | Objectif |
|-------|----------|
| `mem_recall` | Rappel contextuel intelligent avec indice + projet + voisins du graphe |
| `mem_add` | Ajouter un noeud avec auto-importance par type (ou explicite 0.0–1.0) |
| `mem_search` | Recherche par mot-cle (texte integral), classe par importance |
| `mem_query` | Filtrer par tag/type/projet |
| `mem_context` | Rappel contextuel intelligent par projet (sans indice) |
| `mem_related` | Traversee de graphe depuis un ID de noeud (trouve les connaissances connectees) |
### Types de noeuds
| Type | Cree par | Importance |
|------|----------|------------|
| `decision` | Manuel / MCP | 0.9 |
| `resolution` | Manuel / MCP | 0.8 |
| `concept` | Manuel / MCP | 0.7 |
| `project` | Manuel / MCP | 0.7 |
| `instinct` | Auto (reflect) | 0.7 |
| `pattern` | Auto (reflect) | 0.5 |
| `error` | Auto (reflect) | 0.4 |
| `session` | Auto (reflect) | 0.2 |
Cycle de vie : 30+ jours sans acces → 10 % de decroissance d'importance (plancher 0.05). 180+ jours → etiquete `stale`, exclu du rappel. Le tag `pinned` empeche la decroissance.
---
Donnees projet — structure des repertoires
## Donnees projet
Toutes les donnees se trouvent dans `~/.harness/` (repertoire personnel), pas dans la racine de votre projet. Survit a la suppression du projet, ne pollue pas l'historique git.
```
~/.harness/
├── memory.db # Graphe de connaissances SQLite (noeuds + aretes + FTS5)
├── graph.json # Graphe en cache (pour l'interface Web)
├── config.toml # Configuration utilisateur
├── global_patterns.jsonl # Modeles inter-projets (opt-in)
├── orgs/ # Store global des equipes
│ └── {org}/teams/{team}/
│ ├── config.json, mission.md, playbook.md, agents/, .history/
└── projects/{slug}/
├── memory/ # Modeles et regles du projet
├── sessions/ # Instantanes de session (pour resume)
├── obs/ # Journaux d'observation d'utilisation des outils (JSONL)
├── evolved/ # Competences auto-evoluees
│ ├── manifest.json
│ └── {skill}/SKILL.md + meta.json
├── evolved_backup/ # Meilleur point de controle (pour retour en arriere)
├── dispatch/ # Journaux de repartition des competences
├── evolution.jsonl # Historique complet d'evolution
└── metrics.json # Statistiques agregees + attribution des competences
```
Partagez les regles de securite avec votre equipe : `.harness/guard-rules.yaml` a la racine du projet (commite dans git).
---
Configuration — reference config.toml
## Configuration
Tous les parametres ajustables dans `~/.harness/config.toml`. Absent = valeurs par defaut en dur.
```toml
# Priorite : variable d'env (EPIC_HOOK_PROFILE) > ce fichier > valeurs par defaut
[hook]
profile = "standard" # "minimal" | "standard" | "strict"
gateguard_hints = true
[scoring]
weights = [0.5, 0.3, 0.2] # [succes, qualite, cout]
[evolution]
max_skills = 10
stagnation_limit = 3
improvement_threshold = 0.05
gated_promotion_min = 3
[pattern]
# repeated_error_min = 3
# debug_loop_min = 5
# graduated_scope_skip = 0.90
# graduated_scope_moderate = 0.70
[instinct]
# confidence_threshold = 0.8
# promotion_min_projects = 2
# max_instincts = 20
# min_observations = 10
# min_avg_score = 0.5
```
---
## Problemes connus (Jugement de l'agent)
Ces problemes decoulent de l'interpretation du contexte par l'agent plutot que de bogues dans le code. Liste ici pour que les utilisateurs sachent a quoi faire attention.
### Problemes detectes
| Probleme | Quand | Ce qui se passe | Contournement |
|----------|-------|-----------------|---------------|
| **Contournement d'auto-modification orbit** | `/orbit` est demande pour ameliorer orbit lui-meme | L'agent peut contourner entierement le pipeline orbit et modifier les fichiers de maniere ad-hoc sur main, laissant des modifications non commitees sans spec/PR/traçabilite | Apres la completion d'orbit, verifiez `git status`. Si des modifications sont sur main sans etat de pipeline, commitez manuellement ou relancez `/orbit` depuis une branche separee |
| **Tache doc-only saute le protocole** | `/orbit` recoit une modification markdown uniquement (pas de code a tester) | L'agent peut juger les phases TDD/test comme depourvues de sens et sauter le pipeline complet | Acceptable pour les modifications purement documentaires. Pour les modifications mixtes code+doc, assurez-vous que l'agent ne saute pas les phases liees au code |
| **Mauvaise classification de mode** | La demande est a la limite entre Direct et Council | L'agent peut choisir Direct quand Council (4 voix) attraperait plus de cas limites, ou Council quand Direct suffit | Si l'agent choisit un mode qui semble inapproprie, dites explicitement « utilisez le mode Council » ou « utilisez le mode Direct » |
### Choix de conception intentionnels
Ceux-ci ont ete envisages pour amelioration mais maintenus tels quels apres evaluation :
| Choix | Pourquoi non ameliore | Justification |
|-------|----------------------|---------------|
| **Worktree entre en phase Go, pas au debut d'orbit** | Pourrait isoler des la pre-vol | La pre-vol/mode/spec sont en lecture seule. Isoler plus tot ajoute de la complexite sans benefice — la branche n'est pas creee avant la phase Go de toute facon |
| **Worktree preserve apres Ship** | Pourrait supprimer automatiquement a la fusion de la PR | La branche est la tete de la PR. La supprimer avant la fusion casse la PR. Le nettoyage est laisse a l'utilisateur apres la fusion |
| **Branche nommee `orbit-{slug}` et non `feature/{slug}`** | Pourrait correspondre a la nomenclature conventionnelle des branches | `EnterWorktree` n'autorise pas `/` dans les noms. Renommer apres creation ajoute une etape pour un benefice uniquement cosmetique |
| **Pas de chemin de pipeline leger pour les modifications de doc** | Pourrait detecter doc-only et sauter TDD/tests | La detection est fragile (qu'est-ce qui compte comme « doc » ?). Ajouter un chemin separe augmente la complexite du protocole pour un gain marginal |
---
## Depannage
command not found : epic apres l'installation
Ajoutez le repertoire binaire Cargo a votre PATH :
```bash
export PATH="$HOME/.cargo/bin:$PATH"
```
Ajoutez cette ligne a votre `~/.zshrc` ou `~/.bashrc` pour la rendre permanente.
Les hooks ne se declenchent pas dans Claude Code
Réinstallez le plugin pour recharger les hooks :
```
/plugin install epic@epicsagas
```
Puis redémarrez Claude Code. Les hooks sont chargés depuis le `hooks.json` du plugin.
Permission denied sur macOS (Gatekeeper)
macOS peut bloquer les binaires non signes telecharges depuis Internet :
```bash
xattr -d com.apple.quarantine ~/.cargo/bin/epic-harness
xattr -d com.apple.quarantine ~/.cargo/bin/epic
```
epic : binaire introuvable dans les hooks du plugin
Le plugin cherche d'abord le binaire dans `hooks/bin/epic-harness`. Apres une mise a jour via `cargo install`, copiez-le :
```bash
cp ~/.cargo/bin/epic-harness hooks/bin/epic-harness
```
---
## Developpement
```bash
cargo install --path . # Compilation + installation
cp ~/.cargo/bin/epic-harness hooks/bin/epic-harness # Mettre a jour le binaire du plugin
cargo test # Tests
```
Les hooks cherchent le binaire a deux endroits : `hooks/bin/epic-harness` (local au plugin) → `~/.cargo/bin/epic-harness` (PATH).
---
## Liens
- [Journal des modifications](../../CHANGELOG.md) — historique des versions
- [Contribuer](../../CONTRIBUTING.md) — comment contribuer
- [Securite](../../SECURITY.md) — signaler des vulnerabilites
- [Issues](https://github.com/epicsagas/epic-harness/issues) — rapports de bogues et demandes de fonctionnalites
## Remerciements
- [a-evolve](https://github.com/A-EVO-Lab/a-evolve) — Evolution automatisee et schemas de benchmark
- [agent-skills](https://github.com/addyosmani/agent-skills) — Systeme de competences d'agent Claude Code
- [everything-claude-code](https://github.com/affaan-m/everything-claude-code) — Patterns complets Claude Code
- [gstack](https://github.com/garrytan/gstack) — Reference d'architecture de plugin
- [harness](https://github.com/revfactory/harness) — Patterns d'infrastructure de hook et de harnais
- [serena](https://github.com/oraios/serena) — Conception d'agent autonome
- [SuperClaude Framework](https://github.com/SuperClaude-Org/SuperClaude_Framework) — Architecture de framework multi-commandes
- [superpowers](https://github.com/obra/superpowers) — Patterns d'extension Claude Code
## Licence
[Apache 2.0](../../LICENSE)