# MCP / Skills / Agents Development Guide (viva)

Versione: 2026-04-03
Stato: **fonte di verita' attiva** per lo sviluppo futuro nel branch `rework`.

Questa guida sostituisce l'uso operativo della vecchia spec ibrida e separa in modo netto:

- linee guida vive (questo documento);
- storico milestone completate (`docs/completed-milestones-mcp-skills.md`);
- roadmap futura residua (Milestone 8+), con sintesi qui e dettaglio in `docs/future-backlog-mcp-skills.md`.

## 1) Ambito e obiettivo

Obiettivo: mantenere evolvibile l'ecosistema MCP/Skills/Agents senza rumore storico, preservando compatibilita' con host/client MCP severi (Codex, Copilot VS Code e equivalenti).

Guardrail permanenti:

1. compatibilita' legacy prima del refactor esteso;
2. cambi incrementali (una milestone/PR per volta);
3. no riscritture monolitiche fuori scope;
4. aggiornamento coerente di codice, test/smoke e documentazione.

## 2) Architettura viva (MCP + Skills + Agents)

### 2.1 Ruoli

- **Server MCP**: espongono tool/resources/prompts con schema robusti.
- **Skills**: workflow procedurali portabili, con trigger chiari.
- **Agenti `.codex/agents/`**: profili operativi di esecuzione (discovery, implementazione, analisi tecnica).

### 2.2 Routing canonico

- Task analitico multi-sorgente -> `mcp-technical-analyst`.
- Task multi-fase di coordinamento -> `mcp-master-orchestrator`.
- Task mono-dominio -> skill specialistica o server MCP dedicato.
- Task memoria operativa (hygiene/handoff/decision-log) -> `mcp-memory-operator`.

### 2.3 Distinzioni obbligatorie

- `mcp-master-orchestrator` coordina; non sostituisce intake analitico.
- `mcp-technical-analyst` gestisce intake multi-sorgente; non sostituisce skill esecutive.
- Le skill specialistiche eseguono dominio e raccolta evidenze mirate.

### 2.4 Policy globale docs-first

- Prima di concludere "nessuna documentazione trovata", eseguire almeno: `search` full-text, `list_tags`, `list_documents` con `include_tags: true` e `limit >= 50`.
- Nella discovery documentale dare priorita operativa ai tag (tag-first), poi usare titolo/path solo come fallback.
- Se la prima ricerca e vuota, fare una seconda passata bilingue IT+EN con sinonimi dominio (es. `sso`, `autenticazione/authentication`, `attivazione/activation`, `integrazione/integration`, `jwt`, `token`).

### 2.5 Motore Euristico e Routing Context-Aware (Codex Hooks)

L'indirizzamento iniziale dell'agente è potenziato da un **Motore Euristico (Codex Hooks)** locale (`scripts/hooks/`). Questo motore intercetta l'inizio della sessione e l'invio dei prompt per fornire suggerimenti (*hints*) testuali, non bloccanti, all'agente.

Meccanismi chiave da mantenere/evolvere:
- **Taxonomy Bootstrap (`SessionStart`):** L'agente è istruito a usare `docs-node` e `memory-node` all'avvio per scoprire la vera tassonomia del progetto e salvarla in un artifact (`project_taxonomy.md`). **Non hardcodare mai tag MCP esatti negli script.**
- **Intent Detection (`UserPromptSubmit`):** Priorità massima all'intento operativo. Se l'utente fa una domanda, chiede di documentare o di ricordare un'informazione, il motore suggerisce dinamicamente di consultare/scrivere rispettivamente in Docs o Memory MCP.
- **Domain Search Cues:** Il motore individua concetti dominio-specifici (es. `[sso/authentication]`) e suggerisce all'agente di cercare i tag reali corrispondenti nel suo artifact di tassonomia prima di eseguire query full-text.
- **Aggiornamento Catalogo:** Qualsiasi skill o intent aggiunto al catalogo (`routing-catalog.json`) va generato tramite lo script `generate-codex-hooks.js` e mai modificato a mano.

Dettaglio implementativo completo in: `docs/micro-milestone-codex-hooks-routing.md`

## 3) Convenzioni obbligatorie di compatibilita'

1. preservare pattern consolidati: `action`, `project_path`, `save_path` (salvo eccezioni motivate);
2. se introduci `roots`, mantenere fallback `project_path`;
3. se introduci resources/artifact URI, mantenere comportamento legacy quando richiesto;
4. input schema MCP compatibili con client strict;
5. ogni nodo schema con `type: "array"` deve dichiarare `items`.

## 4) Policy MCP (tools/resources/prompts/artifacts)

### 4.1 Tool

- preferire output duale: `content` breve + `structuredContent` stabile;
- separare chiaramente tool read-only da write-capable con annotations/hint coerenti;
- evitare shape ambigue negli input schema.

### 4.2 Resources e artifacts

- esporre resources quando il contenuto e' navigabile/riusabile;
- usare URI stabili e parseabili (`docs://...`, `artifact://...`);
- evitare blob/base64 lunghi in `content`, salvo necessita' esplicita.

