create-pwt 1.0.0

package/README.md

@@ -0,0 +1,51 @@
+# create-pwt
+
+AI-driven project workflow scaffolding for [Claude Code](https://claude.ai/code).
+
+**You direct, Claude executes.** From idea to launch — every project documented, every session productive, zero context lost.
+
+## Quick start
+
+Requires an active [Claude Code](https://claude.ai/code) subscription.
+
+```bash
+npx create-pwt
+```
+
+Or clone the repo and use `npm run init` to always work with the latest version.
+
+## What it does
+
+Creates a standalone project folder with:
+
+- **9-phase workflow** (38 tasks) from idea to launch — ideation, scope, planning, design, architecture, implementation, QA, release, growth
+- **Skills for Claude Code** (`/start`, `/task`, `/roadmap`, `/setup`) — one command to resume any session
+- **Persistent state** (`STATE.json`) — resume any session with `/start`, zero context lost between sessions
+- **Sub-agent with ReAct checkpointing** — isolated task execution with mid-task pause/resume support
+- **TDD enforcement** in the implementation phase — micro-planning + test-first + two-stage review
+
+## Requirements
+
+- [Claude Code](https://claude.ai/code) subscription (no API key needed — runs on your existing subscription)
+- macOS or Linux, bash
+
+## How it works
+
+```
+npx create-pwt          # scaffold a new project
+cd <your-project>
+# open in Claude Code, then:
+/start                  # Claude reads STATE.json and picks up where you left off
+```
+
+After phase 0, `/roadmap` generates a custom roadmap for your specific project — skipping irrelevant tasks (e.g. no design phase for API-only projects).
+
+## Docs
+
+- [How it works](https://github.com/FabioD95/Project-Workflow-Template/blob/main/docs/HOW-IT-WORKS.md) — full system explanation
+- [Architecture](https://github.com/FabioD95/Project-Workflow-Template/blob/main/docs/ARCHITECTURE.md) — patterns and decisions
+- [Roadmap](https://github.com/FabioD95/Project-Workflow-Template/blob/main/docs/ROADMAP.md) — development roadmap
+
+## Source
+
+[github.com/FabioD95/Project-Workflow-Template](https://github.com/FabioD95/Project-Workflow-Template)

package/bin/create-pwt

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+'use strict';
+const { spawnSync } = require('child_process');
+const path = require('path');
+const script = path.join(__dirname, 'init.sh');
+const result = spawnSync('bash', [script, ...process.argv.slice(2)], { stdio: 'inherit' });
+process.exit(result.status ?? 1);

package/bin/init.sh

@@ -0,0 +1,136 @@
+#!/bin/bash
+set -e
+
+# Cross-platform sed in-place
+sed_inplace() {
+  local expr="$1"; local file="$2"
+  if [[ "$(uname)" == "Darwin" ]]; then
+    sed -i '' "$expr" "$file"
+  else
+    sed -i "$expr" "$file"
+  fi
+}
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+TEMPLATE_DIR="$SCRIPT_DIR/../template"
+
+echo "==================================="
+echo "  Project Workflow — Init Progetto "
+echo "==================================="
+echo ""
+
+# 1. Nome progetto
+read -p "Nome del progetto: " PROJECT_NAME
+if [ -z "$PROJECT_NAME" ]; then
+  echo "Errore: nome progetto obbligatorio." >&2
+  exit 1
+fi
+
+SLUG=$(echo "$PROJECT_NAME" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr '_' '-')
+
+# 2. Destinazione
+echo ""
+echo "Dove vuoi creare il progetto?"
+echo "  1) Cartella corrente  →  $(pwd)/$SLUG"
+echo "  2) Scegli un percorso diverso"
+echo ""
+read -p "Scelta [1]: " DEST_CHOICE
+DEST_CHOICE=${DEST_CHOICE:-1}
+
+if [ "$DEST_CHOICE" = "2" ]; then
+  read -p "Percorso: " DEST_INPUT
+  DEST="${DEST_INPUT%/}/$SLUG"
+else
+  DEST="$(pwd)/$SLUG"
+fi
+
+# 3. Riepilogo e conferma
+echo ""
+echo "Riepilogo:"
+echo "  Nome:     $PROJECT_NAME"
+echo "  Slug:     $SLUG"
+echo "  Cartella: $DEST"
+echo ""
+read -p "Confermi? [s/N]: " CONFIRM
+if [[ ! "$CONFIRM" =~ ^[sS]$ ]]; then
+  echo "Annullato."
+  exit 0
+fi
+
+# 4. Controllo destinazione
+if [ -d "$DEST" ]; then
+  echo "Errore: la cartella '$DEST' esiste già." >&2
+  exit 1
+fi
+
+# 5. Copia template
+cp -r "$TEMPLATE_DIR" "$DEST"
+
+# Crea struttura docs/
+mkdir -p "$DEST/docs/phases"
+
+# 6. Gestione preferenze
+PREFS_DEST="$DEST/system/preferences.json"
+PREFS_TEMPLATE="$DEST/system/preferences.json"
+MASTER_PREFS="$TEMPLATE_DIR/system/preferences.json"
+
+echo ""
+echo "Preferenze del progetto:"
+echo "  1) Inizia vuoto  — Claude te le chiederà man mano che servono  [default]"
+if [ -f "$MASTER_PREFS" ]; then
+  echo "  2) Importa dal profilo master  →  $MASTER_PREFS"
+fi
+echo "  3) Importa da un progetto esistente"
+echo ""
+read -p "Scelta [1]: " PREFS_CHOICE
+PREFS_CHOICE=${PREFS_CHOICE:-1}
+
+case "$PREFS_CHOICE" in
+  2)
+    if [ -f "$MASTER_PREFS" ]; then
+      cp "$MASTER_PREFS" "$PREFS_DEST"
+      echo "✓ Preferenze importate dal profilo master"
+    else
+      cp "$PREFS_TEMPLATE" "$PREFS_DEST"
+      echo "⚠ Profilo master non trovato — usando preferenze vuote"
+    fi
+    ;;
+  3)
+    echo ""
+    read -p "Percorso cartella del progetto sorgente: " SRC_PROJECT
+    SRC_PREFS="${SRC_PROJECT%/}/system/preferences.json"
+    if [ -f "$SRC_PREFS" ]; then
+      cp "$SRC_PREFS" "$PREFS_DEST"
+      echo "✓ Preferenze importate da: $SRC_PROJECT"
+    else
+      cp "$PREFS_TEMPLATE" "$PREFS_DEST"
+      echo "⚠ preferences.json non trovato in '$SRC_PREFS' — usando preferenze vuote"
+    fi
+    ;;
+  *)
+    # preferences.json è già in $DEST dopo cp -r — niente da fare
+    echo "✓ Preferenze vuote — Claude te le chiederà man mano"
+    ;;
+esac
+
+# 7. Popola STATE.json
+DATE=$(date +%Y-%m-%dT%H:%M:%S)
+sed_inplace "s/\"project_id\": \"\"/\"project_id\": \"$SLUG\"/" "$DEST/STATE.json"
+sed_inplace "s/\"project_name\": \"\"/\"project_name\": \"$PROJECT_NAME\"/" "$DEST/STATE.json"
+sed_inplace "s/\"last_updated\": \"\"/\"last_updated\": \"$DATE\"/" "$DEST/STATE.json"
+
+# 8. Popola project.json
+TODAY=$(date +%Y-%m-%d)
+sed_inplace "s/\"id\": \"\"/\"id\": \"$SLUG\"/" "$DEST/project.json"
+sed_inplace "s/\"name\": \"\"/\"name\": \"$PROJECT_NAME\"/" "$DEST/project.json"
+sed_inplace "s/\"slug\": \"\"/\"slug\": \"$SLUG\"/" "$DEST/project.json"
+sed_inplace "s/\"created_at\": \"\"/\"created_at\": \"$TODAY\"/" "$DEST/project.json"
+
+echo ""
+echo "✓ Progetto '$PROJECT_NAME' creato in: $DEST"
+echo ""
+echo "Prossimi passi:"
+echo "  cd \"$DEST\""
+echo "  git init   (opzionale)"
+echo "  Apri la cartella in Claude Code e scrivi: /start"
+echo ""

package/bin/update.sh

@@ -0,0 +1,112 @@
+#!/bin/bash
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+TEMPLATE_DIR="$SCRIPT_DIR/../template"
+
+echo "==================================="
+echo "  Project Workflow — Update Progetto"
+echo "==================================="
+echo ""
+
+# Accetta path come argomento o chiede interattivamente
+if [ -n "$1" ]; then
+  PROJECT_DIR="$1"
+else
+  read -p "Percorso del progetto da aggiornare: " PROJECT_DIR
+fi
+
+PROJECT_DIR="${PROJECT_DIR%/}"
+
+# Validazione
+if [ ! -d "$PROJECT_DIR" ]; then
+  echo "Errore: directory '$PROJECT_DIR' non trovata." >&2
+  exit 1
+fi
+
+if [ ! -f "$PROJECT_DIR/STATE.json" ]; then
+  echo "Errore: non è un progetto pwt (STATE.json non trovato in '$PROJECT_DIR')." >&2
+  exit 1
+fi
+
+PROJECT_NAME=$(grep -o '"project_name": "[^"]*"' "$PROJECT_DIR/STATE.json" | cut -d'"' -f4)
+
+echo "Progetto: $PROJECT_NAME"
+echo "Directory: $PROJECT_DIR"
+echo ""
+echo "Verranno aggiornati:"
+echo "  .claude/skills/       (sovrascrive con skills correnti)"
+echo "  .claude/agents/       (sovrascrive con agents correnti)"
+echo "  .claude/settings.json (sovrascrive)"
+echo "  CLAUDE.md             (sovrascrive)"
+echo "  README.md             (sovrascrive)"
+if [ -d "$PROJECT_DIR/.claude/commands" ]; then
+  echo "  .claude/commands/     (eliminato — legacy)"
+fi
+if [ -d "$PROJECT_DIR/phases" ]; then
+  echo "  phases/ → docs/phases/ (migrazione struttura)"
+fi
+echo ""
+echo "NON verranno toccati: STATE.json, project.json, system/preferences.json"
+echo ""
+read -p "Confermi? [s/N]: " CONFIRM
+if [[ ! "$CONFIRM" =~ ^[sS]$ ]]; then
+  echo "Annullato."
+  exit 0
+fi
+
+echo ""
+
+# Aggiorna .claude/skills/
+rm -rf "$PROJECT_DIR/.claude/skills"
+cp -r "$TEMPLATE_DIR/.claude/skills" "$PROJECT_DIR/.claude/skills"
+echo "✓ Aggiornato .claude/skills/"
+
+# Aggiorna .claude/agents/
+rm -rf "$PROJECT_DIR/.claude/agents"
+cp -r "$TEMPLATE_DIR/.claude/agents" "$PROJECT_DIR/.claude/agents"
+echo "✓ Aggiornato .claude/agents/"
+
+# Aggiorna .claude/settings.json
+cp "$TEMPLATE_DIR/.claude/settings.json" "$PROJECT_DIR/.claude/settings.json"
+echo "✓ Aggiornato .claude/settings.json"
+
+# Elimina .claude/commands/ legacy
+if [ -d "$PROJECT_DIR/.claude/commands" ]; then
+  rm -rf "$PROJECT_DIR/.claude/commands"
+  echo "✓ Eliminato .claude/commands/ (legacy)"
+fi
+
+# Aggiorna CLAUDE.md e README.md
+cp "$TEMPLATE_DIR/CLAUDE.md" "$PROJECT_DIR/CLAUDE.md"
+echo "✓ Aggiornato CLAUDE.md"
+
+cp "$TEMPLATE_DIR/README.md" "$PROJECT_DIR/README.md"
+echo "✓ Aggiornato README.md"
+
+# Migrazione phases/ → docs/phases/
+if [ -d "$PROJECT_DIR/phases" ]; then
+  mkdir -p "$PROJECT_DIR/docs"
+  mv "$PROJECT_DIR/phases" "$PROJECT_DIR/docs/phases"
+  echo "✓ Migrato phases/ → docs/phases/"
+fi
+
+# Assicura docs/phases esista
+mkdir -p "$PROJECT_DIR/docs/phases"
+
+# Opzionale: aggiorna workflow e schemas
+echo ""
+read -p "Aggiornare anche system/workflow-v5.json e system/schemas/? [s/N]: " UPDATE_SYS
+if [[ "$UPDATE_SYS" =~ ^[sS]$ ]]; then
+  cp "$TEMPLATE_DIR/system/workflow-v5.json" "$PROJECT_DIR/system/workflow-v5.json"
+  rm -rf "$PROJECT_DIR/system/schemas"
+  cp -r "$TEMPLATE_DIR/system/schemas" "$PROJECT_DIR/system/schemas"
+  echo "✓ Aggiornati system/workflow-v5.json e system/schemas/"
+fi
+
+echo ""
+echo "✓ Progetto '$PROJECT_NAME' aggiornato alla struttura corrente."
+echo ""
+echo "Prossimi passi:"
+echo "  Apri la cartella in Claude Code e scrivi: /start"
+echo ""

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "create-pwt",
+  "version": "1.0.0",
+  "description": "AI-driven project workflow scaffolding for Claude Code — npx create-pwt",
+  "license": "MIT",
+  "author": "Fabio D.",
+  "homepage": "https://github.com/FabioD95/Project-Workflow-Template#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/FabioD95/Project-Workflow-Template.git",
+    "directory": "packages/cli"
+  },
+  "keywords": ["claude-code", "project-management", "workflow", "ai", "scaffolding", "template"],
+  "engines": { "node": ">=18" },
+  "bin": {
+    "create-pwt": "./bin/create-pwt"
+  },
+  "files": [
+    "bin/",
+    "template/"
+  ]
+}

package/template/.claude/agents/task-agent.md

@@ -0,0 +1,142 @@
+---
+name: task-agent
+description: Agente di esecuzione task isolato. Riceve contesto completo dall'orchestratore (task data, risposte interrogazione, checkpoint precedente), esegue il lavoro (skill, web search, MCP), e restituisce un JSON checkpoint strutturato. Invocato da /task dopo la fase di interrogazione.
+model: sonnet
+---
+
+# Task Agent — Esecutore isolato
+
+Sei l'agente di esecuzione del workflow. Lavori in isolamento con il tuo contesto. Non interagire mai con l'utente — restituisci sempre e solo un JSON checkpoint come risposta finale.
+
+## Input atteso
+
+L'orchestratore ti passa tutto il contesto nel prompt di invocazione, in questo formato:
+
+```
+TASK_ID: <id>
+TASK_TITLE: <titolo>
+SKILL: <nome skill oppure "null">
+ITERAZIONE: <numero iterazione corrente>
+CONTESTO_AGGIUNTIVO: <risposta utente al blocco precedente, oppure "nessuno">
+
+OUTPUT_DIPENDENZE:
+<contenuto degli output depends_on, uno per uno>
+
+RISPOSTE_INTERROGAZIONE:
+- <domanda 1>: <risposta 1>
+- <domanda 2>: <risposta 2>
+
+OUTPUT_SCHEMA:
+<sezioni richieste dall'output_schema della task>
+Formato: <format>
+Lunghezza: <length>
+
+DOD:
+<definition of done>
+
+CHECKPOINT_PRECEDENTE:
+<JSON del checkpoint precedente se ITERAZIONE > 1, oppure "nessuno">
+```
+
+## Procedura di esecuzione
+
+### 1. Analisi del contesto
+
+Leggi l'intero input. Se `CHECKPOINT_PRECEDENTE` non è "nessuno", riprendi dal `risultato_parziale` contenuto nel checkpoint — non ripetere lavoro già completato.
+
+### 2. Esecuzione skill (se `SKILL` != "null")
+
+Leggi `.claude/skills/<SKILL>/SKILL.md` e segui le istruzioni in quel file come guida principale per l'esecuzione.
+
+Strumenti disponibili: `Read`, `Write`, `Glob`, `Grep`, `WebSearch`, `WebFetch`, tool MCP (Figma, Postman, ClickUp, ecc.).
+
+Se un MCP tool richiesto non è disponibile, documenta la limitazione nel risultato e continua senza bloccare.
+
+### 3. Generazione output
+
+Segui `OUTPUT_SCHEMA` per strutturare l'output. Se mancano informazioni che:
+- non puoi ricavare autonomamente
+- non sono ricercabili online
+- dipendono da una decisione dell'utente
+
+→ imposta `stato: "partial"`, documenta il blocco, e fermati.
+
+Se hai tutto → imposta `stato: "done"` con `output_finale` completo.
+
+### 3.5 Verifica pre-completamento
+
+Prima di impostare `stato: "done"`, esegui queste tre verifiche nell'ordine. Se una qualsiasi fallisce, imposta `stato: "partial"` con `bloccato_su` che descrive esattamente cosa manca.
+
+**A. Copertura OUTPUT_SCHEMA**
+Per ogni sezione elencata in OUTPUT_SCHEMA, verifica che `output_finale` contenga un heading o sotto-sezione corrispondente. Se manca una sezione → partial, con `bloccato_su: "Sezione mancante nell'output: [nome sezione]"`.
+
+**B. Self-review DOD (criterio per criterio)**
+Rileggi il DOD dall'inizio. Per ogni criterio singolo (separato da punto, punto e virgola, o a capo):
+
+1. Isola il criterio
+2. Cerca nell'output_finale il contenuto che lo soddisfa
+3. Valuta: il contenuto soddisfa il criterio nel **merito** (non solo nella forma)?
+   - Se il criterio dice "almeno 3 alternative analizzate" → conta le alternative nell'output. Sono 3 o più?
+   - Se il criterio dice "piano realistico per 1-2 persone" → il piano tiene conto delle ore/settimana dichiarate?
+   - Se il criterio dice "differenziante esplicitato e motivato" → c'è sia il differenziante che la motivazione?
+4. Segna internamente: ✅ soddisfatto / ❌ non soddisfatto
+
+Se uno o più criteri risultano ❌:
+- Se puoi correggere l'output autonomamente → correggi e ripeti la verifica
+- Se non puoi (mancano informazioni) → partial, con `bloccato_su: "Criteri DOD non soddisfatti: [lista criteri]"` e `contesto_necessario: "[domanda specifica per ottenere l'informazione mancante]"`
+
+**C. Markdown ben formato**
+Verifica che:
+- Tutti i blocchi di codice siano chiusi (``` aperti = ``` chiusi)
+- Le tabelle abbiano header e separatore
+- I link markdown abbiano URL validi (non placeholder `[testo]()`)
+
+Se il markdown è malformato → correggi e ripeti la verifica. Se non correggibile → partial.
+
+Solo se tutte e tre le verifiche passano → procedi al punto 4 con `stato: "done"`.
+
+### 4. Output finale
+
+Rispondi **solo** con il JSON checkpoint, senza testo prima o dopo:
+
+**Se `stato: "partial"`:**
+```json
+{
+  "stato": "partial",
+  "task_id": "<id>",
+  "iterazione": <numero>,
+  "completato": ["<step A>", "<step B>"],
+  "risultato_parziale": "<markdown parziale prodotto finora, o null>",
+  "bloccato_su": "<descrizione precisa del blocco>",
+  "contesto_necessario": "<domanda chiusa e specifica da porre all'utente>",
+  "output_finale": null,
+  "file_prodotti": [],
+  "decisioni_da_approvare": []
+}
+```
+
+**Se `stato: "done"`:**
+```json
+{
+  "stato": "done",
+  "task_id": "<id>",
+  "iterazione": <numero>,
+  "completato": ["<step A>", "<step B>", "stesura output"],
+  "risultato_parziale": null,
+  "bloccato_su": null,
+  "contesto_necessario": null,
+  "output_finale": "<contenuto markdown completo>",
+  "file_prodotti": [],
+  "decisioni_da_approvare": ["<scelta tecnica/di prodotto rilevante>"]
+}
+```
+
+`decisioni_da_approvare`: scelte consequenziali fatte durante l'esecuzione che l'utente deve conoscere (es. "Stack confermato: Next.js + Supabase", "Feature X esclusa dallo scope"). Lista vuota se nessuna scelta rilevante.
+
+## Regole operative
+
+- Non scrivere mai file di output in `docs/phases/` — compito dell'orchestratore dopo l'approvazione
+- Non modificare `STATE.json` — compito dell'orchestratore
+- Il `risultato_parziale` deve includere tutto il lavoro prodotto finora in markdown (viene passato alla prossima iterazione)
+- Sii conservativo sui blocchi: blocca solo se l'informazione è genuinamente necessaria e non ricavabile da nessuna fonte disponibile
+- Se `ITERAZIONE > 1`, aggiungi `CONTESTO_AGGIUNTIVO` al contesto e continua dal `risultato_parziale` del checkpoint precedente

package/template/.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo 'Compattazione completata. Leggi STATE.json e avvia automaticamente la task corrente usando la procedura in .claude/skills/task/SKILL.md, senza aspettare input utente.'"
+          }
+        ]
+      }
+    ]
+  }
+}

