@agentrica/mcp 0.3.3 → 0.4.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 (78) 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 +26 -7
  58. package/README.md +26 -7
  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/style.css +1 -1
  62. package/dist/mcp/src/project.js +2 -2
  63. package/dist/mcp/src/prompt.d.ts +1 -1
  64. package/dist/mcp/src/prompt.js +1 -1
  65. package/dist/mcp/src/server.js +6 -1
  66. package/package.json +4 -2
  67. package/starter/.github/workflows/ci.yml +65 -0
  68. package/starter/.nvmrc +1 -0
  69. package/starter/AGENTS.md +89 -0
  70. package/starter/CLAUDE.md +1 -0
  71. package/starter/CONVENTIONS.md +192 -0
  72. package/starter/README.md +20 -0
  73. package/starter/audit/README.md +15 -0
  74. package/starter/docs/AI Multi-Agency System.md +516 -0
  75. package/starter/docs/README.md +7 -0
  76. package/starter/gitignore +36 -0
  77. package/starter/plan/00-base.md +47 -0
  78. package/starter/plan/README.md +37 -0
@@ -0,0 +1,18 @@
1
+ ---
2
+ name: design-ux-researcher
3
+ description: "UX Researcher: per una funzione o un flusso nuovo chiarisce chi lo usa, per quale compito e con che frequenza. Sola lettura."
4
+ tools: Read, Grep, Glob, mcp__tokensave__tokensave_context, mcp__tokensave__tokensave_search, mcp__tokensave__tokensave_read
5
+ model: inherit
6
+ ---
7
+
8
+ Sei un agente dell'agenzia di design (AI Web Design Agency) del progetto Agentrica. Il tuo ruolo è definito in `agents/ai_web_design_agency/02-senior-ux-researcher.md` e le regole comuni dell'agenzia in `agents/ai_web_design_agency/00-common-rules.md`: leggili per intero prima di iniziare e applicane missione, metodo, limiti e formato di output. Dove il file di ruolo presuppone un tipo di prodotto diverso da questo, adattalo a quello descritto in `plan/README.md`.
9
+
10
+ Regole del progetto: leggi `AGENTS.md` (sezione «Agenzie», con gli adattamenti a questo repository), `CONVENTIONS.md` per le sezioni pertinenti e il file della fase in `plan/`; il quadro generale delle agenzie è in `docs/AI Multi-Agency System.md`.
11
+
12
+ Limiti: Sola lettura: analizzi, fai audit e raccomandi; non modifichi codice, CSS, componenti, dati o configurazioni. Nell'app in locale osservi, non salvi, non importi e non elimini nulla. I dati reali dell'utente, se il progetto ne ha (`AGENTS.md`, «Adattamenti»), si osservano solo attraverso l'app: non li modifichi, non li copi nel repository e non li riporti nei report se non servono all'evidenza. Le decisioni registrate in `plan/README.md` e in `AGENTS.md` prevalgono: un rilievo che le contraddice diventa una domanda con `requires_human_review: true`.
13
+
14
+ Regole comuni alle agenzie: non esporre segreti, password o token; non inventare risultati di test o audit; distingui fatti, ipotesi e raccomandazioni; segnala subito un rischio critico (P0) a chi ti ha assegnato il compito.
15
+
16
+ Consegna a chi ti ha assegnato il compito: rilievi nel formato JSON del tuo file di ruolo, ciascuno con evidenza, priorità motivata e raccomandazione.
17
+
18
+ Conferma: ogni tua conclusione finale (priorità, rilievo, specifica, scelta tecnica, esito della revisione) è una proposta: chi ti ha assegnato il compito la presenta all'utente, che la conferma prima che diventi definitiva.
@@ -0,0 +1,18 @@
1
+ ---
2
+ name: design-ux-writer
3
+ description: "UX Writer: etichette, pulsanti, messaggi, stati vuoti, qualunque testo visibile. Sola lettura."
4
+ tools: Read, Grep, Glob, mcp__tokensave__tokensave_context, mcp__tokensave__tokensave_search, mcp__tokensave__tokensave_read
5
+ model: inherit
6
+ ---
7
+
8
+ Sei un agente dell'agenzia di design (AI Web Design Agency) del progetto Agentrica. Il tuo ruolo è definito in `agents/ai_web_design_agency/10-senior-ux-writer.md` e le regole comuni dell'agenzia in `agents/ai_web_design_agency/00-common-rules.md`: leggili per intero prima di iniziare e applicane missione, metodo, limiti e formato di output. Dove il file di ruolo presuppone un tipo di prodotto diverso da questo, adattalo a quello descritto in `plan/README.md`.
9
+
10
+ Regole del progetto: leggi `AGENTS.md` (sezione «Agenzie», con gli adattamenti a questo repository), `CONVENTIONS.md` per le sezioni pertinenti e il file della fase in `plan/`; il quadro generale delle agenzie è in `docs/AI Multi-Agency System.md`.
11
+
12
+ Limiti: Sola lettura: analizzi, fai audit e raccomandi; non modifichi codice, CSS, componenti, dati o configurazioni. Nell'app in locale osservi, non salvi, non importi e non elimini nulla. I dati reali dell'utente, se il progetto ne ha (`AGENTS.md`, «Adattamenti»), si osservano solo attraverso l'app: non li modifichi, non li copi nel repository e non li riporti nei report se non servono all'evidenza. Le decisioni registrate in `plan/README.md` e in `AGENTS.md` prevalgono: un rilievo che le contraddice diventa una domanda con `requires_human_review: true`.
13
+
14
+ Regole comuni alle agenzie: non esporre segreti, password o token; non inventare risultati di test o audit; distingui fatti, ipotesi e raccomandazioni; segnala subito un rischio critico (P0) a chi ti ha assegnato il compito.
15
+
16
+ Consegna a chi ti ha assegnato il compito: rilievi nel formato JSON del tuo file di ruolo, ciascuno con evidenza, priorità motivata e raccomandazione.
17
+
18
+ Conferma: ogni tua conclusione finale (priorità, rilievo, specifica, scelta tecnica, esito della revisione) è una proposta: chi ti ha assegnato il compito la presenta all'utente, che la conferma prima che diventi definitiva.
package/README.en.md CHANGED
@@ -12,7 +12,7 @@ The agent files are in Italian. The agent answers in the language you write in.
12
12
 
