# Future backlog MCP / Skills (dettaglio operativo) Versione: 2026-05-11 Stato: backlog **attivo** con M11 e M12 archiviate (focus residuo: M8). Questo documento raccoglie il dettaglio operativo della milestone futura ancora aperta (M8), separato dalla guida viva per mantenere leggibilita' e ridurre rumore. ## Milestone 8 - Packaging, distribuzione e runtime utente cross-workspace ### Obiettivo Standardizzare packaging, installazione e configurazione host-specifica per rendere server MCP, skill e profili agentici riusabili fuori dal repository `mcp-servers`, senza duplicare configurazioni e senza degradare il setup locale esistente. La milestone deve coprire in modo esplicito tre scenari: 1. ambiente con **Codex** disponibile; 2. ambiente con **VS Code / GitHub Copilot** disponibile; 3. ambiente misto, con Codex e Copilot entrambi disponibili. Il repository `mcp-servers` deve essere trattato come **sorgente e contenitore degli asset riusabili**, non come unico workspace operativo. Le skill devono poter essere installate o linkate nel profilo utente e poi usate in qualsiasi altro repository. --- ## Principi obbligatori 1. **Node.js only per gli script di automazione.** Tutti gli script nuovi o modificati in questa milestone devono essere JavaScript/Node.js. Non introdurre script Python per installazione, export, merge, validazione o hook runtime. 2. **Nessuna operazione distruttiva di default.** Gli script non devono mai sovrascrivere file utente esistenti senza backup e senza merge conservativo. Questo vale in particolare per: - `~/.codex/hooks.json` - `~/.codex/config.toml` - cartelle skill utente - cartelle agenti utente - eventuali configurazioni Copilot o VS Code. 3. **Host opzionali.** La presenza di Codex non deve essere obbligatoria per installare asset Copilot. La presenza di Copilot non deve essere obbligatoria per installare asset Codex. 4. **Runtime generati, non editati a mano.** Gli output host-specifici devono essere generati da sorgenti canoniche versionate nel repo. Le modifiche manuali ai target runtime devono essere considerate eccezioni operative. 5. **Skill come installazione primaria, hook come booster.** Per Codex, la disponibilita' cross-workspace delle skill deve basarsi su `$HOME/.agents/skills`. `~/.codex/hooks.json` puo' migliorare routing, contesto e suggerimenti, ma non deve sostituire l'installazione reale delle skill. 6. **Copilot gestito con target dedicati.** `hooks.json` e' Codex-specifico. Per VS Code / Copilot usare target dedicati: - `.copilot/agents/*.agent.md` - configurazione MCP utente o workspace - eventuali instruction/prompt file generati o copiati in modo conservativo. 7. **Dry-run prima di scrivere.** Ogni comando di installazione deve supportare `--dry-run` e mostrare quali file verrebbero creati, aggiornati, saltati o sottoposti a backup. 8. **Idempotenza.** Rieseguire lo stesso script due volte non deve produrre duplicati, drift o sovrascritture non necessarie. 9. **CLI-first, interattivita' come wrapper.** L'installer deve funzionare sempre in modalita' headless da CLI. La modalita' interattiva passo-passo e l'eventuale GUI grafica devono usare lo stesso core dell'installer, senza duplicare la logica di installazione. --- ## Architettura target ### Sorgenti canoniche nel repository Il repository deve mantenere sorgenti canoniche versionate: ```text skills/* .codex/agents/* .copilot/agents/* docs/skills/skill-index.md docs/agents/portable-agents-index.md docs/runtime/user-runtime.schema.md scripts/* ``` Nota di standard: per le skill, la forma portabile Anthropic resta la directory `/SKILL.md` con frontmatter YAML `name` e `description`, piu' eventuali risorse progressive in `scripts/`, `references/` e `assets/`. File YAML separati di registry o routing non sono standard Anthropic; se servono, vanno trattati come metadati locali/host-specifici o come output derivati. ### Core installer riusabile La logica di installazione deve essere separata dall'interfaccia utente. Struttura consigliata: ```text scripts/runtime/install-plan.js # calcola piano operazioni scripts/runtime/apply-plan.js # applica piano operazioni scripts/runtime/report.js # report human-readable e JSON scripts/install-user-runtime.js # CLI wrapper headless/interattivo ``` Regole: - `install-plan.js` non deve scrivere file; - `apply-plan.js` deve ricevere un piano gia' validato; - `report.js` deve produrre sia output testuale sia JSON machine-readable; - la modalita' `--interactive` e una futura GUI devono invocare questi moduli; - nessuna logica di merge, backup o path policy deve vivere solo nella GUI o nel wizard. ### Target runtime utente Codex Per Codex, l'installazione utente deve poter generare o aggiornare: ```text $HOME/.agents/skills// $HOME/.codex/hooks.json $HOME/.codex/config.toml $HOME/.codex/hooks/*.mjs $HOME/.codex/agents/*.toml ``` Su Windows: ```text C:\Users\\.agents\skills\\ C:\Users\\.codex\hooks.json C:\Users\\.codex\config.toml C:\Users\\.codex\hooks\*.mjs C:\Users\\.codex\agents\*.toml ``` ### Target runtime utente Copilot / VS Code Per Copilot / VS Code, l'installazione deve poter generare o aggiornare, in base al setup scelto: ```text /*.agent.md /* ``` La milestone non deve imporre una singola directory utente Copilot se l'ambiente non la rende stabile. Lo script deve supportare: - export esplicito verso una directory passata con flag; - copia locale nel repo quando richiesto; - stampa di snippet da incollare manualmente quando non e' sicuro modificare configurazioni utente. --- ## Ruolo di `hooks.json` ### Decisione Introdurre `hooks.json` come **target generato opzionale per Codex user runtime**, non come fonte di verita' e non come registry primario delle skill. Nota 2026-05-13: prima della Fase 3 completa e' prevista una micro-milestone intermedia per generare soltanto un `hooks.json` Codex ispezionabile, con script hook versionati nel repository e installazione manuale a cura dell'utente. Questa micro-milestone non modifica `~/.codex/hooks.json`, non effettua merge automatico e non patcha `~/.codex/config.toml`. Il merge conservativo automatico di `hooks.json` e la patch `codex_hooks = true` restano obiettivi della M8 piena. `hooks.json` serve a: - caricare contesto iniziale leggero sul runtime Sophia MCP/Skills; - migliorare il routing verso skill specifiche quando il prompt contiene segnali forti; - ricordare all'agente che le skill sono installate sotto `$HOME/.agents/skills`; - evitare che l'utente debba ripetere manualmente ogni volta quali skill usare. `hooks.json` non deve: - copiare o installare skill; - contenere tutto il contenuto delle skill; - duplicare `SKILL.md`; - sostituire i trigger delle skill; - bloccare prompt salvo regole esplicitamente documentate in una milestone separata. ### Eventi hook iniziali ammessi #### `SessionStart` Usare `SessionStart` per fornire contesto breve e stabile. Esempio di comportamento dello script: ```json { "hookSpecificOutput": { "hookEventName": "SessionStart", "additionalContext": "Sophia MCP skills may be installed under ~/.agents/skills. Prefer explicit local skills for task-specific workflows; use portable agents only as role baselines." } } ``` #### `UserPromptSubmit` Usare `UserPromptSubmit` per routing leggero e non vincolante. Esempio di comportamento dello script: ```json { "hookSpecificOutput": { "hookEventName": "UserPromptSubmit", "additionalContext": "The prompt looks like multi-source technical analysis. Consider using $mcp-technical-analyst if available." } } ``` Regole: - il matcher non deve essere usato come meccanismo principale per `UserPromptSubmit`; - lo script deve leggere lo stdin JSON; - lo script deve restituire contesto aggiuntivo solo quando c'e' un match abbastanza forte; - in assenza di match deve uscire con successo senza output; - non bloccare prompt nella prima iterazione. --- ## Indice skill e manifest derivati ### Nuovo file umano Aggiungere: ```text docs/skills/skill-index.md ``` ### Scopo L'indice deve documentare le skill installabili o linkabili nel runtime utente, senza diventare la fonte primaria dei trigger. La fonte primaria resta sempre `skills//SKILL.md`, in particolare il campo `description`, coerente con lo standard Anthropic. Formato consigliato: ```markdown | Skill | Path | Installazione Codex | Riferimento Copilot | Note routing | | --- | --- | --- | --- | --- | | mcp-technical-analyst | skills/mcp-technical-analyst | si | si | Analisi tecnica multi-sorgente; evitare per modifiche puntuali gia' definite. | ``` Per automazione Node, gli script devono leggere direttamente: - le directory `skills/*`; - il frontmatter di ogni `SKILL.md`; - l'indice Markdown solo per metadati operativi non esprimibili nello standard skill Anthropic. Se serve un formato macchina, generare un manifest derivato in JSON sotto `docs/runtime/` o in una directory build/cache esplicita. Non introdurre YAML di registry come fonte di verita' per le skill. Regole: - il nome skill deve coincidere con il frontmatter `name` e con la directory, salvo eccezioni legacy documentate; - ogni path deve puntare a una directory contenente `SKILL.md`; - i segnali routing duplicati nell'indice devono restare sintetici e secondari; - le opzioni host-specifiche devono essere dichiarate come metadati locali, non come parte dello standard Anthropic; - non inserire path assoluti nell'indice o nei manifest derivati. --- ## Script Node richiesti ### 1. `scripts/install-user-runtime.js` Script principale di installazione/export. #### Esempi ```bash node scripts/install-user-runtime.js --dry-run node scripts/install-user-runtime.js --codex node scripts/install-user-runtime.js --copilot --copilot-agents-dir "C:\Users\davide\Documents\CopilotAgents" node scripts/install-user-runtime.js --all --use-symlinks node scripts/install-user-runtime.js --all --copy-skills node scripts/install-user-runtime.js --interactive node scripts/install-user-runtime.js --interactive --all node scripts/install-user-runtime.js --all --dry-run --json ``` #### Flag richiesti ```text --dry-run --codex --copilot --all --interactive --json --use-symlinks --copy-skills --backup --force --repo-root --home --copilot-agents-dir --print-snippets ``` #### Semantica dei flag - `--dry-run`: non scrive nulla. - `--codex`: abilita solo target Codex. - `--copilot`: abilita solo target Copilot. - `--all`: abilita tutti i target disponibili. - `--interactive`: avvia un wizard passo-passo da terminale, basato sullo stesso core dell'installer. - `--json`: produce report machine-readable per test, automazioni o wrapper GUI. - `--use-symlinks`: crea symlink/junction quando possibile. - `--copy-skills`: copia le skill invece di linkarle. - `--backup`: crea backup prima di modificare file esistenti. - `--force`: permette aggiornamenti che altrimenti sarebbero saltati, ma sempre con backup se il file esiste. - `--repo-root`: permette esecuzione da cartelle diverse. - `--home`: utile per test o profili non standard. - `--copilot-agents-dir`: directory esplicita per export agenti Copilot. - `--print-snippets`: stampa snippet configurazione invece di scrivere file host-specifici. #### Regole non distruttive Lo script deve classificare ogni operazione come: ```text CREATE UPDATE MERGE SKIP BACKUP WARNING ERROR ``` Non deve mai: - eliminare file utente; - sostituire `hooks.json` interamente se contiene hook non gestiti dal repo; - sostituire `config.toml` interamente; - duplicare voci gia' installate; - modificare configurazioni Copilot se non e' stata passata una destinazione esplicita o un flag dedicato. #### Modalita' interattiva CLI-first La modalita' `--interactive` deve guidare l'utente passo-passo senza cambiare il contratto CLI. Flusso minimo richiesto: 1. rilevazione non distruttiva di OS, home, repo-root e host disponibili; 2. scelta target: Codex, Copilot, entrambi; 3. scelta modalita' skill: symlink/junction oppure copia; 4. raccolta directory Copilot quando necessaria; 5. scelta backup/force quando servono; 6. generazione piano; 7. visualizzazione dry-run con operazioni classificate; 8. conferma esplicita prima di qualsiasi scrittura; 9. report finale separato per host. Regole: - senza conferma esplicita non scrivere nulla; - se l'ambiente non e' interattivo, fallire con messaggio chiaro o richiedere flag headless; - il wizard non deve nascondere warning o errori del piano; - il wizard deve poter essere ricostruito come sequenza equivalente di flag CLI; - su Windows e Ubuntu il flusso deve restare lo stesso, cambiando solo path e capability rilevate. --- ### 2. `scripts/generate-codex-hooks.js` Genera il frammento Codex hook gestito dal repo. Input: - directory `skills/*` e frontmatter `SKILL.md` - `docs/skills/skill-index.md` solo per metadati locali opzionali - template hook in `scripts/templates/codex-hooks.template.json` Output: - oggetto JSON da mergiare in `~/.codex/hooks.json` - script `.mjs` sotto `~/.codex/hooks/` Esempio output gestito: ```json { "hooks": { "SessionStart": [ { "matcher": "startup|resume", "hooks": [ { "type": "command", "command": "node \"C:\\Users\\davide\\.codex\\hooks\\mcp-skills-session-start.mjs\"", "timeout": 10, "statusMessage": "Loading Sophia MCP skill routing" } ] } ], "UserPromptSubmit": [ { "hooks": [ { "type": "command", "command": "node \"C:\\Users\\davide\\.codex\\hooks\\mcp-skills-user-prompt-submit.mjs\"", "timeout": 10, "statusMessage": "Checking Sophia MCP skill routing" } ] } ] } } ``` Regole: - usare `node`, non `python`; - generare path quotati e compatibili Windows; - non assumere che il cwd sia il repository `mcp-servers`; - gli script hook devono essere autonomi rispetto al workspace corrente; - in caso di errore devono fallire in modo conservativo, evitando blocchi. --- ### 3. `scripts/merge-codex-hooks.js` Merge conservativo di `hooks.json`. #### Comportamento Se `~/.codex/hooks.json` non esiste: - creare un nuovo file valido. Se esiste: - leggere e validare JSON; - preservare tutti gli hook non gestiti; - aggiornare solo il blocco gestito dal repo; - evitare duplicati; - creare backup prima della scrittura. #### Marcatori gestiti Usare marcatori nei comandi o nei metadata per riconoscere gli hook gestiti. Esempio: ```json { "type": "command", "command": "node \"C:\\Users\\davide\\.codex\\hooks\\mcp-skills-session-start.mjs\"", "timeout": 10, "statusMessage": "Loading Sophia MCP skill routing" } ``` Il merge deve considerare gestiti gli hook che richiamano: - `mcp-skills-session-start.mjs` - `mcp-skills-user-prompt-submit.mjs` Non introdurre commenti in JSON. --- ### 4. `scripts/merge-codex-config.js` Merge conservativo di `~/.codex/config.toml`. #### Obiettivo Abilitare, se richiesto, il feature flag: ```toml [features] codex_hooks = true ``` #### Regole Se `config.toml` non esiste: - crearlo con il minimo necessario. Se esiste: - preservare tutto il contenuto; - aggiungere `[features]` solo se manca; - aggiungere `codex_hooks = true` solo se manca; - se `codex_hooks = false` e non c'e' `--force`, non modificarlo: emettere warning; - se `codex_hooks = false` e c'e' `--force`, cambiare a `true` con backup; - non riordinare il file intero; - non riformattare sezioni non gestite. Prima iterazione ammessa: - parser TOML minimale line-based; - niente dipendenza pesante se non necessaria; - test con casi Windows path e file gia' popolati. --- ### 5. `scripts/install-user-skills.js` Installa o linka le skill nel profilo utente Codex. Target: ```text $HOME/.agents/skills/ ``` #### Modalita' symlink Preferita per sviluppo locale: ```bash node scripts/install-user-skills.js --use-symlinks ``` Regole: - su Windows usare junction o symlink directory in modo compatibile; - se il target esiste gia': - se punta gia' alla stessa sorgente, `SKIP`; - se e' un symlink diverso, warning e nessuna modifica senza `--force`; - se e' una directory reale, warning e nessuna modifica senza `--force`; - non cancellare mai una directory skill utente. #### Modalita' copia Preferita per distribuzione stabile: ```bash node scripts/install-user-skills.js --copy-skills ``` Regole: - copiare solo file della skill; - non copiare file temporanei; - se il target esiste, creare backup o usare directory versionata; - non fondere parzialmente directory skill senza strategia esplicita. --- ### 6. `scripts/export-copilot-runtime.js` Esporta runtime Copilot / VS Code. Input: - `.codex/agents/*` - `docs/agents/portable-agents-index.md` solo per metadati locali opzionali - `.copilot/agents/*.agent.md` - eventuali template istruzioni Copilot Output: - copia o generazione in directory passata da `--copilot-agents-dir`; - snippet MCP se richiesto; - report delle operazioni. Esempio: ```bash node scripts/export-copilot-runtime.js --copilot-agents-dir "C:\Users\davide\Documents\CopilotAgents" ``` Regole: - se la directory non esiste, crearla solo dopo conferma implicita del flag; - se i file esistono, aggiornarli solo se sono gestiti e con backup; - non assumere che Codex sia installato; - non scrivere in directory VS Code globali non dichiarate esplicitamente; - supportare `--print-snippets` per ambienti dove la configurazione va gestita manualmente. --- ### 7. `scripts/check-user-runtime.js` Validazione locale non distruttiva. Controlla: - manifest skill valido; - skill referenziate esistenti; - ogni skill ha `SKILL.md`; - target Codex generabili; - target Copilot generabili; - `hooks.json` generato e mergiato senza duplicati; - `config.toml` patchabile senza perdita contenuto; - script hook `.mjs` sintatticamente validi; - dry-run coerente; - equivalenza tra piano headless e piano generato dal wizard interattivo. Esempio: ```bash node scripts/check-user-runtime.js node scripts/check-user-runtime.js --home "C:\Users\davide" --codex node scripts/check-user-runtime.js --copilot --copilot-agents-dir "C:\Users\davide\Documents\CopilotAgents" ``` --- ## Installer grafico opzionale ### Decisione La GUI grafica e' ammessa come **wrapper opzionale**, non come requisito bloccante per chiudere M8. La priorita' di M8 resta: 1. core installer headless; 2. report JSON; 3. wizard interattivo da terminale; 4. documentazione Windows/Ubuntu; 5. eventuale GUI solo se non introduce logica duplicata. ### Requisiti minimi per una futura GUI Se viene introdotta nella M8 o in una M8.1, la GUI deve: - invocare lo stesso core Node dell'installer CLI; - mostrare il piano prima di applicarlo; - visualizzare le stesse categorie `CREATE`, `UPDATE`, `MERGE`, `SKIP`, `BACKUP`, `WARNING`, `ERROR`; - richiedere conferma esplicita prima di scrivere; - funzionare almeno come wrapper locale su Windows e Ubuntu; - non richiedere privilegi elevati salvo casi documentati; - non scrivere configurazioni globali VS Code/Copilot senza path esplicito; - generare un comando CLI equivalente per riproducibilita'; - usare `--json` o API interna stabile, non parsing fragile dell'output testuale. ### Non requisiti GUI per M8 Non sono richiesti per la chiusura della milestone: - packaging desktop firmato; - auto-update; - distribuzione via store; - integrazione shell; - installer con privilegi amministrativi; - telemetria; - gestione remota/team. --- ## Script hook Node richiesti Gli hook runtime devono essere `.mjs` o `.js`, non Python. ### `mcp-skills-session-start.mjs` Responsabilita': - leggere manifest runtime generato; - verificare che le skill utente principali siano presenti o linkate; - produrre `additionalContext` breve; - non bloccare la sessione; - non accedere al workspace corrente salvo necessita' futura documentata. Output massimo consigliato: - meno di 1.500 caratteri; - nessun dump del manifest completo; - nessuna lista lunga di skill. ### `mcp-skills-user-prompt-submit.mjs` Responsabilita': - leggere stdin JSON; - estrarre `prompt`; - applicare routing euristico semplice su trigger dal manifest; - se match forte, produrre `additionalContext`; - se match debole o nullo, nessun output; - non bloccare la richiesta. Esempio logica: - prompt con `ticket`, `documentazione`, `commit`, `root cause` -> suggerire `mcp-technical-analyst`; - prompt con `piano`, `multi fase`, `coordina`, `handoff` -> suggerire `mcp-master-orchestrator`; - prompt con `review`, `diff`, `PR`, `regressione` -> suggerire `mcp-code-reviewer`; - prompt con `Mantis`, `Riassunto`, `Descrizione`, `Passaggi` -> suggerire `mcp-mantis-ticket-writer`; - prompt con `ColdFusion`, `CFML`, `Platform`, `cfcomponent` -> suggerire `mcp-coldfusion-developer`. Regole: - il suggerimento deve essere non vincolante; - non suggerire piu' di due skill; - in caso di ambiguita', preferire `mcp-master-orchestrator` solo se il prompt e' chiaramente multi-fase; - non inventare skill non presenti nel manifest. --- ## Gestione ambienti parziali ### Solo Codex Se l'utente esegue: ```bash node scripts/install-user-runtime.js --codex ``` Lo script deve: - installare/linkare skill in `$HOME/.agents/skills`; - generare hook Node; - mergiare `~/.codex/hooks.json`; - patchare `~/.codex/config.toml` solo in modo conservativo; - non toccare target Copilot. ### Solo Copilot Se l'utente esegue: ```bash node scripts/install-user-runtime.js --copilot --copilot-agents-dir "" ``` Lo script deve: - esportare agenti `.agent.md`; - stampare o generare snippet MCP; - non creare `.codex`; - non creare `.agents/skills` salvo flag esplicito; - non richiedere Codex installato. ### Codex + Copilot Se l'utente esegue: ```bash node scripts/install-user-runtime.js --all --use-symlinks --copilot-agents-dir "" ``` Lo script deve: - eseguire prima validazione sorgenti; - installare skill Codex utente; - esportare hook Codex; - esportare agenti Copilot; - produrre un report finale separato per host. ### Wizard interattivo Se l'utente esegue: ```bash node scripts/install-user-runtime.js --interactive ``` Lo script deve: - proporre gli stessi scenari supportati dai flag headless; - mostrare sempre il piano prima della scrittura; - permettere uscita senza modifiche in ogni momento prima della conferma finale; - indicare il comando CLI equivalente alla selezione fatta; - supportare Windows e Ubuntu con path normalizzati nel riepilogo. ### Nessun host rilevato Lo script deve: - non fallire se non c'e' configurazione esistente; - in `--dry-run` mostrare cosa creerebbe; - senza flag espliciti, suggerire i comandi disponibili; - non creare automaticamente cartelle host-specifiche senza intenzione dell'utente. --- ## Backup e rollback Ogni modifica a file utente esistente deve creare backup quando: - `--backup` e' presente; - `--force` e' presente; - lo script deve modificare un file che contiene contenuto non gestito. Formato backup: ```text .bak. ``` Esempi: ```text hooks.json.bak.20260427-153000 config.toml.bak.20260427-153000 explorer.agent.md.bak.20260427-153000 ``` La milestone deve includere una procedura di rollback documentata: ```bash node scripts/install-user-runtime.js --dry-run ``` e istruzioni manuali: - ripristinare il backup; - rimuovere solo i file gestiti; - non cancellare directory utente intere. --- ## File gestiti e ownership Aggiungere un piccolo manifest runtime generato: ```text $HOME/.codex/mcp-skills-runtime.manifest.json ``` Contenuto minimo: ```json { "managedBy": "sophiadeveloper/mcp-servers", "version": 1, "repoRoot": "D:\\mcp-servers", "installedAt": "2026-04-27T00:00:00.000Z", "codex": { "skillsDir": "C:\\Users\\davide\\.agents\\skills", "hooksJson": "C:\\Users\\davide\\.codex\\hooks.json", "configToml": "C:\\Users\\davide\\.codex\\config.toml" }, "copilot": { "agentsDir": null }, "files": [ { "path": "C:\\Users\\davide\\.codex\\hooks\\mcp-skills-session-start.mjs", "kind": "hook-script" } ] } ``` Regole: - il manifest serve solo a riconoscere asset gestiti; - non deve essere necessario per usare le skill; - se manca, gli script devono poter ricostruire lo stato in modo conservativo. --- ## Configurazione MCP host-specifica La milestone deve ridurre duplicazioni tra host. ### Codex Produrre snippet o patch per configurazione MCP Codex solo se richiesto. Non mescolare questo lavoro con `hooks.json`. ### VS Code / Copilot Produrre snippet compatibili con configurazione utente o workspace. Regole: - non modificare automaticamente `.vscode/mcp.json` in altri workspace; - preferire snippet documentati; - se viene passato un path esplicito, applicare merge conservativo; - mantenere `stdio` come default locale. --- ## Aggiornamenti documentali richiesti Aggiornare o creare: ```text docs/user-runtime-installation.md docs/codex-user-hooks.md docs/copilot-user-runtime.md docs/skills/skill-index.md docs/runtime/user-runtime.schema.md ``` ### `docs/user-runtime-installation.md` Deve spiegare: - installazione Codex only; - installazione Copilot only; - installazione mista; - installazione interattiva passo-passo da terminale; - differenza tra installer headless, wizard interattivo e GUI opzionale; - dry-run; - backup; - rollback; - differenza tra symlink e copia; - troubleshooting Windows; - troubleshooting Ubuntu. ### `docs/codex-user-hooks.md` Deve spiegare: - perche' `hooks.json` e' opzionale; - perche' non sostituisce `$HOME/.agents/skills`; - come funziona `SessionStart`; - come funziona `UserPromptSubmit`; - come disabilitare o rimuovere gli hook gestiti. ### `docs/copilot-user-runtime.md` Deve spiegare: - come esportare `.agent.md`; - come configurare MCP in VS Code / Copilot; - limiti rispetto a Codex hooks; - come mantenere parita' semantica con i subagent canonici. --- ## Validazione automatica Estendere la checklist PR con: ```text node scripts/check-skill-evals-json.js node scripts/sync-portable-agents.js node scripts/check-agents-doc.js node scripts/check-user-runtime.js node scripts/install-user-runtime.js --dry-run --all node scripts/install-user-runtime.js --interactive --dry-run node scripts/install-user-runtime.js --all --dry-run --json ``` I check devono essere eseguibili senza modificare il profilo utente reale. Per questo devono supportare: ```bash --home --copilot-agents-dir --dry-run ``` Per `--interactive --dry-run`, i test possono simulare input standard o usare una modalita' fixture documentata. L'obiettivo e' verificare che il wizard produca lo stesso piano del comando headless equivalente. --- ## Non obiettivi Questa milestone non deve: - introdurre un nuovo package manager; - imporre Codex a chi usa solo Copilot; - imporre Copilot a chi usa solo Codex; - riscrivere le skill esistenti; - introdurre script Python; - sovrascrivere configurazioni utente; - trasformare `hooks.json` nel registro canonico delle skill; - bloccare prompt utente tramite hook nella prima iterazione; - modificare workspace esterni senza path esplicito; - introdurre distribuzione remota prima di aver stabilizzato runtime locale; - rendere obbligatoria una GUI grafica per usare l'installer; - duplicare nella GUI logica gia' presente nel core Node. --- ## Piano operativo consigliato ### Fase 1 - Indice skill e validazione Deliverable: - `docs/skills/skill-index.md` - `scripts/check-user-runtime.js` - test fixture con home temporanea Criteri: - tutte le skill indicizzate esistono; - ogni skill ha `SKILL.md`; - nessun path assoluto nell'indice o nei manifest derivati. ### Fase 2 - Installazione skill Codex user Deliverable: - `scripts/install-user-skills.js` - supporto symlink/copia; - dry-run; - backup/report. Criteri: - installazione in `$HOME/.agents/skills`; - nessuna cancellazione; - idempotenza verificata. ### Fase 3 - Hooks Codex Node Nota: la micro-milestone `docs/micro-milestone-codex-hooks-routing.md` copre solo il sotto-step iniziale di generazione manuale (`generate-codex-hooks.js` + hook `.mjs` + documentazione). Non chiude questa fase: il merge automatico conservativo resta qui. Deliverable: - `scripts/generate-codex-hooks.js` - `scripts/merge-codex-hooks.js` - hook `.mjs` - doc `docs/codex-user-hooks.md` Criteri: - merge conservativo di `hooks.json`; - supporto file gia' esistente; - nessun Python; - nessun blocco prompt. ### Fase 4 - Config Codex TOML Deliverable: - `scripts/merge-codex-config.js` Criteri: - abilita `codex_hooks = true` solo in modo conservativo; - preserva config esistente; - non modifica `codex_hooks = false` senza `--force`. ### Fase 5 - Copilot runtime Deliverable: - `scripts/export-copilot-runtime.js` - doc `docs/copilot-user-runtime.md` Criteri: - funziona senza Codex; - esporta `.agent.md`; - produce snippet MCP; - non scrive path globali non dichiarati. ### Fase 6 - Core installer e installer unico headless Deliverable: - `scripts/runtime/install-plan.js` - `scripts/runtime/apply-plan.js` - `scripts/runtime/report.js` - `scripts/install-user-runtime.js` - report finale unificato testuale e JSON Criteri: - `--codex`, `--copilot`, `--all`; - `--dry-run`; - `--json`; - `--home`; - `--backup`; - supporto ambienti parziali; - core riusabile senza dipendere dal wrapper CLI. ### Fase 7 - Wizard interattivo CLI-first Deliverable: - `scripts/install-user-runtime.js --interactive` - prompt passo-passo per Windows/Ubuntu - visualizzazione piano dry-run prima della scrittura - comando CLI equivalente nel riepilogo Criteri: - nessuna scrittura senza conferma esplicita; - supporto Codex only, Copilot only e misto; - warning/errori visibili prima della conferma; - piano equivalente alla modalita' headless; - testabile con home temporanea. ### Fase 8 - GUI grafica opzionale o M8.1 Deliverable eventuali: - wrapper grafico locale basato sul core installer; - lettura piano/report via JSON; - conferma esplicita prima dell'applicazione. Criteri: - non blocca la chiusura M8 se il wizard CLI-first e' completo; - nessuna duplicazione della logica di installazione; - supporto minimo Windows/Ubuntu se incluso nella milestone. --- ## Criteri di accettazione finali La milestone si considera chiusa quando: - esiste un indice delle skill installabili, derivato dallo standard Anthropic `SKILL.md` e non sostitutivo del frontmatter; - le skill possono essere linkate o copiate in `$HOME/.agents/skills`; - `hooks.json` Codex viene generato e mergiato senza distruggere hook esistenti; - `config.toml` Codex viene patchato senza sovrascrivere configurazioni esistenti; - tutti gli hook runtime sono Node.js; - Copilot puo' ricevere agenti e snippet senza richiedere Codex; - Codex puo' ricevere skill e hook senza richiedere Copilot; - il setup misto funziona con un unico comando; - il setup interattivo passo-passo funziona da terminale su Windows e Ubuntu; - tutti gli script supportano dry-run; - l'installer produce un report JSON utilizzabile da test e futuri wrapper GUI; - le scritture utente sono idempotenti e con backup quando necessario; - la documentazione spiega installazione, update e rollback; - la documentazione distingue CLI headless, wizard interattivo e GUI opzionale; - la PR checklist include i check runtime; - non c'e' nessun degrado del setup locale esistente. La GUI grafica desktop non e' criterio obbligatorio di chiusura M8. E' accettabile come deliverable opzionale solo se resta un wrapper del core installer e non sostituisce la CLI. --- ## Sintesi decisionale La direzione architetturale di M8 e': ```text skills/* = sorgenti skill versionate docs/skills/skill-index.md = indice umano, non registry standard Anthropic $HOME/.agents/skills = installazione Codex cross-workspace $HOME/.codex/hooks.json = booster opzionale di routing/contesto $HOME/.codex/config.toml = feature flag e config Codex .copilot/agents/*.agent.md = target Copilot derivato scripts/runtime/*.js = core installer riusabile scripts/install-user-runtime.js = wrapper CLI headless/interattivo scripts/*.js = automazione Node, dry-run, idempotente ``` La regola piu' importante resta: ```text non distruggere mai configurazioni utente esistenti; generare, mergiare, validare e rendere reversibile. ``` La decisione sull'installer interattivo e': ```text M8 deve includere un wizard CLI-first passo-passo; una GUI grafica puo' essere prevista solo come wrapper opzionale successivo, senza duplicare logica e senza diventare requisito per usare l'installer. ```