framework-translator/references/mapping_patterns.md

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:

### 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:

### 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:

### 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