Add unified implementation plan for Phase A and Phase B in Markdown format
- Create a new document `plans/implementation-plan-A-B.md` that consolidates the implementation plans for the Python rewrite (Phase A) and the migration to Linux Mint (Phase B). - The document includes detailed sections such as executive summary, checklist, prerequisites, step-by-step activities, architectural hooks for future phases, risk matrix, and references. - Ensure the plan is self-contained, adhering to specified structure and style guidelines, and does not introduce new technologies or modify existing files.
This commit is contained in:
@@ -0,0 +1,176 @@
|
||||
# Prompt — Generazione piano di implementazione unificato Fase A + Fase B
|
||||
|
||||
> Copia-incolla il blocco sotto come messaggio iniziale all'IA che dovrà
|
||||
> produrre il piano. L'IA deve avere accesso in lettura al repository
|
||||
> `local-ci-cd-system` (in particolare ai file citati nei riferimenti).
|
||||
|
||||
---
|
||||
|
||||
## Prompt da fornire all'IA
|
||||
|
||||
Sei un senior platform/DevOps engineer assegnato al progetto
|
||||
**local-ci-cd-system** (CI/CD on-prem basato su Gitea Actions + act_runner +
|
||||
VMware Workstation Pro + VM ephemere Win/Linux). Il tuo compito è produrre
|
||||
**un singolo documento di piano implementativo dettagliato** che fonde
|
||||
**Fase A** (rewrite Python dell'orchestratore) e **Fase B** (migrazione
|
||||
host da Windows 11 a Linux Mint) in un'unica roadmap eseguibile, mantenendo
|
||||
**hook architetturali compatibili con Fase C** (backend ESXi futuro) senza
|
||||
implementarla.
|
||||
|
||||
### Contesto obbligatorio da leggere PRIMA di scrivere
|
||||
|
||||
Prima di produrre output, leggi e tieni come riferimento:
|
||||
|
||||
1. [AGENTS.md](../AGENTS.md) — vincoli host, PowerShell 5.1, errori frequenti
|
||||
(#1–#12). Tutti i punti devono restare validi o essere esplicitamente
|
||||
superati dal piano.
|
||||
2. [plans/ideas-overview.md](ideas-overview.md) — razionale, ordine, criteri
|
||||
di "fase completata", strategia di rollback.
|
||||
3. [plans/idea-1-python-rewrite.md](idea-1-python-rewrite.md) — Fase A
|
||||
(decisioni di design, mappa di traduzione, step A1–A5, layout repo,
|
||||
rischi, definizione di fatto).
|
||||
4. [plans/idea-2-linux-host.md](idea-2-linux-host.md) — Fase B (decisione
|
||||
hypervisor, mappa di adattamento, step B1–B8, rischi, fatto).
|
||||
5. [plans/idea-3-esxi-support.md](idea-3-esxi-support.md) — Fase C: leggi
|
||||
solo §2 (architettura) e §3 (backend pyVmomi) per sapere quali hook
|
||||
lasciare aperti nel design.
|
||||
6. [docs/ARCHITECTURE.md](../docs/ARCHITECTURE.md), [docs/CI-FLOW.md](../docs/CI-FLOW.md),
|
||||
[docs/HOST-SETUP.md](../docs/HOST-SETUP.md), [docs/RUNBOOK.md](../docs/RUNBOOK.md)
|
||||
per capire layout e operatività attuali.
|
||||
7. La cartella [scripts/](../scripts/) e [template/](../template/) per
|
||||
conoscere l'inventario reale degli script da portare/tenere.
|
||||
|
||||
### Cosa devi produrre
|
||||
|
||||
Un unico file Markdown chiamato
|
||||
`plans/implementation-plan-A-B.md` con la struttura sotto. Il documento
|
||||
deve essere **autocontenuto** (chi lo legge non deve aprire altri 6 file
|
||||
per capire cosa fare oggi), ma deve **citare** i piani originali quando
|
||||
rimanda a sezioni di dettaglio.
|
||||
|
||||
### Struttura obbligatoria del documento
|
||||
|
||||
Usa esattamente questa scaletta e gli heading indicati:
|
||||
|
||||
#### `# Piano implementativo unificato — Fase A (Python) + Fase B (host Linux)`
|
||||
|
||||
#### `## Summary esecutivo`
|
||||
Massimo 25 righe. Includi:
|
||||
- Obiettivo combinato in 2 frasi.
|
||||
- Tabella `Fase | Obiettivo | Output verificabile | Stato`.
|
||||
- Decisioni architetturali chiave già prese (Python 3.11+, pypsrp,
|
||||
paramiko, keyring, Workstation Pro Linux, astrazione `VmBackend`).
|
||||
- Vincoli che NON cambiano (act_runner, Gitea, template VM, workflow YAML
|
||||
invariati a meno di env vars / shell).
|
||||
|
||||
#### `## Checklist riassuntiva master`
|
||||
Una sola checklist `- [ ]` piatta che enumera **tutti** i deliverable
|
||||
ordinati cronologicamente, con prefisso del macro-step (`[A1]`, `[A2]`,
|
||||
…, `[B1]`, …, `[X]` per gli step trasversali). Deve essere copiabile in
|
||||
un issue tracker. Ogni voce: ≤ 1 riga, verbo all'infinito, deliverable
|
||||
osservabile (file, comando, test che passa). Niente prosa qui.
|
||||
|
||||
#### `## 0. Prerequisiti e gating`
|
||||
Cosa deve essere vero PRIMA di iniziare A1. Checklist.
|
||||
|
||||
#### `## 1. Fase A — Rewrite Python (host Windows attuale)`
|
||||
Per ogni step da A1 ad A5:
|
||||
- `### A<n> — <titolo>`
|
||||
- `**Obiettivo**:` 1 frase.
|
||||
- `**Input / dipendenze**:` step precedenti, file, env vars.
|
||||
- `**Attività**:` checklist `- [ ]` granulare (5–15 voci tipiche),
|
||||
ognuna con deliverable osservabile.
|
||||
- `**Hook futuri Fase C**:` cosa deve essere progettato adesso per non
|
||||
bloccare ESXi (es. firma del Protocol `VmBackend`, separazione
|
||||
`clone_linked` da `start`, niente assunzione "stesso host").
|
||||
- `**Test / validazione**:` comandi e criteri pass/fail concreti
|
||||
(pytest target, coverage minima, smoke workflow Gitea da triggerare).
|
||||
- `**Rollback**:` come tornare allo stato precedente lo step.
|
||||
- `**Definizione di fatto step A<n>**:` checklist `- [ ]` di chiusura
|
||||
(max 5 voci).
|
||||
|
||||
#### `## 2. Fase B — Migrazione host Linux Mint`
|
||||
Stessa struttura per gli step da B1 a B8. In più:
|
||||
- Marca esplicitamente quali step sono **eseguibili in parallelo** ad A
|
||||
(B1 setup hardware Linux può iniziare durante A3/A4) e quali sono
|
||||
**strettamente sequenziali** (B6 cutover dopo "A done").
|
||||
- Per ogni step indica **rischi specifici** presi da
|
||||
`idea-2-linux-host.md` §6 e mitigazioni.
|
||||
|
||||
#### `## 3. Step trasversali (X)`
|
||||
Step che attraversano A e B (test, docs, observability, sicurezza,
|
||||
gestione credenziali headless, lint dual-stack PSSA+ruff).
|
||||
Stessa struttura per ogni X<n>.
|
||||
|
||||
#### `## 4. Hook architetturali per Fase C`
|
||||
Lista esplicita dei punti del codice/config che restano "aperti" per
|
||||
ESXi: Protocol `VmBackend`, selezione backend via `config.toml`,
|
||||
separazione control plane / compute, naming neutro (no `vmrun_*` nei
|
||||
nomi pubblici delle API). **Niente implementazione** — solo contratto
|
||||
di design da non violare.
|
||||
|
||||
#### `## 5. Cronoprogramma e dipendenze`
|
||||
Diagramma Mermaid `gantt` o `flowchart` con le dipendenze tra step
|
||||
A1…A5, B1…B8, X1…Xn. **Niente date assolute, niente stime di durata
|
||||
in giorni**: usa solo numerazione di sequenza e dipendenze logiche.
|
||||
|
||||
#### `## 6. Matrice rischi consolidata`
|
||||
Tabella `Rischio | Fase | Severità | Mitigazione | Owner action item`.
|
||||
Unisci §7 di idea-1 e §6 di idea-2, aggiungi rischi di integrazione
|
||||
A↔B che emergono solo nel piano fuso (es. shim PowerShell che assume
|
||||
path Windows e si rompe in Fase B).
|
||||
|
||||
#### `## 7. Definizione di "fatto" globale (A+B)`
|
||||
Una checklist finale `- [ ]` che combina §8 di idea-1 + §8 di idea-2,
|
||||
deduplicata e coerente con la checklist master in testa.
|
||||
|
||||
#### `## 8. Riferimenti`
|
||||
Link relativi ai file originali letti.
|
||||
|
||||
### Regole stilistiche e di contenuto
|
||||
|
||||
1. **Lingua**: italiano tecnico, coerente con i piani esistenti.
|
||||
2. **Tono**: imperativo / dichiarativo, niente "potremmo", "si potrebbe".
|
||||
Ogni attività è un'azione concreta con deliverable.
|
||||
3. **Niente stime di tempo / date / sprint**. Solo dipendenze logiche.
|
||||
4. **Niente nuovi vincoli inventati**: tutto quello che dichiari deve
|
||||
essere derivabile dai 6 file di riferimento o dallo stato attuale del
|
||||
repo. Se proponi qualcosa di nuovo, marcalo con `> NOTA NUOVA:` e
|
||||
spiega perché.
|
||||
5. **Coerenza con `AGENTS.md`**: ogni step PowerShell residuo deve
|
||||
rispettare PS 5.1 (no `??`, no `&&`, ecc.); ogni nuova decisione che
|
||||
supera un errore frequente (#1–#12) deve dichiararlo esplicitamente.
|
||||
6. **Checklist machine-friendly**: usa esclusivamente `- [ ]` (con spazio,
|
||||
non `- [x]`). Una voce per riga. Niente sub-checklist annidate oltre
|
||||
il primo livello dentro la stessa sezione.
|
||||
7. **Tabelle**: usa pipe-tables Markdown standard. Nessun HTML.
|
||||
8. **Mermaid**: un solo diagramma in §5, sintassi valida.
|
||||
9. **Lunghezza target**: 600–1100 righe Markdown. Sotto le 500 è troppo
|
||||
sintetico, sopra le 1300 stai duplicando i piani originali.
|
||||
10. **Auto-verifica finale**: alla fine del documento, prima di §8,
|
||||
aggiungi una sezione `## 7.1 Auto-check` con queste domande a cui
|
||||
il documento stesso deve poter rispondere "sì" leggendolo:
|
||||
- Ogni voce della checklist master compare almeno una volta come
|
||||
`- [ ]` dentro lo step corrispondente?
|
||||
- Ogni step A<n>/B<n>/X<n> ha tutte le sottosezioni richieste?
|
||||
- I 12 errori frequenti di `AGENTS.md` sono stati indirizzati o
|
||||
dichiarati non applicabili?
|
||||
- Gli hook §4 sono coerenti con `idea-3-esxi-support.md` §3?
|
||||
|
||||
### Cosa NON devi fare
|
||||
|
||||
- Non implementare codice. Solo piano.
|
||||
- Non duplicare integralmente i contenuti di idea-1/idea-2: cita e
|
||||
riassumi.
|
||||
- Non introdurre tecnologie nuove non già menzionate (no Ansible,
|
||||
no Terraform, no Docker host-side, no K8s) salvo `> NOTA NUOVA:`
|
||||
motivata.
|
||||
- Non modificare altri file del repo. Solo creazione di
|
||||
`plans/implementation-plan-A-B.md`.
|
||||
- Non includere date, settimane, story point, t-shirt sizing.
|
||||
|
||||
### Output atteso
|
||||
|
||||
Un solo file: `plans/implementation-plan-A-B.md`, conforme alla
|
||||
struttura sopra, pronto per essere committato. Nessun testo
|
||||
conversazionale fuori dal file.
|
||||
Reference in New Issue
Block a user