orto-skills/build/orto-init/SKILL.md

---
name: orto-init
description: Initialize a new community or home garden project in the Orto management system. Use when: (1) setting up a new garden with location, size, and environmental details, (2) creating the directory structure and markdown templates for the project, (3) registering the garden in the project registry, (4) preparing questionnaire blocks for user profiling. Outputs: Garden config markdown, questionnaire templates, audit trail, directory structure ready for onboarding workflow.
---

# Orto Init — Garden Project Initialization

Initialize a new garden project from scratch. This is the first step in the Orto workflow.

## When to Use This Skill

- **New garden setup:** User wants to start managing a garden with Orto
- **Garden registration:** Assign unique ID, name, location, and basic environment data
- **Directory scaffolding:** Create project structure (config, data, logs, media, report folders)
- **Template preparation:** Generate markdown templates for questionnaire, config, calendar, etc.

## Inputs

Codex collects these details from the user (or uses defaults if unavailable):

| Input | Type | Required | Example |
|-------|------|----------|---------|
| `orto_id` | String | Yes | `orto_roma_testaccio_001` |
| `orto_name` | String | Yes | `Orto Testaccio Roma` |
| `provincia` | String | Yes | `Roma` |
| `regione` | String | Yes | `Lazio` |
| `latitude` | Float | Yes | `41.8782` |
| `longitude` | Float | Yes | `12.4922` |
| `area_mq` | Float | No (collect in onboarding) | `50` |
| `climate_zone` | Enum | No (infer from lat/lon) | `centro` |

### Input Validation

- `orto_id`: lowercase, underscore/hyphen only, max 64 chars (e.g., `orto_NAME_NUMBER`)
- `provincia` + `regione`: normalize to Italian region list (Roma → Lazio)
- `latitude`: -90 to 90, decimal
- `longitude`: -180 to 180, decimal
- `area_mq`: positive float if provided

## Process

### Phase 1: Climate Zone Inference

Map `latitude` to Italian macro-zone:

```
if lat >= 44.0:
  zone = "nord"      # Piemonte, Lombardia, Veneto, etc.
  last_frost ≈ 25 aprile
  first_frost ≈ 15 ottobre
elif lat >= 42.5:
  zone = "centro"    # Toscana, Lazio, Marche, etc.
  last_frost ≈ 15 aprile
  first_frost ≈ 25 ottobre
else:
  zone = "sud"       # Campania, Sicilia, Puglia, etc.
  last_frost ≈ 1 aprile
  first_frost ≈ 5 novembre
```

### Phase 2: Generate Directory Structure

Create base folder: `/home/<user>/.openclaw/workspace/Orti/<orto_id>/`

```
<orto_id>/
├── README.md                          # Project overview
├── config/
│   ├── garden_config.md               # Base garden config (location, size, soil, etc.)
│   └── ambiente_vincoli.md            # Environmental constraints
├── dati/
│   ├── questionario/
│   │   ├── blocco_1_localizzazione.md
│   │   ├── blocco_2_layout_spazio.md
│   │   ├── blocco_3_irrigazione.md
│   │   ├── blocco_4_comunita_dieta.md
│   │   └── blocco_5_obiettivi_vincoli.md
│   ├── calendario/
│   │   └── calendario_stagionale.md
│   ├── colture/
│   │   └── piano_colture_annuale.md
│   ├── layout/
│   │   ├── aiuole_dimensioni.md
│   │   └── zone_clima_microclimatico.md
│   ├── irrigazione/
│   │   ├── sistema_irrigazione.md
│   │   ├── sensori_monitoraggio.md
│   │   └── programmi_irrigazione.md
│   ├── meteo/
│   │   └── dati_meteo_giornalieri.md
│   ├── nutrizione/
│   │   ├── analisi_terreno.md
│   │   └── piano_concimazione.md
│   ├── trattamenti/
│   │   ├── diagnosi_problemi.md
│   │   └── piano_trattamenti.md
│   └── raccolti/
│       └── cicli_raccolta_previsti.md
├── log/
│   ├── audit_trail.md                 # Audit log
│   └── note_osservazioni.md           # Field notes
├── media/
│   ├── foto/
│   └── video/
└── report/
    └── (reports generated later)
```

### Phase 3: Generate Markdown Templates

**garden_config.md** (from template)

```markdown
# Configurazione Orto: [ORTO_ID]

## Dati Base
- **Nome:** [ORTO_NAME]
- **ID:** [ORTO_ID]
- **Provincia:** [PROVINCIA]
- **Regione:** [REGIONE]
- **Coordinate:** [LATITUDE], [LONGITUDE]
- **Zona climatica:** [ZONE] (Nord/Centro/Sud)
- **Ultima gelata (app.):** [LAST_FROST_DATE]
- **Prima gelata (app.):** [FIRST_FROST_DATE]
- **Lunghezza stagione:** ~[SEASON_LENGTH] giorni

## Spazio
- **Area disponibile:** ??? m²  *(riempire in onboarding blocco 2)*
- **Tipologia terreno:** ??? *(riempire in onboarding blocco 2)*
- **Esposizione solare:** ??? *(riempire in onboarding blocco 2)*

## Vincoli Ambientali
- **Vincoli agua:** *(riempire in onboarding blocco 3)*
- **Vincoli manutenzione:** *(riempire in onboarding blocco 5)*
- **Note vincoli:** *(riempire in onboarding)*

## Status
- **Data creazione:** [TODAY]
- **Stato workflow:** Init completo, in attesa onboarding
```

