@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,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), logs nothing and has no telemetry. It connects to Agentrica in one case only: when you confirm an [agent rating](#ratings), and it sends only the score, the comment and the version. With `--no-ratings` it never connects. 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.5.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,16 +36,16 @@ 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.5.0"]
40
40
  }
41
41
  }
42
42
  }
43
43
  ```
44
44
 
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.
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. With these permissions, sending a [rating](#ratings) fails with a clear message: to rate agents add `--allow-net`, otherwise add `--no-ratings` at the end of the command.
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.5.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.5.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.
@@ -83,17 +83,32 @@ The command menu shows only the squad's prompts, and `elenca_agenti` and `agente
83
83
  |---|---|---|
84
84
  | `elenca_agenti` (list agents) | optional `reparto` (department: `AIBPD`, `AICA`, `AIPCA`, `AISA`, `AIWDA`) | id, code name, role and department of each agent |
85
85
  | `agente` (agent) | `id` (e.g. `AISA-02`), optional `compito` (task) | the agent's full instructions |
86
+ | `rate_agent` | `id`, `rating` from 1 to 5, optional `comment` and `publish`; then `code` | a preview of the rating and a code; with the code, the sending (see [Ratings](#ratings)) |
86
87
 
87
88
  For example: "Use elenca_agenti, pick the right Agentrica agent and check the accessibility of the login form".
88
89
 
89
90
  Number 01 in each department is the director: it coordinates the specialists and consolidates their findings.
90
91
 
92
+ While working, the agent says who it is, for example "AISA-02 · ALTAIR — Senior Software Architect, reparto AISA (AI Software)": at the start, when it hands over to another agent and in the final summary.
93
+
94
+ ## Ratings
95
+
96
+ You can give an agent a score from 1 to 5 and a comment on what to improve: ratings are used to fix the role files. When the agent has finished the task it suggests a rating, once per session; if it has been working for more than 30 minutes, the server reminds the model once. You can also ask ("rate AISA-02").
97
+
98
+ - **Nothing is sent without your yes.** `rate_agent` first shows a preview of what will be sent and a code valid for 10 minutes; the model shows it to you and sends only with the code, exactly that content. With `--panel` you rate from the page, in the "Valuta gli agenti" section.
99
+ - **What is sent.** The agent id, the score, the comment, whether you allow the comment to be published on the site (off by default), the package version and a random rating code. No task, files, paths or project name, no account. Do not write names, personal data or parts of your project in the comment.
100
+ - **After sending** you get the rating code: with it you can ask for the rating to be deleted or for the comment not to be published. An agent can be rated once per session and once a day from the same network.
101
+ - **If sending fails** (offline, service down) the tool says so and the work goes on; the rating is not stored anywhere.
102
+ - **To drop the tool** and the suggestions, add `--no-ratings` to the command: the server never connects.
103
+
104
+ How ratings are handled: [legal notes](https://agentrica.vercel.app/note-legali#valutazioni) (in Italian).
105
+
91
106
  ## Local panel
92
107
 
93
108
  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
109
 
95
110
  ```sh
96
- claude mcp add agentrica -- npx -y @agentrica/mcp@0.3.3 --panel
111
+ claude mcp add agentrica -- npx -y @agentrica/mcp@0.5.0 --panel
97
112
  ```
98
113
 
99
114
  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:
@@ -111,14 +126,32 @@ With the panel the model has two more tools:
111
126
 
112
127
  If the page is not open, `ask_user` opens it. The client waits for the answer as long as the server sends progress notifications (up to 4 hours; 25 minutes with a client that does not request them), then the agent asks in the terminal. The client's own questions, such as tool permissions, stay in the client.
113
128
 
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`.
129
+ **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, except the ratings you send from the page. 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
130
 
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.
131
+ **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
132
 
118
133
  - `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
134
  - 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
135
  - `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
136
 
137
+ ## New project
138
+
139
+ `init` creates a project with Agentrica's way of working, ready for Claude Code:
140
+
141
+ ```sh
142
+ npx -y @agentrica/mcp@0.5.0 init my-project --name "My project"
143
+ ```
144
+
145
+ Without a folder it uses the current one; without `--name` the name is the folder's. It writes, in Italian:
146
+
147
+ - `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);
148
+ - `plan/` with `README.md` (decisions, glossary, phases) and `00-base.md`, the F0 phase to start from; `audit/` and `docs/`;
149
+ - `agents/` and `.claude/agents/`: the 56 roles of this version and one subagent per role, with the project name;
150
+ - `.github/workflows/ci.yml` (`npm run verify` and `verify:e2e`, skipped until F0 creates them), `.gitignore`, `.nvmrc`, `.env.example`;
151
+ - `.mcp.json` with this server at an exact version and `--panel`, so the panel reads the plan right away.
152
+
153
+ 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.
154
+
122
155
  ## Put to the test
123
156
 
124
157
  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 +172,8 @@ The same catalog can be read from code, without starting the server: `import { l
139
172
 
140
173
  ## Versions
141
174
 
175
+ - **0.5.0**: agent ratings (two-step `rate_agent` tool with preview and code, "Valuta gli agenti" section in the panel, suggestion at the end of the work and a reminder after 30 minutes), the server's only connection and only after your confirmation; `--no-ratings` removes it. The agent says who it is (code name, role, department) at the start, at handovers and in the summary.
176
+ - **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
177
  - **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
178
  - **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
179
  - **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 registra e non ha telemetria. Apre una connessione verso Agentrica in un caso solo: quando confermi la [valutazione di un agente](#valutazioni), e invia solo voto, commento e versione. Con `--no-ratings` non si collega mai. 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.5.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,16 +34,16 @@ 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.5.0"]
38
38
  }
39
39
  }
40
40
  }
41
41
  ```
42
42
 
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.
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. Con questi permessi l'invio di una [valutazione](#valutazioni) fallisce con un messaggio chiaro: se vuoi votare gli agenti aggiungi `--allow-net`, altrimenti aggiungi `--no-ratings` in fondo al comando.
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.5.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.5.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.
@@ -81,19 +81,32 @@ Nel menu dei comandi restano solo i prompt della squadra, e anche `elenca_agenti
81
81
  |---|---|---|
82
82
  | `elenca_agenti` | `reparto` facoltativo (`AIBPD`, `AICA`, `AIPCA`, `AISA`, `AIWDA`) | id, nome in codice, ruolo e reparto di ogni agente |
83
83
  | `agente` | `id` (es. `AISA-02`), `compito` facoltativo | le istruzioni complete dell'agente |
84
+ | `rate_agent` | `id`, `rating` da 1 a 5, `comment` e `publish` facoltativi; poi `code` | l'anteprima della valutazione e un codice; con il codice, l'invio (vedi [Valutazioni](#valutazioni)) |
84
85
 
85
86
  Per esempio: «Usa elenca_agenti, scegli l'agente di Agentrica adatto e verifica l'accessibilità del form di login».
86
87
 
87
88
  Il numero 01 di ogni reparto è il direttore: coordina gli specialisti e consolida i loro rilievi.
88
89
 
89
- I file degli agenti sono in italiano; l'agente risponde nella lingua in cui gli scrivi.
90
+ I file degli agenti sono in italiano; l'agente risponde nella lingua in cui gli scrivi. Durante il lavoro l'agente dice chi è, per esempio «AISA-02 · ALTAIR — Senior Software Architect, reparto AISA (AI Software)»: all'inizio, quando passa a un altro agente e nel riepilogo finale.
91
+
92
+ ## Valutazioni
93
+
94
+ Puoi dare a un agente un voto da 1 a 5 e un commento su cosa migliorare: servono a correggere i file di ruolo. Quando l'agente ha finito il compito te lo propone, una volta per sessione; se lavora da più di 30 minuti, il server lo ricorda al modello una volta. Puoi anche chiederlo tu («valuta AISA-02»).
95
+
96
+ - **Niente parte senza il tuo sì.** `rate_agent` prima mostra l'anteprima di ciò che parte e un codice valido 10 minuti; il modello te la mostra e invia solo con il codice, esattamente quel contenuto. Con `--panel` voti dalla pagina, nella sezione «Valuta gli agenti».
97
+ - **Cosa parte.** Id dell'agente, voto, commento, se permetti di pubblicare il commento sul sito (spento di default), versione del pacchetto e un codice casuale della valutazione. Niente compito, file, percorsi o nome del progetto, niente account. Nel commento non scrivere nomi, dati personali o parti del progetto.
98
+ - **Dopo l'invio** ricevi il codice della valutazione: con quello puoi chiedere di cancellarla o di non pubblicare il commento. Un agente si valuta una volta per sessione e una volta al giorno dalla stessa rete.
99
+ - **Se l'invio non riesce** (offline, servizio giù) il tool lo dice e il lavoro continua; il voto non resta salvato da nessuna parte.
100
+ - **Per non avere il tool** né le proposte, aggiungi `--no-ratings` al comando: il server non si collega mai.
101
+
102
+ Come trattiamo le valutazioni: [note legali](https://agentrica.vercel.app/note-legali#valutazioni).
90
103
 
91
104
  ## Pannello locale
92
105
 
93
106
  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
107
 
95
108
  ```sh
96
- claude mcp add agentrica -- npx -y @agentrica/mcp@0.3.3 --panel
109
+ claude mcp add agentrica -- npx -y @agentrica/mcp@0.5.0 --panel
97
110
  ```
98
111
 
99
112
  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:
@@ -111,14 +124,32 @@ Con il pannello il modello ha due tool in più:
111
124
 
112
125
  Se la pagina non è aperta, `ask_user` la apre. Il client aspetta la risposta finché il server manda notifiche di avanzamento (fino a 4 ore; 25 minuti con un client che non le chiede), poi l'agente chiede nel terminale. Le domande del client, come i permessi dei tool, restano nel client.
113
126
 
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`.
127
+ **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, salvo le valutazioni che invii dalla pagina. 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
128
 
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.
129
+ **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
130
 
118
131
  - `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
132
  - 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
133
  - `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
134
 
135
+ ## Nuovo progetto
136
+
137
+ `init` crea un progetto con il metodo di lavoro di Agentrica, pronto per Claude Code:
138
+
139
+ ```sh
140
+ npx -y @agentrica/mcp@0.5.0 init mio-progetto --name "Mio progetto"
141
+ ```
142
+
143
+ Senza cartella usa quella corrente; senza `--name` il nome è quello della cartella. Scrive:
144
+
145
+ - `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»;
146
+ - `plan/` con `README.md` (decisioni, glossario, fasi) e `00-base.md`, la fase F0 da cui si parte; `audit/` e `docs/`;
147
+ - `agents/` e `.claude/agents/`: i 56 ruoli di questa versione e un subagent per ruolo, con il nome del progetto;
148
+ - `.github/workflows/ci.yml` (`npm run verify` e `verify:e2e`, saltati finché F0 non li crea), `.gitignore`, `.nvmrc`, `.env.example`;
149
+ - `.mcp.json` con questo server a versione esatta e `--panel`, così il pannello legge subito il piano.
150
+
151
+ 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ù.
152
+
122
153
  ## Messi alla prova
123
154
 
124
155
  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 +170,8 @@ Lo stesso catalogo si legge anche da codice, senza avviare il server: `import {
139
170
 
140
171
  ## Versioni
141
172
 
173
+ - **0.5.0**: valutazione degli agenti (tool `rate_agent` in due passi con anteprima e codice, sezione «Valuta gli agenti» nel pannello, proposta a fine lavoro e promemoria dopo 30 minuti), unica connessione del server e solo dopo la conferma; `--no-ratings` la toglie. L'agente dice chi è (nome in codice, ruolo, reparto) all'inizio, ai cambi e nel riepilogo.
174
+ - **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
175
  - **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
176
  - **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
177
  - **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
- // Pagina del pannello: legge /api/state, si aggiorna con /api/events e manda le risposte a /api/answer.
1
+ // Pagina del pannello: legge /api/state, si aggiorna con /api/events e manda le risposte a /api/answer e i voti a /api/rate.
2
2
  // I dati del progetto entrano nel DOM solo come testo (textContent), mai come HTML.
3
3
  "use strict";
4
4
 
@@ -132,12 +132,12 @@ function renderActivity({ activity }) {
132
132
  : el(
133
133
  "ol",
134
134
  { class: "activity" },
135
- activity.map((a) =>
135
+ activity.map((a, i) =>
136
136
  el(
137
137
  "li",
138
- { "data-dept": a.department },
138
+ { "data-dept": a.department, class: i === 0 ? "active" : null },
139
139
  el("time", { datetime: a.time, class: "mono" }, time(a.time)),
140
- el("span", { class: "dot" }, el("strong", {}, a.codeName), ` — ${a.role}`),
140
+ el("span", { class: "dot" }, el("strong", {}, a.codeName), ` — ${a.role}, reparto ${a.department}`, i === 0 && el("span", { class: "now" }, "attivo")),
141
141
  a.task && el("span", { class: "task" }, a.task),
142
142
  ),
143
143
  ),
@@ -145,6 +145,71 @@ function renderActivity({ activity }) {
145
145
  );
146
146
  }
147
147
 
148
+ // Un modulo per agente usato, creato una volta sola: un aggiornamento non deve cancellare un commento a metà.
149
+ function renderRatings({ activity, rating }) {
150
+ const card = $("ratings-card");
151
+ card.hidden = !rating;
152
+ if (!rating) return;
153
+ const box = $("ratings");
154
+ const agents = [...new Map(activity.map((a) => [a.id, a])).values()];
155
+ for (const agent of agents) {
156
+ const node = box.querySelector(`[data-agent="${CSS.escape(agent.id)}"]`);
157
+ const done = rating.rated.includes(agent.id);
158
+ if (!node) box.append(done ? ratedNote(agent) : rateForm(agent, rating));
159
+ else if (done && node.tagName === "FORM" && !node.dataset.sent) node.replaceWith(ratedNote(agent));
160
+ }
161
+ box.querySelector(".empty")?.remove();
162
+ if (!box.querySelector("[data-agent]")) box.append(empty("Quando usi un agente, qui puoi dargli un voto."));
163
+ }
164
+
165
+ const ratedNote = (agent) => el("p", { class: "sent", "data-agent": agent.id, "data-dept": agent.department }, el("strong", {}, agent.codeName), " — valutato in questa sessione.");
166
+
167
+ function rateForm(agent, rating) {
168
+ const name = `r-${agent.id}`;
169
+ const error = el("p", { class: "error", role: "alert", hidden: true });
170
+ const stars = [1, 2, 3, 4, 5].map((n) =>
171
+ el("label", { class: "star" }, el("input", { type: "radio", name, value: String(n) }), el("span", {}, `${n}`)),
172
+ );
173
+ const form = el(
174
+ "form",
175
+ { class: "question", "data-agent": agent.id, "data-dept": agent.department, onsubmit: (event) => sendRating(event, agent, form, error) },
176
+ el(
177
+ "fieldset",
178
+ {},
179
+ el("legend", {}, el("span", { class: "dot" }, el("strong", {}, agent.codeName)), ` — ${agent.role}, reparto ${agent.department}. Voto da 1 a 5:`),
180
+ el("div", { class: "stars" }, stars),
181
+ ),
182
+ el("label", { class: "note" }, "Cosa è andato bene o cosa migliorare (facoltativo)", el("textarea", { name: "comment", maxlength: String(rating.maxComment) })),
183
+ el("label", { class: "check" }, el("input", { type: "checkbox", name: "publish" }), "Puoi pubblicare il mio commento sul sito di Agentrica"),
184
+ el("p", { class: "hint" }, rating.notice),
185
+ el("button", { type: "submit", class: "send" }, "Invia la valutazione"),
186
+ error,
187
+ );
188
+ return form;
189
+ }
190
+
191
+ async function sendRating(event, agent, form, error) {
192
+ event.preventDefault();
193
+ const picked = form.querySelector("input[type=radio]:checked");
194
+ if (!picked) {
195
+ error.textContent = "Scegli un voto da 1 a 5.";
196
+ error.hidden = false;
197
+ return;
198
+ }
199
+ const body = { agentId: agent.id, rating: Number(picked.value), comment: form.elements.comment.value, publish: form.elements.publish.checked };
200
+ const response = await fetch("/api/rate", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) }).catch(() => null);
201
+ const result = response ? await response.json().catch(() => null) : null;
202
+ if (!result?.ok) {
203
+ error.textContent = result?.message ?? (response ? "Valutazione non valida." : "Il pannello non risponde: la sessione è ancora aperta?");
204
+ error.hidden = false;
205
+ return;
206
+ }
207
+ form.dataset.sent = "true";
208
+ form.replaceChildren(
209
+ el("p", { class: "sent", role: "status" }, `Valutazione di ${agent.codeName} inviata, grazie. Codice della valutazione: `, el("code", {}, result.usageId), ". Conservalo per chiedere di cancellarla o di non pubblicare il commento."),
210
+ );
211
+ }
212
+
148
213
  function table(head, rows) {
149
214
  return el(
150
215
  "div",
@@ -277,6 +342,7 @@ function render() {
277
342
  renderCounts(state);
278
343
  renderQuestions(state);
279
344
  renderActivity(state);
345
+ renderRatings(state);
280
346
  renderPhases(state);
281
347
  renderFilters();
282
348
  renderFindings(state);
@@ -36,6 +36,10 @@
36
36
  <h2 id="h-agents">Agenti in uso</h2>
37
37
  <div id="activity"></div>
38
38
  </section>
39
+ <section aria-labelledby="h-ratings" class="card" id="ratings-card" hidden>
40
+ <h2 id="h-ratings">Valuta gli agenti</h2>
41
+ <div id="ratings"></div>
42
+ </section>
39
43
  </div>
40
44
  </div>
41
45
 
@@ -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;
@@ -91,6 +91,14 @@ ol.activity { list-style: none; margin: 0; padding: 0; }
91
91
  ol.activity li { display: grid; grid-template-columns: 3.5em 1fr; gap: 0 8px; padding: 6px 0; border-top: 1px solid var(--border); }
92
92
  ol.activity li:first-child { border-top: 0; }
93
93
  .dot::before { content: "●"; color: var(--dept); margin-right: 6px; }
94
+ ol.activity li.active strong { color: var(--dept); }
95
+ .now { margin-left: 8px; font-size: 0.8rem; color: var(--background); background: var(--dept); border-radius: 999px; padding: 0 8px; font-weight: 600; }
96
+ .stars { display: flex; flex-wrap: wrap; gap: 6px; }
97
+ .star { display: inline-flex; align-items: center; gap: 4px; min-height: 44px; min-width: 44px; padding: 0 8px; border: 1px solid var(--border); border-radius: 8px; cursor: pointer; }
98
+ .star:has(input:checked) { border-color: var(--dept); color: var(--dept); font-weight: 700; }
99
+ .star input { accent-color: var(--dept); }
100
+ label.check { display: flex; gap: 8px; align-items: center; margin-top: 8px; }
101
+ #ratings .question + .question, #ratings .sent + .question, #ratings .question + .sent { margin-top: 12px; }
94
102
  .task { grid-column: 2; color: var(--muted-foreground); overflow-wrap: anywhere; }
95
103
 
96
104
  .scroll { overflow-x: auto; }
@@ -1,3 +1,4 @@
1
+ import { type SendResult } from "./ratings.ts";
1
2
  export interface Choice {
2
3
  label: string;
3
4
  description: string;
@@ -24,6 +25,18 @@ export interface Activity {
24
25
  department: string;
25
26
  task: string;
26
27
  }
28
+ /** Le valutazioni viste dal pannello (F20): il server MCP le passa, il pannello non apre connessioni da solo. */
29
+ export interface PanelRatings {
30
+ isRated(agentId: string): boolean;
31
+ /** Invia una valutazione confermata nella pagina. */
32
+ rate(input: RateInput): Promise<SendResult>;
33
+ }
34
+ export interface RateInput {
35
+ agentId: string;
36
+ rating: number;
37
+ comment: string;
38
+ publish: boolean;
39
+ }
27
40
  export interface Panel {
28
41
  /** URL con il token: apre la sessione del browser. */
29
42
  url: string;
@@ -35,6 +48,8 @@ export interface Panel {
35
48
  }
36
49
  /** Controlla una risposta della pagina contro la domanda: etichette esistenti, una sola se la scelta è singola. */
37
50
  export declare function parseAnswer(question: QuestionInput, body: unknown): Answer | null;
51
+ /** Controlla una valutazione dalla pagina: agente fra quelli usati, voto intero 1–5, commento corto, casella booleana. */
52
+ export declare function parseRate(used: ReadonlySet<string>, body: unknown): RateInput | null;
38
53
  /** Apre l'URL nel browser predefinito; se non riesce (es. sessione remota) l'URL resta nella risposta del tool. */
39
54
  export declare function openBrowser(url: string): void;
40
- export declare function startPanel(root: string, pageDir?: string): Promise<Panel>;
55
+ export declare function startPanel(root: string, ratings?: PanelRatings, pageDir?: string): Promise<Panel>;