# Analisi tecnica finale per Codex - Handoff pack, spec compliance e routing review Data: 2026-05-19 Repository target: `sophiadeveloper/mcp-servers` Modalita richiesta: patch conservativa, reviewable, senza scritture fuori repo Priorita fonti: 1) analisi collega nel file allegato, 2) analisi/TLDR discussi in chat, 3) convenzioni gia presenti nel repo --- ## 1. Sintesi decisionale Implementare tre interventi principali e uno di routing/documentazione: | Area | Decisione | Forma | |---|---|---| | Handoff finale | Approvato | Nuova skill generica `mcp-handoff-pack` | | Spec compliance | Approvato | Nuova modalita in `mcp-code-reviewer`, non nuova skill | | CFML docs-node lookup | Approvato | Regola condizionale dentro `mcp-code-reviewer`, mantenuta generica | | Auto-subagents | Solo hint/orchestrazione esplicita | Hook non bloccanti + workflow orchestrator, nessuna auto-delega invisibile | Principio guida: ```text Non aggiungere agenti o skill duplicati. Aggiungere una sola skill nuova per produrre artifact di handoff. Rafforzare mcp-code-reviewer con spec-compliance e lookup condizionale di regole locali. Mantenere hook e orchestrator come routing esplicito/non invisibile. ``` --- ## 2. Contesto repo e convenzioni da rispettare Dal repo emergono alcune convenzioni da preservare: 1. `mcp-code-reviewer` e gia la skill corretta per review di snippet, file, commit, diff, branch o PR. La descrizione attuale copre regole locali, leggibilita, manutenibilita, correttezza, robustezza, performance, test coverage e contesto funzionale disponibile. 2. `mcp-code-reviewer` e read-only quando usata tramite `code_reviewer`: non deve editare file, non deve produrre patch complete, deve produrre finding, proposte di fix e raccomandazioni test. 3. `mcp-memory-operator` e pensata per memoria operativa verificabile: decisioni validate, root cause, workaround, vincoli ambiente, handoff sintetici e continuita cross-session. 4. `mcp-master-orchestrator` coordina task multi-fase tra skill specialistiche, soprattutto quando il lavoro include analisi, fix, test, reporting o handoff. 5. Gli hook Codex esistenti sono non bloccanti, non sostituiscono `AGENTS.md`, `SKILL.md` o MCP, non devono fare chiamate MCP dirette e devono produrre massimo pochi hint brevi. 6. I subagent portabili sono ruoli operativi. Non devono sostituire skill specialistiche locali e non devono attivarsi invisibilmente. Vincolo importante emerso nel consolidamento: ```text Le skill devono restare generiche il piu possibile. ColdFusion/CFML e solo un caso condizionale nel reviewer. ``` --- ## 3. Obiettivo implementativo Preparare una patch che aggiunge: ```text skills/mcp-handoff-pack/ skills/mcp-code-reviewer/ aggiornato scripts/hooks/sophia-user-prompt-submit.mjs aggiornato solo per hint docs/orchestrator o references aggiornati con workflow sviluppo controllato evals minimi per coprire i nuovi comportamenti ``` La patch deve essere piccola, leggibile e coerente con le convenzioni gia presenti nel repo. --- ## 4. Nuova skill `mcp-handoff-pack` ### 4.1 Scopo Creare una skill generica per produrre un file Markdown finale di handoff, utile a: - utente; - Codex; - Copilot; - agenti futuri; - reviewer; - ticket/PR/Mantis; - sessioni successive. La skill deve spiegare: ```text - cosa e stato fatto; - perche e stato fatto; - quali file/artifact sono coinvolti; - quali vincoli sono stati rispettati; - quali verifiche sono state eseguite; - quali rischi residui restano; - quali prossime azioni sono consigliate; - quali skill/agenti usare per continuare; - quali informazioni sono candidate per memory-node. ``` ### 4.2 Confine con `mcp-memory-operator` Non deve sovrapporsi a `mcp-memory-operator`. | Componente | Responsabilita | |---|---| | `mcp-handoff-pack` | Produce un artifact Markdown completo di fine lavoro | | `mcp-memory-operator` | Salva solo decisioni, root cause, workaround e vincoli riusabili | | `mcp-master-orchestrator` | Decide quando usare handoff e memory in flussi multi-fase | Regola: ```text mcp-handoff-pack genera il report. mcp-memory-operator salva solo la parte stabile e riusabile, se richiesto. ``` ### 4.3 Non obiettivi `mcp-handoff-pack` non deve: - rifare analisi multi-sorgente; - cercare fonti da sola salvo input espliciti; - duplicare ticket, PRD, ADR, commit, diff o report gia presenti; - salvare automaticamente memoria; - scrivere direttamente su ticket/Mantis; - sostituire `mcp-master-orchestrator`. ### 4.4 Struttura file proposta ```text skills/mcp-handoff-pack/ ├── SKILL.md ├── references/ │ ├── handoff-template.md │ ├── memory-sync-policy.md │ └── evidence-policy.md └── evals/ └── evals.json ``` ### 4.5 Contenuto richiesto per `SKILL.md` Creare `skills/mcp-handoff-pack/SKILL.md` con frontmatter simile: ```md --- name: mcp-handoff-pack description: Generate a generic Markdown handoff artifact at the end of development, review, analysis, or multi-step work. Use when the user needs a concise but complete deliverable explaining what was done, why, touched files/artifacts, validations, risks, next actions, and reusable memory candidates. --- ``` Sezioni minime: ```md # MCP Handoff Pack ## Quick Routing Use when: - fine sviluppo; - fine review; - fine analisi tecnica; - passaggio di contesto a un altro agente; - consegna a ticket, PR o reviewer; - preparazione sessione successiva. Do not use when: - serve solo salvare memoria riusabile: usare `mcp-memory-operator`; - serve analisi multi-sorgente: usare `mcp-technical-analyst`; - serve coordinamento multi-fase: usare `mcp-master-orchestrator`; - serve scrivere direttamente ticket/Mantis: usare skill dedicata. ## Permanent Rules 1. Non rifare analisi gia svolta. 2. Non duplicare diff, commit, ticket, PRD, ADR o report esistenti: referenziali per path, ID o URL. 3. Distingui fatti verificati, inferenze, rischi residui e prossime azioni. 4. Suggerisci skill/agenti per continuare. 5. Prepara eventuali `Memory candidates`, ma non salvarli automaticamente. 6. Non includere segreti, token, dump lunghi, stack trace completi o dati sensibili. ## Output Genera Markdown con struttura stabile: - Contesto - Cosa e stato fatto - Perche - File modificati / artifact - Vincoli rispettati - Verifiche eseguite - Rischi residui - Prossime azioni - Skill / agent consigliati - Memory candidates ## Suggested path Preferire: ```text docs/handoffs/YYYY-MM-DD-.md ``` ``` ### 4.6 Template `references/handoff-template.md` Creare: ```md # Handoff - Data: Ticket/PR/Branch: Project path: `` ## 1. Contesto ## 2. Cosa e stato fatto - - - ## 3. Perche ## 4. File modificati / artifact | File / Artifact | Tipo | Motivo | |---|---|---| | `` | modifica / report / test / doc | | ## 5. Vincoli rispettati - - ## 6. Verifiche eseguite | Verifica | Esito | Evidenza | |---|---:|---| | | PASS/FAIL/N.A. | | ## 7. Rischi residui - Mitigazione: ## 8. Prossime azioni 1. 2. ## 9. Skill / agent consigliati - ``: ## 10. Memory candidates Da salvare eventualmente con `mcp-memory-operator`: - Decisione riusabile: <...> - Root cause validata: <...> - Workaround validato: <...> - Vincolo ambiente/progetto: <...> Non salvare se l'informazione e gia nel ticket, nel diff o in documentazione indicizzata. ``` ### 4.7 `references/memory-sync-policy.md` Contenuto minimo: ```md # Memory sync policy `mcp-handoff-pack` produce artifact Markdown. `mcp-memory-operator` salva solo memoria operativa riusabile. ## Salvare in memory solo se - decisione tecnica validata; - root cause verificata; - workaround validato; - vincolo ambiente/progetto riusabile; - pattern bug ricorrente; - handoff checkpoint realmente utile a sessioni future. ## Non salvare in memory - diff completo; - contenuto del ticket; - report gia tracciato; - log lunghi; - stack trace completi; - segreti o dati sensibili; - inferenze non verificate. ``` ### 4.8 `references/evidence-policy.md` Contenuto minimo: ```md # Evidence policy Nel file di handoff distinguere sempre: - fatto verificato; - inferenza; - decisione; - rischio residuo; - azione successiva. Referenziare artifact esistenti invece di duplicarli: - ticket ID; - branch/commit; - path file; - PR; - documento; - log o test report. ``` --- ## 5. Estensione `mcp-code-reviewer`: mode `spec-compliance` ### 5.1 Scopo Aggiungere una modalita che verifica: ```text La patch rispetta davvero ticket, analisi iniziale, requisiti, criteri di accettazione e vincoli espliciti? ``` Non e una review tecnica generale. ### 5.2 Perche non creare nuova skill/agente ora La proposta del collega e corretta: `spec-compliance` ha alto valore ma va inserita in `mcp-code-reviewer` per evitare duplicazioni. Motivi: - `mcp-code-reviewer` e gia la skill di review; - `code_reviewer` e gia il subagent read-only per review focalizzata; - la differenza e il modo di review, non un dominio nuovo; - se diventera molto usata si potra valutare un subagent `spec_reviewer` in futuro. ### 5.3 Patch richiesta in `skills/mcp-code-reviewer/SKILL.md` Aggiungere sezione: ```md ## Mode: spec-compliance Usa questa modalita quando l'obiettivo e verificare se una patch rispetta ticket, analisi iniziale, requisiti, criteri di accettazione o vincoli espliciti. Questa modalita non e una review generica di qualita. Concentrati su: - requisiti coperti; - requisiti mancanti; - modifiche fuori scope; - vincoli ignorati; - comportamento richiesto ma non verificabile; - ambiguita che impediscono un verdetto affidabile. Non inventare requisiti. Se mancano ticket, analisi, criteri di accettazione o contesto funzionale, dichiara `UNCLEAR`. ### Output spec-compliance ```md ## Spec compliance | Requisito / vincolo | Evidenza nel codice/diff | Esito | Note | |---|---|---:|---| | ... | ... | PASS/FAIL/UNCLEAR | ... | ## Scope drift - Modifiche fuori scope: - Requisiti non coperti: - Ambiguita residue: - Evidenze mancanti: ## Verdetto APPROVATO / DA CORREGGERE / SERVE CHIARIMENTO ``` ### Escalation - Se serve ricostruire ticket + docs + allegati + commit: passa a `mcp-technical-analyst`. - Se serve review + fix + test + handoff: passa a `mcp-master-orchestrator`. - Se serve solo checklist test: delega a `test_writer`. ``` ### 5.4 Possibile reference separata Se il file `SKILL.md` rischia di diventare troppo lungo, creare: ```text skills/mcp-code-reviewer/references/spec-compliance.md ``` e aggiungerla a `## References`. --- ## 6. Estensione `mcp-code-reviewer`: domain-specific local rules lookup ### 6.1 Obiettivo Mantenere `mcp-code-reviewer` generico, ma permettere lookup condizionale di regole locali quando il diff contiene segnali forti di uno stack/framework/runtime. Questa e la parte importante per evitare che la skill diventi troppo ColdFusion-specifica. ### 6.2 Patch generica richiesta Aggiungere in `mcp-code-reviewer`: ```md ## Domain-specific local rules lookup Quando il diff contiene segnali forti di uno stack, framework o runtime specifico, prima di applicare best practice generiche verifica eventuali convenzioni locali tramite: 1. `AGENTS.md` e file di regole locali; 2. documentazione locale o indicizzata; 3. docs MCP / `mcp-docs-navigator`, se disponibile; 4. skill specialistica pertinente, se il dominio richiede runtime/debug o conoscenza specifica. Mantieni la review generica: consulta regole dominio-specifiche solo per ridurre falsi positivi, non per trasformare questa skill in una skill specialistica. ``` ### 6.3 Caso condizionale CFML Aggiungere sotto-blocco: ```md ### ColdFusion / CFML conditional lookup Se il diff contiene `.cfm`, `.cfc`, `cfquery`, `Application.cfc`, `Application.cfm` o pattern ColdFusion legacy: 1. consulta docs-node / `mcp-docs-navigator` per convenzioni CFML locali quando disponibili; 2. valuta se serve `mcp-coldfusion-developer`; 3. separa i finding in: - bug funzionale; - violazione convenzione locale; - rischio runtime; - miglioramento non bloccante; 4. non proporre refactor generici se il pattern e imposto da framework/progetto; 5. se la review richiede lint, runtime, log, bridge CF o debug applicativo, escalare a `mcp-coldfusion-developer`. Questa regola e condizionale: non deve rallentare review non-CFML e non deve trasformare `mcp-code-reviewer` in una skill ColdFusion. ``` ### 6.4 Possibile reference separata Se preferibile: ```text skills/mcp-code-reviewer/references/domain-specific-local-rules.md ``` --- ## 7. Aggiornamento hook routing ### 7.1 Obiettivo Aggiornare `scripts/hooks/sophia-user-prompt-submit.mjs` solo per hint non bloccanti. Non fare: - chiamate MCP dirette; - auto-delega invisibile a subagent; - blocchi; - output rumoroso; - piu di due hint per prompt; - hardcoding di tag MCP reali. ### 7.2 Nuovi intent/hint Aggiungere segnali per handoff: ```js 'mcp-handoff-pack': [ 'handoff', 'consegna', 'fine lavoro', 'fine sviluppo', 'report finale', 'riepilogo finale', 'passaggio di contesto', 'sessione successiva', 'cosa e stato fatto', 'prossime azioni' ] ``` Messaggio suggerito: ```text Sophia routing hint: this prompt may benefit from `mcp-handoff-pack` to generate a final Markdown handoff artifact. Use `mcp-memory-operator` only for reusable decisions, root causes, constraints, or validated workarounds. ``` Aggiungere segnali per spec-compliance come hint verso `mcp-code-reviewer`: ```js 'spec-compliance': [ 'aderenza al ticket', 'coerenza con il ticket', 'rispetta i requisiti', 'criteri di accettazione', 'fuori scope', 'scope drift', 'verifica requisiti', 'analisi iniziale' ] ``` Messaggio suggerito: ```text Sophia routing hint: for requirement/scope verification, consider `mcp-code-reviewer` in `spec-compliance` mode. Verify against ticket, analysis, acceptance criteria, and explicit constraints; do not invent missing requirements. ``` ### 7.3 Subagents Non implementare auto-delega invisibile. Aggiungere solo eventuale hint quando il prompt parla esplicitamente di flusso completo: ```text For a full development workflow, consider explicit orchestration: analysis -> implementer -> spec-compliance -> code_reviewer -> test_writer -> mcp-handoff-pack. ``` --- ## 8. Aggiornamento orchestrator/workflow ### 8.1 Obiettivo Aggiungere un workflow di sviluppo controllato a `mcp-master-orchestrator`, preferibilmente in: ```text skills/mcp-master-orchestrator/references/workflows.md ``` oppure in un reference equivalente gia presente. ### 8.2 Workflow proposto ```md ## Workflow sviluppo controllato con handoff Usa questo workflow quando il task richiede analisi, sviluppo, review, test e consegna finale. 1. `mcp-technical-analyst`: analisi ticket/documenti/evidenze, se il task parte da fonti esterne o requisiti non banali. 2. Piano implementativo: definire file target, vincoli, rischi e validazioni. 3. `implementer`: implementazione mirata, un punto alla volta, delta minimo. 4. `mcp-code-reviewer` in `spec-compliance` mode: verifica aderenza a ticket, analisi, requisiti e vincoli. 5. `mcp-code-reviewer` / `code_reviewer`: verifica tecnica, regressioni, convenzioni locali e test gap. 6. `test_writer`: checklist test manuali, smoke, regressione, edge case. 7. `mcp-handoff-pack`: artifact Markdown finale con modifiche, motivazioni, verifiche, rischi e prossime azioni. 8. `mcp-memory-operator`: salva solo decisioni/root cause/workaround/vincoli riusabili, se presenti e se richiesto. ``` Regola: ```text I subagent restano ruoli espliciti. Gli hook possono suggerire. L'orchestrator puo pianificare. Nessuna auto-attivazione invisibile. ``` --- ## 9. Aggiornamento documentazione Aggiornare, se presenti e coerenti: ```text docs/developer-guide-agentic-programming.md docs/agents/local-orchestration-playbook.md docs/codex-user-hooks.md docs/skill-governance-matrix.md docs/skills/skill-index.md ``` Non duplicare contenuto lungo. Inserire solo riferimenti e regole brevi. ### 9.1 Nota consigliata per local orchestration playbook Aggiungere una riga nel flusso pratico: ```text Test Writer / Code Reviewer -> mcp-handoff-pack - quando serve un artifact finale di consegna per utente, Codex, Copilot o sessione successiva. ``` ### 9.2 Nota consigliata per governance ```text mcp-handoff-pack genera artifact Markdown di fine lavoro. mcp-memory-operator salva solo memoria operativa riusabile. ``` --- ## 10. Evals minimi ### 10.1 `skills/mcp-code-reviewer/evals/evals.json` Aggiungere casi o estendere struttura esistente con: ```json { "id": "spec-compliance-conforme", "prompt": "Reviewa questo diff in modalita spec-compliance rispetto al ticket MNT-123 e all'analisi iniziale.", "expected_output": "Verifica requisiti e vincoli senza fare review tecnica generica estesa.", "expectations": [ "Produce tabella requisito/evidenza/esito/note", "Segnala requisiti coperti", "Non inventa requisiti", "Restituisce verdetto APPROVATO, DA CORREGGERE o SERVE CHIARIMENTO" ] } ``` ```json { "id": "spec-compliance-fuori-scope", "prompt": "Reviewa un diff tecnicamente valido ma con modifiche extra non richieste dal ticket.", "expected_output": "Segnala scope drift e distingue qualita tecnica da aderenza alla spec.", "expectations": [ "Segnala modifiche fuori scope", "Non trasforma la review in refactor advice generico", "Usa FAIL o SERVE CHIARIMENTO quando la conformita non e dimostrabile" ] } ``` ```json { "id": "cfml-conditional-lookup", "prompt": "Reviewa un diff che modifica file .cfc e .cfm. Verifica convenzioni locali se disponibili.", "expected_output": "Attiva lookup condizionale CFML senza trasformare la review in sviluppo/debug ColdFusion.", "expectations": [ "Rileva segnali CFML forti", "Suggerisce docs-node / mcp-docs-navigator per convenzioni locali", "Valuta escalation a mcp-coldfusion-developer solo se servono lint/runtime/log/debug", "Separa bug funzionali, violazioni convenzione locale, rischi runtime e miglioramenti non bloccanti", "Non rallenta ne altera review non-CFML" ] } ``` ### 10.2 `skills/mcp-handoff-pack/evals/evals.json` Creare: ```json { "skill_name": "mcp-handoff-pack", "eval_focus": [ "generic-markdown-handoff", "no-memory-duplication", "artifact-references-not-duplication", "next-session-agent-readiness" ], "evals": [ { "id": "handoff-finale-generico", "prompt": "Genera un handoff finale per il ticket MNT-123 dopo sviluppo, review e test.", "expected_output": "Markdown completo con contesto, cosa fatto, perche, file, verifiche, rischi, prossime azioni e memory candidates.", "expectations": [ "Non salva automaticamente memoria", "Distingue handoff artifact da memory operator", "Referenzia artifact esistenti invece di duplicarli", "Suggerisce skill/agenti per continuare" ] }, { "id": "handoff-sessione-successiva", "prompt": "Compatta questa sessione per farla continuare a Codex domani.", "expected_output": "Handoff sintetico orientato a un agente fresco.", "expectations": [ "Include stato corrente e prossima azione concreta", "Include limiti e rischi residui", "Indica quali skill usare nella sessione successiva", "Non include rumore conversazionale" ] } ] } ``` --- ## 11. Pianificazione degli sviluppi per step ### 11.1 Presupposti operativi Il branch dedicato agli sviluppi e gia stato preparato. La patch deve restare conservativa, piccola e reviewable. Gli step sono ordinati per ridurre rischio e facilitare review/test incrementali. Principi: - prima discovery read-only; - poi modifica del reviewer; - poi nuova skill `mcp-handoff-pack`; - poi routing hook e documentazione; - infine validazione completa e review; - nessuna auto-delega invisibile dei subagent; - nessuna modifica a profili utente o file fuori repository. ### 11.2 Step 0 - Discovery read-only Obiettivo: confermare struttura reale del repo, file target, convenzioni e comandi disponibili. Attivita: 1. leggere `skills/mcp-code-reviewer/SKILL.md` e references esistenti; 2. leggere `skills/mcp-code-reviewer/evals/evals.json`; 3. verificare struttura delle altre skill con `SKILL.md`, `references/`, `evals/`; 4. leggere `skills/mcp-memory-operator/SKILL.md` per rispettare il confine handoff/memory; 5. leggere `skills/mcp-master-orchestrator/SKILL.md` e `references/workflows.md`, se presente; 6. leggere `scripts/hooks/sophia-user-prompt-submit.mjs`; 7. identificare eventuali index/governance docs da aggiornare solo se gia usati dal repo; 8. rilevare comandi di test/lint disponibili. Output atteso: - piano file; - rischi; - comandi di validazione; - nessuna modifica applicata. ### 11.3 Step 1 - Estendere `mcp-code-reviewer` Obiettivo: aggiungere due capacita al reviewer senza creare nuove skill o agenti. Modifiche: 1. aggiungere mode `spec-compliance`; 2. aggiungere lookup generico per regole locali dominio-specifiche; 3. aggiungere sotto-caso CFML solo condizionale; 4. creare reference separate solo se `SKILL.md` diventasse troppo lungo; 5. aggiornare references list; 6. aggiornare evals minimi del reviewer. Vincoli: - `spec-compliance` resta una modalita di `mcp-code-reviewer`; - non creare `spec-reviewer`; - non creare `code-quality-reviewer`; - non trasformare il reviewer in skill ColdFusion; - CFML lookup si attiva solo con `.cfm`, `.cfc`, `cfquery`, `Application.cfc`, `Application.cfm` o pattern ColdFusion legacy. Validazioni minime: - JSON evals valido; - diff contenuto; - verifica che le nuove regole non contraddicano routing/escalation esistenti. ### 11.4 Step 2 - Creare `mcp-handoff-pack` Obiettivo: aggiungere una skill generica per generare artifact Markdown di fine lavoro. File attesi: ```text skills/mcp-handoff-pack/SKILL.md skills/mcp-handoff-pack/references/handoff-template.md skills/mcp-handoff-pack/references/memory-sync-policy.md skills/mcp-handoff-pack/references/evidence-policy.md skills/mcp-handoff-pack/evals/evals.json ``` Confini obbligatori: - `mcp-handoff-pack` produce report Markdown completo; - `mcp-memory-operator` salva solo decisioni, root cause, workaround e vincoli riusabili; - nessun salvataggio automatico in memory; - nessuna duplicazione di ticket, diff, commit, PRD, ADR o report esistenti; - nessuna analisi multi-sorgente rifatta dalla skill. Validazioni minime: - struttura coerente con le skill esistenti; - template completo; - evals JSON valido; - riferimenti chiari a `mcp-memory-operator` senza duplicarne la logica. ### 11.5 Step 3 - Aggiornare routing hook e orchestrator/docs Obiettivo: rendere scopribili le nuove capacita senza automatismi invasivi. Modifiche: 1. aggiornare `scripts/hooks/sophia-user-prompt-submit.mjs` con hint per `mcp-handoff-pack`; 2. aggiungere hint per `mcp-code-reviewer` in mode `spec-compliance`; 3. mantenere massimo due hint per prompt; 4. evitare chiamate MCP dirette; 5. evitare auto-delega invisibile dei subagent; 6. aggiornare workflow orchestrator con sequenza sviluppo controllato; 7. aggiornare documentazione/index/governance solo se gia presente e pertinente. Workflow da documentare: ```text analysis -> plan -> implementer -> spec-compliance -> code review -> test_writer -> mcp-handoff-pack -> mcp-memory-operator solo per memoria riusabile ``` Validazioni minime: - `node --check scripts/hooks/sophia-user-prompt-submit.mjs`; - test hook se presenti; - verifica manuale di casi prompt handoff/spec-compliance; - nessun output rumoroso o bloccante. ### 11.6 Step 4 - Validazione complessiva Obiettivo: verificare coerenza, sintassi e assenza di regressioni documentali. Controlli minimi: ```bash node --check scripts/hooks/sophia-user-prompt-submit.mjs node -e "JSON.parse(require('fs').readFileSync('skills/mcp-code-reviewer/evals/evals.json','utf8')); console.log('mcp-code-reviewer evals ok')" node -e "JSON.parse(require('fs').readFileSync('skills/mcp-handoff-pack/evals/evals.json','utf8')); console.log('mcp-handoff-pack evals ok')" git diff --check git diff --stat ``` Se il repo espone comandi dedicati, eseguire anche: ```bash npm test npm run lint npm run test:hooks ``` solo se esistono e sono coerenti con il progetto. ### 11.7 Step 5 - Review finale Obiettivo: review read-only del diff complessivo prima della consegna. Verificare: 1. `mcp-handoff-pack` non duplica `mcp-memory-operator`; 2. `spec-compliance` non e diventata una nuova skill/agente; 3. lookup dominio-specifico resta generico; 4. CFML resta solo caso condizionale; 5. hook restano hint non bloccanti; 6. subagent restano espliciti; 7. evals minimi coprono i casi richiesti; 8. nessun registry YAML manuale; 9. nessuna modifica fuori repo; 10. patch piccola e coerente con stile esistente. Output atteso: - finding bloccanti; - finding non bloccanti; - eventuale patch correttiva minima; - conferma finale per review umana. ### 11.8 Strategia modello e reasoning Per lo sviluppo usare `5.3-codex` con reasoning `medium` e branch dedicato. Motivo: - buon compromesso tra qualita e consumo token; - il lavoro e principalmente documentale/strutturale; - il branch dedicato riduce rischio operativo; - gli step separati permettono review incrementale. Usare reasoning piu alto solo se durante la discovery emergono conflitti architetturali o convenzioni non chiare. ### 11.9 Uso consigliato dei subagent Usare subagent in modo esplicito, non automatico: - `implementer` per applicare patch piccole e mirate; - `code_reviewer` per review tecnica read-only; - `test_writer` per checklist test/eval/regressione; - nessun nuovo `spec_reviewer` in questa fase. Sequenza consigliata: ```text Codex principale -> implementer -> code_reviewer -> test_writer -> implementer solo per fix puntuali -> review finale umana ``` --- ## 12. Criteri di accettazione La patch e accettabile se: 1. `mcp-handoff-pack` esiste come skill generica e produce un handoff Markdown finale. 2. `mcp-handoff-pack` non salva memoria automaticamente. 3. `mcp-handoff-pack` distingue chiaramente artifact/report da memory-node. 4. `mcp-code-reviewer` contiene `spec-compliance` come mode, non come nuova skill. 5. `spec-compliance` non inventa requisiti e usa `UNCLEAR` quando mancano fonti. 6. `mcp-code-reviewer` contiene lookup generico di regole locali dominio-specifiche. 7. Il caso CFML e condizionale e limitato ai segnali: `.cfm`, `.cfc`, `cfquery`, `Application.cfc`, `Application.cfm` o pattern ColdFusion legacy. 8. Gli hook suggeriscono `mcp-handoff-pack` e `spec-compliance` senza chiamare MCP o delegare subagent invisibilmente. 9. Il workflow orchestrator documenta la sequenza controllata. 10. Evals minimi presenti e JSON valido. 11. Nessun registry YAML manuale nuovo. 12. Nessuna modifica a file fuori repo o profili utente. 13. Patch piccola, coerente e reviewable. --- ## 13. Cose da non fare ```text NON creare ora una nuova skill spec-reviewer. NON creare ora un subagent spec_reviewer. NON creare code-quality-reviewer. NON rendere mcp-code-reviewer una skill ColdFusion. NON spostare logica mcp-memory-operator dentro mcp-handoff-pack. NON fare auto-delega invisibile dei subagent. NON trasformare hook in orchestratori. NON fare chiamate MCP dagli hook. NON introdurre registry YAML manuali. NON duplicare contenuti lunghi in docs e runtime agent files. ``` --- ## 14. Nota finale per chi implementa La priorita e rispettare la forma gia presente nel repo: ```text Skill snelle e specializzate. Subagent come ruoli operativi espliciti. Hook come suggerimenti brevi e non bloccanti. Orchestrator per flussi multi-fase. Memory per conoscenza riusabile, non per report completi. Docs-node come fonte documentale quando serve contesto locale. ``` La nuova funzionalita deve migliorare il workflow senza aumentare ambiguita tra skill, agenti, hook e memory. --- ## 15. Post-sviluppo: consolidamento e controlli ricorrenti Lo sviluppo principale e stato impostato correttamente; gli interventi successivi hanno chiuso piccoli gap di robustezza/governance. Per evitare regressioni conviene irrobustire la documentazione operativa su questo punto, monitorando come check ricorrente che ogni nuovo `PreToolUse` aggiunto in `generate-codex-hooks.js` sia allineato anche in `preparePortableRoot` dentro `smoke-codex-hooks.js`, validando sempre analisi e implementazione rispetto alle regole gia presenti nel repository e aggiornando, quando necessario, documentazione e tabelle di compatibilita/governance per facilitare analisi future.