### 4.3 Prompts MCP

- usare prompt per discoverability e kickoff rapidi;
- non sostituire forzatamente le skill nei workflow complessi;
- documentare sempre fallback skill equivalente.

Regola pratica: prompt MCP per ingresso rapido, skill per orchestrazione robusta e portabile.

## 5) Host/client compatibility discipline

Requisiti minimi per modifiche MCP:

- `tools/list` e schema input validabili da host severi;
- fallback documentati per feature MCP non uniformemente supportate;
- esplicitazione rischio cross-host in PR (`Basso/Medio/Alto` + motivazione).

Riferimenti operativi:

- `docs/server-capability-matrix.md`
- `docs/pr-checklist-mcp.md`
- `docs/mcp-runtime-upgrade-governance.md`

## 6) Test strategy e review discipline

Per ogni server/skill modificato:

1. smoke test/initialize + caso felice + caso errore;
2. validazione schema input (incluso controllo array/items);
3. se cambia stato persistente, test migration su stato vuoto e legacy;
4. se cambiano dipendenze, setup workspace rieseguito o impatto documentato;
5. aggiornamento test/eval/documentazione locale;
6. checklist PR compilata.

Per skill core:

- trigger correctness (corretto/mancato/abuso);
- routing correctness (analyst vs orchestrator vs specialistico);
- output verificabile con separazione fatti/inferenze/punti aperti dove previsto.

## 7) Evoluzione operativa

### 7.1 Nuovi server MCP

Processo consigliato:

1. capability baseline + rischio compatibilita';
2. design schema tool/resources/prompts con fallback legacy;
3. design upgrade runtime: setup dipendenze, storage locale, migration/versioning se persistente;
4. smoke + test schema + docs locali;
5. aggiornamento capability matrix e PR checklist evidence.

### 7.1.1 Upgrade runtime e stato persistente

Policy canonica: `docs/mcp-runtime-upgrade-governance.md`.

Regole sintetiche:

- dopo update repository, il percorso supportato e' rilanciare `setup.ps1` o `setup.sh`, poi riavviare server/client MCP;
- i server non installano dipendenze npm o asset esterni durante l'avvio ordinario;
- ogni storage persistente evolvibile deve avere baseline legacy e migrazioni versionate non distruttive prima della prima modifica schema;
- le cache rigenerabili devono essere documentate come tali e separate dai dati utente non rigenerabili;
- PR che cambia schema/storage/dipendenze native deve includere test upgrade e nota restart/setup.

### 7.2 Evoluzione skill esistenti

- `SKILL.md` breve e triggerabile;
- dettagli estesi in `references/`;
- `scripts/` dove la procedura e' deterministica/ripetitiva;
- eval minimi per skill ad alto uso.

### 7.2.1 Token Diet MCP/Skill

Budget consigliati per ridurre rumore nei client MCP:

- tool `description`: massimo 120 caratteri quando possibile;
- param `description`: massimo 90 caratteri;
- prompt `description`: massimo 140 caratteri;
- skill frontmatter `description`: massimo 400-600 caratteri;
- corpo `SKILL.md`: quick routing in alto, procedure lunghe in `references/`.

Non comprimere via omissione informazioni critiche: sicurezza, `destructiveHint`, `project_path`, `save_path`, `allowed_roots`/`allowedRoots` e fallback legacy devono restare espliciti.

### 7.3 Nuovi profili in `.codex/agents/`

- profili stretti e non generici;
- confini anti-overlap espliciti;
- limiti di parallelismo/profondita' dichiarati;
- coerenza con routing skill (analyst/orchestrator/specialistiche).

Riferimento locale: `.codex/agents/README.md`.

### 7.4 Link runtime utente

Per sviluppo locale e bootstrap rapido e' disponibile:

```bash
./link-user-runtime.sh --dry-run
./link-user-runtime.sh
```

Lo script ricava automaticamente l'utente target (`SUDO_USER` quando presente,
altrimenti `id -un`) e crea link non distruttivi per skill e agenti Codex /
Copilot nel profilo utente. Per Codex mantiene anche il target canonico
`$HOME/.agents/skills`.

## 8) Backlog futuro residuo (attivo)

Questa guida considera **attivo** solo il backlog post-M7:

- **Milestone 8**: packaging/distribuzione e razionalizzazione configurazioni host-specifiche.

Dettaglio operativo futuro:

- `docs/future-backlog-mcp-skills.md`

Il dettaglio storico M0-M7 e' stato spostato in:

- `docs/completed-milestones-mcp-skills.md`

## 9) Mappa documentale minima

- Guida viva: `docs/mcp-skills-agents-development-guide.md`
- Storico milestone completate: `docs/completed-milestones-mcp-skills.md`
- Backlog futuro (dettaglio M8+): `docs/future-backlog-mcp-skills.md`
- Capability matrix server: `docs/server-capability-matrix.md`
- Governance matrix skill: `docs/skill-governance-matrix.md`
- PR checklist: `docs/pr-checklist-mcp.md`
- Regole concise di ingaggio: `AGENTS.md`
- Profili agenti Codex: `.codex/agents/README.md`