@agentrica/mcp 0.3.3 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. package/.claude/agents/business-product/biz-business-analyst-requirements-strategist.md +18 -0
  2. package/.claude/agents/business-product/biz-business-development-manager.md +18 -0
  3. package/.claude/agents/business-product/biz-business-financial-analyst.md +18 -0
  4. package/.claude/agents/business-product/biz-chief-officer.md +18 -0
  5. package/.claude/agents/business-product/biz-customer-success-retention-strategist.md +18 -0
  6. package/.claude/agents/business-product/biz-growth-monetization-manager.md +18 -0
  7. package/.claude/agents/business-product/biz-market-research-analyst.md +18 -0
  8. package/.claude/agents/business-product/biz-product-innovation-strategist.md +18 -0
  9. package/.claude/agents/business-product/biz-product-manager.md +18 -0
  10. package/.claude/agents/business-product/biz-product-marketing-manager.md +18 -0
  11. package/.claude/agents/business-product/biz-product-portfolio-roadmap-manager.md +18 -0
  12. package/.claude/agents/business-product/biz-sales-revenue-strategist.md +18 -0
  13. package/.claude/agents/cybersecurity/sec-appsec-engineer.md +18 -0
  14. package/.claude/agents/cybersecurity/sec-awareness-engineer.md +18 -0
  15. package/.claude/agents/cybersecurity/sec-ciso.md +18 -0
  16. package/.claude/agents/cybersecurity/sec-cloud-security-engineer.md +18 -0
  17. package/.claude/agents/cybersecurity/sec-iam-engineer.md +18 -0
  18. package/.claude/agents/cybersecurity/sec-incident-response.md +18 -0
  19. package/.claude/agents/cybersecurity/sec-network-security-engineer.md +18 -0
  20. package/.claude/agents/cybersecurity/sec-pentest-specialist.md +18 -0
  21. package/.claude/agents/cybersecurity/sec-risk-compliance-auditor.md +18 -0
  22. package/.claude/agents/cybersecurity/sec-security-architect.md +18 -0
  23. package/.claude/agents/cybersecurity/sec-soc-analyst.md +18 -0
  24. package/.claude/agents/cybersecurity/sec-vulnerability-management.md +18 -0
  25. package/.claude/agents/privacy-compliance/privacy-breach-response.md +18 -0
  26. package/.claude/agents/privacy-compliance/privacy-chief-officer.md +18 -0
  27. package/.claude/agents/privacy-compliance/privacy-compliance-auditor.md +18 -0
  28. package/.claude/agents/privacy-compliance/privacy-data-governance.md +18 -0
  29. package/.claude/agents/privacy-compliance/privacy-data-subject-rights.md +18 -0
  30. package/.claude/agents/privacy-compliance/privacy-dpia-specialist.md +18 -0
  31. package/.claude/agents/privacy-compliance/privacy-gdpr-specialist.md +18 -0
  32. package/.claude/agents/privacy-compliance/privacy-legal-specialist.md +18 -0
  33. package/.claude/agents/privacy-compliance/privacy-security-engineer.md +18 -0
  34. package/.claude/agents/privacy-compliance/privacy-vendor-compliance.md +18 -0
  35. package/.claude/agents/software/sw-architect.md +18 -0
  36. package/.claude/agents/software/sw-backend-developer.md +18 -0
  37. package/.claude/agents/software/sw-code-reviewer.md +18 -0
  38. package/.claude/agents/software/sw-cto.md +18 -0
  39. package/.claude/agents/software/sw-database-engineer.md +18 -0
  40. package/.claude/agents/software/sw-devops-engineer.md +18 -0
  41. package/.claude/agents/software/sw-frontend-developer.md +18 -0
  42. package/.claude/agents/software/sw-fullstack-developer.md +18 -0
  43. package/.claude/agents/software/sw-functional-analyst.md +18 -0
  44. package/.claude/agents/software/sw-performance-engineer.md +18 -0
  45. package/.claude/agents/software/sw-qa-engineer.md +18 -0
  46. package/.claude/agents/software/sw-security-engineer.md +18 -0
  47. package/.claude/agents/web-design/design-accessibility-specialist.md +18 -0
  48. package/.claude/agents/web-design/design-dataviz-designer.md +18 -0
  49. package/.claude/agents/web-design/design-director.md +18 -0
  50. package/.claude/agents/web-design/design-information-architect.md +18 -0
  51. package/.claude/agents/web-design/design-system-specialist.md +18 -0
  52. package/.claude/agents/web-design/design-ui-designer.md +18 -0
  53. package/.claude/agents/web-design/design-usability-auditor.md +18 -0
  54. package/.claude/agents/web-design/design-ux-designer.md +18 -0
  55. package/.claude/agents/web-design/design-ux-researcher.md +18 -0
  56. package/.claude/agents/web-design/design-ux-writer.md +18 -0
  57. package/README.en.md +44 -9
  58. package/README.md +43 -10
  59. package/dist/mcp/src/init.d.ts +6 -0
  60. package/dist/mcp/src/init.js +103 -0
  61. package/dist/mcp/src/page/app.js +70 -4
  62. package/dist/mcp/src/page/index.html +4 -0
  63. package/dist/mcp/src/page/style.css +9 -1
  64. package/dist/mcp/src/panel.d.ts +16 -1
  65. package/dist/mcp/src/panel.js +38 -2
  66. package/dist/mcp/src/project.js +2 -2
  67. package/dist/mcp/src/prompt.d.ts +6 -2
  68. package/dist/mcp/src/prompt.js +12 -2
  69. package/dist/mcp/src/ratings.d.ts +54 -0
  70. package/dist/mcp/src/ratings.js +115 -0
  71. package/dist/mcp/src/server.js +88 -11
  72. package/package.json +5 -3
  73. package/starter/.github/workflows/ci.yml +65 -0
  74. package/starter/.nvmrc +1 -0
  75. package/starter/AGENTS.md +89 -0
  76. package/starter/CLAUDE.md +1 -0
  77. package/starter/CONVENTIONS.md +192 -0
  78. package/starter/README.md +20 -0
  79. package/starter/audit/README.md +15 -0
  80. package/starter/docs/AI Multi-Agency System.md +516 -0
  81. package/starter/docs/README.md +7 -0
  82. package/starter/gitignore +36 -0
  83. package/starter/plan/00-base.md +47 -0
  84. package/starter/plan/README.md +37 -0
