c40ddf4b59
- 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.
455 lines
14 KiB
Markdown
455 lines
14 KiB
Markdown
# 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_
|