# Mapping Patterns — Trasformazione Framework → AgentSkills

_Pattern di mappatura per trasformare entità framework (agenti, workflow, knowledge) in skills AgentSkills-compatibili._

_Usato da: framework-translator (Fase 2)_

---

## Panoramica

Questa reference documenta i pattern di trasformazione usati in **Fase 2: Mappatura Entità → Skills** del processo `framework-translator`.

Ogni pattern include:
- **Descrizione:** Quando applicare il pattern
- **Esempio:** Caso concreto da orto_v1 → orto-skills
- **Criteri:** Condizioni per applicare il pattern
- **Output:** Cosa genera il pattern

---

## Pattern 1: 1 Agente → 1 Skill

**Descrizione:** Un agente auto-contenuto con responsabilità chiara diventa una skill singola.

**Esempio:**
```
Input:  Agente 02 "Agronomo Colture" (piano colture, varietà, rotazioni)
Output: orto-agronomo skill
```

**Criteri:**
- Agente ha missione ben definita e singola
- Non ha overlap significativo con altri agenti (<30%)
- Knowledge richiesta è specifica del dominio
- Output è chiaramente identificabile

**Output:**
- 1 skill con nome `<prefix>-<agente-name>` (kebab-case)
- Corpo SKILL.md con fasi derivate da workflow associati
- References: knowledge specifica dell'agente

---

## Pattern 2: 2+ Agenti → 1 Skill (Merge Funzionale)

**Descrizione:** Agenti con responsabilità correlate o overlap funzionale sono mergiati in una skill unica.

**Esempio:**
```
Input:  Agente 04 "Fitopatologo" + Skill PHYTO-DIAG + PHYTO-TREAT-BIO
Output: orto-fitopatologo skill (diagnosi + trattamenti unificati)
```

**Criteri:**
- Overlap funzionale >50% (confronta descrizioni missione)
- Agenti lavorano sullo stesso output/documento
- Separazione è artificiale (storica, non funzionale)
- Merge semplifica UX senza perdere chiarezza

**Output:**
- 1 skill con nome che copre tutte le responsabilità
- Corpo SKILL.md con sezioni distinte per ogni sotto-funzionalità
- References: knowledge condivisa tra agenti originali

**Giustificazione da documentare:**
```markdown
### Decisione: Merge Agente 04 + PHYTO-DIAG + PHYTO-TREAT-BIO

**Motivo:** Diagnosi e trattamenti sono strettamente accoppiati nel workflow reale.
Separarli richiederebbe all'utente due skill distinte per un singolo task.

**Vantaggi:**
- UX semplificata (una skill per "problema piante")
- Meno context switching
- Knowledge condivisa (malattie, trattamenti) centralizzata

**Rischi:**
- Skill più grande (gestito con references separate)
- Mitigazione: sezioni chiare nel corpo SKILL.md
```

---

## Pattern 3: Workflow → Skill Operativa

**Descrizione:** Un workflow end-to-end con script associato diventa una skill operativa.

**Esempio:**
```
Input:  Workflow 00 "Inizializzazione Orto" + init_new_orto.py
Output: orto-init skill
```

**Criteri:**
- Workflow ha trigger chiaro (es. "nuovo progetto")
- Workflow produce output tangibile (struttura directory, file)
- Script esistente automatizza il workflow
- Workflow è eseguible in modo autonomo (no dipendenze da altri workflow)

**Output:**
- 1 skill con nome `<prefix>-<workflow-name>`
- Script incluso in `scripts/` della skill (se riutilizzabile)
- Corpo SKILL.md descrive fasi del workflow

---

## Pattern 4: Agente + Workflow → Skill Orchestratore

**Descrizione:** Agente di coordinamento + workflow multipli diventano skill orchestratore.

**Esempio:**
```
Input:  Agente 01 "Orchestratore/Planner" + Workflow 02/03/04 + QA Agent
Output: orto-orchestratore skill
```

**Criteri:**
- Agente ha responsabilità di coordinamento
- Workflow multipli coinvolgono questo agente
- Skill deve risolvere conflitti tra output di altre skills
- QA/validazione è parte del coordinamento

