# Analisi tecnica - Skill `mcp-sophia-yii-developer` Data: 2026-04-27 Stato: implementata come skill v1 il 2026-04-28 Decisione: creare una skill specialistica dedicata allo sviluppo Sophia Framework/Yii 1.1. ## Stato implementazione v1 La skill `mcp-sophia-yii-developer` e stata creata in `skills/mcp-sophia-yii-developer/` con `SKILL.md`, reference locali modulari ed eval minimi. Sono stati aggiornati anche routing orchestrator, sidecar analyst e governance matrix. La v1 non introduce server MCP, non modifica schema MCP e non richiede riavvio server. ## Done consolidamento v1 Il consolidamento v1 aggiunge verificabilita' e routing operativo senza estendere il runtime: - `evals/evals.json` allineato allo standard delle skill mature con `eval_focus` ed `expectations[]`; - reference operative aggiunte per review PR e matrice routing; - `SKILL.md` aggiornato con link ai nuovi reference; - nessuna modifica a server MCP, schema MCP o tool runtime; - esclusi volutamente dalla v1 consolidata: PHPCS/PHPStan, arricchimento da uso reale su progetto Sophia e script deterministici locali. Verifiche richieste per chiusura: validazione JSON eval, presenza reference linkati, `git diff --check` pulito. Se cambiano solo skill/docs, non serve riavvio server MCP. ## Verifica aggiuntiva con docs MCP e progetto locale Su richiesta e' stata fatta una passata di controllo anche tramite `mcp-docs-navigator` / `docs-mcp-server` e su un progetto Sophia locale. Evidenze docs MCP: - feature `tags` e `scan_sources` inizializzate; - scaffale `sophia-apps-documentation` disponibile con 19 documenti; - tag utili confermati: `sophia`, `yii`, `framework-sophia`, `layers`, `configuration`, `forms`, `grids`, `export`, `permissions`, `db-scripts`; - documenti letti per confronto: - `docs://document/27` - Architecture Layers FRM APP CLI; - `docs://document/33` - Gestione campi e form; - `docs://document/35` - Gestione griglie; - `docs://document/32` - Gestione export; - `docs://document/38` - Gestione script DB. Evidenze progetto locale: - path osservato: `C:\xampp183\htdocs\SOPHIA_framework2`; - struttura coerente con skill/reference: `protected/config`, `controllers`, `models`, `views`, `widgets`, `data`, `gii`; - config presenti: `config_frm.php`, `config_app.php`, `config_client.php`, `main.php`; - registry script DB presenti: `scripts_aggiornamento_framework.php`, `scripts_aggiornamento_application.php`, `scripts_aggiornamento_client.php`; - runtime PHP XAMPP osservato: PHP 5.5.9; - smoke `php -l` riuscito su campioni config, controller, model e registry script DB. Questa verifica conferma che i reference locali della skill sono allineati sia al corpus MCP indicizzato sia a una tree Sophia reale. Il path locale resta evidenza di test, non dipendenza della skill. ## Sintesi decisionale Vale la pena consolidare l'analisi prima dello sviluppo della skill. La motivazione principale e che Sophia non e solo un'applicazione Yii 1.1: introduce convenzioni operative proprie su layering `FRM` / `APP` / `CLI-client`, configurazioni gerarchiche, rendering dinamico tramite `RenderSettings`, permessi centralizzati, export, script DB e generazione Gii custom. Una skill specialistica riduce il rischio che l'agente applichi pattern Yii generici dove servono pattern Sophia. La nuova skill dovrebbe essere analoga a `mcp-coldfusion-developer` per ruolo: - specialistica ed esecutiva; - non orchestratore generalista; - basata su reference locali caricati a domanda; - integrata con `mcp-technical-analyst`, `mcp-master-orchestrator`, docs, DB, browser, git/ticketing e linter. ## Fonti osservate ### Governance repo - `AGENTS.md`: regole permanenti, routing skill, compatibilita legacy, done minimo. - `docs/mcp-skills-agents-development-guide.md`: skill brevi, dettagli in `references/`, routing analyst/orchestrator/specialistiche, test e schema discipline. - `docs/skill-governance-matrix.md`: modello di governance per trigger, references, eval, confini con analyst/orchestrator. - `skills/mcp-coldfusion-developer/SKILL.md`: riferimento strutturale per skill specialistica esecutiva. - `skills/mcp-master-orchestrator/SKILL.md`: gate di routing e matrice decisionale. - `skills/mcp-technical-analyst/SKILL.md`: criteri per analisi multi-sorgente e handoff verso skill specialistiche. - `E:\anthropics\skills\skills\skill-creator\SKILL.md`: processo consigliato per definire scopo, trigger, output, eval e iterazione skill. ### Scaffale `sophia-apps-documentation` Scaffale docs-node: `sophia-apps-documentation`, 19 documenti indicizzati, tag principali `sophia`, `yii`, `framework-sophia`, `framework-base`. Documenti chiave letti: - `docs://document/27` - Architecture Layers FRM APP CLI. - `docs://document/28` - Configuration And Environments. - `docs://document/30` - Cruge RBAC Authentication. - `docs://document/32` - Gestione export. - `docs://document/33` - Gestione campi e form. - `docs://document/34` - Gii And Code Generation. - `docs://document/35` - Gestione griglie. - `docs://document/36` - Menu And Permissions Management. - `docs://document/38` - Gestione script DB. - `docs://document/39` - SOPHIA Framework 2 - Developer Agent Guide. - `docs://document/40` - Struttura e funzioni del Sophia Framework. ### Regole Yii esterne Il path `I:\Drive condivisi\Intelligenza Artificiale\Documentazione e regole per gli agenti\Yii.md` non era accessibile come drive locale nel sandbox. La ricerca Google Drive ha trovato un file `Yii.md` coerente con il contenuto Sophia Framework 2: - Drive file: `https://drive.google.com/file/d/1EtvQiu_ULoq7qhfF2DOkoMghVNO0yAgf` Il contenuto e sostanzialmente allineato a `docs://document/39`: architettura Sophia 2 su Yii 1.1, layer `FRM` / `APP` / `CLI`, `controllerMap`, configurazioni, `RenderSettings`, asset, scheduler, Cruge e helper globali. ## Evidenze tecniche rilevanti ### Layering Sophia Sophia usa tre livelli di responsabilita: - `FRM`: framework condiviso, controller/model/base comuni, rendering, helper, costanti runtime. - `APP`: logica applicativa e override di dominio. - `CLI/client`: specializzazione cliente o variante di installazione; nello scaffale `cli` non significa necessariamente console command Yii. Il routing operativo passa da `controllerMap`: - `protected/config/config_frm.php` definisce mapping base. - `protected/config/config_app.php` sovrascrive mapping applicativi. - `protected/config/config_client.php` puo rimappare verso controller client-specific. Implicazione skill: prima di modificare codice Sophia, l'agente deve classificare il layer corretto. Questa classificazione deve diventare un gate esplicito della skill. ### Configurazioni e ambienti La configurazione e gerarchica: - `protected/config/main.php` - `protected/config/config_frm.php` - `protected/config/config_app.php` - `protected/config/config_client.php` - `protected/config/environment/{dev,demo,test,preprod,prod}.php` - `protected/config/db/dbconnect.*.php` - `protected/config/mailer/*` Regola skill: non hardcodare valori ambientali nel codice business; usare environment e configurazioni corrette. ### Model, controller e rendering Pattern centrali: - model DB basati su `frmCActiveRecord`; - `RenderSettings` inizializzato nel model e valorizzato nel controller; - `initfields($model, $rendertype)` come punto di configurazione UI; - metodi ordinatori come `getrenderfilters()`, `getrenderadminbtns()`, `getrenderadmin()`, `getrenderform()`, `getrenderformbtn()`; - view che richiamano helper come `drawInitFields()`, `drawInitButtons()`, `drawInitAdminButtons()`. Regola skill: evitare markup UI manuale nelle view quando il pattern `RenderSettings` e applicabile. ### Griglie ed export Pattern griglie: - default `widgets.FrmGridView`; - `ajaxType = 'POST'`; - filtri avanzati tramite form nascosta; - `nRighe` come dimensione pagina; - azioni riga tramite `TbButtonColumn` o `grid_view_buttons`; - editing inline tramite `TbEditableColumn` solo con action dedicata `UpdateInline`. Pattern export: - controller prepara data provider; - colonne export costruite manualmente, non copia cieca della griglia; - `setPagination(false)`; - `toExcel()` tramite `EExcelBehavior`; - formati `Excel5`, `Excel2007`, `PDF`, `HTML`, `CSV`. Regola skill: trattare griglia ed export come due contratti vicini ma distinti. ### Permessi, menu e Cruge Sophia usa Cruge per autenticazione/RBAC, ma aggiunge policy applicative: - `GetAbilitazioni($controller, $action)`; - `hasAnyRole(...)`; - `Yii::app()->user->isSuperAdmin`; - costanti `RUOLO_*`; - feature flag come `ABIL_MENU_*`; - catena `AbilitazioniFrmController` -> `AbilitazioniAppController` -> `AbilitazioniCliController`. Regola skill: nuove action, menu e pulsanti griglia devono passare dal controller di abilitazione, non da controlli sparsi nelle view. ### Script DB Gli script DB hanno lifecycle dedicato: - registry file-backed: `protected/data/scripts_aggiornamento_framework.php`, `protected/data/scripts_aggiornamento_application.php`, eventuale client; - modelli `_scripts_aggiornamento_*` basati su `ArrayModel`; - tracking DB: `frm_sys_scriptsdb_frm`, `frm_sys_scriptsdb_app`, `frm_sys_scriptsdb_cli`; - esecuzione centralizzata in `SiteController`; - rischio operativo: esecuzione non transazionale applicativa, tracking successivo alla query, massivo non ricalcola script gia tracciati. Regola skill: ogni modifica script DB deve dichiarare modo `Frm` / `App` / `Cli`, ticket, effetto SQL, cautela di deploy e verifica tracking. ## Skill proposta Nome consigliato: ```yaml name: mcp-sophia-yii-developer ``` Descrizione consigliata: ```yaml description: Develop and debug Sophia Framework 2 applications based on Yii 1.1, including FRM/APP/CLI-client layering, controllerMap overrides, RenderSettings forms and grids, Gii custom scaffolding, Cruge/RBAC permissions, exports, DB scripts, and post-fix validation. Use this whenever the user asks to inspect, modify, generate, debug, or validate PHP/Yii code in a Sophia application, even if they only mention Yii, Sophia, Musa, controllerMap, RenderSettings, FrmGridView, Cruge, or Gii. ``` ## Perimetro Usare la skill quando il lavoro principale riguarda: - codice PHP/Yii Sophia; - controller, model, view, config o helper Sophia; - nuova pagina o CRUD; - form, filtri, griglie, export; - permessi/menu/Cruge; - script DB Sophia; - debug UI o runtime collegato a una feature Sophia; - review operativa di una modifica Sophia. Non usarla come primaria quando: - il task e una ricostruzione multi-sorgente da ticket, commit, DB e documenti: primaria `mcp-technical-analyst`; - il task richiede coordinamento multi-fase tra piu skill: primaria `mcp-master-orchestrator`; - il task e solo SQL/schema/explain: primaria `mcp-database-expert`; - il task e solo browser validation: primaria `mcp-browser-automation`; - il task e solo documentazione/scaffale: primaria `mcp-docs-navigator`. ## Struttura file consigliata ```text skills/mcp-sophia-yii-developer/ SKILL.md references/ architecture-layers.md configuration-environments.md render-settings-forms-grids.md gii-code-generation.md cruge-permissions-menu.md db-scripts-and-migrations.md export-management.md post-fix-checklist.md evals/ evals.json ``` In prima iterazione non servono `scripts/`, salvo emergano controlli deterministici utili. Quando il linter supportera PHP, si potra aggiungere un riferimento operativo forte a `linter-mcp-server` e, se utile, micro-script di discovery per trovare controller/model/view correlati. ## Workflow operativo base 1. Identifica `project_path` della Sophia app. 2. Classifica scenario: CRUD, form/griglia, export, permessi, config, script DB, debug runtime, review. 3. Classifica layer target: `FRM`, `APP`, `CLI/client`. 4. Carica reference locale minimo della skill. 5. Cerca nello scaffale `sophia-apps-documentation` se il caso non e coperto dal reference locale o se serve conferma viva. 6. Ispeziona codice Sophia vicino alla modifica. 7. Esegui lint PHP quando disponibile; fino ad allora usa controlli statici leggeri e pattern review. 8. Applica modifica minima. 9. Valida: - lint PHP appena disponibile; - test/smoke applicativo se esiste; - DB/schema con `mcp-database-expert` se tocca persistenza; - browser con `mcp-browser-automation` se tocca UI; - docs/handoff se cambia convenzione o workflow. 10. Chiudi con rischi residui e indicazione di eventuale riavvio/server/cache se richiesto dall'app. ## Sinergie MCP e skill ### `mcp-docs-navigator` Ruolo: fonte viva per `sophia-apps-documentation`. Usarlo quando: - i reference locali non bastano; - serve verificare una convenzione Sophia; - bisogna aggiornare o indicizzare documentazione nuova; - serve ricerca tag-first su `sophia`, `yii`, `framework-sophia`, `configuration`, `grids`, `permissions`, `db-scripts`. ### `mcp-database-expert` Ruolo: schema, dati reali, explain, query SELECT. Usarlo quando: - modifica model/search/relations; - cambia script DB; - cambia export o filtro dati; - serve verificare `frm_cruge_*`, `frm_sys_*`, tabelle tracking script; - serve confronto ambiente `dev/test/preprod/prod`. ### `mcp-browser-automation` Ruolo: validazione UI e flussi reali. Usarlo quando: - cambia form, griglia, filtro, export download, menu o permesso; - bisogna verificare Ajax update, `FrmGridView`, Select2, DatePicker, editable inline; - bisogna catturare errori console/network. ### `mcp-git-mantis-workflow` Ruolo: ticket, commit, branch, allegati, tracciabilita. Usarlo quando: - task nasce da ticket Mantis; - script DB deve citare ticket; - serve capire regressione da commit; - bisogna lasciare nota tecnica o allegato. ### `mcp-technical-analyst` Ruolo: intake multi-sorgente. Diventa primario quando: - servono ticket + docs + codice + DB; - esistono evidenze contraddittorie; - serve stato dell'arte, gap analysis o piano tecnico finale. La skill Sophia resta sidecar specialistico per interpretare codice e convenzioni Yii/Sophia. ### `mcp-master-orchestrator` Ruolo: coordinatore multi-fase. Diventa primario quando il task richiede sequenza dipendente, per esempio: 1. leggere ticket; 2. verificare docs Sophia; 3. modificare codice Yii; 4. validare DB; 5. validare browser; 6. produrre nota o report. La skill Sophia deve essere aggiunta alla matrice decisionale orchestrator come skill specialistica per "Modificare logica Sophia/Yii". ### `mcp-code-reviewer` Ruolo: review difetti/regressioni. Usarlo quando: - richiesta e review di patch Sophia; - bisogna verificare boundary layer, permessi, rendering, query, export e test gap. ### `mcp-office-expert` Ruolo: allegati/report/export. Usarlo quando: - export prodotto va analizzato come Excel; - specifiche arrivano da PDF/DOCX/XLSX; - deliverable finale e Office/PDF. ### `linter-mcp-server` Assunzione: supportera PHP in futuro. Integrazione prevista: - audit lint read-only prima di modifiche PHP; - lint dei file modificati prima della consegna; - nessun fix automatico senza richiesta esplicita; - regole PHP Sophia aggiuntive se disponibili. Fino al supporto PHP: la skill deve dichiarare "lint quando disponibile" e usare code review + smoke come fallback. ## Integrazione in `mcp-master-orchestrator` Aggiornare la matrice decisionale con una riga: | Se l'obiettivo e... | Parti da questo skill | Sidecar tipici | | --- | --- | --- | | Modificare o validare logica Sophia/Yii | `mcp-sophia-yii-developer` | `mcp-docs-navigator`, `mcp-database-expert`, `mcp-browser-automation`, `mcp-git-mantis-workflow` | Aggiornare anche i gate: - task Sophia mono-dominio -> skill Sophia diretta; - task Sophia da ticket/docs/DB/commit -> `mcp-technical-analyst` primario, Sophia sidecar; - task Sophia con discovery + fix + DB/browser/report -> orchestrator primario, Sophia come fase esecutiva. ## Aggiornamenti governance consigliati Aggiornare: - `docs/skill-governance-matrix.md`: nuova riga `mcp-sophia-yii-developer`; - `skills/mcp-master-orchestrator/SKILL.md`: matrice decisionale e sidecar; - eventualmente `skills/mcp-technical-analyst/SKILL.md`: sezione sidecar con Sophia/Yii accanto a ColdFusion; - `docs/mcp-skills-agents-development-guide.md`: solo se si vuole citare la nuova specialistica tra esempi ad alto uso; - `skills/mcp-sophia-yii-developer/evals/evals.json`: eval minimi subito, non rimandati. ## Eval minimi consigliati ### Eval 1 - Routing mono-dominio Sophia Prompt: "Devo aggiungere un campo filtro in una griglia Sophia/Yii esistente usando RenderSettings." Atteso: usa `mcp-sophia-yii-developer`, classifica layer, richiama reference form/griglie, non passa da analyst. ### Eval 2 - Routing multi-sorgente Prompt: "Parti da questo ticket Mantis e verifica se il bug Sophia sulla griglia dipende da permessi, DB o regressione commit." Atteso: primaria `mcp-technical-analyst`, Sophia sidecar, DB/git/docs come fonti. ### Eval 3 - Orchestrator multi-fase Prompt: "Implementa una nuova action Sophia con permesso, script DB, validazione browser e nota finale." Atteso: primaria `mcp-master-orchestrator`, fase esecutiva Sophia, sidecar DB/browser/git-mantis. ### Eval 4 - Confine Yii generico vs Sophia Prompt: "Genera un CRUD Yii per una tabella in Sophia." Atteso: non usare Yii stock; richiamare Gii custom Sophia, layer `FRM`/`APP`/`CLI-client`, `RenderSettings`, permessi, traduzioni e audit fields. ### Eval 5 - Post-fix validation Prompt: "Ho modificato un export Sophia, controlla se posso chiudere." Atteso: verifica colonne export separate dalla griglia, filtri/sessione, paginazione disattivata, lint PHP quando disponibile, eventuale browser/download. ## Rischi e mitigazioni | Rischio | Impatto | Mitigazione | | --- | --- | --- | | Skill troppo ampia | Trigger confusi, overlap con orchestrator | Tenere `SKILL.md` breve, scenario-based, con anti-trigger espliciti | | Duplicazione dello scaffale docs | Reference pesanti e divergenti | Condensare solo regole operative; usare docs-node per fonte viva | | Yii generico usato al posto di Sophia | Codice non conforme | Descrizione pushy con trigger Sophia/Yii/RenderSettings/controllerMap/Cruge/Gii | | Linter PHP non ancora disponibile | Validazione incompleta | Dichiarare fallback temporaneo e futuro gate linter | | Confusione `CLI` | Modifiche nel layer sbagliato | Reference dedicato architecture-layers con nota `CLI/client` | | Script DB rischiosi | Effetti su dati/prod | Handoff obbligatorio a DB expert per schema/query/ambiente | | UI Ajax non validata | Regressioni invisibili staticamente | Handoff browser per form/griglie/export/menu | ## Piano di sviluppo consigliato 1. Creare `skills/mcp-sophia-yii-developer/SKILL.md` con trigger, perimetro, scenari e handoff. 2. Creare reference locali sintetici dai documenti `sophia-apps-documentation`. 3. Creare `evals/evals.json` con almeno i cinque casi sopra. 4. Aggiornare `mcp-master-orchestrator` con riga Sophia/Yii. 5. Aggiornare `mcp-technical-analyst` sidecar specialistici. 6. Aggiornare `docs/skill-governance-matrix.md`. 7. Eseguire smoke documentale: leggere skill, verificare link reference, validare JSON eval. 8. Informare che non serve riavvio MCP se cambiano solo skill/docs; serve riavvio solo se verranno cambiati server MCP. ## Conclusione La nuova skill e giustificata e dovrebbe essere preceduta da questa analisi tecnica. Il valore non e solo "sapere Yii", ma codificare il modo corretto di lavorare su Sophia: layer, override, rendering, permessi, export, script DB e validazione. L'integrazione con orchestrator e analyst va progettata subito per evitare overlap e per rendere prevedibile il routing nei task reali.