@dtlabs/ai-toolkit 0.1.6 → 0.2.0

package/bin/cli.js

@@ -40,10 +40,18 @@ function banner() {
 
 // ── helpers ──────────────────────────────────────────────────────────────────
 
+// User-owned config that must NEVER be copied into a destination. We only verify
+// and advise on these — copying would clobber the user's existing settings.
+const NEVER_COPY = new Set(['settings.json', 'settings.local.json']);
+
 function fileHash(filePath) {
   return crypto.createHash('md5').update(fs.readFileSync(filePath)).digest('hex');
 }
 
+function readJsonSafe(filePath) {
+  try { return JSON.parse(fs.readFileSync(filePath, 'utf8')); } catch { return null; }
+}
+
 function ensureDir(filePath) {
   const dir = path.dirname(filePath);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
@@ -67,10 +75,12 @@ function expandMappings(mappings) {
     if (!fs.existsSync(src)) continue;
     if (fs.statSync(src).isDirectory()) {
       for (const entry of walkDir(src)) {
+        if (NEVER_COPY.has(path.basename(entry))) continue; // never clobber user config
         const rel = path.relative(src, entry);
         files.push({ src: entry, dest: path.join(dest, rel) });
       }
     } else {
+      if (NEVER_COPY.has(path.basename(src))) continue;
       files.push({ src, dest });
     }
   }
@@ -262,6 +272,52 @@ async function askMattPocock() {
   else console.log(`  ${clr('gray', 'Skipped.')}\n`);
 }
 
+// ── subagent spawn-depth check (verify & advise only — never write) ────────────
+
+const SPAWN_DEPTH_VAR = 'CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH';
+
+// Report whether the spawn-depth prerequisite is satisfied for a destination,
+// checking both project-level and local-override settings files. Purely advisory:
+// this NEVER creates or modifies any settings file.
+function checkSpawnDepth(destRoot) {
+  const candidates = [
+    path.join(destRoot, '.claude', 'settings.json'),
+    path.join(destRoot, '.claude', 'settings.local.json'),
+  ];
+
+  console.log(divider());
+  console.log(bold('  Subagent spawn depth (required for orchestrated pipelines)'));
+  console.log(divider());
+
+  for (const file of candidates) {
+    if (!fs.existsSync(file)) continue;
+    const json = readJsonSafe(file);
+    const value = json && json.env && json.env[SPAWN_DEPTH_VAR];
+    if (value !== undefined && Number(value) >= 2) {
+      console.log(`  ${clr('green', '✔')}  ${SPAWN_DEPTH_VAR}=${value} found in ${dim(path.relative(process.cwd(), file))}`);
+      console.log(`     ${dim('Orchestrators can spawn worker subagents — pipelines will run as designed.')}\n`);
+      return;
+    }
+  }
+
+  console.log(`  ${clr('yellow', '⚠')}  ${SPAWN_DEPTH_VAR} is not set to 2+ in this project.`);
+  console.log(`     ${dim('Without it, /implement-feature and /assess-codebase run every worker inline')}`);
+  console.log(`     ${dim('on the orchestrator model: per-agent model assignment, context isolation,')}`);
+  console.log(`     ${dim('and per-agent token telemetry are all lost.')}`);
+  console.log();
+  console.log(`     ${bold('Action required')} — add this to ${clr('cyan', '.claude/settings.json')} (project)`);
+  console.log(`     or ${clr('cyan', '~/.claude/settings.json')} (all projects). We do not edit it for you,`);
+  console.log(`     ${dim('to avoid clobbering your existing configuration:')}`);
+  console.log();
+  console.log(clr('gray', '       {'));
+  console.log(clr('gray', '         "env": {'));
+  console.log(clr('gray', `           "${SPAWN_DEPTH_VAR}": "2"`));
+  console.log(clr('gray', '         }'));
+  console.log(clr('gray', '       }'));
+  console.log();
+  console.log(`     ${dim('Then restart Claude Code so the variable is loaded.')}\n`);
+}
+
 // ── entry points ──────────────────────────────────────────────────────────────
 
 async function installLocal(targetDir, force) {
@@ -277,6 +333,7 @@ async function installLocal(targetDir, force) {
   await runInstall(`local project`, mappings, force);
   writeInstalledVersion(targetDir);
   console.log(`  ${clr('green', '✔')}  ${bold('Install complete.')}\n`);
+  checkSpawnDepth(targetDir);
   await askMattPocock();
   console.log(divider());
   console.log(`\n  ${bold('Next steps:')}`);
@@ -293,15 +350,17 @@ async function installGlobal(force) {
     console.log(`  ${clr('cyan', '▸')}  Target: ${bold(target)}  ${clr('gray', '(global Claude folder)')}\n`);
     await checkVersion(target, force);
     const mappings = [
-      { src: path.join(packageRoot, '.claude', 'agents'),   dest: path.join(target, 'agents') },
-      { src: path.join(packageRoot, '.claude', 'skills'),   dest: path.join(target, 'skills') },
-      { src: path.join(packageRoot, '.claude', 'commands'), dest: path.join(target, 'commands') },
-      { src: path.join(packageRoot, 'docs'),                dest: path.join(target, 'docs') },
-      { src: path.join(packageRoot, 'CLAUDE.md'),           dest: path.join(target, 'CLAUDE.md') },
+      { src: path.join(packageRoot, '.claude', 'agents'),    dest: path.join(target, 'agents') },
+      { src: path.join(packageRoot, '.claude', 'skills'),    dest: path.join(target, 'skills') },
+      { src: path.join(packageRoot, '.claude', 'commands'),  dest: path.join(target, 'commands') },
+      { src: path.join(packageRoot, '.claude', 'workflows'), dest: path.join(target, 'workflows') },
+      { src: path.join(packageRoot, 'docs'),                 dest: path.join(target, 'docs') },
+      { src: path.join(packageRoot, 'CLAUDE.md'),            dest: path.join(target, 'CLAUDE.md') },
     ];
     await runInstall('global Claude folder', mappings, force);
     writeInstalledVersion(target);
     console.log(`  ${clr('green', '✔')}  ${bold('Global install complete.')}\n`);
+    checkSpawnDepth(homedir);
     await askMattPocock();
     console.log(divider());
     console.log(`\n  ${bold('Next steps:')}`);

package/docs/token-optimization-backlog.md

@@ -0,0 +1,115 @@
+# Token Optimization — Backlog di feature atomiche
+
+> Deriva da `docs/token-optimization.md`. Data: 2026-07-24.
+> Ogni voce è **atomica**: implementabile e verificabile in isolamento.
+> "Criticità" = priorità di ottimizzazione (impatto/rischio), NON severità di difetto.
+> Nessun intervento è un bug attivo → nessun `CRITICAL`.
+> Sequenza consigliata = ordine degli ID.
+
+## Quadro sintetico
+
+| ID | Intervento | Criticità | Sforzo | Rischio | File toccati | Dipende da |
+|----|-----------|-----------|--------|---------|--------------|-----------|
+| OPT-01 ✅ | `model:` esplicito su ogni agent (→ FTR-007, PR #20) | **HIGH** | Basso | Basso | 15 agent (frontmatter) | — |
+| OPT-02 | Deduplicare CLAUDE.md globale vs progetto | **HIGH** | Minimo | Zero | `~/.claude/CLAUDE.md` | — |
+| OPT-03 | Blocco "Compact instructions" in CLAUDE.md | MEDIUM | Minimo | Zero | `CLAUDE.md` (progetto) | — |
+| OPT-04 | Spostare i cataloghi da CLAUDE.md a reference.md | MEDIUM | Basso | Basso | `CLAUDE.md`, `docs/reference.md` | — |
+| OPT-05 | Procedure on-demand — assessment-manager | MEDIUM | Medio | Basso | `assessment-manager.md` | — |
+| OPT-06 | Procedure on-demand — project-manager | MEDIUM | Medio | Basso | `project-manager.md` | — |
+| OPT-07 | Resource-budget testuale negli assessment agent | MEDIUM | Basso | Basso | 3+ assessment agent | — |
+| OPT-08 | Summary/full split negli output di assessment | **HIGH** | Alto | Medio | assessment agents + int-doc + manager | OPT-07 |
+| OPT-09 | Estrarre calcolo deterministico da assessment-manager | **HIGH** | Alto | Medio | `assessment-manager.md` + nuovo script | — |
+| OPT-10 | generic-software-assessment → ruolo triage | MEDIUM | Medio | Medio | `generic-software-assessment.md` + manager | OPT-08 |
+| OPT-11 | Delegation policy negli orchestratori | LOW | Basso | Basso | 2 orchestratori | — |
+| OPT-12 | Hook di filtro output verboso (opzionale) | LOW | Basso | Basso | `settings.json` + script hook | — |
+
+---
+
+## Feature atomiche
+
+### OPT-01 — `model:` esplicito su ogni agent
+- **Criticità:** HIGH · **Sforzo:** Basso · **Rischio:** Basso
+- **Obiettivo:** ogni agent dichiara il modello adatto al suo ruolo, così nessuno eredita Opus per default.
+- **Scope (solo frontmatter):** aggiungere `model:` ai 15 agent che ne sono privi. Mappatura:
+  - `sonnet`: `assessment-manager`, `project-manager`, `developer-backend`, `developer-frontend`, `developer-testing`, `god-class-decomposition`, `domain-model-refactoring`, `dependency-injection-refactoring`, `security-hardening`, `dependency-supply-chain-security`, `define-feature`, `init-agents-md`, `install-toolkit`, `intervention-documentation-standard`
+  - `opus`: `review-solution` (unico ruolo con giudizio architetturale profondo)
+- **Fuori scope:** i 7 agent già `haiku` restano invariati.
+- **Criteri di accettazione:** `grep -L "^model:" .claude/agents/*.md` non restituisce nulla; ogni valore ∈ {haiku, sonnet, opus}.
+- **Dipendenze:** nessuna.
+
+### OPT-02 — Deduplicare CLAUDE.md globale vs progetto
+- **Criticità:** HIGH · **Sforzo:** Minimo · **Rischio:** Zero
+- **Obiettivo:** eliminare il duplicato caricato a ogni sessione; il `CLAUDE.md` di progetto resta la fonte unica del catalogo toolkit.
+- **Scope:** ridurre `~/.claude/CLAUDE.md` alle sole preferenze cross-progetto (lingua, stile, convenzioni personali). Rimuovere il catalogo toolkit duplicato.
+- **Criteri di accettazione:** `diff ~/.claude/CLAUDE.md ./CLAUDE.md` NON è più identico; il globale non contiene più le tabelle Skills/Commands/Agents; il Gate Protocol resta accessibile (nel progetto).
+- **Dipendenze:** nessuna. ⚠️ File utente globale — confermare con l'utente prima di modificare.
+
+### OPT-03 — Blocco "Compact instructions" in CLAUDE.md
+- **Criticità:** MEDIUM · **Sforzo:** Minimo · **Rischio:** Zero
+- **Obiettivo:** guidare l'auto-compaction a preservare ciò che conta (decisioni, file, finding IDs) e scartare rumore.
+- **Scope:** aggiungere al `CLAUDE.md` di progetto una sezione `# Compact instructions` (preserva: obiettivo corrente, decisioni confermate, risposte utente, file modificati, errori aperti, finding/artifact IDs; scarta: risultati grep grezzi, output tool riusciti, spiegazioni ripetute, piani superati).
+- **Criteri di accettazione:** la sezione esiste in `CLAUDE.md`; nessun'altra modifica.
+- **Dipendenze:** nessuna. (Coordinare con OPT-04 se si tocca lo stesso file.)
+
+### OPT-04 — Spostare i cataloghi da CLAUDE.md a reference.md
+- **Criticità:** MEDIUM · **Sforzo:** Basso · **Rischio:** Basso
+- **Obiettivo:** CLAUDE.md sotto ~200 righe, solo essenziali operativi; il catalogo di scoperta vive in reference.md.
+- **Scope:** spostare le tabelle Skills / Commands / Agents / Procedures in `docs/reference.md`. In `CLAUDE.md` restano: Dependencies, How it works, override procedure, **Gate Protocol**. Aggiungere in CLAUDE.md un puntatore a reference.md.
+- **Criteri di accettazione:** `CLAUDE.md` < 200 righe; nessuna tabella-catalogo persa (presente in reference.md); Gate Protocol ancora in CLAUDE.md.
+- **Dipendenze:** nessuna.
+
+### OPT-05 — Procedure on-demand (assessment-manager)
+- **Criticità:** MEDIUM · **Sforzo:** Medio · **Rischio:** Basso
+- **Obiettivo:** leggere ogni procedura nella fase in cui serve, non tutte all'avvio.
+- **Scope:** in `assessment-manager.md`, spostare le istruzioni "read at startup" così che `token-estimation.md`/`pricing.md` si leggano in Phase 3-4, `assessment-findings-gate.md` in Phase 5, ecc.
+- **Criteri di accettazione:** nessuna procedura letta prima della fase che la usa; il comportamento delle fasi resta invariato.
+- **Dipendenze:** nessuna. (Se si fa OPT-09, `token-estimation.md` sparisce del tutto dal contesto LLM.)
+
+### OPT-06 — Procedure on-demand (project-manager)
+- **Criticità:** MEDIUM · **Sforzo:** Medio · **Rischio:** Basso
+- **Obiettivo:** stesso principio di OPT-05 applicato al `project-manager` (che legge ancora più procedure).
+- **Scope:** riorganizzare `project-manager.md` per caricare ogni procedura alla fase pertinente (PR-procedure alla fase PR, ecc.).
+- **Criteri di accettazione:** nessuna procedura caricata anticipatamente; pipeline invariata.
+- **Dipendenze:** nessuna.
+
+### OPT-07 — Resource-budget testuale negli assessment agent
+- **Criticità:** MEDIUM · **Sforzo:** Basso · **Rischio:** Basso
+- **Obiettivo:** limiti di lettura/output come **istruzioni nel prompt** (NON frontmatter — `budget:` non è supportato dall'harness).
+- **Scope:** aggiungere una sezione `## Resource budget` in prosa agli assessment agent (es. "Inspect at most ~25 files; ≤2 evidence snippets per finding; stop when evidence is sufficient — do not explore to increase coverage").
+- **Criteri di accettazione:** la sezione è testo del prompt, non YAML; presente in `generic-software-assessment`, `layered-architecture-assessment`, `concurrency-safety-assessment`.
+- **Dipendenze:** nessuna.
+
+### OPT-08 — Summary/full split negli output di assessment
+- **Criticità:** HIGH · **Sforzo:** Alto · **Rischio:** Medio
+- **Obiettivo:** l'orchestratore legge un **summary compatto**, non il documento intero. Il guadagno reale (non il formato JSON in sé).
+- **Scope:** ogni assessment agent produce `{PREFIX}-{area}.full.md` (dettagli) + `{PREFIX}-{area}.summary` (conteggi per severità, finding IDs, path del full). `assessment-manager` e `intervention-documentation-standard` consumano il summary; il full si apre solo per i finding accettati.
+- **Criteri di accettazione:** ogni agent scrive entrambi i file; il manager non legge i `.full` in Phase 3; l'int-doc apre i full solo per i finding selezionati.
+- **Dipendenze:** OPT-07 (budget di output coerente).
+
+### OPT-09 — Estrarre calcolo deterministico da assessment-manager
+- **Criticità:** HIGH · **Sforzo:** Alto · **Rischio:** Medio
+- **Obiettivo:** togliere dal prompt ~3.500 parole di pseudo-codice (calcolo token/effort, registry write) che un LLM esegue in modo costoso e fragile.
+- **Scope:** spostare Token-Estimate / Effort-Estimate / registry-write in uno script (`scripts/estimate.*`) invocato via Bash; il prompt dell'agent si riduce a "esegui lo script con questi input e verifica l'output".
+- **Criteri di accettazione:** i tre file prodotti sono identici (per input noti) a prima; `assessment-manager.md` perde le sezioni di calcolo passo-passo; nessun errore aritmetico possibile lato LLM.
+- **Dipendenze:** nessuna hard; sinergica con OPT-05.
+
+### OPT-10 — generic-software-assessment → ruolo triage
+- **Criticità:** MEDIUM · **Sforzo:** Medio · **Rischio:** Medio
+- **Obiettivo:** evitare che il generic duplichi il lavoro degli specialisti (layer, security, concurrency) sullo stesso codebase.
+- **Scope:** trasformare `generic-software-assessment` in triage: scansione superficiale che decide quali specialisti attivare e copre solo le aree non coperte (Opzione A della gap analysis).
+- **Criteri di accettazione:** il generic non riesamina aree già coperte da uno specialista attivo; l'output indica gli specialisti raccomandati.
+- **Dipendenze:** meglio dopo OPT-08 (contratto di output stabile).
+
+### OPT-11 — Delegation policy negli orchestratori
+- **Criticità:** LOW · **Sforzo:** Basso · **Rischio:** Basso
+- **Obiettivo:** regola esplicita "delega un subagent solo se serve" (task indipendente/parallelo, output voluminoso, riuso multiplo); non delegare ciò che una grep/read risolve.
+- **Scope:** aggiungere una sezione `## Delegation policy` a `assessment-manager` e `project-manager`.
+- **Criteri di accettazione:** entrambi gli orchestratori contengono i criteri delega/non-delega.
+- **Dipendenze:** nessuna.
+
+### OPT-12 — Hook di filtro output verboso (opzionale)
+- **Criticità:** LOW · **Sforzo:** Basso · **Rischio:** Basso
+- **Obiettivo:** filtrare output verbosi (build/test/log) prima che entrino nel contesto.
+- **Scope:** `PreToolUse` su Bash in `settings.json` + script che riduce l'output di test/build alle sole righe rilevanti.
+- **Criteri di accettazione:** l'hook appare in `/hooks`; un comando di test mostra solo failures.
+- **Dipendenze:** nessuna. Fare solo se gli assessment inizieranno a lanciare build/test.

package/docs/token-optimization.md

@@ -0,0 +1,274 @@
+# Ottimizzazione dell'uso dei token — AI Toolkit
+
+> Report di analisi. Data: 2026-07-23.
+> Fonti: misurazioni sul repo + documentazione ufficiale Claude Code (`code.claude.com/docs/en/costs`).
+> Stato: **solo raccomandazioni** — nessuna modifica applicata.
+
+## Come Claude Code fattura i token (il modello mentale corretto)
+
+Il costo scala con la **dimensione del contesto processato a ogni turno**, non con
+il numero di file nel toolkit. Tre meccanismi automatici mitigano già molto:
+
+- **Prompt caching**: system prompt, CLAUDE.md e tool definitions ripetuti vengono
+  cachati (cache read costa ~1/10 di un input token). Vita cache: 1h su subscription,
+  5 min su API/usage-credits.
+- **Auto-compaction**: la history lunga viene riassunta vicino al limite di contesto.
+- **Subagent isolati**: l'output verboso resta nel contesto del subagent, al main
+  loop torna solo un riassunto.
+
+Conseguenza pratica: **le leve più grosse non sono "accorciare i prompt" ma
+(a) non pagare due volte lo stesso contesto, (b) usare il modello giusto per ogni
+agent, (c) tenere fuori dal contesto ciò che non serve al turno corrente.**
+
+---
+
+## Leva 1 — Deduplicare CLAUDE.md  ⭐ impatto alto / sforzo minimo / rischio zero
+
+### Cosa ho misurato
+- `CLAUDE.md` (progetto) e `~/.claude/CLAUDE.md` (globale) sono **byte-per-byte identici**
+  (verificato con `diff -q`).
+- 169 righe / 1.257 parole ciascuno (~1.700 token).
+- Entrambi vengono caricati in **ogni** sessione → ~3.400 token di contesto base,
+  di cui **metà è puro duplicato**.
+- 55 delle 169 righe sono tabelle-catalogo (elenco skill/comandi/agent) — informazione
+  di *scoperta*, non *istruzione operativa*.
+
+### Raccomandazione
+1. **Il globale non deve duplicare il progetto.** `~/.claude/CLAUDE.md` dovrebbe
+   contenere solo preferenze cross-progetto (lingua, stile). Il catalogo del toolkit
+   vive già nel `CLAUDE.md` di progetto + `docs/reference.md`.
+2. **Spostare le tabelle-catalogo in `docs/reference.md`** (che già esiste ed è pensato
+   come cheatsheet). CLAUDE.md tiene solo: dipendenze, Gate Protocol, override
+   procedure. La doc ufficiale raccomanda **CLAUDE.md < 200 righe, solo essenziali**.
+3. Il Gate Protocol (regole MANDATORY sul PM) **resta** in CLAUDE.md: è un vincolo
+   operativo che deve essere sempre attivo.
+
+### Risparmio stimato
+~1.700 token di duplicato eliminati + ~600 token di catalogo spostato = **~2.300 token
+risparmiati su ogni turno di ogni sessione**. Su sessioni lunghe (dove il contesto si
+rimanda intero a ogni messaggio) è il risparmio con il miglior rapporto costo/beneficio.
+
+---
+
+## Leva 2 — Assegnare `model:` esplicito a ogni agent  ⭐ impatto altissimo
+
+### Cosa ho misurato
+Solo 7 agent su 22 hanno `model:` nel frontmatter (tutti `haiku`). Gli altri 15 —
+**inclusi i due orchestratori `assessment-manager` e `project-manager`** — non lo
+specificano e quindi ereditano il modello di sessione (spesso Opus).
+
+### Perché conta più di tutto il resto
+Dal listino in `docs/pricing.md`:
+
+| Modello | Blended $/1k token | Rapporto vs Haiku |
+|---|---|---|
+| Opus 4.8 | $0.009000 | **5×** |
+| Sonnet 5 | $0.005400 | 3× |
+| Haiku 4.5 | $0.001800 | 1× |
+
+Un agent che gira su Opus invece che su Sonnet costa **~1,7× in più a parità di token**.
+La doc ufficiale è esplicita: *"Reserve Opus for complex architectural decisions or
+multi-step reasoning. For simple subagent tasks, specify `model: haiku`."*
+
+### Raccomandazione — mappatura per ruolo
+| Ruolo | Modello suggerito | Motivo |
+|---|---|---|
+| Orchestratori (`assessment-manager`, `project-manager`) | **sonnet** | Coordinamento, non ragionamento profondo. La doc consiglia Sonnet per il coordinamento nei team. |
+| Assessment read-only (già haiku) | haiku ✅ | Pattern-matching su codice |
+| `generate-*`, `validate-*` (già haiku) | haiku ✅ | Trasformazione documentale |
+| Developer (`developer-backend/frontend/testing`) | **sonnet** | Scrittura codice, buon compromesso |
+| Refactoring (`god-class`, `domain-model`, `dependency-injection`) | **sonnet** | Modifiche strutturali con verifica build |
+| `review-solution` | **opus** *(o sonnet)* | Unico punto dove il ragionamento profondo ripaga |
+| `define-feature`, `init-agents-md` | sonnet | Interviste/analisi |
+
+Regola: **default Sonnet, Haiku per il meccanico, Opus solo dove il giudizio architetturale ripaga.**
+
+### Risparmio stimato
+Se gli orchestratori giravano su Opus, passarli a Sonnet è **~40% sul loro costo**.
+Dato che `assessment-manager` è l'agent più pesante (~6.700 token di solo prompt +
+~3.000 di procedure lette a runtime), è il singolo intervento a maggior ritorno.
+
+---
+
+## Leva 3 — Estrarre la logica deterministica da `assessment-manager`  ⭐ impatto alto / sforzo medio
+
+### Cosa ho misurato
+`assessment-manager.md` = **5.052 parole (~6.700 token)**, il doppio del secondo agent.
+Di queste, le sezioni righe **104–357** (calcolo Token/Effort Estimate) e **378–630**
+(Data Contracts + Registry Write Algorithm) sono **~3.500 parole di pseudo-codice
+deterministico**: somme, formule fisse, gestione errori I/O passo-passo, parsing tabelle.
+
+### Il problema
+Far *eseguire a un LLM* aritmetica e I/O deterministici è:
+- **costoso** — quelle 3.500 parole entrano nel contesto dell'agent a ogni run;
+- **fragile** — il modello può sbagliare una somma o un formato;
+- **ridondante** — è esattamente il lavoro che uno script fa a costo ~zero.
+
+### Raccomandazione
+Spostare la logica meccanica fuori dal prompt in uno di questi modi (in ordine di preferenza):
+1. **Script esterno** (Python/Node) invocato via Bash: prende i `<usage>` block +
+   Interventions-Index e produce Token-Estimate.md / Effort-Estimate.md / registry.md.
+   Il prompt dell'agent si riduce a "esegui `scripts/estimate.py` con questi input".
+2. **Workflow script** (`Workflow` tool) se preferisci restare dentro Claude Code:
+   fan-out degli assessment + fasi di calcolo deterministico in JS.
+3. Se deve restare prosa, **comprimere** i Data Contract e la gestione errori in una
+   procedura referenziata (`docs/procedures/`) letta solo quando serve, non inline.
+
+Il prompt di `assessment-manager` potrebbe scendere da ~6.700 a ~2.500 token.
+
+### Risparmio stimato
+~4.000 token di prompt in meno per ogni invocazione dell'assessment-manager, **più**
+eliminazione del rischio di errori aritmetici (che oggi costano ri-esecuzioni).
+
+---
+
+## Leva 4 — Procedure lette on-demand invece che all'avvio  ⭐ impatto medio
+
+### Cosa ho misurato
+`assessment-manager` legge all'avvio 4 procedure + `pricing.md`:
+`process-log` (144w) + `issues-register` (140w) + `assessment-findings-gate` (629w)
++ `token-estimation` (1.283w) + `pricing` = **~2.900 parole (~3.900 token)** iniettate
+nel contesto *prima* di iniziare. 7 agent hanno questo pattern "read these procedures".
+
+### Raccomandazione
+- Leggere ogni procedura **nel momento in cui serve**, non tutte all'inizio.
+  Es. `token-estimation.md` serve solo in Phase 3/4, non in Phase 1.
+- Se la Leva 3 estrae il calcolo token in uno script, `token-estimation.md` (1.283w,
+  la procedura più grossa) **non serve più nel contesto dell'LLM**.
+- Valutare la compressione delle procedure più lunghe: `token-estimation.md` e
+  `approval-gates.md` contengono esempi ripetuti comprimibili.
+
+### Risparmio stimato
+~2.000 token per run dell'assessment-manager, cumulativo con la Leva 3.
+
+---
+
+## Leva 5 — Igiene di sessione (comportamentale, costo zero)
+
+Dalla doc ufficiale, gli sprechi più comuni sono **sessioni mai pulite** e **modello
+troppo grosso di default**:
+
+- **`/clear` tra task non correlati.** Il contesto stantio si ri-invia a ogni messaggio.
+  Prima di pulire, `/rename` per ritrovare la sessione, poi `/resume`.
+- **`/compact "focus su X"`** quando serve continuità ma il contesto è cresciuto.
+- **`/context` e `/usage`** per vedere cosa occupa spazio; `/usage` segnala i
+  comportamenti che superano il 10% (long context, cache miss).
+- **Cache miss**: la prima richiesta dopo >1h (subscription) ri-processa tutto il
+  contesto. Raggruppare il lavoro sul toolkit in finestre temporali serrate aiuta.
+- **`/effort` più basso** per i task meccanici: i thinking token sono fatturati come
+  output. Per gli agent Haiku (assessment pattern-matching) l'effort alto raramente ripaga.
+
+---
+
+## Leva 6 — Hook di pre-processing per output verbosi  ⭐ opzionale
+
+Gli agent di assessment leggono molto codice. Un hook `PreToolUse` su Bash può
+filtrare l'output dei comandi (es. solo righe `ERROR`/`FAIL`, o `grep` mirati) prima
+che entri nel contesto — la doc mostra un esempio che riduce un log da decine di
+migliaia a centinaia di token. Utile se in futuro gli assessment lanciano build/test.
+
+---
+
+## Riepilogo prioritizzato
+
+| # | Leva | Impatto | Sforzo | Rischio | Risparmio stimato |
+|---|---|---|---|---|---|
+| 1 | Deduplicare CLAUDE.md globale/progetto | Alto | Minimo | Zero | ~2.300 tok / turno |
+| 2 | `model:` esplicito su tutti gli agent | **Altissimo** | Basso | Basso | ~40% sugli orchestratori |
+| 3 | Estrarre calcolo deterministico da assessment-manager | Alto | Medio | Medio | ~4.000 tok / run |
+| 4 | Procedure on-demand | Medio | Medio | Basso | ~2.000 tok / run |
+| 5 | Igiene di sessione (/clear, /compact, /effort) | Alto | Zero | Zero | variabile, cumulativo |
+| 6 | Hook di filtro output | Medio | Basso | Basso | dipende dall'uso |
+
+**Ordine consigliato di attacco:** 2 → 1 → 5 (tutti a basso sforzo e alto ritorno),
+poi 3 → 4 (refactoring più impegnativo dell'assessment-manager), infine 6 se necessario.
+
+---
+
+## Riconciliazione con l'analisi ChatGPT del repo
+
+ChatGPT ha analizzato il repo pubblico `dtlab-tech/ai-toolkit` e prodotto ~15
+raccomandazioni. Ecco il giudizio critico su ciascuna, alla luce di **come funziona
+realmente Claude Code** (non un framework generico) e di cosa ho verificato sul codice.
+
+### Convergenze — GPT ha ragione, e coincide con le mie leve
+
+| Raccomandazione GPT | Mio giudizio | Nota |
+|---|---|---|
+| Modelli differenziati per ruolo (haiku/sonnet/opus) | ✅ **Valida, priorità #1** | = mia Leva 2. Allineata alla doc ufficiale. |
+| Effort basso per task meccanici | ✅ Valida | Thinking token = output token. `/effort` o `MAX_THINKING_TOKENS`. |
+| Summary + full split (orchestratore legge solo il summary) | ✅ **Valida, alto ROI** | La doc Anthropic lo raccomanda esplicitamente per i subagent. |
+| Procedure caricate on-demand per fase | ✅ Valida | = mia Leva 4. |
+| `/clear`, `/compact`, compact-instructions in CLAUDE.md | ✅ Valida | = mia Leva 5. Confermato dalla doc. |
+| CLAUDE.md breve | ✅ **Valida** | = mia Leva 1 — ma GPT non poteva vedere il duplicato globale/progetto. |
+| generic-assessment → triage (non duplicare gli specialisti) | ✅ Valida | Riduce sovrapposizione di scope. Buon punto. |
+| Delegation policy (subagent solo se serve) | ✅ Valida | Allineata alla doc sui subagent. |
+| Scope a livello di file, non solo di agente | 🟡 Utile | Vero che `--scope` seleziona agent, non file. Ma vedi caveat sotto. |
+
+### Caveat e correzioni — dove GPT ragiona da "framework tradizionale"
+
+1. **"Aggiungi `budget:` nel frontmatter dell'agent" — ❌ tecnicamente errato.**
+   Lo schema frontmatter degli agent Claude Code (`name`, `description`, `model`,
+   `tools`) **non ha un campo `budget:`**. Metterlo lì non fa nulla: non è *enforced*
+   dall'harness. Un `max_files: 25` in YAML è ignorato.
+   → *Correzione:* i limiti vanno espressi come **istruzioni testuali nel corpo del
+   prompt** ("Inspect at most ~25 files; stop when evidence is sufficient"). Sono
+   linee guida che il modello segue, non vincoli hard. Un budget di token *reale*
+   esiste solo dentro i **Workflow script** (`budget.total`), che è un altro meccanismo.
+
+2. **"Repository Scanner unico + `repository-index.json`" (P0 di GPT) — 🟡 valido come
+   principio, sopravvalutato nell'impatto.** GPT assume che ogni agent "riceva/riscansioni
+   l'intero repository". In realtà un subagent Claude Code parte con **contesto minimo**
+   e legge on-demand via Grep/Glob/Read: ricevere il *path* ≠ ricevere tutto il repo.
+   La duplicazione di lettura esiste (N agent che grep-ano gli stessi file), ma è meno
+   drammatica del quadro dipinto. Inoltre, su un toolkit *generico* che gira su codebase
+   arbitrarie, l'indice va **rigenerato a ogni run** (= una scansione comunque). Il
+   risparmio reale c'è **solo se molti agent condividono lo stesso indice** — va misurato,
+   non assunto. Buona idea per l'assessment parallelo; ROI da verificare.
+
+3. **"Output JSON compatti invece di Markdown" (P0 di GPT) — 🟡 il punto giusto è un
+   altro.** JSON non è intrinsecamente più economico del Markdown: virgolette, parentesi
+   e chiavi ripetute spesso lo rendono *più* verboso. Il guadagno vero non è "JSON vs MD"
+   ma **il summary/full split** (l'orchestratore legge il riassunto, non il documento
+   intero). Adottare lo split: sì. Farlo *perché* è JSON: irrilevante.
+
+4. **"Cache hash-based (commit_sha + agent_version + …)" (P1 di GPT) — 🟡 chiarire il
+   livello.** Questo è caching **applicativo** (evitare di *ri-eseguire* un agent se
+   l'input non è cambiato), NON il **prompt caching** di Claude (che riduce il costo
+   input a ogni turno ed è già automatico). Sono complementari. La cache hash-based è
+   utile ma va capito che agisce su un asse diverso dal costo per-turno.
+
+5. **"Skill progressive per Clean Code / Clean Architecture" (P1 di GPT) — 🟡 premessa
+   parz. sovrastimata.** GPT ipotizza "300 righe di regole Clean Code nei prompt".
+   Verificato: gli agent **non** contengono quel volume — `god-class-decomposition` e
+   `domain-model-refactoring` citano i concetti brevemente. L'idea di skill progressive
+   resta buona in generale, ma il risparmio su *questo* repo è minore di quanto stimato.
+
+6. **"agent-registry.json per evitare la discovery ripetuta" (P1) — 🟢 basso ROI.**
+   GPT stesso ammette che "il costo non è enorme". Micro-ottimizzazione: leggere i
+   frontmatter di ~22 file è economico. Farlo solo se si tocca comunque l'installer.
+
+7. **"Handbook di 120-150 pagine" — ⚠️ attenzione al paradosso token.** Un manuale
+   umano va benissimo *come documentazione*. Ma se lo si referenzia da CLAUDE.md o lo si
+   fa leggere agli agent, **aumenta** i token — l'opposto dell'obiettivo. Tenerlo come
+   riferimento per umani, mai in contesto automatico.
+
+### Suggerimenti "generici" (non da questa chat) che comunque NON valgono per Claude Code
+
+- **"Abbassa `max_tokens` / `temperature`"** — non esposti nella CLI; la lunghezza
+  dell'output è guidata dal task.
+- **"Manda meno messaggi"** — irrilevante: costa il *contesto per turno*, non il numero
+  di messaggi.
+- **"Usa un modello piccolo per tutto"** — controproducente: un modello troppo debole
+  sbaglia e forza ri-esecuzioni. La regola è *modello adatto al task*.
+
+### Sintesi del giudizio
+
+La base del toolkit è solida (GPT dà 6,5/10, ragionevole). Le raccomandazioni a **più
+alto ritorno e più basso rischio**, su cui io e GPT convergiamo, sono:
+**(1) modelli differenziati, (2) summary/full split, (3) procedure on-demand, (4) igiene
+di sessione.** A queste aggiungo la **deduplicazione del CLAUDE.md globale/progetto**
+(che GPT non poteva vedere). Le idee più "architetturali" di GPT (repository-scanner,
+budget, cache hash-based) sono valide come *direzione* ma vanno (a) tradotte nei
+meccanismi reali di Claude Code e (b) **misurate con `/usage` prima e dopo**, non
+adottate sulla fiducia.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dtlabs/ai-toolkit",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "description": "AI Toolkit — reusable agents and procedures for developers to build AI-powered applications.",
   "files": [
     "docs/",