@@ -0,0 +1,89 @@
1
+ # Regole per gli agenti
2
+
3
+ Prima di implementare leggi le sezioni pertinenti di [CONVENTIONS.md](CONVENTIONS.md) e il file della fase in [plan/](plan/README.md): queste regole li completano, non li sostituiscono (CONVENTIONS §16).
4
+
5
+ <!-- Se il framework scrive da solo un blocco di regole qui in testa (per esempio Next.js con `next dev`), lascialo e committalo. -->
6
+
7
+ ## Esplorare il codice: tokensave
8
+
9
+ Il progetto è indicizzato con tokensave (cartella `.tokensave/`, ignorata da git). Gira tutto sulla postazione: non chiama modelli né servizi a pagamento e riduce i token, perché restituisce solo il codice che serve. Per esplorare il codice usa i tool `tokensave_*` prima di Grep e Read:
10
+
11
+ - `tokensave_context` per un concetto o un compito, in linguaggio naturale;
12
+ - `tokensave_search` per un simbolo per nome, con `literal: true` per il testo esatto;
13
+ - `tokensave_callers`, `tokensave_callees` e `tokensave_impact` per chi usa cosa.
14
+
15
+ Il server MCP non ha un progetto predefinito: passa `graph_root: "{{PROJECT_PATH}}"`, oppure usa la CLI dalla root (`tokensave tool search <query>`). A fine di ogni fase l'indice si aggiorna con `tokensave sync` dalla root, come passo della chiusura (CONVENTIONS §13.7); anche dopo modifiche importanti a metà fase. L'indice si crea in F0 con `tokensave init`, quando c'è il primo codice. Se tokensave non è installato, esplora con ricerca e lettura dei file.
16
+
17
+ ## Scrivere codice: Ponytail
18
+
19
+ Prima di scrivere codice, fermati al primo gradino che regge:
20
+
21
+ 1. Serve davvero? Se il bisogno è ipotetico, non si fa.
22
+ 2. C'è già nel progetto? Riusa helper, tipi e pattern esistenti.
23
+ 3. Lo fa la libreria standard?
24
+ 4. Lo fa la piattaforma (HTML, CSS, il browser, il framework)?
25
+ 5. Lo fa una dipendenza già installata? Niente dipendenze nuove per poche righe.
26
+ 6. Basta una riga?
27
+ 7. Solo allora: il codice minimo che funziona.
28
+
29
+ Un bug si corregge alla causa, nel punto per cui passano tutti i chiamanti. Niente astrazioni non richieste, niente codice «per dopo». Le semplificazioni volute si segnano con un commento `ponytail:` che dice il limite e quando superarlo.
30
+
31
+ ## Efficienza
32
+
33
+ Il costo di una sessione cresce con le chiamate e con la dimensione del contesto: ogni chiamata lo rilegge tutto. L'abbonamento ha limiti di cinque ore e settimanali.
34
+
35
+ - **Agenti**: sono la voce più cara. Si avviano solo quando un'attività lo richiede e solo gli specialisti pertinenti, mai tutte le agenzie insieme (sezione «Agenzie»).
36
+ - Una sessione per fase: dopo la chiusura (CONVENTIONS §13.7) se ne apre una nuova (`/clear`). Lo stato è nel piano, in git e nella memoria.
37
+ - Dentro la fase, `/compact` quando il contesto diventa grande.
38
+ - Durante lo sviluppo test mirati (un file di test, una spec e2e); la verifica completa con `npm run verify`, in un comando solo.
39
+ - Letture indipendenti nella stessa chiamata; righe mirate invece di file interi; non rileggere un file già nel contesto.
40
+ - Screenshot solo per una verifica visiva, non ripetuti sulla stessa schermata.
41
+ - `CONVENTIONS.md` per le sezioni pertinenti al compito, non intero.
42
+
43
+ ## Verifica
44
+
45
+ - `npm run verify` (typecheck, lint, test unitari, build) deve passare prima di ogni commit.
46
+ - `npm run verify:e2e` (Playwright) prima del merge di una fase, dalla fase che lo introduce.
47
+ - Le modifiche visibili si provano nell'app (`npm run dev`) prima di dichiararle fatte. Se una prova non è stata fatta, si dice.
48
+ - La CI (`.github/workflows/ci.yml`) esegue gli stessi due comandi: i nomi `verify` e `verify:e2e` sono il contratto fra il progetto e la CI.
49
+
50
+ ## Agenzie
51
+
52
+ Cinque team di ruoli. I file dei ruoli sono in `agents/` (in ogni cartella `README.md`, `00-common-rules.md` con le regole comuni e un file numerato per ruolo); in `.claude/agents/` ogni ruolo è anche un subagent che rimanda al suo file (56 in tutto). Il quadro completo è in `docs/AI Multi-Agency System.md`.
53
+
54
+ | Agenzia | Ruoli | Prefisso | Cosa fa | Attiva |
55
+ |---|---|---|---|---|
56
+ | Software (`agents/ai_software_agency/`) | 12 | `sw-` | analisi, sviluppo e verifica. È l'unica che modifica il codice | sì |
57
+ | Web Design (`agents/ai_web_design_agency/`) | 10 | `design-` | audit di UX, UI, architettura informativa, design system, dati e grafici, accessibilità, usabilità e testi. Sola lettura | <!-- sì/no --> |
58
+ | Privacy & Compliance (`agents/ai_privacy_compliance_agency/`) | 10 | `privacy-` | trattamenti di dati, basi giuridiche, conservazione, fornitori, sicurezza dei dati, DPIA. Sola lettura, non dichiara conformità | <!-- sì/no --> |
59
+ | Business & Product (`agents/ai_business_product_development_agency/`) | 12 | `biz-` | obiettivi, requisiti, priorità, roadmap, business case, mercato. Sola lettura, nessun contatto esterno | <!-- sì/no --> |
60
+ | Cybersecurity (`agents/ai_cybersecurity_agency/`) | 12 | `sec-` | threat model, configurazioni di hosting e database, accessi, dipendenze e vulnerabilità, log, risposta agli incidenti. Sola lettura, nessun test attivo senza autorizzazione scritta | <!-- sì/no --> |
61
+
62
+ <!-- In F0 si decide con l'utente quali agenzie restano attive. Quelle non attive si tolgono da agents/ e .claude/agents/ (quando servono si ricopiano dalle stesse cartelle del pacchetto `@agentrica/mcp`) e la decisione va nella tabella di plan/README.md. Togli dai subagent anche i ruoli che il progetto non usa. -->
63
+
64
+ ### Due regole che valgono sempre
65
+
66
+ - **Attivazione su richiesta.** Le agenzie non sono un sistema sempre acceso: nessun agente parte senza un'attività che lo richieda, e non si avviano mai tutte le agenzie o tutti gli agenti insieme. Per ogni attività si scelgono l'agenzia e i soli specialisti pertinenti, nel momento in cui servono.
67
+ - **Conferma dell'utente.** Ogni decisione finale delle agenzie è una proposta finché l'utente non la conferma: priorità e contenuto del backlog, requisiti e specifiche, scelte di architettura e di modello dei dati, rilievi accettati o respinti, chiusura di un'attività, dipendenze nuove, commit, merge, push, deploy e migrazioni. Si presentano le alternative con le motivazioni (con AskUserQuestion) e si procede solo dopo il suo ok. A fine fase commit, merge in `develop`, push e `tokensave sync` si confermano con un'unica domanda (CONVENTIONS §13.7).
68
+
69
+ ### Come si usano
70
+
71
+ - Nel lavoro di tutti i giorni i ruoli sono un modo di lavorare della sessione principale; i subagent si avviano per gli audit e quando l'utente li chiede.
72
+ - Funzioni o iniziative nuove: ruoli business per obiettivo, valore, requisiti e priorità, prima del design.
73
+ - Modifiche con effetti visibili: ruoli di design pertinenti prima (controlli) e dopo (revisione nell'app).
74
+ - Trattamenti di dati personali (dati nuovi, import ed export, fornitori, conservazione): ruoli privacy prima (requisiti) e dopo (verifica delle misure).
75
+ - Modifiche al codice: sviluppo nei ruoli software che corrispondono ai file toccati, poi QA (sempre), Security e Performance quando toccati, infine il Code Reviewer sul diff (`APPROVE`, `REQUEST_CHANGES` o `COMMENT`).
76
+ - Sicurezza dell'applicazione intera (audit periodici, nuove integrazioni o fornitori, segreti e accessi, aggiornamenti delle dipendenze, incidenti): ruoli cybersecurity. Il diff di una singola modifica resta al Security della software; i dati personali restano alla privacy.
77
+ - Ordine per una richiesta trasversale: business → design → privacy → **conferma dell'utente** → software → revisione design → revisione privacy → Code Reviewer → **conferma dell'utente**. Si saltano i passaggi non pertinenti o delle agenzie non attive.
78
+ - I rilievi di design e privacy sono requisiti: se uno non è fattibile torna all'agenzia o all'utente, non si cambia in silenzio.
79
+ - Priorità: `P0` critica, `P1` alta, `P2` media, `P3` bassa, sempre motivate. Gravità tecnica, rischio privacy, impatto UX e impatto di business sono dimensioni distinte.
80
+
81
+ ### Adattamenti a questo repository
82
+
83
+ <!-- Da compilare in F0 e aggiornare quando cambiano. -->
84
+
85
+ - **Stack.** <!-- es. «Vite e TypeScript strict; logica pura e testata in src/lib» -->
86
+ - **Dati.** <!-- Mock e dati finti, oppure dati reali dell'utente: dove stanno, cosa gli agenti non devono mai fare (salvare, importare, eliminare, copiare nel repository). -->
87
+ - **Audit.** I rilievi stanno in `audit/<audit_id>/` (un JSON per agente, i report dei direttori in `report-*.md`), le evidenze in `audit/<audit_id>/evidenze/`.
88
+ - **Versionati.** `agents/`, `.claude/agents/`, `audit/`, `docs/` e `plan/` sono nel repository. Se le evidenze degli audit mostrano dati personali, si attiva la riga `audit/*/evidenze/` del `.gitignore`.
89
+ - Push, deploy e migrazioni in produzione richiedono l'approvazione esplicita dell'utente.
@@ -0,0 +1 @@
1
+ @AGENTS.md
@@ -0,0 +1,192 @@
1
+ # Convenzioni di {{PROJECT_NAME}}
2
+
3
+ Regole per chi lavora al codice di {{PROJECT_NAME}}, persone o agenti. `AGENTS.md` le completa con le regole per gli agenti e le agenzie (§16). Le parti marcate «da compilare» dipendono dallo stack e si scrivono in F0; il resto vale per ogni progetto.
4
+
5
+ ## 1. Scopo
6
+
7
+ <!-- Da compilare: cos'è il prodotto, per chi, e cosa non si deve mai rompere (dati reali, partite salvate, contenuti pubblicati…). -->
8
+
9
+ Le regole servono a tre cose, in quest'ordine: non perdere né alterare i dati e il lavoro dell'utente, tenere il codice semplice e leggibile, consegnare modifiche verificate.
10
+
11
+ ## 2. Flusso di lavoro
12
+
13
+ ### 2.1 Leggere prima
14
+ Prima di modificare il codice si leggono questo documento (le sezioni pertinenti), `AGENTS.md`, il file della fase in `plan/` e i criteri di accettazione. Uno script, una libreria o una configurazione esiste solo se lo si trova nel repository, non perché un documento lo descrive.
15
+
16
+ ### 2.2 Capire il codice esistente
17
+ Si guardano i file coinvolti e le loro dipendenze, si cercano helper, tipi e componenti che risolvono già il problema, si capisce come scorrono i dati. Si seguono i pattern esistenti, salvo un motivo concreto.
18
+
19
+ ### 2.3 Chiarire le ambiguità che contano
20
+ Si procede da soli quando i requisiti sono chiari e le scelte sono a basso rischio e reversibili. Si chiede all'utente quando un'ambiguità può cambiare il comportamento visibile, l'integrità dei dati, la sicurezza, il modello dei dati o il perimetro. Le decisioni di prodotto non si prendono in silenzio.
21
+
22
+ ### 2.4 La soluzione più piccola che regge
23
+ Si applica la scala Ponytail di `AGENTS.md`. Niente refactoring estranei, niente astrazioni o dipendenze non necessarie, comportamento esistente preservato.
24
+
25
+ ### 2.5 Verificare
26
+ Si rilegge il diff, si eseguono i controlli (§13), si verificano i criteri di accettazione sull'implementazione reale. Non si dichiara superato un controllo che non è stato eseguito.
27
+
28
+ ### 2.6 Fasi e backlog
29
+ Il lavoro si divide in fasi, una alla volta, elencate in `plan/README.md` (tabella «Fasi») con le decisioni prese.
30
+ - **File di fase.** Ogni fase ha `plan/NN-nome.md` con obiettivo, stato, agenzie, situazione di partenza, decisioni dell'utente, `## Backlog`, `## Criteri di accettazione` e, alla chiusura, «Fatto», «Verifiche» e «Rilievi aperti» (modello: `plan/00-base.md`).
31
+ - **Backlog.** Una tabella con id `FN-NN`, task e priorità (`P0`–`P3`, come in `AGENTS.md`), confermata dall'utente all'apertura. Un task è fatto quando «Fatto» cita il suo id in grassetto (`**FN-NN**`) con l’evidenza: il pannello di `@agentrica/mcp` (`--panel`) legge questo formato.
32
+ - **Apertura.** Le «proposte da confermare» del file si decidono con l'utente; si apre `fase/fN-nome` da `develop`.
33
+ - **Durante.** Ciò che esce dal perimetro diventa una voce del backlog o un rilievo aperto, non una modifica di passaggio (§14). Le correzioni fuori fase vanno su `fix/nome`.
34
+ - **Chiusura.** Procedura di §13.7; i «Rilievi aperti» restano visibili finché una fase successiva non li chiude con un'evidenza.
35
+
36
+ ## 3. Scrittura del codice
37
+
38
+ - **Leggibilità prima di tutto**: nomi che dicono cosa contengono, funzioni brevi con una responsabilità, flusso lineare con uscite anticipate.
39
+ - **Semplicità**: il codice più corto che resta chiaro. Niente «per dopo».
40
+ - **DRY senza esagerare**: si estrae alla terza ripetizione o quando la logica deve restare identica.
41
+ - **Costanti**: niente valori magici ripetuti; le stringhe di dominio stanno in un solo punto.
42
+ - **Commenti**: spiegano il perché, non il cosa. Brevi, in italiano. Una semplificazione voluta si segna con `ponytail:`, dicendo il limite e quando superarlo.
43
+ - **Codice morto**: si toglie, non si commenta.
44
+ - **Difese**: si valida l'input ai confini (azioni lato server, route, import, input dell'utente); dentro, si usano i tipi.
45
+
46
+ ## 4. TypeScript
47
+
48
+ - `strict` resta attivo, con `noUncheckedIndexedAccess`. Niente `any`; `unknown` ai confini, poi restringimento.
49
+ - Asserzioni (`as`, `!`) solo dove un controllo precedente le garantisce, con un commento se non è evidente.
50
+ - Un tipo si definisce una volta e si deriva (`Pick`, `Omit`, tipi inferiti dallo schema) invece di ridefinirlo.
51
+ - <!-- Da compilare: unità e formati del dominio (es. importi interi in centesimi, date `YYYY-MM-DD`, unità di misura del mondo di gioco). -->
52
+
53
+ ## 5. Architettura del repository
54
+
55
+ | Cartella | Contenuto |
56
+ |---|---|
57
+ | `src/lib/` | logica pura e testata: niente DOM, rete, database né orologio (riceve `today` o `dt` come parametro) |
58
+ | <!-- da compilare --> | <!-- pagine, componenti, scena, server… --> |
59
+ | `e2e/` | test end-to-end e cattura delle evidenze degli audit |
60
+ | `scripts/` | script di progetto (migrazioni, dati dei test, utilità) |
61
+ | `plan/` | decisioni e fasi |
62
+ | `agents/`, `.claude/agents/` | ruoli delle agenzie e subagent |
63
+ | `audit/` | rilievi e report degli audit |
64
+ | `docs/` | materiale di riferimento |
65
+
66
+ La logica che si può testare senza framework, rete o database va in `src/lib`. Un controllo di lint lo fa rispettare quando lo stack lo permette.
67
+
68
+ ## 6. Dati e stato
69
+
70
+ <!-- Da compilare: dove si leggono e si scrivono i dati, dove vive lo stato (URL, server, client locale), come si invalida dopo una scrittura. Regola comune: lo stato che deve sopravvivere a un link sta nell'URL; niente librerie di stato globale senza un motivo registrato in plan/README.md. -->
71
+
72
+ ## 7. Confini: API, azioni, input
73
+
74
+ <!-- Da compilare: come entrano dati e comandi (Server Actions, API, eventi di input, file importati). Regole comuni: -->
75
+
76
+ - Ogni scrittura passa da un solo punto per area, valida i suoi input e restituisce un esito vero: un aggiornamento che non tocca nulla non risponde «aggiornato».
77
+ - Le scritture in più passi sono atomiche (transazione o equivalente).
78
+
79
+ ## 8. Form e interazioni
80
+
81
+ <!-- Da compilare: componenti dei form, formati di input (es. importi in formato italiano), comportamento dopo il salvataggio; oppure, per un gioco, mappa dei comandi e feedback. -->
82
+
83
+ ## 9. Componenti
84
+
85
+ - Un componente fa una cosa. Si riusano i componenti condivisi prima di crearne di nuovi.
86
+ - Le chiavi delle liste sono stabili e uniche. Niente effetti per calcolare valori derivabili.
87
+ - <!-- Da compilare: regole del framework (Server/Client Components, ciclo di vita della scena…). -->
88
+
89
+ ## 10. Accesso e protezione
90
+
91
+ - Nessun segreto nel codice né nei log. I file `.env*` (tranne `.env.example`) non entrano in git.
92
+ - Ogni controllo d'accesso si ripete dove si usano i dati, non solo al primo filtro.
93
+ - <!-- Da compilare quando arrivano account o dati per utente: come si entra, dove vive la sessione, come si separano i dati. -->
94
+
95
+ ## 11. Interfaccia, coerenza e accessibilità
96
+
97
+ - Si usano i token del design system, mai colori scritti a mano.
98
+ - Lo stato non si affida mai al solo colore: c'è sempre un segno, una forma o un testo.
99
+ - HTML semantico: un `h1` per pagina, titoli di sezione, tabelle con intestazioni, etichette sui campi.
100
+ - Tastiera: ogni azione è raggiungibile, il focus è visibile, i dialoghi lo intrappolano e lo restituiscono.
101
+ - Contrasto WCAG 2.2 AA: almeno 4,5:1 per il testo, 3:1 per gli elementi grafici.
102
+ - Responsive fino a 390 px senza scorrimento orizzontale della pagina. <!-- adattare ai dispositivi del progetto -->
103
+ - Ogni dato ha i suoi stati: caricamento, vuoto, errore.
104
+ - Testi in italiano, brevi, con il glossario di `plan/README.md`.
105
+
106
+ ## 12. Prestazioni e affidabilità
107
+
108
+ - Si ottimizza solo su misure.
109
+ - Le dipendenze nuove richiedono un motivo e l'ok dell'utente; prima si guarda la libreria standard e la piattaforma. Le versioni si fissano esatte.
110
+ - Le operazioni distruttive (import, eliminazioni, migrazioni, reset dei salvataggi) hanno conferma, esito e un modo per tornare indietro.
111
+
112
+ ## 13. Test e controlli
113
+
114
+ ### 13.1 Cosa testare
115
+ Si testano il comportamento e i rischi, con i casi limite del dominio. Un bug corretto ha il suo test di regressione.
116
+
117
+ ### 13.2 Test unitari
118
+ <!-- Da compilare: strumento e posizione, es. «`node --test` in `src/lib/*.test.ts` (`npm test`), senza dipendenze in più». -->
119
+
120
+ ### 13.3 Schema e migrazioni
121
+ <!-- Da compilare se c'è un database: come si generano, si rileggono e si provano su una copia prima di applicarle. -->
122
+
123
+ ### 13.4 Test end-to-end
124
+ Con Playwright in `e2e/`. I test usano solo dati finti e non toccano mai i dati reali dell'utente. L'accessibilità si controlla con axe dove c'è un'interfaccia HTML: nessuna violazione serious o critical, salvo i rilievi aperti elencati.
125
+
126
+ ### 13.5 Controlli prima del commit e del merge
127
+ - `npm run verify`: typecheck, lint, test unitari e build. Prima di ogni commit. Stampa solo errori e riepiloghi.
128
+ - `npm run verify:e2e`: test end-to-end. Prima del merge di una fase.
129
+
130
+ La CI esegue gli stessi due script: se uno manca, quel passo della CI si salta.
131
+
132
+ ### 13.6 Riferire i risultati
133
+ Si riportano i comandi eseguiti e l'esito reale, e si dice esplicitamente cosa non è stato verificato.
134
+
135
+ ### 13.7 Chiusura di una fase
136
+ Si lavora su `fase/fN-nome` (o `fix/nome` per una correzione fuori fase), partendo da `develop`. Quando i criteri di accettazione sono soddisfatti, la fase si chiude con questi passi, in quest'ordine:
137
+
138
+ 1. **Piano.** Il file della fase passa a «completata» con «Fatto», «Verifiche» e «Rilievi aperti»; si aggiornano la riga in «Fasi» e, se servono, «Decisioni» e «Glossario» di `plan/README.md`.
139
+ 2. **Controlli.** `npm run verify` e `npm run verify:e2e` (da quando esiste), con l'esito reale.
140
+ 3. **Proposta.** All'utente si presentano il riepilogo (§19) e la sequenza dei passi 4–7, con un'unica domanda di conferma. Senza l'ok non si va avanti; se l'utente chiede modifiche, si riparte dal passo 1.
141
+ 4. **Commit** sul branch della fase, con il messaggio che dice cosa cambia.
142
+ 5. **Merge** in `develop` con `--no-ff` e messaggio «Merge fase/fN-nome in develop».
143
+ 6. **Push** di `develop` e del branch della fase; la CI (`.github/workflows/ci.yml`) deve diventare verde (`gh run list`, `gh run watch`). Se è rossa, la si corregge su un `fix/…` prima di aprire la fase successiva.
144
+ 7. **Indice.** `tokensave sync` dalla root.
145
+ 8. **Sessione nuova.** Si dice all'utente che lo stato è completo in `plan/` e in git e che può fare `/clear`; la fase successiva riparte leggendo `plan/README.md` e il suo file.
146
+
147
+ Se un passo fallisce ci si ferma, si riferisce l'errore e non si salta ai passi successivi. Una correzione `fix/…` segue gli stessi passi; il messaggio del merge è «Merge fix/nome in develop».
148
+
149
+ ### 13.8 Rilascio in `main`
150
+ Non fa parte della chiusura di una fase: si fa solo quando l'utente lo chiede, con la CI di `develop` verde.
151
+ 1. Pull request da `develop` a `main` (`gh pr create --base main --head develop --title "Rilascio: FN descrizione breve"`), unita con merge commit quando la CI è verde (`gh pr merge --merge`). Conviene un ruleset su `main` che vieti push diretti e force push.
152
+ 2. <!-- Da compilare: hosting, cosa pubblica `main`, passi per le migrazioni, controllo dopo il deploy. -->
153
+
154
+ Deploy e migrazioni in produzione partono sempre con un ok esplicito, a parte da quello della fase.
155
+
156
+ ## 14. Perimetro e difetti esistenti
157
+
158
+ - Si fa ciò che la fase chiede. Un difetto direttamente collegato si corregge nello stesso task e si segnala; gli altri diventano voci del backlog in `plan/`, non modifiche di passaggio.
159
+ - Il comportamento esistente si preserva, salvo che la fase lo cambi.
160
+
161
+ ## 15. Configurazione del repository
162
+
163
+ ### 15.1 Stack
164
+ <!-- Da compilare in F0: framework, versioni, file di configurazione e loro particolarità. Una sottosezione per strumento (15.2, 15.3…). -->
165
+
166
+ ### 15.x Evidenze per gli audit
167
+ <!-- Quando serve: uno script `audit:capture` (Playwright) che salva screenshot, report axe e albero accessibile in `audit/<audit_id>/evidenze/`, su dati finti. -->
168
+
169
+ ### 15.y Agenzie
170
+ Ruoli, attivazione e coordinamento delle agenzie sono in `AGENTS.md`, sezione «Agenzie», e in `docs/AI Multi-Agency System.md`. Le regole delle agenzie si aggiungono a questo documento, non lo sostituiscono.
171
+
172
+ ## 16. Istruzioni e conflitti
173
+
174
+ L'ordine di precedenza è: richiesta esplicita dell'utente, poi decisioni registrate in `plan/`, poi questo documento, poi `AGENTS.md` e i file di ruolo delle agenzie. Se due regole si contraddicono si segnala il conflitto all'utente invece di sceglierne una in silenzio. `CLAUDE.md` importa `AGENTS.md`.
175
+
176
+ ## 17. Definition of Done
177
+
178
+ **Implementazione**: criteri di accettazione soddisfatti, codice secondo queste regole, nessun codice morto, nessun segreto.
179
+
180
+ **Esperienza e affidabilità**: stati di caricamento, vuoto ed errore; tastiera e contrasto; dispositivi del progetto provati; esiti veri; nessun dato dell'utente perso o alterato.
181
+
182
+ **Verifica**: `npm run verify` superato; `npm run verify:e2e` superato per il merge; test nuovi per il comportamento nuovo; revisione del Code Reviewer.
183
+
184
+ **Comunicazione**: file della fase aggiornato; rilievi aperti elencati; conferma dell'utente per commit, merge e push.
185
+
186
+ ## 18. Eccezioni
187
+
188
+ Un'eccezione a queste regole si scrive nella tabella «Decisioni» di `plan/README.md` o nel file della fase, con il motivo, prima del codice.
189
+
190
+ ## 19. Risposta finale
191
+
192
+ Chi chiude un task riferisce, in quest'ordine: cosa è stato fatto, file toccati, controlli eseguiti con l'esito reale, ruoli delle agenzie consultati, rilievi rimasti aperti e decisioni che servono all'utente.
@@ -0,0 +1,20 @@
1
+ # {{PROJECT_NAME}}
2
+
3
+ <!-- Cos'è, per chi, stato attuale. -->
4
+
5
+ ## Avvio
6
+
7
+ <!-- Da compilare in F0: requisiti (Node da .nvmrc), npm ci, npm run dev, variabili da .env.example. -->
8
+
9
+ ## Come si lavora
10
+
11
+ | File | Contenuto |
12
+ |---|---|
13
+ | [AGENTS.md](AGENTS.md) | regole per gli agenti: tokensave, Ponytail, efficienza, verifica, agenzie (`CLAUDE.md` lo importa) |
14
+ | [CONVENTIONS.md](CONVENTIONS.md) | convenzioni del codice, test, pubblicazione |
15
+ | [plan/](plan/README.md) | decisioni e fasi, una per file |
16
+ | [agents/](agents/) e [.claude/agents/](.claude/agents/) | ruoli delle agenzie e subagent |
17
+ | [audit/](audit/README.md) | rilievi e report degli audit |
18
+ | [docs/](docs/README.md) | materiale di riferimento |
19
+
20
+ Branch: `develop` per lo sviluppo, `main` per le versioni stabili, `fase/fN-nome` e `fix/nome` partendo da `develop`. Controlli: `npm run verify` prima di ogni commit, `npm run verify:e2e` prima del merge di una fase.
@@ -0,0 +1,15 @@
1
+ # Audit
2
+
3
+ Un audit è una cartella `audit/<audit_id>/`, dove `audit_id` è la data (`AAAA-MM-GG`) con un suffisso se nello stesso giorno ce n'è più d'uno (`AAAA-MM-GG-privacy`).
4
+
5
+ | File | Contenuto |
6
+ |---|---|
7
+ | `<ruolo>.json` | rilievi di un agente, nel formato JSON del suo file di ruolo in `agents/` |
8
+ | `report-<agenzia>.md` | report consolidato del direttore dell'agenzia: priorità, backlog proposto, decisioni per l'utente |
9
+ | `evidenze/` | screenshot, report axe, alberi accessibili, log usati come prova |
10
+
11
+ Regole:
12
+
13
+ - Ogni rilievo ha evidenza, priorità P0–P3 motivata e raccomandazione; un rilievo è una proposta finché l'utente non lo conferma.
14
+ - Le decisioni prese sull'audit vanno nella tabella «Decisioni» di `plan/README.md`; i rilievi accettati diventano task di una fase.
15
+ - Le evidenze si catturano su dati finti. Se mostrano dati personali, si attiva la riga `audit/*/evidenze/` del `.gitignore`.