framework-translator/scripts/README.md

Scripts — Framework Translator (LLM-Native)

Script meccanici per supporto operativo al processo LLM.

Panoramica

Questi script NON fanno analisi semantica — solo operazioni meccaniche:

• Listare file
• Creare directory
• Creare symlink
• Generare file template (INSTALL.sh, README.md)

Tutta l'analisi e generazione è fatta da LLM leggendo SKILL.md.

---

Script Disponibili

01_scan_files.sh — Scansione Framework

Scopo: Lista file markdown e struttura directory del framework.

Input:

• Percorso framework

Output:

• Lista directory
• Lista file markdown
• Lista script
• Cartelle chiave identificate

Utilizzo:

./scripts/01_scan_files.sh /path/to/framework

Output esempio:

📂 Scansione framework: /path/to/orto_v1
==============================================

### STRUTTURA DIRECTORY

/path/to/orto_v1
/path/to/orto_v1/docs
/path/to/orto_v1/docs/agents
/path/to/orto_v1/docs/workflows
...

### FILE MARKDOWN (47 totali)

/path/to/orto_v1/README.md
/path/to/orto_v1/docs/agents/00_agent_index.md
/path/to/orto_v1/docs/agents/01_orchestratore.md
...

### CARTELLE CHIAVE IDENTIFICATE

✓ agents: /path/to/orto_v1/docs/agents
✓ workflows: /path/to/orto_v1/docs/workflows
✓ knowledge: /path/to/orto_v1/docs/knowledge
✓ scripts: /path/to/orto_v1/scripts

Per LLM: Usa questo output come contesto per Fase 1 (analisi framework).

---

02_create_structure.sh — Crea Struttura Distribuzione

Scopo: Organizza skills e references in struttura finale, crea symlink.

Input:

• Nome framework (es. orto-skills)
• Directory sorgente (con skills e references generate)

Output:

• Directory <framework>-suite/ organizzata
• Symlink references/ in ogni skill

Utilizzo:

./scripts/02_create_structure.sh orto-skills ./output/

Output esempio:

📦 Creazione struttura distribuzione: orto-skills-suite
==============================================

### Spostamento skills...
  ✓ Skill: orto-init
  ✓ Skill: orto-agronomo
  ✓ Skill: orto-calendario

### Spostamento references...
  ✓ References directory

### Creazione symlink references...
  ✓ Symlink: orto-init/references → ../references
  ✓ Symlink: orto-agronomo/references → ../references
  ✓ Symlink: orto-calendario/references → ../references

✅ Struttura creata: orto-skills-suite

Per LLM: Esegui dopo Fase 4 (generazione skills completata).

---

03_generate_packaging.sh — Genera Packaging

Scopo: Genera INSTALL.sh e README.md per distribuzione.

Input:

• Directory distribuzione (<framework>-suite/)

Output:

• INSTALL.sh (script installazione automatica)
• README.md (documentazione con lista skills)

Utilizzo:

./scripts/03_generate_packaging.sh ./orto-skills-suite

Output esempio:

📦 Generazione packaging per: ./orto-skills-suite
==============================================

### Generazione INSTALL.sh...
  ✓ INSTALL.sh generato

### Generazione README.md...
  ✓ README.md generato

✅ Packaging completato

File generati:
-rwxr-xr-x INSTALL.sh
-rw-r--r-- README.md

Per LLM: Esegui come ultimo step (Fase 5).

---

Workflow Completo (LLM + Script)

# FASE 1-4: LLM (leggi SKILL.md, esegui analisi e generazione)
# ... LLM lavora su analysis_report.md, mapping_plan.md, references/, skills/ ...

# FASE 5: Script meccanici

# 1. Scansione iniziale (opzionale, per contesto)
./scripts/01_scan_files.sh /path/to/framework > ./output/scan_results.txt

# 2. Crea struttura distribuzione (dopo Fase 4)
./scripts/02_create_structure.sh orto-skills ./output/

# 3. Genera packaging (dopo step 2)
./scripts/03_generate_packaging.sh ./orto-skills-suite

---

Differenze vs. Approccio Python (Archiviato)

Aspetto	Script Python (archiviati)	Script Bash (attuali)
Analisi semantica	Sì (regex, euristico)	No (solo meccanico)
Generazione contenuto	Sì (template rigido)	No (fatto da LLM)
Linee di codice	~2,000	~150
Manutenzione	Complessa (test, debug)	Semplice (solo I/O)
Flessibilità	Bassa (formati fissi)	Alta (LLM si adatta)
Token usage	0	~35-65K per framework

---

Script Archiviati (Python)

Gli script Python originali sono archiviati in:

scripts-archive/
├── analyze_framework.py       # Fase 1 (parsing automatico)
├── map_entities.py            # Fase 2 (mappatura euristica)
├── extract_knowledge.py       # Fase 3 (estrazione keyword)
└── generate_skill.py          # Fase 4 (template rigido)

Perché archiviati: Troppo complessi, fragili, output generico. L'approccio LLM-native è più flessibile e produce output di qualità superiore.

Quando usarli: Solo come riferimento o se vuoi sperimentare approccio ibrido.

---

Note Tecniche

Bash vs. Python

Bash scelto perché:

• Script <100 linee (semplici)
• Solo I/O e operazioni file
• Nessuna logica complessa
• Ubiquo (tutti i sistemi Unix)

Python non necessario perché:

• LLM fa analisi/generazione
• Script sono solo "colla" meccanica

Compatibilità

Testato su:

• Linux (Ubuntu/Debian)
• macOS
• Windows (WSL, Git Bash)

Permessi

Assicura che gli script siano eseguibili:

chmod +x scripts/*.sh

---

Aggiornato: 2026-03-07 | Versione: 2.0 (LLM-Native)