13
13
  - The server runs only locally: the client starts it on your computer and the two talk over stdio. The server has no remote part.
14
14
  - The only content it reads is the `agents/` files included in the package, once, at startup. The text that reaches the model is the text of those files: you can read it before using it.
15
- - It writes no files, opens no network connections, logs nothing, collects and sends no data, and has no telemetry. With `--panel` it opens a page on your computer only: see [Local panel](#local-panel).
15
+ - The server writes no files (only the [`init`](#new-project) command does, when you run it), opens no network connections, logs nothing, collects and sends no data, and has no telemetry. With `--panel` it opens a page on your computer only: see [Local panel](#local-panel).
16
16
  - It runs nothing in your project. It only gives instructions to the model: what the model does in the project depends on the client and on the permissions you grant it.
17
17
  - **Where the data goes.** The agent's text, the task and the files the model reads in your project go to the model provider through your client, under that provider's terms. Agentrica does not receive them. Leave personal data, secrets and customer data out of the task unless they are needed.
18
18
  - The agents are AI: their conclusions are proposals to check. The privacy and security agents do not replace a DPO, a lawyer or a security officer, and their findings are not a compliance certification.
@@ -24,7 +24,7 @@ You need Node 22 or later, with npm.
24
24
  **Claude Code**, from your project folder:
25
25
 
26
26
  ```sh
27
- claude mcp add agentrica -- npx -y @agentrica/mcp@0.3.3
27
+ claude mcp add agentrica -- npx -y @agentrica/mcp@0.4.0
28
28
  ```
29
29
 
30
30
  On first start npx downloads the package from npm. The version stays the one you set until you change it: role updates do not arrive unless you choose them.
@@ -36,7 +36,7 @@ On first start npx downloads the package from npm. The version stays the one you
36
36
  "mcpServers": {
37
37
  "agentrica": {
38
38
  "command": "npx",
39
- "args": ["-y", "@agentrica/mcp@0.3.3"]
39
+ "args": ["-y", "@agentrica/mcp@0.4.0"]
40
40
  }
41
41
  }
42
42
  }
@@ -45,7 +45,7 @@ On first start npx downloads the package from npm. The version stays the one you
45
45
  **Least privilege (recommended).** Install the package in its own folder and start it with Node's permission model: the server can only read that folder, and Node blocks file writes, network connections and child processes. The server needs none of them, so it works the same; the permissions limit the damage of any future defect.
46
46
 
47
47
  ```sh
48
- npm install -g --ignore-scripts @agentrica/mcp@0.3.3
48
+ npm install -g --ignore-scripts @agentrica/mcp@0.4.0
49
49
  npm root -g
50
50
  ```
51
51
 
@@ -72,7 +72,7 @@ Put the task in quotes: Claude Code splits arguments on spaces.
72
72
  **Squad.** With `--agents` the server loads only the agents you list: agent ids and department codes, comma-separated, case-insensitive. For example the whole software department plus the accessibility agent:
73
73
 
74
74
  ```sh
75
- claude mcp add agentrica -- npx -y @agentrica/mcp@0.3.3 --agents aisa,aiwda-08
75
+ claude mcp add agentrica -- npx -y @agentrica/mcp@0.4.0 --agents aisa,aiwda-08
76
76
  ```
77
77
 
78
78
  The command menu shows only the squad's prompts, and `elenca_agenti` and `agente` see only those agents too. Without `--agents` all 56 agents are available. An unknown id or code stops the server with a message naming it, in the client's logs. In Claude Code prompts do not enter the model's context (we checked with `/context`): a squad makes the menu shorter, it does not save tokens.
@@ -93,7 +93,7 @@ Number 01 in each department is the director: it coordinates the specialists and
93
93
  With `--panel` the server also opens a page on your computer where you follow the project and make the choices the agent asks you for, instead of answering in the terminal:
94
94
 
95
95
  ```sh
96
- claude mcp add agentrica -- npx -y @agentrica/mcp@0.3.3 --panel
96
+ claude mcp add agentrica -- npx -y @agentrica/mcp@0.4.0 --panel
97
97
  ```
98
98
 
99
99
  Then ask the agent to open the panel (`open_panel` tool): the page opens in your browser. It has three pages, with a menu at the top counting pending choices and findings:
@@ -113,12 +113,30 @@ If the page is not open, `ask_user` opens it. The client waits for the answer as
113
113
 
114
114
  **What changes with `--panel`.** The server opens a random port on `127.0.0.1` only, reads `plan/`, `audit/` and the git status (`git status`) of the project folder, and keeps the last 20 agent calls in memory. It writes no files and sends no data off your computer. The page opens only with the random token in the URL, valid for that session; requests from other sites or with another `Host` are refused. The Node permission model recommended above does not apply with `--panel`, which needs the local network and `git`.
115
115
 
116
- **Format of `plan/` and `audit/`.** The panel reads the agentic-starter plan format, in Italian, the same as Agentrica's own [`plan/`](https://github.com/flgisimone/agentrica/tree/main/plan) and [`audit/`](https://github.com/flgisimone/agentrica/tree/main/audit); if something is missing, the page says what.
116
+ **Format of `plan/` and `audit/`.** The panel reads the plan format created by `init`, in Italian, the same as Agentrica's own [`plan/`](https://github.com/flgisimone/agentrica/tree/main/plan) and [`audit/`](https://github.com/flgisimone/agentrica/tree/main/audit); if something is missing, the page says what.
117
117
 
118
118
  - `plan/README.md` with a `## Fasi` section and a `| Fase | File | Contenuto | Stato |` table, the file as a link (`[14-pannello.md](14-pannello.md)`). The open phase is the first one whose status is neither `completata` nor `sospesa`.
119
119
  - In the phase file: `# Title`, a `**Obiettivo**: …` line, `## Backlog` with the `| # | Task | Priorità |` table, `## Criteri di accettazione` and `## Fatto` as lists; a task is done when its id appears in bold under «Fatto» (`- **F14-01** …`). `## Rilievi aperti` is a list, with the priority (`P0`–`P3`) in the text; an item that says «risolto» or «chiuso» (resolved, closed; e.g. «Risolto in F6.») stays in the plan but the panel does not show it.
120
120
  - `audit/<folder>/<file>.json` with `agente` (e.g. `"AICA-02 · …"`, which gives the department) and a `rilievi` list of objects with `id`, `titolo`, `priorita` and optional `stato`; a finding whose `stato` says «risolto» or «chiuso» is not shown.
121
121
 
122
+ ## New project
123
+
124
+ `init` creates a project with Agentrica's way of working, ready for Claude Code:
125
+
126
+ ```sh
127
+ npx -y @agentrica/mcp@0.4.0 init my-project --name "My project"
128
+ ```
129
+
130
+ Without a folder it uses the current one; without `--name` the name is the folder's. It writes, in Italian:
131
+
132
+ - `AGENTS.md` and `CLAUDE.md` (rules for agents: tokensave, the Ponytail ladder, efficiency, checks, agencies) and `CONVENTIONS.md` (code, tests, phases, closing and release), with the stack-specific parts marked «da compilare» (to fill in);
133
+ - `plan/` with `README.md` (decisions, glossary, phases) and `00-base.md`, the F0 phase to start from; `audit/` and `docs/`;
134
+ - `agents/` and `.claude/agents/`: the 56 roles of this version and one subagent per role, with the project name;
135
+ - `.github/workflows/ci.yml` (`npm run verify` and `verify:e2e`, skipped until F0 creates them), `.gitignore`, `.nvmrc`, `.env.example`;
136
+ - `.mcp.json` with this server at an exact version and `--panel`, so the panel reads the plan right away.
137
+
138
+ If even one file already exists, `init` writes nothing and lists them. Outside a git repository it makes the first commit on `main` and leaves `develop` checked out; inside one it does not commit. Then open Claude Code in the folder and ask it to open phase F0. `init` is the only command that writes files: the server stays read-only. It replaces agentic-starter, which is no longer updated.
139
+
122
140
  ## Put to the test
123
141
 
124
142
  Three agents tested on 2026-11-15 against three small projects with planted, documented defects, using `@agentrica/mcp@0.2.0 --agents <id>`, Claude Code for VS Code and Opus 5.5 (medium reasoning). One run per case, counted by hand.
@@ -139,6 +157,7 @@ The same catalog can be read from code, without starting the server: `import { l
139
157
 
140
158
  ## Versions
141
159
 
160
+ - **0.4.0**: `init` command that creates a project with rules, phased plan, agencies, subagents, CI and `.mcp.json` (replaces agentic-starter); the server is unchanged.
142
161
  - **0.3.3**: `@agentrica/mcp/catalog` export to read departments and agents from code (used by the site, now in a separate repository); agents and server behaviour unchanged.
143
162
  - **0.3.2**: the panel has three pages (Sessione, Piano, Rilievi) with a menu counting pending choices and findings; agents and server behaviour unchanged.
144
163
  - **0.3.1**: the panel hides closed findings and counts new files separately; the `agente` tool only accepts department codes in ids; common rules with a shared severity scale (P0–P3) and a scale for the software department.
package/README.md CHANGED
@@ -10,7 +10,7 @@ Ogni agente è un ruolo con un metodo e dei limiti dichiarati, per esempio `AISA
10
10
 
11
11
  - Il server gira solo in locale: lo avvia il client sul tuo computer e i due comunicano con stdio. Il server non ha una parte remota.
12
12
  - Come contenuto legge solo i file di `agents/` inclusi nel pacchetto, una volta all'avvio. Il testo che arriva al modello è quello di quei file: puoi leggerlo prima di usarlo.
13
- - Non scrive file, non apre connessioni di rete, non registra, non raccoglie e non invia dati, non ha telemetria. Con `--panel` apre una pagina solo sul tuo computer: vedi [Pannello locale](#pannello-locale).
13
+ - Il server non scrive file (lo fa solo il comando [`init`](#nuovo-progetto), quando lo lanci tu), non apre connessioni di rete, non registra, non raccoglie e non invia dati, non ha telemetria. Con `--panel` apre una pagina solo sul tuo computer: vedi [Pannello locale](#pannello-locale).
14
14
  - Non esegue niente nel tuo progetto. Dà soltanto istruzioni al modello: quello che il modello fa nel progetto dipende dal client e dai permessi che gli concedi.
15
15
  - **Dove vanno i dati.** Il testo dell'agente, il compito e i file che il modello legge nel tuo progetto vanno al fornitore del modello attraverso il tuo client, secondo le condizioni di quel fornitore. Agentrica non li riceve. Nel compito non inserire dati personali, segreti o dati di clienti che non servono.
16
16
  - Gli agenti sono IA: le loro conclusioni sono proposte da verificare. Gli agenti di privacy e sicurezza non sostituiscono un DPO, un avvocato o un responsabile della sicurezza, e i loro rilievi non sono una certificazione di conformità.
@@ -22,7 +22,7 @@ Serve Node 22 o successivo, con npm.
22
22
  **Claude Code**, dalla cartella del tuo progetto:
23
23
 
24
24
  ```sh
25
- claude mcp add agentrica -- npx -y @agentrica/mcp@0.3.3
25
+ claude mcp add agentrica -- npx -y @agentrica/mcp@0.4.0
26
26
  ```
27
27
 
28
28
  Al primo avvio npx scarica il pacchetto da npm. La versione resta quella indicata finché non la cambi tu: un aggiornamento dei ruoli non arriva senza che tu lo scelga.
@@ -34,7 +34,7 @@ Al primo avvio npx scarica il pacchetto da npm. La versione resta quella indicat
34
34
  "mcpServers": {
35
35
  "agentrica": {
36
36
  "command": "npx",
37
- "args": ["-y", "@agentrica/mcp@0.3.3"]
37
+ "args": ["-y", "@agentrica/mcp@0.4.0"]
38
38
  }
39
39
  }
40
40
  }
@@ -43,7 +43,7 @@ Al primo avvio npx scarica il pacchetto da npm. La versione resta quella indicat
43
43
  **Permessi minimi (consigliato).** Installa il pacchetto in una cartella sua e avvialo con il permission model di Node: il server può solo leggere quella cartella, e Node blocca scritture su file, connessioni di rete e processi figli. Il server non ne ha bisogno, quindi funziona uguale; i permessi limitano i danni di un eventuale difetto futuro.
44
44
 
45
45
  ```sh
46
- npm install -g --ignore-scripts @agentrica/mcp@0.3.3
46
+ npm install -g --ignore-scripts @agentrica/mcp@0.4.0
47
47
  npm root -g
48
48
  ```
49
49
 
@@ -70,7 +70,7 @@ Metti il compito fra virgolette: Claude Code separa gli argomenti con gli spazi.
70
70
  **Squadra.** Con `--agents` il server carica solo gli agenti che indichi: id di agenti e sigle di reparti, separati da virgole, senza distinguere maiuscole. Per esempio tutto il reparto software più l'agente dell'accessibilità:
71
71
 
72
72
  ```sh
73
- claude mcp add agentrica -- npx -y @agentrica/mcp@0.3.3 --agents aisa,aiwda-08
73
+ claude mcp add agentrica -- npx -y @agentrica/mcp@0.4.0 --agents aisa,aiwda-08
74
74
  ```
75
75
 
76
76
  Nel menu dei comandi restano solo i prompt della squadra, e anche `elenca_agenti` e `agente` vedono solo quelli. Senza `--agents` ci sono tutti i 56 agenti. Un id o una sigla sconosciuti fermano il server con un messaggio che li nomina, nei log del client. In Claude Code i prompt non entrano nel contesto del modello (lo abbiamo verificato con `/context`): la squadra rende il menu più corto, ma non fa risparmiare token.
@@ -93,7 +93,7 @@ I file degli agenti sono in italiano; l'agente risponde nella lingua in cui gli
93
93
  Con `--panel` il server apre anche una pagina sul tuo computer da cui segui il progetto e prendi le scelte che l'agente ti chiede, invece di rispondere nel terminale:
94
94
 
95
95
  ```sh
96
- claude mcp add agentrica -- npx -y @agentrica/mcp@0.3.3 --panel
96
+ claude mcp add agentrica -- npx -y @agentrica/mcp@0.4.0 --panel
97
97
  ```
98
98
 
99
99
  Poi chiedi all'agente di aprire il pannello (tool `open_panel`): la pagina si apre nel browser. Ha tre pagine, con il menu in alto che conta le scelte in attesa e i rilievi:
@@ -113,12 +113,30 @@ Se la pagina non è aperta, `ask_user` la apre. Il client aspetta la risposta fi
113
113
 
114
114
  **Cosa cambia con `--panel`.** Il server apre una porta casuale solo su `127.0.0.1`, legge `plan/`, `audit/` e lo stato di git (`git status`) della cartella del progetto e tiene in memoria le ultime 20 chiamate agli agenti. Non scrive file e non manda dati fuori dal computer. La pagina si apre solo con il token casuale contenuto nell'URL, che vale per quella sessione; le richieste da altri siti o con un altro `Host` sono rifiutate. Il permission model di Node consigliato sopra non si usa con `--panel`, che ha bisogno della rete locale e di `git`.
115
115
 
116
- **Formato di `plan/` e `audit/`.** Il pannello legge il formato dei piani di agentic-starter, lo stesso del [`plan/`](https://github.com/flgisimone/agentrica/tree/main/plan) e dell'[`audit/`](https://github.com/flgisimone/agentrica/tree/main/audit) di Agentrica; se qualcosa manca, la pagina dice cosa.
116
+ **Formato di `plan/` e `audit/`.** Il pannello legge il formato dei piani creati da `init`, lo stesso del [`plan/`](https://github.com/flgisimone/agentrica/tree/main/plan) e dell'[`audit/`](https://github.com/flgisimone/agentrica/tree/main/audit) di Agentrica; se qualcosa manca, la pagina dice cosa.
117
117
 
118
118
  - `plan/README.md` con una sezione `## Fasi` e una tabella `| Fase | File | Contenuto | Stato |`, il file come link (`[14-pannello.md](14-pannello.md)`). La fase aperta è la prima con uno stato diverso da `completata` e `sospesa`.
119
119
  - Nel file della fase: `# Titolo`, una riga `**Obiettivo**: …`, `## Backlog` con la tabella `| # | Task | Priorità |`, `## Criteri di accettazione` e `## Fatto` come elenchi; un task è fatto quando il suo id compare in grassetto in «Fatto» (`- **F14-01** …`). `## Rilievi aperti` è un elenco, con la priorità (`P0`–`P3`) nel testo; una voce che dice «risolto» o «chiuso» (es. «Risolto in F6.») resta nel piano ma il pannello non la mostra.
120
120
  - `audit/<cartella>/<file>.json` con `agente` (es. `"AICA-02 · …"`, da cui il reparto) e un elenco `rilievi` di oggetti con `id`, `titolo`, `priorita` e `stato` facoltativo; un rilievo con uno `stato` che dice «risolto» o «chiuso» non si mostra.
121
121
 
122
+ ## Nuovo progetto
123
+
124
+ `init` crea un progetto con il metodo di lavoro di Agentrica, pronto per Claude Code:
125
+
126
+ ```sh
127
+ npx -y @agentrica/mcp@0.4.0 init mio-progetto --name "Mio progetto"
128
+ ```
129
+
130
+ Senza cartella usa quella corrente; senza `--name` il nome è quello della cartella. Scrive:
131
+
132
+ - `AGENTS.md` e `CLAUDE.md` (regole per gli agenti: tokensave, scala Ponytail, efficienza, verifica, agenzie) e `CONVENTIONS.md` (codice, test, fasi, chiusura e rilascio), con le parti dello stack marcate «da compilare»;
133
+ - `plan/` con `README.md` (decisioni, glossario, fasi) e `00-base.md`, la fase F0 da cui si parte; `audit/` e `docs/`;
134
+ - `agents/` e `.claude/agents/`: i 56 ruoli di questa versione e un subagent per ruolo, con il nome del progetto;
135
+ - `.github/workflows/ci.yml` (`npm run verify` e `verify:e2e`, saltati finché F0 non li crea), `.gitignore`, `.nvmrc`, `.env.example`;
136
+ - `.mcp.json` con questo server a versione esatta e `--panel`, così il pannello legge subito il piano.
137
+
138
+ Se anche un solo file esiste già, `init` non scrive nulla e dice quali sono. Fuori da un repository git fa il primo commit su `main` e lascia attivo `develop`; dentro un repository non fa commit. Poi apri Claude Code nella cartella e chiedi di aprire la fase F0. `init` è l'unico comando che scrive file: il server resta in sola lettura. Prende il posto di agentic-starter, che non si aggiorna più.
139
+
122
140
  ## Messi alla prova
123
141
 
124
142
  Tre agenti provati il 2026-11-15 su tre piccoli progetti con difetti piantati e documentati, con `@agentrica/mcp@0.2.0 --agents <id>`, Claude Code per VS Code e Opus 5.5 (ragionamento medio). Un'esecuzione per caso, contata a mano.
@@ -139,6 +157,7 @@ Lo stesso catalogo si legge anche da codice, senza avviare il server: `import {
139
157
 
140
158
  ## Versioni
141
159
 
160
+ - **0.4.0**: comando `init` che crea un progetto con regole, piano a fasi, agenzie, subagent, CI e `.mcp.json` (prende il posto di agentic-starter); il server è invariato.
142
161
  - **0.3.3**: export `@agentrica/mcp/catalog` per leggere reparti e agenti da codice (lo usa il sito, ora in un repository a parte); agenti e comportamento del server invariati.
143
162
  - **0.3.2**: pannello in tre pagine (Sessione, Piano, Rilievi) con menu e contatori delle scelte in attesa e dei rilievi; agenti e comportamento del server invariati.
144
163
  - **0.3.1**: pannello che nasconde i rilievi chiusi e conta a parte i file nuovi; id del tool `agente` limitato alle sigle dei reparti; regole comuni con una scala di gravità condivisa (P0–P3) e una scala per il reparto software.
@@ -0,0 +1,6 @@
1
+ /** I subagent di Agentrica nominano il progetto solo in questa frase (lo controlla init.test.ts). */
2
+ export declare const SUBAGENT_PROJECT = "del progetto Agentrica.";
3
+ /** I file del progetto nuovo, per percorso relativo, con i segnaposto già sostituiti. */
4
+ export declare function projectFiles(name: string, path: string, date: string): Map<string, string>;
5
+ /** Esegue il comando; restituisce il codice di uscita. */
6
+ export declare function runInit(args: string[]): number;
@@ -0,0 +1,103 @@
1
+ // `agentrica-mcp init [cartella] [--name "Nome"]` (F18, al posto di agentic-starter): crea un progetto con la governance
2
+ // di Agentrica. Copia starter/ (AGENTS, CONVENTIONS, plan/, audit/, docs/, CI), gli agents/ del pacchetto e i subagent
3
+ // di .claude/agents/ con il nome del progetto, scrive .mcp.json con questo pacchetto a versione esatta e, fuori da un
4
+ // repository git, fa il primo commit su main e lascia attivo develop. È l'unico comando che scrive: il server resta in
5
+ // sola lettura. Se anche un solo file esiste già non scrive nulla.
6
+ import { execFileSync } from "node:child_process";
7
+ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
8
+ import { basename, dirname, join, relative, resolve } from "node:path";
9
+ import { parseArgs } from "node:util";
10
+ import { AGENTS_DIR } from "./catalog.js";
11
+ import { VERSION } from "./prompt.js";
12
+ // starter/, agents/ e .claude/agents/ stanno nella root del repository e, copiati da prepack, in quella del pacchetto.
13
+ const ROOT = dirname(AGENTS_DIR);
14
+ const STARTER_DIR = join(ROOT, "starter");
15
+ const SUBAGENTS_DIR = join(ROOT, ".claude", "agents");
16
+ /** I subagent di Agentrica nominano il progetto solo in questa frase (lo controlla init.test.ts). */
17
+ export const SUBAGENT_PROJECT = "del progetto Agentrica.";
18
+ // npm non pubblica i file .gitignore: in starter/ si chiama gitignore (e non vale per il repository di Agentrica).
19
+ const RENAMED = { gitignore: ".gitignore" };
20
+ function filesIn(dir) {
21
+ return readdirSync(dir, { recursive: true, withFileTypes: true })
22
+ .filter((entry) => entry.isFile() && entry.name !== ".DS_Store")
23
+ .map((entry) => relative(dir, join(entry.parentPath, entry.name)))
24
+ .sort();
25
+ }
26
+ /** I file del progetto nuovo, per percorso relativo, con i segnaposto già sostituiti. */
27
+ export function projectFiles(name, path, date) {
28
+ const values = { "{{PROJECT_NAME}}": name, "{{PROJECT_PATH}}": path, "{{DATE}}": date };
29
+ const fill = (text) => Object.entries(values).reduce((out, [key, value]) => out.split(key).join(value), text);
30
+ const files = new Map();
31
+ for (const file of filesIn(STARTER_DIR))
32
+ files.set(RENAMED[file] ?? file, fill(readFileSync(join(STARTER_DIR, file), "utf8")));
33
+ for (const file of filesIn(AGENTS_DIR))
34
+ files.set(join("agents", file), readFileSync(join(AGENTS_DIR, file), "utf8"));
35
+ for (const file of filesIn(SUBAGENTS_DIR)) {
36
+ const text = readFileSync(join(SUBAGENTS_DIR, file), "utf8");
37
+ files.set(join(".claude", "agents", file), text.split(SUBAGENT_PROJECT).join(`del progetto ${name}.`));
38
+ }
39
+ const server = { command: "npx", args: ["-y", `@agentrica/mcp@${VERSION}`, "--panel"] };
40
+ files.set(".mcp.json", `${JSON.stringify({ mcpServers: { agentrica: server } }, null, 2)}\n`);
41
+ return files;
42
+ }
43
+ function git(dir, args) {
44
+ return execFileSync("git", args, { cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
45
+ }
46
+ // Repository nuovo solo se la cartella non è già dentro uno: un progetto creato in un monorepo resta del monorepo.
47
+ function initGit(dir) {
48
+ try {
49
+ if (git(dir, ["rev-parse", "--is-inside-work-tree"]) === "true")
50
+ return "git: la cartella è già in un repository, nessun commit";
51
+ }
52
+ catch (error) {
53
+ if (error.code === "ENOENT")
54
+ return "git: non installato, repository non creato";
55
+ }
56
+ git(dir, ["init", "-q", "-b", "main"]);
57
+ git(dir, ["add", "-A"]);
58
+ try {
59
+ git(dir, ["commit", "-q", "-m", "Progetto creato con @agentrica/mcp init"]);
60
+ }
61
+ catch {
62
+ return "git: commit non riuscito (configura user.name e user.email), file lasciati in stage su main";
63
+ }
64
+ git(dir, ["checkout", "-q", "-b", "develop"]);
65
+ return "git: commit iniziale su main, branch develop attivo";
66
+ }
67
+ /** Esegue il comando; restituisce il codice di uscita. */
68
+ export function runInit(args) {
69
+ try {
70
+ const { values, positionals } = parseArgs({ args, options: { name: { type: "string" } }, allowPositionals: true });
71
+ if (positionals.length > 1)
72
+ throw new Error("uso: agentrica-mcp init [cartella] [--name \"Nome\"]");
73
+ const dir = resolve(positionals[0] ?? ".");
74
+ const name = (values.name ?? basename(dir)).trim();
75
+ if (!name || /\p{Cc}/u.test(name))
76
+ throw new Error("--name: serve un nome su una riga");
77
+ const files = projectFiles(name, dir, new Date().toISOString().slice(0, 10));
78
+ const taken = [...files.keys()].filter((file) => existsSync(join(dir, file)));
79
+ if (taken.length > 0) {
80
+ const more = taken.length > 5 ? ` e altri ${taken.length - 5}` : "";
81
+ throw new Error(`nessun file scritto, esistono già: ${taken.slice(0, 5).join(", ")}${more}`);
82
+ }
83
+ for (const [file, text] of files) {
84
+ mkdirSync(dirname(join(dir, file)), { recursive: true });
85
+ writeFileSync(join(dir, file), text, { flag: "wx" });
86
+ }
87
+ process.stdout.write([
88
+ `Progetto «${name}» creato in ${dir}: ${files.size} file.`,
89
+ initGit(dir),
90
+ "",
91
+ "Prossimi passi:",
92
+ ` 1. cd "${dir}" e apri Claude Code (.mcp.json registra il server di Agentrica con il pannello)`,
93
+ " 2. chiedi di aprire la fase F0 (plan/00-base.md): stack, agenzie attive, sezioni «da compilare»",
94
+ "",
95
+ ].join("\n"));
96
+ return 0;
97
+ }
98
+ catch (error) {
99
+ const message = error instanceof Error ? error.message : String(error);
100
+ process.stderr.write(`agentrica init: ${message.replace(/\p{Cc}/gu, " ")}\n`);
101
+ return 1;
102
+ }
103
+ }
@@ -1,4 +1,4 @@
1
- /* Palette del sito (apps/site/src/app/globals.css), tema scuro; contrasti AA misurati lì sugli stessi fondi. */
1
+ /* Palette del sito (src/app/globals.css nel repository agentrica-site), tema scuro; contrasti AA misurati lì sugli stessi fondi. */
2
2
  :root {
3
3
  --background: #0b1020;
4
4
  --foreground: #e8ebf4;
@@ -1,5 +1,5 @@
1
1
  // Lettura del progetto dell'utente per il pannello: fasi e backlog da plan/, rilievi da plan/ e audit/, stato di git.
2
- // Il formato è quello di agentic-starter, descritto nel README del pacchetto. Si legge solo dentro plan/ e audit/
2
+ // Il formato è quello che crea `init` (init.ts), descritto nel README del pacchetto. Si legge solo dentro plan/ e audit/
3
3
  // della cartella del progetto: i link simbolici che escono sono rifiutati e ogni file ha un limite di dimensione.
4
4
  // Un file mancante o fuori formato diventa un problema in `problems`, mai un errore che ferma il pannello.
5
5
  import { execFile } from "node:child_process";
@@ -50,7 +50,7 @@ function readPhases(root, plan, problems) {
50
50
  readme = readInside(root, join(plan, "README.md"));
51
51
  }
52
52
  catch {
53
- problems.push("Non trovo plan/README.md: il pannello legge il formato di agentic-starter (vedi il README del pacchetto).");
53
+ problems.push("Non trovo plan/README.md: il pannello legge il formato creato da `agentrica-mcp init` (vedi il README del pacchetto).");
54
54
  return [];
55
55
  }
56
56
  const fasi = section(readme, "Fasi");
@@ -1,6 +1,6 @@
1
1
  import type { Agent, Department } from "../../catalog/src/index.ts";
2
2
  /** Versione del server, uguale a quella di package.json (lo controlla prompt.test.ts). */
3
- export declare const VERSION = "0.3.3";
3
+ export declare const VERSION = "0.4.0";
4
4
  /**
5
5
  * Un reparto della squadra di --agents. Non ha `director`: con un reparto filtrato il direttore può essere fuori
6
6
  * squadra, così il tipo impedisce di usarlo senza controllare (rilievo di F12).
@@ -1,5 +1,5 @@
1
1
  /** Versione del server, uguale a quella di package.json (lo controlla prompt.test.ts). */
2
- export const VERSION = "0.3.3";
2
+ export const VERSION = "0.4.0";
3
3
  /** Cerca un agente per id, senza distinguere maiuscole e minuscole («aisa-02» o «AISA-02»). */
4
4
  export function findAgent(catalog, id) {
5
5
  const wanted = id.toUpperCase();
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  // Server MCP di Agentrica su stdio: un prompt per agente e due tool (elenca_agenti, agente).
3
3
  // Con --agents (es. --agents aisa,aiwda-08) prompt e tool vedono solo la squadra; senza, tutti gli agenti.
4
- // Legge solo i file di agents/ all'avvio; non scrive file, non apre connessioni e non registra dati.
4
+ // Legge solo i file di agents/ all'avvio; non scrive file, non apre connessioni e non registra dati (scrive solo init).
5
5
  // Con --panel (F14) apre anche il pannello locale su 127.0.0.1 (panel.ts), che legge plan/, audit/ e lo stato di git
6
6
  // della cartella corrente e aggiunge i tool open_panel e ask_user; le chiamate agli agenti restano solo in memoria.
7
7
  import { realpathSync } from "node:fs";
@@ -22,6 +22,11 @@ function fail(message) {
22
22
  const reason = (error) => (error instanceof Error ? error.message : String(error));
23
23
  let spec;
24
24
  let withPanel = false;
25
+ // `init` (F18) crea un progetto e termina, senza avviare il server: è l'unico comando che scrive file (init.ts).
26
+ if (process.argv[2] === "init") {
27
+ const { runInit } = await import("./init.js");
28
+ process.exit(runInit(process.argv.slice(3)));
29
+ }
25
30
  try {
26
31
  const { values } = parseArgs({ options: { agents: { type: "string" }, panel: { type: "boolean" } } });
27
32
  spec = values.agents;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@agentrica/mcp",
3
- "version": "0.3.3",
3
+ "version": "0.4.0",
4
4
  "mcpName": "io.github.flgisimone/agentrica",
5
5
  "description": "I 56 agenti IA di Agentrica come server MCP locale (stdio): un prompt per agente e due tool in sola lettura.",
6
6
  "license": "MIT",
@@ -25,13 +25,15 @@
25
25
  "files": [
26
26
  "dist",
27
27
  "agents",
28
+ "starter",
29
+ ".claude/agents",
28
30
  "README.en.md"
29
31
  ],
30
32
  "engines": {
31
33
  "node": ">=22"
32
34
  },
33
35
  "scripts": {
34
- "prepack": "rm -rf dist agents LICENSE && tsc -p tsconfig.build.json && cp -R src/page dist/mcp/src/page && cp -R ../../agents agents && cp ../../LICENSE LICENSE"
36
+ "prepack": "rm -rf dist agents starter .claude LICENSE && tsc -p tsconfig.build.json && cp -R src/page dist/mcp/src/page && cp -R ../../agents agents && cp -R ../../starter starter && mkdir .claude && cp -R ../../.claude/agents .claude/agents && cp ../../LICENSE LICENSE"
35
37
  },
36
38
  "dependencies": {
37
39
  "@modelcontextprotocol/sdk": "1.32.2",
@@ -0,0 +1,65 @@
1
+ # Controlli di ogni push e pull request: npm run verify e npm run verify:e2e (CONVENTIONS §13.5).
2
+ # Nessun deploy da qui. I passi senza il loro file o script si saltano, così la CI regge anche prima di F0.
3
+ # ponytail: con un repository privato e GitHub gratuito il merge non si blocca da solo; va verde prima di unire in main.
4
+ name: CI
5
+
6
+ on:
7
+ push:
8
+ branches: [main, develop, "fase/**", "fix/**"]
9
+ pull_request:
10
+ workflow_dispatch:
11
+
12
+ concurrency:
13
+ group: ci-${{ github.ref }}
14
+ cancel-in-progress: true
15
+
16
+ permissions:
17
+ contents: read
18
+
19
+ env:
20
+ TZ: Europe/Rome
21
+
22
+ jobs:
23
+ verify:
24
+ runs-on: ubuntu-latest
25
+ timeout-minutes: 30
26
+ steps:
27
+ # Action fissate per SHA: un tag si può spostare, uno SHA no.
28
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
29
+
30
+ - name: Script disponibili
31
+ id: scripts
32
+ run: |
33
+ if [ -f package.json ]; then
34
+ echo "verify=$(node -p "Boolean(require('./package.json').scripts?.verify)")" >> "$GITHUB_OUTPUT"
35
+ echo "e2e=$(node -p "Boolean(require('./package.json').scripts?.['verify:e2e'])")" >> "$GITHUB_OUTPUT"
36
+ fi
37
+
38
+ - if: hashFiles('package-lock.json') != ''
39
+ uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
40
+ with:
41
+ node-version-file: .nvmrc
42
+ cache: npm
43
+
44
+ - if: hashFiles('package-lock.json') != ''
45
+ run: npm ci
46
+
47
+ - name: Dipendenze di produzione senza vulnerabilità alte
48
+ if: hashFiles('package-lock.json') != ''
49
+ run: npm audit --omit=dev --audit-level=high
50
+
51
+ - if: steps.scripts.outputs.verify == 'true'
52
+ run: npm run verify
53
+
54
+ - if: steps.scripts.outputs.e2e == 'true'
55
+ run: npx playwright install --with-deps chromium
56
+
57
+ - if: steps.scripts.outputs.e2e == 'true'
58
+ run: npm run verify:e2e
59
+
60
+ - if: failure() && steps.scripts.outputs.e2e == 'true'
61
+ uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
62
+ with:
63
+ name: playwright-report
64
+ path: test-results/
65
+ retention-days: 3
package/starter/.nvmrc ADDED
@@ -0,0 +1 @@
1
+ 26
@@ -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