**Output:**
- 1 skill con nome `<prefix>-orchestratore` o `<prefix>-planner`
- Corpo SKILL.md con sezione "Risoluzione Conflitti"
- Reference: `conflitti_risoluzione.md` (pattern di risoluzione)
- Output: PlanBundle unificato o documento master

---

## Pattern 5: Agente Eliminato (Non Essenziale)

**Descrizione:** Agente non essenziale per MVP viene eliminato, senza creare skill.

**Esempio:**
```
Input:  Agente 08 "Data/Knowledge Manager", Agente 09 "UI/UX Agent", Agente 12 "Ops & Integrazioni"
Output: Nessuna skill generata (funzionalità assorbite o posticipate)
```

**Criteri:**
- Agente gestisce funzionalità non critiche per MVP
- Funzionalità può essere posticipata a v2
- Altre skills possono assorbire responsabilità minori
- Eliminare semplifica senza perdere valore

**Output:**
- Nessuna skill generata
- Documenta in `mapping_plan.md` sezione "Eliminati"
- Eventuali funzionalità critiche assorbite da altre skills

**Giustificazione da documentare:**
```markdown
### Decisione: Eliminare Agente 09 (UI/UX)

**Motivo:** UI/UX è importante ma non essenziale per MVP testuale.
Skill AgentSkills sono per automazione, non per generazione UI.

**Funzionalità perse:**
- Wireframe generation
- Componenti UI specs

**Recupero futuro:**
- Skill separata "ui-generator" in v2
- Per ora: documentazione UI rimane in docs/ del framework
```

---

## Pattern 6: Agente Assorbito (Funzionalità Merge)

**Descrizione:** Agente con funzionalità micro o ridondante viene assorbito da altra skill.

**Esempio:**
```
Input:  Agente 10 "QA & Safety Agent"
Output: Funzionalità QA assorbite da orto-orchestratore
```

**Criteri:**
- Agente ha responsabilità di validazione/check
- Validazione può essere integrata in altra skill (es. orchestratore)
- Separare richiederebbe skill troppo piccola (<100 linee)
- Assorbire migliora coesione

**Output:**
- Nessuna skill separata generata
- Funzionalità QA documentate in skill assorbente (es. orchestratore)
- Reference: `qa_checklist.md` (condivisa)

**Giustificazione da documentare:**
```markdown
### Decisione: Assorbire Agente 10 (QA) in Orchestratore

**Motivo:** QA è parte naturale del processo di orchestrazione.
Separare richiederebbe due step (genera → valida) invece di uno integrato.

**Vantaggi:**
- Workflow più fluido (validazione inline)
- Meno skills da gestire
- QA context-aware (orchestratore conosce tutto il piano)

**Implementazione:**
- orto-orchestratore include sezione "Validazione QA"
- Reference qa_checklist.md consultata durante orchestrazione
```

---

## Pattern 7: Knowledge → Reference Centralizzata

**Descrizione:** Knowledge condivisa da 2+ skills o >500 linee diventa reference centralizzata.

**Esempio:**
```
Input:  docs/knowledge/colture.md (20 KB, usato da Agronomo + Layout)
Output: references/colture_it.md (symlink da entrambe le skills)
```

**Criteri:**
- Knowledge usata da 2+ skills diverse
- Knowledge >500 linee o >10 KB
- Knowledge è dominio-specifica (tabelle, parametri, regole)
- Knowledge è relativamente statica (non cambia per progetto)

**Output:**
- File `references/<nome>.md`
- Symlink da ogni skill che la usa → `../references/<nome>.md`
- Header nel reference: "Usato da: skill-X, skill-Y"

**Tipologie di knowledge da centralizzare:**
- Cataloghi (colture, malattie, varietà)
- Parametri (ET₀, Kc, soglie meteo)
- Tabelle (consociazioni, rotazioni)
- Regole (conflitti, QA checklist)

---

## Pattern 8: Knowledge → Inline nel Corpo

**Descrizione:** Knowledge piccola (<500 linee) e specifica di una skill rimane nel corpo SKILL.md.

**Esempio:**
```
Input:  Agente 02 sezione "Varietà consigliate" (50 righe)
Output: Integrato in orto-agronomo SKILL.md (Fase 2: Lista Colture)
```

**Criteri:**
- Knowledge usata da 1 sola skill
- Knowledge <500 linee e <10 KB
- Knowledge è specifica del dominio della skill
- Separare aggiungerebbe complessità non necessaria