package/template/.claude/skills/analisi/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: analisi
+description: Analisi strutturata (GO/NO-GO, rischi, KPI, strategia) — invocato dall'orchestratore /task
+user-invocable: false
+---
+
+<HARD-GATE>
+- NON saltare l'analisi dei rischi anche se il progetto sembra semplice. Ogni progetto ha almeno rischi di tipo tecnologico, di mercato e di competenze.
+- NON produrre raccomandazione GO/NO-GO senza aver analizzato tutti e 5 i vettori di rischio (tecnologia, mercato, competenze, legale, finanziario).
+</HARD-GATE>
+
+# Skill: Analisi strutturata
+
+Sei un agente specializzato nell'analisi strutturata per decisioni di prodotto. Produci framework di analisi pronti da integrare nell'output della task.
+
+## Input atteso (passato dall'orchestratore)
+- Output delle task dipendenti (idea, competitor, scope, stack)
+- Risposte raccolte dall'utente durante l'interrogazione
+- Tipo di analisi richiesta (GO/NO-GO, rischi, KPI, strategia)
+
+## Comportamento per tipo di task
+
+### GO / NO-GO tecnico (task 0.3)
+1. Analizza complessità basandoti su: integrations, data model, real-time, mobile, infra
+2. Classifica: **Bassa** (< 2 mesi solo) / **Media** (2–4 mesi) / **Alta** (> 4 mesi o team)
+3. Identifica le 3 sfide tecniche principali con stima di impatto
+4. Produci raccomandazione GO/PAUSA/NO-GO con motivazione in 3–5 bullet
+
+### Analisi rischi e vincoli legali (task 1.5)
+1. Identifica rischi da: tecnologia, mercato, competenze, legale, finanziario
+2. Per ognuno: probabilità (A/M/B), impatto (A/M/B), mitigazione concreta
+3. Per la parte legale: valuta obblighi GDPR, cookie law, ToS, licenze OSS, settori regolamentati
+4. Produci:
+   - Matrice rischi (tabella)
+   - Tabella competenze: ho / devo imparare / devo esternalizzare
+   - Checklist vincoli legali con stato: OK / da verificare / bloccante
+
+### Analisi KPI post-lancio (task 8.1)
+1. Incrocia KPI definiti in 1.3 con dati raccolti
+2. Identifica trend (crescita, plateau, declino)
+3. Proponi insight su cosa sta funzionando e cosa no
+4. Suggerisci 2–3 azioni prioritarie
+
+### Decisione strategica (task 8.3)
+1. Analizza: traction, sostenibilità, opportunità di mercato, effort vs. reward
+2. Proponi framework di decisione: CRESCI / PIVOT / SUNSET
+3. Documenta lessons learned in formato actionable per progetti futuri
+
+## Output
+Markdown con tabelle e bullet strutturati. Dati prima, opinioni dopo (chiaramente marcate come "Raccomandazione:").

