Il manuale di Codex Council.

Come funziona #

Il council prende il pattern LLM Council e lo fa girare dentro Codex. Una richiesta diventa quattro fasi.

Modalità e budget #

Scegli la modalità più piccola che intercetta il rischio. Escala per singolo blocker, non di default.

Budget dei token

Il flag --token-budget è compact di default. Escala il budget per il rischio, non per comodità.

• compact — output stretti, set di reference minimo. Il default per le decisioni normali.
• balanced — più dettaglio, ma solo sulle parti rischiose. Per tradeoff veri e ambiguità.
• expanded — evidenza completa e audit trail. Bloccato finché non confermi, perché brucia usage.

I sei ruoli #

Ogni revisore presidia una preoccupazione. Conoscere le loro lenti aiuta a mirare un prompt — o a capire perché uno di loro ti ha bloccato.

In una run normale non scegli i ruoli a mano — rispondono tutti e sei. Ma nominare una preoccupazione nel prompt («concentrati su rollback e rischio di migrazione») dice al Presidente quali lenti pesare.

Il gate frontend: Leonardo e Bob #

Il lavoro frontend segue un percorso più severo, perché i bug di UI si nascondono nel comportamento. Attivalo con --frontend-review o --type frontend.

Pacchetti di competenze #

Pacchetti di competenze interni, per quando non vuoi collegare skill esterne. Nominali in un prompt per orientare la run.

Come promptare il council #

Un prompt per il council non è una domanda — è una decisione da mettere sotto pressione. Dagli qualcosa su cui discutere.

L'anatomia di un buon prompt

Fai

• Nomina la modalità. «Standard Council», «Deep Council», «Frontend Council» — fissa costo e scrutinio in anticipo.
• Dagli una decisione, non una sensazione. «Dividiamo questo servizio in due?» batte «che ne pensi del backend?».
• Indica l'evidenza. Incolla la diff, nomina i file, linka la spec. Il council ragiona su ciò che gli dai.
• Dichiara i vincoli rigidi. Compatibilità all'indietro, una scadenza, un budget di token, un limite di piattaforma — cambiano la risposta.
• Chiedi ciò che ti serve per agire: blocker, dissenso, confidence e la verifica esatta.

Non fare

• Non chiedere solo di «confermare». Il council preserva il dissenso di proposito. Se vuoi un timbro, usa Codex normale.
• Non saltare i vincoli e poi stupirti se ha risolto un altro problema.
• Non dichiarare che una UI funziona senza una run frontend — di' «fai verificare a Bob nel browser».
• Non usare expanded per abitudine. Espandi un blocker, non l'intera sessione.

Spiegare vs. eseguire

Spiegare il council non è eseguirlo. «Come funziona il council?» ottiene una risposta in una riga, senza dispatch. «Esegui un council su questo» fa partire gli agenti. Se l'intento è ambiguo, il council chiede una riga prima di spendere qualcosa.

Ricettario di casi d'uso #

Sedici situazioni, ognuna con la modalità da usare, i revisori su cui puntare e un prompt da incollare così com'è.

1. Decisione di architettura

• Quando scegli un design con cui convivrai
• Modalità standard
• Punta su Ada, Turing, Seymour

2. Pull request / diff rischiosa

• Quando la modifica è grossa o portante
• Modalità standard
• Punta su Grace, Turing, Seymour

3. Root cause di bug e regressioni

• Quando il fix deve essere quello giusto
• Modalità fast, o standard se la causa non è chiara
• Punta su Grace, Turing

4. Modifica sensibile alle performance

