# 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:**
```bash
./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:**
```bash
./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:**
```bash
./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)

```bash
# 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:
```bash
chmod +x scripts/*.sh
```

---

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