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.
700 lines
25 KiB
Markdown
700 lines
25 KiB
Markdown
# 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._
|