**Output:**
- Knowledge integrata nel corpo SKILL.md (sezione dedicata)
- Nessun reference file creato

---

## Pattern 9: Script → scripts/ nella Skill

**Descrizione:** Script riutilizzabile e deterministico viene incluso nella skill.

**Esempio:**
```
Input:  init_new_orto.py (20 KB, crea struttura directory)
Output: orto-init/scripts/init_new_orto.py
```

**Criteri:**
- Script è riutilizzabile (eseguito multiple volte)
- Script è deterministico (stesso input → stesso output)
- Script ha dipendenze minime (Python standard lib OK)
- Script è più efficiente che riscriverlo inline

**Output:**
- Script copiato in `<skill-name>/scripts/`
- Documentato in SKILL.md (sezione "Scripts")
- Eventuale `requirements.txt` se dipendenze esterne

---

## Pattern 10: Script → Inline nel Corpo

**Descrizione:** Script semplice o una-tantum viene convertito in logica inline nel corpo SKILL.md.

**Esempio:**
```
Input:  json_to_md_converter.py (3 KB, utility migrazione)
Output: Logica descritta in SKILL.md (nessuno script incluso)
```

**Criteri:**
- Script è una-tantum (migrazione, setup iniziale)
- Script è semplice (<50 righe)
- Logica può essere descritta in markdown
- Includere script aggiungerebbe complessità non necessaria

**Output:**
- Logica descritta in corpo SKILL.md (pseudocodice o descrizione)
- Nessuno script incluso

---

## Pattern 11: Script → Eliminato

**Descrizione:** Script non necessario a runtime viene eliminato.

**Esempio:**
```
Input:  sync_md_from_agents.py (5 KB, validazione post-hoc)
Output: Nessuno script incluso (funzionalità assorbita da QA inline)
```

**Criteri:**
- Script è tool di sviluppo/test, non runtime
- Funzionalità è già coperta da QA inline
- Script richiede configurazione complessa
- Eliminare semplifica senza perdere valore

**Output:**
- Script non incluso
- Eventuale menzione in `mapping_plan.md` (sezione "Eliminati")

---

## Pattern 12: Prompt → Integrato come Input Section

**Descrizione:** Prompt che sono template di input diventano sezioni Input nella skill.

**Esempio:**
```
Input:  prompts/prompt_onboarding.md (template questionario)
Output: orto-onboarding SKILL.md, sezione "Input" con tabella campi
```

**Criteri:**
- Prompt è template di raccolta dati
- Prompt definisce input strutturati
- Prompt può essere convertito in tabella markdown

**Output:**
- Tabella Input in SKILL.md (nome, tipo, obbligatorio, esempio)
- Eventuale template markdown in `assets/` se complesso

---

## Pattern 13: Prompt → Eliminato

**Descrizione:** Prompt di generazione framework (non runtime) vengono eliminati.

**Esempio:**
```
Input:  prompts/master_prompt_openclaw.md (generazione specifiche)
Output: Nessuna inclusione (prompt di generazione, non runtime)
```

**Criteri:**
- Prompt serve a generare framework, non a eseguirlo
- Prompt non è necessario per le skills runtime
- Eliminare non perde funzionalità runtime

**Output:**
- Prompt non incluso
- Eventuale menzione storica in README.md

---

## Decision Tree per Mappatura

