Harmonist

Orchestrazione portatile di agenti AI con applicazione meccanica dei protocolli

Un framework multi-agente "drop-in" per Cursor, Claude Code, Copilot, Windsurf, Aider e altri assistenti di codifica AI.

Costruito e mantenuto da GammaLab · @GammaLabTechnologies

La maggior parte dei framework di codifica AI si fida del modello linguistico per seguire le regole. Harmonist si rifiuta di lasciarlo saltarle. Ogni modifica del codice è controllata da hook che verificano se i revisori richiesti sono intervenuti, se la memoria è stata aggiornata e se l'integrità della supply chain di ogni file spedito è intatta. Se i controlli falliscono, il "turno" non si completa — non importa quanto fiducioso il modello affermi di aver finito.

Questo è il primo framework di agenti open-source in cui l'applicazione del protocollo è un gate meccanico, non una cortese richiesta in un prompt.

Introduzione

Perché esiste Harmonist

Gli assistenti di codifica AI hanno un problema strutturale che la sola ingegneria del prompt non può risolvere.

Il problema: ogni serio flusso di lavoro ingegneristico ha regole non negoziabili — "nessun numero in virgola mobile per il denaro", "eseguire il QA prima di unire", "ogni chiamata esterna tenta di nuovo con chiavi di idempotenza", "revisione della sicurezza prima di toccare il codice di autenticazione". Si può dire a un LLM di seguirle, ma non esiste un meccanismo che lo forzi a farlo. Può accettare, proseguire e saltare silenziosamente il passaggio. In una buona giornata lo si nota. In una brutta giornata il bug viene rilasciato.

Il panorama attuale è diviso tra due risposte imperfette:

• Framework di agenti "leggeri" (LangChain, CrewAI, AutoGen, MetaGPT e molti altri) forniscono primitive di orchestrazione ma lasciano l'applicazione del protocollo al prompt. Il modello può sempre ignorare il proprio protocollo.
• Piattaforme enterprise "pesanti" promettono governance attraverso runtime separati, database e vendor lock-in — ma richiedono infrastrutture da installare, non funzionano sul laptop di un singolo sviluppatore e non possono essere verificate file per file.

Harmonist assume una posizione diversa. L'applicazione del protocollo è implementata come hook a livello di IDE — script shell e Python concreti che osservano ogni dispatch di sotto-agenti, ogni modifica di file, ogni interruzione di sessione. Quando le regole dichiarate dal progetto non vengono rispettate, l'hook stop restituisce un followup_message all'AI e si rifiuta di consentire il completamento del turno. Il modello non può discuterci; è una macchina a stati su disco.

Nessun runtime. Nessun database. Nessun vendor lock-in. Solo markdown, Python stdlib e bash — accanto al tuo codice, che svolgono un compito correttamente.

Caratteristiche

Sette proprietà concrete e verificabili — ognuna risolve una lacuna che altri framework di agenti open-source lasciano aperta.

1. Applicazione meccanica del protocollo tramite hook IDE

L'hook stop in .cursor/hooks/ analizza i marcatori di dispatch dei sotto-agenti dalla sessione, verifica se qa-verifier è stato eseguito, se un revisore richiesto era mancante, se session-handoff.md è stato aggiornato, e restituisce un followup_message strutturato se il turno è incompleto. loop_limit: 3 limita i tentativi. All'esaurimento, un incidente viene registrato e segnalato nella sessione successiva. L'AI non può letteralmente rilasciare una modifica del codice che ha saltato la revisione.

2. Verifica della supply-chain delle definizioni degli agenti

Ogni file spedito è hashato in MANIFEST.sha256. upgrade.py verifica l'hash di ogni sorgente prima di copiarlo in un progetto. Un security-reviewer.md manomesso (ad esempio, uno che restituisce approve per tutto) viene RIFIUTATO — non entra mai nel progetto. install_extras.py eredita la stessa protezione per installazioni specialistiche on-demand. Questo è il primo catalogo di agenti OSS con una postura di supply-chain di livello paranoico.

3. ID di correlazione della memoria che l'LLM non può falsificare

Ogni voce di memoria ha un correlation_id del tipo <session_id>-<task_seq> generato dagli hook all'inizio della sessione (<unix-seconds><pid4> — a prova di collisione tra sessioni parallele). L'LLM legge l'ID attivo tramite CLI; non scrive mai l'ID stesso. Ciò significa che il collegamento tra una voce state, una decision e un pattern dalla stessa attività è criptograficamente ordinato dal punto di vista dell'hook — non affidato al modello.

4. Memoria validata da schema con scansione di pattern segreti

memory.py append è l'unico percorso di scrittura supportato. Valida ogni voce rispetto a uno schema YAML (memory/SCHEMA.md), rifiuta i duplicati e scansiona il corpo per circa 30 classi di segreti: chiavi di accesso AWS, PAT GitHub, token Stripe, webhook Slack, account di servizio GCP, stringhe di connessione Azure, token bot Telegram, token Discord, UUID Heroku/Postmark (ambito contestuale), token generici ad alta entropia con prefissi secret:, e stringhe di connessione DB con credenziali incorporate. I segnaposto (${VAR}, <NAME>) sopprimono la scansione in modo che i tuoi template scrivano ancora in modo pulito.

5. 186 specialisti di dominio curati, non un generico "coder"