**blocco_1_localizzazione.md** (questionnaire template)

```markdown
# Blocco 1 — Localizzazione Orto

## Domande

### Q1.1 — Dove si trova l'orto?
**Provincia:** [auto-filled]  
**Regione:** [auto-filled]  
**Indirizzo (opz.):** ___

### Q1.2 — Accessibilità
- [ ] Facile accesso da casa (< 10 min a piedi)
- [ ] Accesso moderato (10-30 min)
- [ ] Accesso difficile (> 30 min)

### Q1.3 — Proprietà/Gestione
- [ ] Proprietà privata personale
- [ ] Orto comunitario
- [ ] Terreno affittato
- [ ] Altro: ___

## Descrizione
[Spazio libero per note]

## Data risposta
[TODAY]
```

### Phase 4: Register Garden in Registry

Append to central registry (or create if not exists):

**orti_registry.json** (location: `/home/<user>/.openclaw/workspace/Orti/orti_registry.json`)

```json
{
  "orti": [
    {
      "orto_id": "[ORTO_ID]",
      "name": "[ORTO_NAME]",
      "provincia": "[PROVINCIA]",
      "regione": "[REGIONE]",
      "latitude": [LAT],
      "longitude": [LON],
      "zone": "[ZONE]",
      "created_at": "[TODAY_ISO]",
      "status": "init_complete",
      "path": "/home/<user>/.openclaw/workspace/Orti/[ORTO_ID]"
    }
  ]
}
```

### Phase 5: Generate Audit Trail Entry

Create `log/audit_trail.md`:

```markdown
# Audit Trail — [ORTO_ID]

## Event: Init

| Field | Value |
|-------|-------|
| **Timestamp** | [TODAY_ISO] |
| **Event** | orto_init |
| **Status** | success |
| **Orto ID** | [ORTO_ID] |
| **Coordinator** | Codex (skill: orto-init) |
| **Details** | Garden project initialized. Config created, directory structure scaffolded, questionnaire templates generated. |

---
```

## Output

**Structure created:**
- Directory `/Orti/<orto_id>/` with all subdirectories ✓
- File `garden_config.md` (initial template) ✓
- Files `blocco_1...5.md` (questionnaire templates, empty) ✓
- File `audit_trail.md` (init event) ✓
- Registry entry in `orti_registry.json` ✓

**Console output (Markdown):**

```markdown
# ✅ Orto Initialized

**Orto ID:** [ORTO_ID]  
**Name:** [ORTO_NAME]  
**Location:** [PROVINCIA], [REGIONE]  
**Zone:** [ZONE] (Frost: [LAST_FROST]—[FIRST_FROST])  
**Area:** ??? m² (collect in Blocco 2)  
**Path:** /home/<user>/.openclaw/workspace/Orti/[ORTO_ID]

## Next Step

→ Run **orto-onboarding** skill to collect garden profile via 5 questionnaire blocks.

**Expected time:** 15-30 minutes

```

## Error Handling

| Error | Fallback |
|-------|----------|
| Directory already exists | Skip creation; update registry and confirm with user |
| Invalid coordinates | Use centro-Italy defaults (Lazio) and flag for user verification |
| Registry file missing | Create new registry with this entry |
| Invalid orto_id format | Suggest normalized ID and ask for confirmation |

## References

See bundled `references/calendario_it.md` for frost dates and climate zone details.

## Scripts

This skill uses bundled Python script for deterministic directory creation:

```bash
scripts/init_new_orto_bundled.sh \
  --id <orto_id> \
  --name "<orto_name>" \
  --provincia <provincia> \
  --regione <regione> \
  --lat <latitude> \
  --lon <longitude>
```

Script is fully self-contained and idempotent (safe to re-run).

---

## Examples

### Example 1: Roma Garden

**Input:**
```
orto_id: orto_roma_testaccio_001
orto_name: Orto Testaccio Roma
provincia: Roma
regione: Lazio
latitude: 41.8782
longitude: 12.4922
```

**Output:**
- Directory created: `/Orti/orto_roma_testaccio_001/`
- Zone inferred: `centro` (last frost ~15 apr, first frost ~25 oct)
- Status: Init complete, ready for onboarding

---

### Example 2: Milano Garden

**Input:**
```
orto_id: orto_milano_lambro_001
orto_name: Orto Lambro Milano
provincia: Milano
regione: Lombardia
latitude: 45.4642
longitude: 9.1900
```

**Output:**
- Directory created: `/Orti/orto_milano_lambro_001/`
- Zone inferred: `nord` (last frost ~25 apr, first frost ~15 oct)
- Status: Init complete

---

## Assumptions

1. Codex is running on a machine with filesystem access to `/home/<user>/.openclaw/workspace/`
2. User has write permissions to create directories and files
3. Climate zone is inferred from latitude alone (simplification; refine if needed)
4. All templates are in Italian language (Italiano)
5. Questionnaire templates are empty stubs; filled during orto-onboarding skill

## Validation Checklist

- ✓ `orto_id` is unique in registry
- ✓ Directory path does not conflict with existing gardens
- ✓ Coordinates are valid (lat/lon bounds)
- ✓ Provincia and Regione match Italian administrative divisions
- ✓ All template files created and readable

---

**Skill: orto-init** | Version 1.0 | Status: Production-Ready