```
Start: Entità framework (agente/workflow/knowledge/script)
  │
  ├─→ È un Agente?
  │   ├─→ Ha overlap >50% con altro agente?
  │   │   ├─→ SÌ → Pattern 2 (Merge 2+ Agenti → 1 Skill)
  │   │   └─→ NO → È essenziale per MVP?
  │   │       ├─→ SÌ → Pattern 1 (1 Agente → 1 Skill)
  │   │       └─→ NO → Pattern 5 (Eliminato) o Pattern 6 (Assorbito)
  │   │
  │   └─→ È di coordinamento/orchestrazione?
  │       ├─→ SÌ → Pattern 4 (Agente + Workflow → Orchestratore)
  │       └─→ NO → (vedi sopra)
  │
  ├─→ È un Workflow?
  │   ├─→ Ha script associato?
  │   │   ├─→ SÌ → Pattern 3 (Workflow → Skill Operativa)
  │   │   └─→ NO → È orchestrato da altro agente?
  │   │       ├─→ SÌ → Pattern 4 (Agente + Workflow → Orchestratore)
  │   │       └─→ NO → Pattern 3 (Workflow → Skill, no script)
  │   │
  │   └─→ (vedi sopra)
  │
  ├─→ È Knowledge?
  │   ├─→ È condivisa da 2+ skills o >500 linee?
  │   │   ├─→ SÌ → Pattern 7 (Knowledge → Reference Centralizzata)
  │   │   └─→ NO → Pattern 8 (Knowledge → Inline nel Corpo)
  │   │
  │   └─→ (vedi sopra)
  │
  └─→ È uno Script?
      ├─→ È riutilizzabile e deterministico?
      │   ├─→ SÌ → Pattern 9 (Script → scripts/ nella Skill)
      │   └─→ NO → È semplice o una-tantum?
      │       ├─→ SÌ → Pattern 10 (Script → Inline nel Corpo)
      │       └─→ NO → Pattern 11 (Script → Eliminato)
      │
      └─→ (vedi sopra)
```

---

## Esempi da orto_v1 → orto-skills

| Entità Origine | Pattern Applicato | Output | Giustificazione |
|----------------|-------------------|--------|-----------------|
| Agente 01 (Orchestratore) | Pattern 4 | orto-orchestratore | Coordina workflow multipli + QA |
| Agente 02 (Agronomo) | Pattern 1 | orto-agronomo | Auto-contenuto, responsabilità chiara |
| Agente 03 (Stagionalità) | Pattern 1 | orto-calendario | Auto-contenuto |
| Agente 04 (Fitopatologo) + PHYTO-DIAG + PHYTO-TREAT-BIO | Pattern 2 | orto-fitopatologo | Merge funzionale (diagnosi + trattamenti) |
| Agente 05 (Irrigazione) | Pattern 1 | orto-irrigazione | Auto-contenuto |
| Agente 06 (Layout) | Pattern 1 | orto-layout | Auto-contenuto |
| Agente 07 (Nutrizione) | Pattern 6 | Assorbito in orto-agronomo | Overlap forte con agronomo |
| Agente 08 (Data Manager) | Pattern 6 | Assorbito in orchestratore | QA già in orchestratore |
| Agente 09 (UI/UX) | Pattern 5 | Eliminato | Non essenziale per MVP testuale |
| Agente 10 (QA) | Pattern 6 | Assorbito in orchestratore | Validazione inline |
| Agente 11 (Meteo) | Pattern 1 | orto-meteo-decisioni | Auto-contenuto |
| Agente 12 (Ops) | Pattern 5 | Eliminato | Integrazioni gestite da singole skills |
| Workflow 00 (Init) + init_new_orto.py | Pattern 3 | orto-init | Workflow operativo con script |
| Workflow 01 (Onboarding) | Pattern 3 | orto-onboarding | Workflow di raccolta dati |
| colture.md (knowledge) | Pattern 7 | references/colture_it.md | Condivisa, 20 KB |
| init_new_orto.py | Pattern 9 | orto-init/scripts/ | Riutilizzabile, deterministico |
| json_to_md_converter.py | Pattern 11 | Eliminato | Utility migrazione, non runtime |
| prompt_onboarding.md | Pattern 12 | orto-onboarding Input section | Template di raccolta dati |
| master_prompt_openclaw.md | Pattern 13 | Eliminato | Prompt di generazione, non runtime |

---

## Checklist Applicazione Pattern

Prima di finalizzare la mappatura, verifica:

- [ ] Ogni agente ha un pattern applicato (1, 2, 4, 5, o 6)
- [ ] Ogni workflow ha un pattern applicato (3 o 4)
- [ ] Ogni knowledge ha un pattern applicato (7 o 8)
- [ ] Ogni script ha un pattern applicato (9, 10, o 11)
- [ ] Ogni prompt ha un pattern applicato (12 o 13)
- [ ] Pattern applicati sono coerenti con criteri
- [ ] Giustificazioni documentate per Pattern 2, 5, 6
- [ ] Decision tree seguito in ordine logico

---

_Aggiornato: 2026-03-07 | Versione: 1.0_