Il catalogo di Harmonist non è una manciata di ruoli. Sono 186 specialisti curati distribuiti in 16 categorie: revisore di sicurezza blockchain per audit Solidity, zk-steward per circuiti a conoscenza zero, visionos-spatial-engineer per Apple Vision Pro, wechat-mini-program-developer e xiaohongshu-specialist per il mercato cinese, laravel-livewire-specialist per PHP, roblox-systems-scripter per Roblox Luau, oltre 30 agenti di marketing dal SEO a Douyin, copertura finanza / vendite / prodotto / supporto / accademico. L'orchestratore seleziona per domains × roles × tags, non per liste di slug hardcoded.

6. Integrazione-come-prompt

Non esiste un binario di installazione. L'integrazione avviene incollando integration-prompt.md in una sessione in modalità Agente di Cursor. L'AI legge il prompt, analizza il progetto, chiede all'utente quali roles saranno attivi (ingegneria / design / prodotto / marketing / vendite / supporto / finanza / testing / accademico), seleziona gli specialisti giusti da agents/index.json e configura tutto — inclusa la scrittura di un AGENTS.md specifico per il progetto con invarianti adattati al dominio. L'AI si integra da sola.

7. Zero dipendenze runtime, parità cross-platform

Nessun npm, nessun Docker, nessun LangChain, nessun database vettoriale. Solo Python stdlib + bash. Il runtime di enforcement ha due implementazioni — script POSIX .sh per macOS / Linux / WSL, e un puro Python hook_runner.py per Windows nativo — ed entrambi i percorsi sono testati rispetto a scenari di test identici. Più di 430 asserzioni di test in CI li mantengono compatibili bit per bit.

Requisiti

Installazione

Opzione 1 — Integra tramite Cursor (raccomandato)

# 1. Clona nella root del tuo progetto
cd il-tuo-progetto/
git clone https://github.com/GammaLabTechnologies/harmonist.git

# 2. Apri il progetto in Cursor, passa alla modalità Agente
# 3. Incolla il contenuto di harmonist/integration-prompt.md
# 4. Segui il walkthrough dell'AI — chiederà il dominio e i ruoli
#    del tuo progetto, quindi configurerà tutto.
# 5. Avvia una NUOVA chat quando l'integrazione è completata.

Questo è tutto. L'AI legge harmonist/agents/index.json, sceglie gli specialisti giusti per il tuo stack, scrive un AGENTS.md specifico del dominio, bootstrappa .cursor/memory/, installa gli hook di enforcement e registra lo stato di integrazione in .cursor/pack-version.json.

Opzione 2 — Integra tramite CLI (non è necessario Cursor)

cd il-tuo-progetto/
git clone https://github.com/GammaLabTechnologies/harmonist.git
python3 harmonist/agents/scripts/integrate.py --pack harmonist --project .

Opzione 3 — Integrazione manuale

Consulta GUIDE_EN.md per il percorso manuale passo-passo.

Architettura

                     ┌────────────────────────────┐
                     │        AGENTS.md           │
                     │      Orchestrator          │
                     │                            │
                     │  Protocollo · Fasi Hook    │
                     │  Invarianti · Memoria      │
                     └─────────────┬──────────────┘
                                   │  legge
                                   ▼
                     ┌────────────────────────────┐
                     │   agents/index.json        │   ← generato
                     │                            │
                     │   per categoria · per tag  │   ← tabella di routing
                     │   186 voci                 │
                     └─────────────┬──────────────┘
                                   │  instrada a
            ┌──────────────────────┼──────────────────────┐
            ▼                      ▼                      ▼
     ┌──────────────┐      ┌──────────────┐      ┌──────────────┐
     │ orchestrazione│      │   revisione  │      │   persona    │
     │ (scout,      │      │ (strict,     │      │ (ingegneria, │
     │  repo-map)   │      │  sola lettura)│      │  design, …)  │
     └──────────────┘      └──────────────┘      └──────────────┘
                                   │                      │
            ┌──────────────────────┴──────────────────────┐
            ▼                                             ▼
     ┌──────────────┐                             ┌──────────────┐
     │ Gate di revisione│                             │   .cursor/   │
     │              │                             │   memory/    │
     │ qa · sec     │                             │              │
     │ sre · perf   │                             │ sessione     │
     │ regressione   │                             │ decisioni    │
     └──────────────┘                             │ pattern      │
                                                  └──────────────┘

Come funziona

1. Pool unificato singolo. Ogni agente vive in agents/<category>/<slug>.md con lo stesso Schema v2 frontmatter. Uno schema, un catalogo.
2. Routing basato sui dati. L'orchestratore non codifica mai slug. Estrae i tag delle attività ("payments", "react", "solidity"), interseca con agents/index.json, filtra per i domains e roles dichiarati dal progetto e sceglie lo specialista giusto.
3. Livelli di protocollo per metadati. Gli agenti con protocol: strict (orchestrazione + revisione) sono gate obbligatori che vengono eseguiti su trigger. Gli agenti con protocol: persona sono specialisti a forma libera con profondità di dominio.
4. Esecuzione osservata dagli hook. Gli hook sessionStart, afterFileEdit, subagentStart, subagentStop e stop tracciano l'intero ciclo di vita. L'hook stop è il gate.
5. Memoria persistente. Tra le sessioni, stato / decisioni / pattern vivono sotto .cursor/memory/, collegati da ID di correlazione. La sessione successiva legge le ultime tre istantanee di stato e tre decisioni prima della pianificazione.

Il catalogo di 186 agenti

Ogni conteggio seguente è un mirror di agents/index.json e verificato da check_pack_health.py — la tabella e l'indice non possono divergere.