docs(01): create phase 1 plan (2 plans, 2 waves)

2026-03-24 19:42:52 +01:00
parent e5af5162f9
commit 9229ffe19d
3 changed files with 519 additions and 3 deletions
--- a/.planning/phases/01-setup-git-foundation/01-02-PLAN.md
+++ b/.planning/phases/01-setup-git-foundation/01-02-PLAN.md
@@ -0,0 +1,256 @@
+---
+phase: 01-setup-git-foundation
+plan: 02
+type: execute
+wave: 2
+depends_on: [01-01]
+files_modified: [README.md, labs/, how-to-guides/, reference/]
+autonomous: true
+requirements: [GIT-04, GIT-05, SETUP-05]
+user_setup: []
+
+must_haves:
+  truths:
+    - "Studente puo clonare repository e trovare istruzioni chiare per configurare Docker"
+    - "Studente puo eseguire script di verifica ambiente dopo cloning"
+    - "Repository ha struttura chiara con cartelle labs/, how-to-guides/, reference/"
+    - "README include quick start con comando check-env.sh"
+    - "README documenta 5 laboratori con brevi descrizioni"
+    - "README include istruzioni per Docker Engine >= 24.0 e Compose V2"
+  artifacts:
+    - path: "README.md"
+      provides: "Project overview and setup instructions"
+      min_lines: 60
+      contains: ["Docker Engine", "Compose V2", "check-env.sh", "Laboratori", "Quick Start"]
+    - path: "labs/"
+      provides: "Directory for individual lab modules"
+      type: "directory"
+    - path: "how-to-guides/"
+      provides: "Directory for procedure-specific guides"
+      type: "directory"
+    - path: "reference/"
+      provides: "Directory for technical specifications"
+      type: "directory"
+  key_links:
+    - from: "README.md"
+      to: "scripts/check-env.sh"
+      via: "Quick Start instructions"
+      pattern: "check-env\\.sh"
+    - from: "README.md"
+      to: "Docker documentation"
+      via: "Prerequisites section"
+      pattern: "Docker Engine.*24"
+    - from: "labs/ directory"
+      to: "Individual lab modules"
+      via: "Directory structure"
+      pattern: "lab-0[1-5]"
+---
+
+<objective>
+Create repository structure with clear directory layout and comprehensive README documenting project, prerequisites, and quick start instructions.
+
+Purpose: Students need to understand the project structure immediately after cloning and have clear guidance on setting up their Docker environment.
+Output: Repository with labs/, how-to-guides/, reference/ directories and comprehensive README.md following Diátaxis principles (direct, simple tone).
+</objective>
+
+<execution_context>
+@/home/luca/.claude/get-shit-done/workflows/execute-plan.md
+@/home/luca/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/STATE.md
+@.planning/ROADMAP.md
+@.planning/REQUIREMENTS.md
+@.planning/phases/01-setup-git-foundation/01-RESEARCH.md
+@.planning/phases/01-setup-git-foundation/01-VALIDATION.md
+@CLAUDE.md
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Create repository directory structure</name>
+  <files>labs/, labs/lab-01-iam/, labs/lab-02-network/, labs/lab-03-compute/, labs/lab-04-storage/, labs/lab-05-database/, how-to-guides/, reference/</files>
+  <action>
+Create directory structure for the course following RESEARCH.md specification:
+
+1. **Create labs/ directory** with subdirectories for each lab:
+   - labs/lab-01-iam/ (IAM & Sicurezza)
+   - labs/lab-02-network/ (Network & VPC)
+   - labs/lab-03-compute/ (Compute & EC2)
+   - labs/lab-04-storage/ (Storage & S3)
+   - labs/lab-05-database/ (Database & RDS)
+
+2. **Create how-to-guides/ directory** for procedure-specific guides (e.g., "Come generare chiavi SSH", "Come ripulire volumi Docker")
+
+3. **Create reference/ directory** for technical specifications (e.g., docker-compose.yml examples, IP mappings, port references)
+
+4. **Add placeholder README.md in each lab directory** with:
+   ```markdown
+   # Lab XX: [Lab Name]
+
+   Coming soon.
+
+   This lab will cover: [brief description]
+   ```
+
+DO NOT create any lab content yet — only directory structure and placeholder READMEs.
+</action>
+  <verify>
+    <automated>test -d labs && test -d how-to-guides && test -d reference && test -d labs/lab-01-iam && test -d labs/lab-02-network && test -d labs/lab-03-compute && test -d labs/lab-04-storage && test -d labs/lab-05-database && echo "STRUCTURE_OK"</automated>
+  </verify>
+  <done>
+  All required directories exist (labs/, how-to-guides/, reference/).
+  All 5 lab subdirectories exist under labs/.
+  Each lab has a placeholder README.md.
+  </done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Write comprehensive README.md</name>
+  <files>README.md</files>
+  <action>
+Write project README.md following the template from RESEARCH.md and Diátaxis framework (direct, simple, technically accurate tone).
+
+**Required sections:**
+
+1. **Project Overview (What and Why):**
+   ```markdown
+   # Laboratori Cloud - Corso Soluzioni Cloud
+
+   Simulazione pratica di servizi cloud usando Docker locale.
+
+   Questo corso ti insegna i concetti fondamentali del cloud (IAM, Network, Compute, Storage, Database)
+   attraverso laboratori pratici che usano Docker per simulare servizi AWS/Azure/GCP.
+   ```
+
+2. **Prerequisites:**
+   ```markdown
+   ## Prerequisiti
+
+   Prima di iniziare, assicurati di avere:
+
+   - Docker Engine >= 24.0 installato
+   - Docker Compose V2 (comando `docker compose`, non `docker-compose`)
+   - Utility di rete: netcat, curl, iproute2
+
+   ### Risorse Minime Consigliate
+
+   - RAM: 16 GB (funziona con 8 GB, ma alcuni lab potrebbero essere lenti)
+   - CPU: 4 core
+   - Spazio disco: 20 GB liberi
+   ```
+
+3. **Quick Start:**
+   ```markdown
+   ## Quick Start
+
+   1. Clona questa repository:
+      ```bash
+      git clone [repository-url]
+      cd laboratori-cloud
+      ```
+
+   2. Verifica il tuo ambiente:
+      ```bash
+      ./scripts/check-env.sh
+      ```
+
+   3. Se tutti i check passano, sei pronto per iniziare il primo laboratorio!
+   ```
+
+4. **Lab Overview (5 labs briefly described):**
+   ```markdown
+   ## Laboratori
+
+   1. **IAM & Sicurezza** - Configura utenti Linux, permessi Docker socket, capisci i paralleli IAM
+   2. **Network & VPC** - Crea reti Docker isolate che simulano VPC e Subnets cloud
+   3. **Compute & EC2** - Deploy container con limiti CPU/memoria e healthchecks
+   4. **Storage & S3** - Configura Docker Volumes e MinIO per storage S3-compatible
+   5. **Database & RDS** - Deploy PostgreSQL in rete privata con persistenza dati
+   ```
+
+5. **Git Workflow Brief:**
+   ```markdown
+   ## Git Workflow
+
+   Questo repository segue [Conventional Commits](https://www.conventionalcommits.org/).
+
+   Esempi di commit che troverai:
+   - `feat(lab-01): add user configuration script`
+   - `test(lab-02): add network isolation test`
+   - `docs(lab-03): add explanation for healthchecks`
+
+   Ogni laboratorio e sviluppato su un branch isolato (es. `lab-01-iam`) e
+   mergeggiato su `main` solo quando completo e testato.
+   ```
+
+6. **Troubleshooting Pointers:**
+   ```markdown
+   ## Troubleshooting
+
+   ### Docker non parte
+   - Verifica che il demone Docker sia in esecuzione: `docker ps`
+   - Riavvia Docker: `sudo systemctl restart docker` (Linux)
+
+   ### Script check-env.sh fallisce
+   - Verifica la versione di Docker: `docker --version` (deve essere >= 24.0)
+   - Verifica Compose V2: `docker compose version` (non `docker-compose`)
+
+   ### Reset completo ambiente
+   - Per pulire tutto tra un lab e l'altro: `./scripts/reset-env.sh`
+   ```
+
+**Tone guidelines (per PRD requirements):**
+- Direct and simple: avoid jargon where possible
+- Technically accurate: don't oversimplify technical details
+- Italian language: course is in Italian
+- Action-oriented: tell students what to do, not what to think about
+
+DO NOT include emojis in the README. DO NOT write placeholder text — all content must be complete and useful.
+</action>
+  <verify>
+    <automated>grep -q "Docker Engine.*24" README.md && grep -q "check-env.sh" README.md && grep -q "Quick Start" README.md && grep -q "IAM.*Network.*Compute.*Storage.*Database" README.md && echo "README_COMPLETE"</automated>
+  </verify>
+  <done>
+  README.md exists with all required sections.
+  Prerequisites section documents Docker >= 24.0 and Compose V2.
+  Quick Start includes cloning instructions and check-env.sh command.
+  Lab overview describes all 5 labs.
+  Git workflow brief explains Conventional Commits.
+  Troubleshooting section covers common issues.
+  </done>
+</task>
+
+</tasks>
+
+<verification>
+After all tasks complete:
+1. Verify directory structure: `ls -la labs/` shows 5 lab directories
+2. Verify README completeness: All sections present and filled with useful content
+3. Verify README accuracy: Instructions in README can be followed literally
+4. Verify placeholder READMEs exist in each lab directory
+5. Test Quick Start instructions by following them literally
+
+Cross-verification:
+- Directory structure validates GIT-05 (clear repo structure)
+- README validates GIT-04 (cloning and setup instructions)
+- README references scripts from Plan 01 (check-env.sh, reset-env.sh)
+</verification>
+
+<success_criteria>
+1. Repository structure matches RESEARCH.md specification exactly
+2. README.md can be followed by a new student to set up Docker environment
+3. All 5 lab directories have placeholder READMEs
+4. Quick Start instructions are accurate and complete
+5. README follows Diátaxis tone guidelines (direct, simple, accurate)
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/01-setup-git-foundation/01-02-SUMMARY.md` with:
+- Directory structure created
+- README.md sections and line counts
+- Any deviations from RESEARCH.md template
+- Verification results from following README instructions literally
+</output>