01
Contratti tra agenti
Un manifest, un insieme di ruoli e un file per ogni task definiscono chi fa cosa, dove può scrivere e quando deve fermarsi.
- Il manifest elenca lo stack, la proprietà delle sorgenti, i ruoli, i task e i gate in un unico posto.
- Ogni task indica i percorsi consentiti, i suoi comandi e le condizioni che fermano l’esecuzione.
- Un controllo valida il manifest, i ruoli, i task e le regole di marca prima che il lavoro inizi.
npm run agent:checknpm run agent:context
diagramma di architettura: agents. Nodi: ingress, router, planner, executor, state, audit. Flusso: da ingress a router (primario); da router a executor (primario); da executor a state (primario); da router a planner (di supporto); da planner a state (di supporto); da executor a audit (feedback).
02
Copy e tono di voce
Il linting deterministico mantiene la scrittura nella mia voce; un passaggio opzionale di modello rende più naturali le bozze, e sono i gate a decidere cosa resta.
- Il controllo del copy applica regole a pattern singolo più un audit anti-slop pesato sulla densità, in inglese e italiano.
- Un passaggio di fix applica le sostituzioni sicure e deterministiche senza toccare il significato.
- Una revisione AI lascia che un modello proponga riscritture; copy-lint, frontmatter e parità scelgono se tenerle.
npm run copy:checknpm run copy:ai-review -- --changed --write
diagramma di architettura: tools. Nodi: agent, policy, MCP, adapter, tool, audit. Flusso: da agent a MCP (primario); da MCP a adapter (primario); da adapter a tool (primario); da agent a policy (di supporto); da policy a adapter (di supporto); da tool a audit (feedback).
03
Loop di automazione completa
Job GitHub Actions schedulati aggiornano i contenuti, abbozzano articoli e propongono cambi SEO. Aprono pull request — mai commit diretti su main.
- Il refresh settimanale traduce gli articoli mancanti, riempie le chiavi UI in italiano, genera FAQ e takeaway ancorati al testo, umanizza le bozze, rigenera i feed e controlla la salute dei contenuti sul sito buildato.
- I loop mensili abbozzano un articolo ancorato dietro gate di originalità e un giudice consultivo, e trasformano la domanda da Search Console in proposte SEO e brief sui temi mancanti.
- Un loop showcase propone schede progetto da repository pubblici e ne unisce una solo con tutti i gate verdi; il rescue CI tenta fix sulle issue ci-failure con Codex e non unisce mai il proprio lavoro.
- L’automazione pusha con un token GitHub App così Flash CI gira sulla PR; le esecuzioni sporche ricevono needs-human, e ogni PR di automazione porta needs-translation-review.
npm run content:mapnpm run copy:ai-review:full -- --writenpm run article:judge
diagramma di architettura: workflow. Nodi: start, branch, retry, gate, commit, checkpoint. Flusso: da start a branch (primario); da branch a gate (primario); da gate a commit (primario); da branch a retry (di supporto); da retry a branch (loop); da gate a checkpoint (feedback).
04
Pipeline di pubblicazione
Le release software archiviate vivono in un repository separato. Il sito consuma i DOI concetto Zenodo tramite un registry, uno script di sync e un gate di deriva — mai aggiornati in automatico in build.
- Il repository software pubblica una release GitHub, riserva un nuovo DOI versione Zenodo e sincronizza CITATION.cff da release.toml.
- publications.json è il registry del sito: DOI concetto per il copy pubblico, DOI versione e publishedVersion per i controlli di deriva.
- publication:sync aggiorna il registry da Zenodo e GitHub, propaga i DOI concetto nel catalogo e nel copy dei progetti, e rigenera il JSON-LD della landing.
- publication:check blocca la CI quando github-stats, i file consumer o i metadati Zenodo divergono; una persona revisiona la PR prima del merge.
npm run publication:syncnpm run publication:check
diagramma di architettura: memory. Nodi: event, encode, episodic, semantic, recall, compress. Flusso: da event a encode (primario); da encode a semantic (primario); da semantic a recall (primario); da encode a episodic (di supporto); da episodic a recall (di supporto); da recall a compress (feedback).
05
SEO e GEO
La sitemap, l’indice llms.txt e i dati strutturati derivano tutti da un’unica tabella di route, così la superficie leggibile dalle macchine non si discosta mai dal sito.
- Le route statiche vivono in un’unica lista condivisa che alimenta sia la sitemap sia l’indice llms.txt.
- Ogni pagina porta con sé JSON-LD: una persona, la traccia di breadcrumb e un tipo adatto alla pagina.
- Un loop su Search Console e un report sui temi mancanti mi indicano cosa scrivere dopo; una baseline GEO manuale traccia menzioni e citazioni nelle risposte AI.
npm run seo:checknpm run topic:gap
diagramma di architettura: retrieval. Nodi: docs, chunks, vector, lexical, rerank, eval. Flusso: da docs a chunks (primario); da chunks a vector (primario); da vector a rerank (primario); da chunks a lexical (di supporto); da lexical a rerank (di supporto); da rerank a eval (feedback).
06
Gate di qualità
Un comando esegue l’intero gate pre-merge: tipi, lint, formato, test, salute dei contenuti, parità e deriva dell’output generato.
- Il controllo di qualità è l’equivalente locale del gate che la CI esegue a ogni modifica.
- I file generati vengono rigenerati e confrontati, così l’output vecchio blocca la build invece di passare inosservato.
- Un controllo di governance protegge la documentazione pubblica da affermazioni che non faccio più.
npm run quality:check
diagramma di architettura: evals. Nodi: trace, cases, score, regress, report, fix. Flusso: da trace a cases (primario); da cases a score (primario); da score a report (primario); da score a regress (feedback); da regress a fix (di supporto); da fix a trace (loop).
07
Build deterministica
La build di produzione è pura: pre-renderizza ogni route, scrive mirror markdown per lettori e modelli, e non chiama alcun modello esterno.
- Vite costruisce l’app, poi un passaggio di prerender scrive HTML statico per ogni route localizzata.
- I mirror markdown di ogni articolo vengono pubblicati accanto all’HTML per i lettori automatici.
- Il container serve il risultato; niente su questo percorso dipende da una chiave API.
npm run build
diagramma di architettura: memory. Nodi: event, encode, episodic, semantic, recall, compress. Flusso: da event a encode (primario); da encode a semantic (primario); da semantic a recall (primario); da encode a episodic (di supporto); da episodic a recall (di supporto); da recall a compress (feedback).
08
CI e deploy
Flash CI builda il sito, scansiona le pagine renderizzate ed esegue i controlli browser; un run verde su main attiva un deploy in produzione con controllo di supersede.
- Dopo i gate pre-merge, la CI esegue una build di produzione, content:scan su dist/ e un controllo sul budget di bundle.
- Un job browser separato scarica quella build ed esegue controlli di contrasto e regressione visiva prima che il merge sia consentito.
- Il deploy segue un Flash CI riuscito su main, pubblica immagini arm64 su GHCR e verifica che la produzione serva il commit nuovo.
npm run buildnpm run content:scannpm run perf:budget
diagramma di architettura: evals. Nodi: trace, cases, score, regress, report, fix. Flusso: da trace a cases (primario); da cases a score (primario); da score a report (primario); da score a regress (feedback); da regress a fix (di supporto); da fix a trace (loop).