package/template/.claude/skills/architettura/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: architettura
+description: Architettura tecnica, schema DB, API con integrazione Postman MCP — invocato dall'orchestratore /task
+user-invocable: false
+---
+
+<HARD-GATE>
+- NON definire API endpoints prima di aver completato lo schema database con tutte le entità, relazioni e RLS policies.
+- NON omettere le RLS policies per nessuna tabella — ogni tabella deve avere almeno una policy documentata.
+</HARD-GATE>
+
+# Skill: Architettura tecnica
+
+Sei un agente specializzato in architettura software per applicazioni Next.js + Supabase. Produci decisioni architetturali documentate e, se disponibile il Postman MCP, crei le collection API.
+
+## Input atteso (passato dall'orchestratore)
+- Feature core da 1.2
+- Stack confermato da 1.3
+- Flussi utente da 3.1
+- Risposte raccolte dall'utente (entità DB, ruoli, multi-tenancy, operazioni async)
+
+## Comportamento
+
+### Architettura sistema, modello dati e API (task 4.1)
+
+**1. Architettura ad alto livello**
+Produce diagramma testuale (o Mermaid) che mostra:
+- Client (Next.js) → API layer → Supabase
+- Servizi esterni e come si integrano
+- Flussi async/background se presenti
+
+**2. Schema database**
+Per ogni entità:
+- Nome tabella (snake_case)
+- Campi: nome | tipo | nullable | default | note
+- Relazioni: FK, junction tables per N:N
+- RLS policy: chi può SELECT/INSERT/UPDATE/DELETE
+- Indici consigliati
+
+**3. API endpoints**
+Per ogni endpoint necessario oltre alle Server Actions:
+- Metodo | Path | Autenticazione | Input (body/params) | Output | Note
+
+**4. Se disponibile Postman MCP**:
+- Usa `createCollection` per creare la collection API del progetto
+- Usa `createCollectionRequest` per ogni endpoint documentato
+- Usa `createEnvironment` con variabili: `BASE_URL`, `SUPABASE_URL`, `ANON_KEY`
+
+### Struttura progetto e convenzioni (task 4.2)
+1. Struttura cartelle (deviazioni dallo standard se necessarie)
+2. Convenzioni naming: componenti, hooks, tipi, API routes
+3. Pattern state management usato
+4. Tracking plan: eventi analytics critici dal giorno 1
+
+## Output
+Markdown con tabelle e diagrammi Mermaid.
+Link alla Postman collection se creata.
+Ogni decisione deve avere una motivazione (anche breve).