Initial commit: framework-translator skill (LLM-native approach)

- SKILL.md: Istruzioni complete per LLM (Fasi 1-5) - references/mapping_patterns.md: 13 pattern di trasformazione - references/skill_template.md: Template standardizzato SKILL.md - scripts/: 3 script meccanici bash (scan, structure, packaging) - PIANO_SVILUPPO.md: Piano di sviluppo originale (documentazione) Approccio: LLM-native con script minimali per operazioni meccaniche. Token usage stimato: ~35-65K per framework. Vantaggi: comprensione semantica, adattabilità, manutenzione semplice.
2026-03-07 10:14:37 +01:00 · 2026-03-07 10:14:37 +01:00 · c40ddf4b59
commit c40ddf4b59
9 changed files with 3344 additions and 0 deletions
--- a/PIANO_SVILUPPO.md
+++ b/PIANO_SVILUPPO.md
@ -0,0 +1,700 @@
+# Framework → AgentSkills Translator
+
+**Piano di Sviluppo per Skill Generalizzata di Trasformazione**
+
+_Versione: 1.0 | Data: 2026-03-07 | Autore: AgentePotente_
+
+---
+
+## 🎯 Obiettivo
+
+Creare una skill **`framework-translator`** che trasformi framework testuali eterogenei (come `orto_v1`) in un set di skills AgentSkills-compatibili, strutturate e pronte per la distribuzione.
+
+**Problema:** I framework sono spesso documenti complessi, multi-cartella, con strutture arbitrarie (agenti, workflow, knowledge, script, prompt). Trasformarli manualmente in AgentSkills richiede lavoro ripetitivo e conoscenza del formato target.
+
+**Soluzione:** Una skill che:
+1. Analizza la struttura del framework input
+2. Identifica entità trasformabili (agenti, workflow, knowledge)
+3. Applica pattern di mappatura predefiniti
+4. Genera skills AgentSkills-compatibili con struttura standardizzata
+5. Produce references centralizzate e documentazione
+
+---
+
+## 📊 Analisi del Caso di Studio: orto_v1 → orto-skills
+
+### Input: orto_v1 Framework
+
+```
+orto_v1/
+├── README.md                          # Panoramica framework
+├── orti_registry.json                 # Registry centrale
+├── docs/
+│   ├── 00_indice.md                   # Index documentazione
+│   ├── 01_visione_e_requisiti.md      # Visione prodotto
+│   ├── 02_scope_e_assunzioni.md       # Scope e assunzioni
+│   ├── 03_architettura_multiagente.md # Architettura agenti (12)
+│   ├── 04_contratti_e_messaggistica.md
+│   ├── 05_sicurezza_privacy_affidabilita.md
+│   ├── architettura_storage.md        # Storage markdown
+│   ├── agents/                        # 12 agenti specializzati
+│   │   ├── 00_agent_index.md
+│   │   ├── 01_orchestratore_planner.md
+│   │   ├── 02_agronomo_colture.md
+│   │   ├── 03_stagionalita_calendario.md
+│   │   ├── 04_fitopatologo_trattamenti.md
+│   │   ├── 05_irrigazione_automazione.md
+│   │   ├── 06_layout_zoning.md
+│   │   ├── 07_nutrizione_consumi.md
+│   │   ├── 08_data_knowledge_manager.md
+│   │   ├── 09_ui_ux_agent.md
+│   │   ├── 10_qa_safety_agent.md
+│   │   ├── 11_weather_intelligence_agent.md
+│   │   └── 12_ops_integrazioni_agent.md
+│   ├── workflows/                     # 5 workflow end-to-end
+│   │   ├── 00_workflow_index.md
+│   │   ├── 00_init_orto.md
+│   │   ├── 01_onboarding.md
+│   │   ├── 02_piano_stagionale.md
+│   │   ├── 03_esecuzione_settimanale.md
+│   │   ├── 04_diagnosi_problemi.md
+│   │   └── 05_irrigazione_dinamica_meteo.md
+│   ├── data/                          # Data model
+│   ├── schemas/                       # JSON schemas
+│   ├── gui/                           # GUI specification
+│   ├── skills/                        # Skills catalog (17 skills)
+│   │   ├── 00_skills_overview.md
+│   │   └── 01_skill_catalog.md
+│   ├── knowledge/                     # Knowledge base
+│   └── allegati/                      # Templates + examples
+├── prompts/
+│   ├── master_prompt_openclaw.md
+│   ├── prompt_onboarding.md
+│   ├── prompt_init_orto.md
+│   └── prompt_demo_sessione_tipo.md
+└── scripts/
+    ├── README_SCRIPTS.md
+    ├── init_new_orto.py
+    ├── init_orto.sh
+    ├── json_to_md_converter.py
+    ├── sync_md_from_agents.py
+    ├── register_orto.py
+    ├── template_garden_config.md
+    └── template_questionnaire_responses.md
+```
+
+### Output: orto-skills Suite
+
+```
+orto-suite/
+├── 9 skills AgentSkills:
+│   ├── orto-init/                     # Da: Workflow 00 + init_new_orto.py
+│   ├── orto-onboarding/               # Da: Workflow 01 + prompt_onboarding.md
+│   ├── orto-agronomo/                 # Da: Agente 02 + skill AGR-CROP-MIX
+│   ├── orto-calendario/               # Da: Agente 03 + skill AGR-SEASONALITY
+│   ├── orto-fitopatologo/             # Da: Agente 04 + skill PHYTO-DIAG + PHYTO-TREAT-BIO
+│   ├── orto-layout/                   # Da: Agente 06 + skill AGR-COMPANION
+│   ├── orto-irrigazione/              # Da: Agente 05 + skill IRR-ZONING + IRR-SCHEDULING
+│   ├── orto-meteo-decisioni/          # Da: Agente 11 + skill MET-IRR-DECISION
+│   └── orto-orchestratore/            # Da: Agente 01 + QA-CONSISTENCY + merge workflow
+│
+├── references/ (8 file, 88 KB)
+│   ├── colture_it.md                  # Da: docs/knowledge/ + colture catalog
+│   ├── calendario_it.md               # Da: docs/workflows/ + stagionalità
+│   ├── malattie_trattamenti.md        # Da: docs/agents/04 + knowledge fitopatologia
+│   ├── irrigazione_parametri.md       # Da: docs/agents/05 + knowledge irrigazione
+│   ├── consociazioni_layout.md        # Da: docs/agents/06 + knowledge consociazioni
+│   ├── meteo_soglie.md                # Da: docs/agents/11 + knowledge meteo
+│   ├── conflitti_risoluzione.md       # Da: docs/03_architettura_multiagente.md (sez. conflitti)
+│   └── qa_checklist.md                # Da: Agente 10 QA & Safety
+│
+└── Symlink: ogni skill → ../references (condivisi)
+```
+
+---
+
+## 🔍 Pattern di Trasformazione Distillati
+
+### 1. **Agente → Skill (Non 1:1)**
+
+| Pattern | Esempio | Note |
+|---------|---------|------|
+| **1 Agente → 1 Skill** | Agente 02 (Agronomo) → orto-agronomo | Caso ideale, quando agente è auto-contenuto |
+| **1 Agente → 1 Skill + References** | Agente 05 (Irrigazione) → orto-irrigazione + irrigazione_parametri.md | Knowledge pesante estratta in references |
+| **2+ Agenti → 1 Skill** | Agente 04 (Fitopatologo) + skill PHYTO-DIAG + PHYTO-TREAT-BIO → orto-fitopatologo | Agenti correlati mergiati per coerenza |
+| **Agente + Workflow → Skill** | Agente 01 (Orchestratore) + Workflow 02/03/04 → orto-orchestratore | Orchestratore coordina workflow multipli |
+| **Workflow → Skill** | Workflow 00 (Init) + init_new_orto.py → orto-init | Workflow con script diventa skill operativa |
+| **Agente Eliminato** | Agente 08 (Data Manager), 09 (UI/UX), 12 (Ops) | Non essenziali per MVP, funzionalità assorbite |
+
+**Regola:** Non mappare 1:1. Raggruppa per **coerenza funzionale** e **minimizza skills** mantenendo separazione of concerns.
+
+### 2. **Knowledge → References Centralizzate**
+
+| Input Pattern | Output Pattern |
+|--------------|----------------|
+| `docs/knowledge/*.md` | `references/*.md` (1:1 o mergiato) |
+| `docs/agents/*/` (sezioni knowledge) | Estratte → `references/*.md` |
+| `docs/skills/01_skill_catalog.md` | Mappato → references da creare |
+| Tabelle, liste, parametri | Mantenuti in markdown strutturato |
+
+**Regola:** Tutto il knowledge **pesante** (>500 linee) o **condiviso** (usato da 2+ skills) → references/. Skills leggono references on-demand.
+
+### 3. **Workflow → Fasi nel Corpo SKILL.md**
+
+| Input | Output |
+|-------|--------|
+| `docs/workflows/01_onboarding.md` | orto-onboarding: Fase 1-5 (blocchi questionario) |
+| `docs/workflows/02_piano_stagionale.md` | orto-agronomo: Fase 1-4 (filtra, candidate, costruisci piano) |
+| `docs/workflows/03_esecuzione_settimanale.md` | orto-calendario: Fase 1-3 (genera task, meteo-check, output) |
+
+**Regola:** Ogni workflow diventa una **sequenza di fasi** nel corpo della skill. Mantenere nomi fasi descrittivi (Fase 1: Filtra Colture per Vincoli).
+
+### 4. **Scripts → scripts/ nella Skill (Opzionale)**
+
+| Input | Output | Decisione |
+|-------|--------|-----------|
+| `init_new_orto.py` (20 KB) | Integrato in orto-init (logica inline) | Script semplice → inline nel corpo |
+| `json_to_md_converter.py` | Non incluso | Utility una-tantum, non needed runtime |
+| `sync_md_from_agents.py` | Non incluso | QA tool, non needed runtime |
+
+**Regola:** Includere `scripts/` solo se:
+- Script è **riutilizzabile** (eseguito multiple volte)
+- Script è **deterministico** (no modifiche ambientali)
+- Script è **più efficiente** che riscriverlo ogni volta
+
+### 5. **Storage Architecture → Documentato in SKILL.md**
+
+| Input | Output |
+|-------|--------|
+| `docs/architettura_storage.md` | Sezione "Gestione Progetti & Registry" in orto-orchestratore + orto-init |
+| Struttura directory orto/ | Documentata in SKILL.md con tree markdown |
+| Registry JSON | Specificato formato + percorso in SKILL.md |
+
+**Regola:** La skill deve sapere **dove leggere/scrivere**. Documentare struttura directory e convenzioni naming nel corpo SKILL.md.
+
+### 6. **Prompts → Integrati o Eliminati**
+
+| Input | Output |
+|-------|--------|
+| `prompts/master_prompt_openclaw.md` | Non incluso (era prompt di generazione, non runtime) |
+| `prompts/prompt_onboarding.md` | Integrato in orto-onboarding (Fase 1: Raccolta Dati) |
+| `prompts/prompt_init_orto.md` | Integrato in orto-init (Input section) |
+
+**Regola:** Prompt che sono **template di input** → integrati come sezioni Input nella skill. Prompt di **generazione framework** → eliminati (non servono runtime).
+
+---
+
+## 🏗️ Architettura della Skill `framework-translator`
+
+### Struttura Proposta
+
+```
+framework-translator/
+├── SKILL.md                           # Istruzioni traduzione
+├── scripts/
+│   ├── analyze_framework.py           # Analizza struttura input
+│   ├── map_entities.py                # Mappa agenti/workflow → skills
+│   ├── extract_knowledge.py           # Estrae knowledge → references
+│   ├── generate_skill.py              # Genera SKILL.md da template
+│   └── validate_output.py             # Valida skills generate
+├── references/
+│   ├── mapping_patterns.md            # Pattern di mappatura (tabella sopra)
+│   ├── skill_template.md              # Template SKILL.md standardizzato
+│   ├── agent_analysis_checklist.md    # Checklist analisi agenti
+│   └── quality_criteria.md            # Criteri QA per skills generate
+└── assets/
+    └── example_outputs/               # Esempi: orto_v1 → orto-skills
+```
+
+### Frontmatter (Bozza)
+
+```yaml
+name: framework-translator
+description: Trasformare framework testuali eterogenei (multi-cartella, multi-agente, workflow) in set di skills AgentSkills-compatibili. Usare quando: (1) convertire framework esistente in skills eseguibili, (2) standardizzare documentazione multi-agente in formato AgentSkills, (3) estrarre knowledge da framework e centralizzare in references, (4) generare pipeline di skills coordinate da orchestratore. Output: Cartella <framework>-skills/ con N skills AgentSkills-compatibili, references centralizzate, script INSTALL.sh, documentazione installazione.
+```
+
+---
+
+## 📋 Processo di Traduzione (Workflow della Skill)
+
+### Fase 1: Analisi Framework Input
+
+**Obiettivo:** Capire struttura, entità, dipendenze del framework input.
+
+**Input:** Percorso framework (es. `/path/to/framework/`)
+
+**Azioni:**
+
+1. **Scansiona struttura directory**
+   ```bash
+   find <framework_path> -type f -name "*.md" | head -50
+   ```
+
+2. **Identifica cartelle chiave**
+   - `agents/` o `agenti/` → Agenti da trasformare
+   - `workflows/` o `flussi/` → Workflow da mappare
+   - `knowledge/` o `docs/` → Knowledge da estrarre
+   - `scripts/` → Script da valutare
+   - `prompts/` → Prompt da integrare
+
+3. **Leggi file index/overview**
+   - `agents/00_agent_index.md` o simile
+   - `workflows/00_workflow_index.md` o simile
+   - `README.md` del framework
+
+4. **Estrai metadata agenti**
+   Per ogni file agente:
+   - Nome agente
+   - Missione/responsabilità
+   - Input/output (se specificati)
+   - Skills richieste (se specificate)
+   - Regole decisionali
+
+5. **Estrai metadata workflow**
+   Per ogni workflow:
+   - Nome workflow
+   - Trigger/condizioni
+   - Fasi/step
+   - Agenti coinvolti
+
+**Output:** `analysis_report.md` con:
+- Lista agenti (N totale, nomi, responsabilità)
+- Lista workflow (N totale, nomi, agenti coinvolti)
+- Knowledge base identificata (file, dimensioni, argomenti)
+- Scripts valutati (includere? sì/no + motivo)
+
+---
+
+### Fase 2: Mappatura Entità → Skills
+
+**Obiettivo:** Decidere come trasformare agenti + workflow in skills.
+
+**Input:** `analysis_report.md`
+
+**Azioni:**
+
+1. **Applica pattern di mappatura** (da references/mapping_patterns.md)
+   - 1 Agente → 1 Skill (se auto-contenuto)
+   - 2+ Agenti → 1 Skill (se correlati funzionalmente)
+   - Workflow → Skill (se operativo, con script)
+   - Agente + Workflow → Skill (se orchestrazione)
+
+2. **Raggruppa per coerenza funzionale**
+   ```
+   Esempio:
+   - Agronomo Colture + Nutrizione & Consumi → orto-agronomo (se overlap forte)
+   - Fitopatologo + Trattamenti → orto-fitopatologo (già uniti)
+   - Irrigazione + Automazione → orto-irrigazione (mantieni unito)
+   ```
+
+3. **Identifica orchestratore**
+   - Quale skill coordina le altre?
+   - Di solito: Agente 01 (Planner/Orchestratore) + QA
+
+4. **Identifica references necessarie**
+   - Quali knowledge sono condivisi da 2+ skills?
+   - Quali sono troppo pesanti per il corpo SKILL.md?
+
+**Output:** `mapping_plan.md` con:
+- Skills da generare (N totale, nomi, agenti/workflow di origine)
+- References da creare (N totale, nomi, contenuti)
+- Giustificazione decisioni di mappatura
+
+---
+
+### Fase 3: Estrazione Knowledge → References
+
+**Obiettivo:** Centralizzare knowledge in file references condivisi.
+
+**Input:** `mapping_plan.md` + framework source files
+
+**Azioni:**
+
+1. **Per ogni reference pianificata:**
+   - Identifica file sorgente nel framework
+   - Estrai contenuto rilevante (tabelle, liste, parametri)
+   - Riformatta in markdown strutturato (TOC, sezioni, tabelle)
+   - Normalizza naming (lowercase, underscore)
+
+2. **Applica criterio di inclusion**
+   - Includere: Dati fattuali, parametri, tabelle, regole
+   - Escludere: Narrative, introduzioni lunghe, esempi ridondanti
+
+3. **Crea symlink plan**
+   - Quali skills useranno quale reference?
+   - Documenta nel file reference (header: "Usato da: skill-X, skill-Y")
+
+**Output:** Cartella `references/` con N file `.md`
+
+---
+
+### Fase 4: Generazione Skills
+
+**Obiettivo:** Creare N skills AgentSkills-compatibili.
+
+**Input:** `mapping_plan.md` + `references/` + framework source
+
+**Azioni:**
+
+1. **Per ogni skill pianificata:**
+
+   a. **Genera frontmatter YAML**
+      ```yaml
+      name: <skill-name>
+      description: <descrizione concisa con trigger e output>
+      ```
+
+   b. **Genera corpo SKILL.md** (usa template da references/skill_template.md)
+      - **Quando Usare:** 3-5 scenari trigger
+      - **Input:** Tabella input richiesti (nome, tipo, obbligatorio, esempio)
+      - **Processo:**
+        - Fase 1: <nome fase> (da workflow o agente)
+        - Fase 2: <nome fase>
+        - ...
+      - **Output:** File/documento generato, formato, struttura
+      - **Gestione Progetti:** (se applicabile) Struttura directory, registry
+      - **References:** Elenco references usate con link
+
+   c. **Integra script** (se deciso in Fase 2)
+      - Copia script in `scripts/` della skill
+      - Documenta uso nel corpo SKILL.md
+
+   d. **Valida struttura**
+      - Frontmatter presente e valido?
+      - Corpo <500 linee (o references usate)?
+      - References linkati esistono?
+
+2. **Crea struttura skill**
+   ```
+   <skill-name>/
+   ├── SKILL.md
+   ├── scripts/ (opzionale)
+   └── README.md (opzionale, solo se utile per umani)
+   ```
+
+**Output:** Cartella `<framework>-skills/` con N sottocartelle skill
+
+---
+
+### Fase 5: Packaging e Documentazione
+
+**Obiettivo:** Rendere le skills pronte per distribuzione.
+
+**Input:** Cartella `<framework>-skills/`
+
+**Azioni:**
+
+1. **Crea references centralizzate**
+   - Sposta `references/` in root di `<framework>-skills/`
+   - Crea symlink in ogni skill → `../references`
+
+2. **Genera INSTALL.sh**
+   ```bash
+   #!/bin/bash
+   # Script installazione framework-skills
+   SOURCE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+   TARGET="$HOME/.openclaw/skills/<framework>-skills"
+   
+   echo "Installing <framework>-skills..."
+   cp -r "$SOURCE/<framework>-suite" "$TARGET"
+   echo "Installation complete!"
+   ```
+
+3. **Genera README.md root**
+   - Panoramica framework
+   - Lista skills (N totale, nomi, descrizioni brevi)
+   - Istruzioni installazione (3 metodi: script, manuale, chat-only)
+   - Struttura directory
+
+4. **Validazione finale**
+   - Tutte le skills hanno SKILL.md valido?
+   - Tutti i references linkati esistono?
+   - INSTALL.sh funziona?
+   - README.md chiaro?
+
+**Output:** Pacchetto pronto per distribuzione
+
+---
+
+## ✅ Criteri di Qualità (QA Checklist)
+
+### Per Ogni Skill Generata
+
+- [ ] **Frontmatter YAML valido** (name + description presenti)
+- [ ] **Descrizione trigger-specifica** (include "Usare quando:" con 3+ scenari)
+- [ ] **Corpo <500 linee** (o references usate appropriatamente)
+- [ ] **Fasi numerate e nominate** (Fase 1: <nome>, Fase 2: <nome>, ...)
+- [ ] **Output documentato** (file, formato, struttura)
+- [ ] **References linkati** (se usati, percorsi corretti)
+- [ ] **Niente JSON per dati** (solo markdown, tranne registry)
+- [ ] **Niente sezioni ridondanti** (no "When to Use" nel corpo se già in description)
+
+### Per Ogni Reference
+
+- [ ] **TOC in header** (se >100 linee)
+- [ ] **Contenuto strutturato** (tabelle, liste, sezioni)
+- [ ] **Niente narrative** (solo dati fattuali, parametri, regole)
+- [ ] **Header con metadata** (Usato da: skill-X, skill-Y)
+- [ ] **Nome lowercase underscore** (es. `colture_it.md`)
+
+### Per Pacchetto Complessivo
+
+- [ ] **Struttura ultra-semplice** (una cartella da copiare)
+- [ ] **Symlink funzionanti** (tutti risolti)
+- [ ] **INSTALL.sh testato** (esecuzione verificata)
+- [ ] **README.md chiaro** (installazione in 3 metodi)
+- [ ] **Niente file ridondanti** (no build/, no guide duplicate)
+- [ ] **Git-initialized** (ogni skill ha `.git/` se richiesto)
+
+---
+
+## 🧪 Piano di Test
+
+### Test 1: Framework Semplice (1-2 agenti)
+
+**Input:** Framework minimale con 2 agenti + 1 workflow
+
+**Obiettivo:** Verificare mappatura base 1:1
+
+**Criteri successo:**
+- 2 skills generate
+- 1 reference (se knowledge condiviso)
+- INSTALL.sh funziona
+
+---
+
+### Test 2: Framework Medio (5-7 agenti)
+
+**Input:** Framework con 5-7 agenti + 3 workflow + knowledge
+
+**Obiettivo:** Verificare raggruppamento agenti correlati
+
+**Criteri successo:**
+- 4-5 skills generate (alcuni merge)
+- 3-4 references centralizzate
+- Orchestratore identificato correttamente
+
+---
+
+### Test 3: Framework Complesso (10+ agenti)
+
+**Input:** orto_v1 o simile (12 agenti, 5 workflow, knowledge estesa)
+
+**Obiettivo:** Verificare scala completa
+
+**Criteri successo:**
+- 8-10 skills generate (merge ottimizzati)
+- 6-10 references
+- Conflitti gestiti (documentati in reference conflitti)
+- Pacchetto pronto per produzione
+
+---
+
+## 📅 Roadmap di Sviluppo
+
+### Sprint 1: Core Infrastructure (2-3 sessioni)
+
+- [ ] Creare struttura skill `framework-translator`
+- [ ] Scrivere `references/mapping_patterns.md` (pattern distillati sopra)
+- [ ] Scrivere `references/skill_template.md` (template standardizzato)
+- [ ] Implementare `scripts/analyze_framework.py`
+- [ ] Testare su framework semplice (mock o reale)
+
+---
+
+### Sprint 2: Estrazione e Mappatura (3-4 sessioni)
+
+- [ ] Implementare `scripts/map_entities.py`
+- [ ] Implementare `scripts/extract_knowledge.py`
+- [ ] Scrivere `references/agent_analysis_checklist.md`
+- [ ] Testare su framework medio (5-7 agenti)
+- [ ] Raffinare pattern di mappatura basato su test
+
+---
+
+### Sprint 3: Generazione Skills (4-5 sessioni)
+
+- [ ] Implementare `scripts/generate_skill.py`
+- [ ] Scrivere `references/quality_criteria.md`
+- [ ] Implementare validazione output
+- [ ] Testare su orto_v1 (framework complesso)
+- [ ] Confrontare output con orto-skills manuali (gap analysis)
+
+---
+
+### Sprint 4: Packaging e Documentazione (2-3 sessioni)
+
+- [ ] Implementare `scripts/validate_output.py`
+- [ ] Automatizzare creazione symlink
+- [ ] Generare INSTALL.sh dinamico
+- [ ] Generare README.md dinamico
+- [ ] Documentare skill (corpo SKILL.md completo)
+- [ ] Test end-to-end su 2-3 framework diversi
+
+---
+
+### Sprint 5: Refinement e Production (2-3 sessioni)
+
+- [ ] Raccogliere feedback da test reali
+- [ ] Ottimizzare pattern di mappatura
+- [ ] Migliorare gestione edge cases
+- [ ] Scrivere esempi in `assets/example_outputs/`
+- [ ] Pubblicare skill (clawhub o manuale)
+
+---
+
+## 🔧 Edge Cases da Gestire
+
+### 1. Framework Non-Standard
+
+**Problema:** Framework senza cartelle `agents/` o `workflows/`
+
+**Soluzione:** 
+- Scansione euristica (cerca file con "agent", "workflow", "skill" nel nome)
+- Chiedi all'utente di identificare entità principali
+- Fallback: tratta ogni file `.md` come potenziale skill
+
+---
+
+### 2. Agenti con Overlap Funzionale Forte
+
+**Problema:** 2+ agenti con responsabilità quasi identiche
+
+**Soluzione:**
+- Rileva overlap (confronta descrizioni missione)
+- Suggerisci merge in skill unica
+- Documenta decisione in `mapping_plan.md`
+
+---
+
+### 3. Knowledge Molto Grande (>50 KB)
+
+**Problema:** Single reference file troppo pesante
+
+**Soluzione:**
+- Splitta per argomento (es. `colture_it.md` → `colture_nord.md`, `colture_centro.md`, `colture_sud.md`)
+- Usa TOC dettagliato per navigazione
+- Documenta in SKILL.md quando leggere quale parte
+
+---
+
+### 4. Workflow con Dipendenze Cicliche
+
+**Problema:** Workflow A richiede output di B, B richiede output di A
+
+**Soluzione:**
+- Rileva cicli (grafo dipendenze)
+- Segnala all'utente (richiede refactoring framework)
+- Fallback: crea skill orchestratore che gestisce iterazione
+
+---
+
+### 5. Script con Dipendenze Esterne
+
+**Problema:** Script richiedono librerie Python non standard
+
+**Soluzione:**
+- Documenta dipendenze in `scripts/README.md`
+- Genera `requirements.txt` per la skill
+- Valuta se includere script o convertire logica in markdown
+
+---
+
+## 📝 Decisioni di Progetto
+
+### 1. Naming Convention
+
+**Decisione:** Skill names in `lowercase-kebab-case` con prefix del framework
+
+**Esempio:** `orto-init`, `orto-agronomo`, `framework-translator`
+
+**Motivo:** Coerente con AgentSkills esistenti, leggibile, git-friendly
+
+---
+
+### 2. References: Copie o Symlink?
+
+**Decisione:** Symlink centralizzati (una copia, N link)
+
+**Motivo:**
+- Aggiornamenti automatici (modifichi reference, tutte skills vedono cambio)
+- Risparmio spazio (no duplicati)
+- Coerente con orto-skills
+
+---
+
+### 3. Script: Includere o Inline?
+
+**Decisione:** Includere solo se riutilizzabile e deterministico
+
+**Motivo:**
+- Script una-tantum → inline nel corpo (meno complessità)
+- Script riutilizzabile → `scripts/` (efficienza, token savings)
+
+---
+
+### 4. Output: Una Cartella o N Cartelle Separate?
+
+**Decisione:** Una cartella `<framework>-suite/` con tutte skills + references
+
+**Motivo:**
+- Ultra-semplice da installare (cp -r)
+- References centralizzati
+- Coerente con orto-skills
+
+---
+
+## 🎓 Lezioni Apprese da orto_v1 → orto-skills
+
+### Cosa Ha Funzionato Bene
+
+1. **Raggruppamento agenti correlati** (es. Fitopatologo + Trattamenti → 1 skill)
+2. **References centralizzate** (8 file, 88 KB, condivisi da 9 skills)
+3. **Symlink per references** (aggiornamenti automatici, no duplicati)
+4. **Una cartella da copiare** (installazione ultra-semplice)
+5. **Documentazione fasi nel corpo** (Fase 1, Fase 2, ... chiaro e azionabile)
+
+---
+
+### Cosa Potrebbe Migliorare
+
+1. **Automazione analisi iniziale** (fatta manuale, potrebbe essere script)
+2. **Pattern di mappatura documentati prima** (abbiamo distillato dopo)
+3. **Validazione QA automatizzata** (fatta manuale, checklist non eseguita automaticamente)
+4. **Gestione conflitti** (documentata in reference, ma potrebbe essere più esplicita nel processo)
+
+---
+
+### Pattern da Preservare
+
+1. **Progressive disclosure** (metadata → SKILL.md → references)
+2. **Concise is key** (SKILL.md <500 linee, references per dettagli)
+3. **Human-readable output** (markdown, tabelle, liste, no JSON per dati)
+4. **Audit trail** (documentare decisioni in mapping_plan.md)
+
+---
+
+## 🚀 Prossimi Passi Immediati
+
+1. **Creare cartella `framework-translator/`** nel workspace
+2. **Scrivere SKILL.md bozza** (frontmatter + processo alto livello)
+3. **Creare `references/mapping_patterns.md`** (pattern distillati sopra)
+4. **Creare `references/skill_template.md`** (template standardizzato)
+5. **Testare analisi su orto_v1** (run manuale di Fase 1)
+6. **Iterare basato su risultati**
+
+---
+
+## 📌 Note Finali
+
+**Questa skill è meta:** Trasforma framework in skills, che a loro volta potrebbero essere usate per trasformare altri framework.
+
+**Valore principale:** Riduce tempo di trasformazione da **giorni/settimane** a **ore**, con consistenza e qualità prevedibili.
+
+**Rischio principale:** Over-engineering. Mantenere skill semplice e focalizzata su pattern comuni. Edge cases gestiti con escalation all'utente.
+
+**Successo metrico:** Framework trasformato in ≤4 ore, con QA score ≥0.9 (da qa_checklist.md).
+
+---
+
+_Fine del documento di piano. Pronto per revisione e feedback._