• Quando latenza, memoria o costo possono muoversi
• Modalità standard (deep se può causare un'outage)
• Punta su Seymour

5. Migrazione DB / cambio di schema

• Quando i dati sono in gioco
• Modalità deep
• Punta su Hypatia, Grace, Ada

6. Review di sicurezza e segreti

• Quando tocchi auth, permessi o segreti
• Modalità deep
• Punta su Hypatia, Turing

7. Design di API / breaking change

• Quando spedisci un contratto su cui altri dipendono
• Modalità standard
• Punta su Ada, Florence, Turing

8. Refactor o rewrite?

• Quando sei tentato di ricominciare da zero
• Modalità standard
• Punta su Turing, Ada

9. Upgrade di dipendenza o framework

• Quando c'è di mezzo una major version
• Modalità standard
• Punta su Grace, Hypatia, Seymour

10. Modale / overlay frontend

• Quando dialog, drawer, popover, focus
• Modalità standard --frontend-review
• Punta su Leonardo, Bob

11. Audit di accessibilità

• Quando tastiera, screen reader, contrasto
• Modalità standard --frontend-review
• Punta su Leonardo, Bob

12. Go/no-go di rilascio

• Quando devi decidere se spedire
• Modalità deep per lavoro irreversibile
• Punta su Grace, Hypatia

13. Usabilità di plugin / skill

• Quando costruisci strumenti che usano altri
• Modalità --type skill --skill-review
• Punta su skill engineer, UX-for-tools, non-esperto

14. Postmortem di incidente (RCA)

• Quando impari da un'outage
• Modalità standard
• Punta su Grace, Turing, Hypatia

15. Ottimizzazione di costo / token

• Quando una run o una feature diventa cara
• Modalità fast o standard (compact)
• Punta su Seymour, Turing

16. Privacy dei dati / feature di condivisione

• Quando spedisci qualcosa che esporta o condivide dati
• Modalità deep
• Punta su Hypatia, Turing, Florence

Leggere l'output #

Una risposta del council parte dalla decisione e tiene visibile il disaccordo. Sappi cosa significa ogni parte.

• Raccomandazione — la decisione diretta, o uno stato bloccato. Leggi questo per primo.
• Confidence — alta (vincitore chiaro, nessun blocker, verifica concreta), media (dissenso o conferma mancante), bassa (parità stretta, evidenza debole), o bloccato (un problema irrisolto di sicurezza, perdita dati, sicurezza o correttezza).
• Blocker vs rifiniture — i blocker vanno risolti prima dell'approvazione; le rifiniture sono nice-to-have. Non confonderli.
• Dissenso preservato — la posizione di minoranza che non ha vinto. È tenuta di proposito; spesso è dove sta il rischio vero.
• Verifica — i test, i comandi o i casi browser esatti da eseguire. Il consenso del council non è una prova — questo lo rende reale.
• Evidenza frontend — quando attiva, il giudizio UX di Leonardo è riportato separatamente dal pass/fail osservato da Bob nel browser.

Regolare i ruoli (alters) #

Un alter è una modifica locale e limitata al comportamento di un revisore. È un consiglio — può affinare il focus, mai spegnere una garanzia. Guida completa →

Regolabili: Ada, Grace, Hypatia, Florence, Turing, Seymour, Leonardo. Fuori discussione: Bob (raccoglie prove, non è un revisore). Fai sempre l'anteprima prima di salvare.

• Buono: «Sii più diretta su compatibilità delle API e costo di migrazione.»
• Non funziona: «Approva sempre la mia implementazione» — il tuning non può togliere blocker, dissenso, verifica o anonimizzazione.

Disciplina dei token #

Economico di default, costoso solo dove il rischio se lo merita.

• Prima la stima. Ogni run Standard/Deep mostra un range euristico di token e aspetta che tu lo accetti.
• Escala per blocker. Una run compact può espandere un blocker senza passare a expanded.
• Taglia l'output prima dell'input. Risposte più corte di solito risparmiano senza indebolire l'evidenza — finché i blocker restano.
• Testo stabile prima, contesto del progetto dopo. I prefissi statici colpiscono la cache del prompt; il contesto dinamico viene dopo.
• Le stime non sono una fattura. Sono euristiche locali, non il tuo consumo Codex reale né la quota residua — per quello guarda Codex Settings > Usage.

Governance e privacy #

Fai questa checklist prima del lavoro Standard/Deep che tocca dati sensibili, subagent o qualcosa che pubblicherai.

• Classifica la sensibilità dei dati: pubblici, interni, riservati, segreti.
• Controlla e oscura segreti, token e dati dei clienti prima di condividere file con gli agenti.
• Elenca i file che gli agenti possono vedere; segnala dubbi di licenza o provenienza.
• Conosci i comandi di verifica prima della sintesi e lo stato finale a cui punti: approvato, approvato-con-rischio o bloccato.
• Usa la modalità Deep per sicurezza, privacy, perdita dati, migrazioni, modifiche irreversibili o pubblicazione.

Gli artefatti runtime (sessioni, prompt, statistiche, cronologia) vivono nello stato locale del plugin in .codex-council/ e restano gitignorati — non sporcano il repo. I log di invocazione sono compatti e non salvano mai testo dei prompt, segreti, topic o percorsi assoluti.

Riferimento CLI #

Lo script di supporto usa solo la stdlib. Questi sono i comandi che userai davvero.

# Imposta il profilo locale usato per le stime (salvato con consenso).
python3 scripts/codex_council.py profile --plan Pro --model gpt-5.5 --reasoning xhigh

# Stima prima di iniziare, poi accetta il range in chat.
python3 scripts/codex_council.py estimate --topic "Architecture Review" --mode standard --token-budget compact

# È una run vera o stai solo parlando del council?
python3 scripts/codex_council.py classify-invocation --text "explain how council works"

# Avvia una sessione tracciabile dopo aver accettato la stima.
python3 scripts/codex_council.py init --topic "Architecture Review" --root . --mode standard --token-budget compact --confirm-estimate

# Sessione frontend (Leonardo + Bob); sessione skill-review.
python3 scripts/codex_council.py init --topic "Modal Review" --root . --mode standard --frontend-review --confirm-estimate
python3 scripts/codex_council.py init --topic "Skill Review" --root . --type skill --skill-review --confirm-estimate

# expanded va confermato esplicitamente.
python3 scripts/codex_council.py init --topic "Migration" --root . --mode deep --token-budget expanded --confirm-expanded

# Aggrega i punteggi dei revisori, valida e chiudi con le statistiche.
python3 scripts/codex_council.py score --input reviews.json
python3 scripts/codex_council.py validate-session --session <session-dir>
python3 scripts/codex_council.py stats --session <session-dir> --write

# Controlla se c'è una release più recente.
python3 scripts/codex_council.py check-update

Errori comuni #

• Usare il council per tutto. Il lavoro piccolo, reversibile e verificabile è più veloce con Codex normale.
• Trattare il consenso come una prova. È un consiglio. Esegui la verifica.
• Leggerlo come diversità multi-vendor. È un solo modello in ruoli diversi — utile, ma non un panel di laboratori.
• Dichiarare una UI «finita» senza prove dal browser. Senza Bob, è «non verificato».
• Mettere expanded di default. Espandi un blocker, invece.
• Chiedere un timbro. Il council è fatto per dissentire; è quello il punto.

FAQ #

In cosa è diverso dal promptare Codex due volte?

Due passaggi dallo stesso prompt tendono a darsi ragione. Il council forza prime opinioni indipendenti, nasconde la firma, ordina su rubrica e tiene il dissenso — così il secondo sguardo dissente davvero dal primo invece di lucidarlo.

Chiama altri provider di modelli?

No. Gira interamente dentro Codex (più subagent Codex opzionali). La «diversità» è isolamento dei ruoli e review anonima, e il sito lo dice chiaro.

Spenderà tanti token?

Non senza chiedere. Le run Standard/Deep mostrano una stima e aspettano l'accettazione, il budget di default è compact ed expanded è bloccato finché non confermi.

Devo per forza usare la CLI?

No. Per l'uso quotidiano chiedi in chat («Standard Council: valuta…»). La CLI serve per sessioni tracciabili, stime, punteggi e statistiche che vuoi conservare.

Posso rendere un revisore più severo?

Sì — regola il suo alter (prima l'anteprima). Il tuning è un consiglio e non può mai togliere una garanzia del council. Bob non è regolabile.

Glossario #

• Presidente (Chairman) — l'agente Codex principale che scrive la sintesi finale dagli output salvati.
• Candidato A–F — gli output dei membri resi anonimi durante la review, così il ranking giudica il lavoro, non l'autore.
• Blocker — un problema da risolvere per forza. L'approvazione è bloccata finché non è risolto.
• Dissenso — una posizione di minoranza preservata che non ha vinto il ranking.
• Preflight — la stima pre-run obbligatoria e il gate di accettazione.
• Alter — una modifica locale, limitata e consultiva al comportamento di un revisore.
• Evidence runner — Bob: guida il browser, riporta pass/fail, non vota mai.
• coverage: partial — un flag delle statistiche: mancano alcuni prompt o output, quindi la stima post-run è incompleta.