Vai al contenuto

AI Agents & Orchestration — Roadmap

Backlog di miglioramenti per portare l'orchestrazione Claude + agent a livello production-ready. Ogni voce ha priorità (P0/P1/P2) e prerequisiti.

✅ Completato (in feature/skill-review)

  • B1 — Single source of truth: tutte le rules in .claude/rules/. Agent e skill review linkano lì.
  • B2 — Gate qualità: npm run check (lint + typecheck + format check) in package.json; permessi in .claude/settings.json.
  • B3 — Auto-review agent: ogni agent esegue review delle rules sul proprio diff prima di restituire.
  • F1 — Output Contract: formato strutturato obbligatorio per gli agent (vedi .claude/rules/_agent-protocol.md).
  • Tone rigidità: documentato in orchestration.md, _agent-protocol.md e nei system prompt degli agent. Niente accomodamenti.
  • Progressive loading: rules caricate on-demand per tipo di file (_agent-protocol.md §caricamento). Agent ~30-42 righe.
  • Hooks di enforcement: format-touched (PostToolUse, auto-fix prettier sul file toccato), check-incremental (Stop, blocca su lint/format dei file cambiati con guard anti-loop), graph-staleness (SessionStart, warning >48h). Script in .claude/hooks/, registrati in .claude/settings.json. Copre anche F2 (graph staleness).
  • Tooling allineato alle rules: installati eslint-plugin-prettier + eslint-config-prettier (lint era rotto); no-explicit-any e no-unused-vars portati da off a warn (→ error dopo cleanup legacy).
  • Agent tools: + model:: ogni agent ha tool ristretti (no Web) e modello pinnato. opus: component/service/lib-dev. sonnet: page-dev, style-dev (task meccanici/assembly, gated da hook+review).

🟠 Prossimo (P0 — blocker per production)

Debito legacy da ripulire (sbloccato da questo round)

  • Formattazione: ~120 file mai passati per prettier (default config corretta). prettier --write . in un commit dedicato style: → poi npm run check verde project-wide.
  • any: ~47 occorrenze in 24 file. Dopo cleanup, alzare no-explicit-any da warn a error in eslint.config.js.

B4 — Agent test-dev e policy di copertura

Il progetto ha 0 file .spec.ts (verificato): nessun test. Production-ready senza test su src/services/ e src/utils/ non esiste.

Da fare: - Decidere framework (Karma resta o si passa a Jest/Vitest?). - Creare .claude/agents/test-dev.md con scope **/*.spec.ts. - Aggiungere .claude/rules/testing.md: cosa testare (utils sempre, services sempre per metodi HTTP+state, componenti solo se logica non-banale), naming pattern, no test su template HTML banali. - Policy nell'orchestrator: ogni nuovo metodo pubblico in src/services/ o src/utils/ richiede uno spec creato dallo stesso PR. - npm run check estende con npm run test:ci (modalità headless con coverage threshold).

Prerequisito: decisione framework + soglia di copertura minima accettabile.

F2 — Graph staleness enforcement ✅ (parziale, fatto)

Hook SessionStart graph-staleness.sh implementato (warning se graph.json manca o >48h). Resta opzionale: un PostToolUse su src/** che ricordi di rigenerare il grafo a fine batch (non implementato — l'orchestratore lo fa già da orchestration.md).

🟡 Successivo (P1 — qualità alta, non bloccante)

F5a — Agent a11y-review

WCAG 2.1 AA. Le rules attuali coprono solo alt/aria-label. Per un'app HR (GDPR + European Accessibility Act) serve di più: tab order, role, focus management, contrasto, screen reader compatibility.

Da fare: - .claude/agents/a11y-review.md con scope read-only su .html/.ts. - .claude/rules/accessibility.md (WCAG 2.1 AA checklist applicata al progetto). - Skill /a11y-review invocabile separatamente da /angular-review (più costosa, on-demand).

F5b — Agent perf-review

Bundle size, lazy loading verifica, OnPush coverage, @defer opportunities, preload strategies, immagini ottimizzate.

Da fare: - .claude/agents/perf-review.md con tooling integrato (source-map-explorer o webpack-bundle-analyzer). - .claude/rules/performance.md (soglie bundle per route, OnPush mandatory, lazy mandatory). - Comando npm run build:analyze per il bundle report.

F5c — Integrazione security-review built-in

La skill security-review esiste già come built-in Claude Code ma non è integrata nel workflow del progetto.

Da fare: - Documentare in orchestration.md quando invocarla obbligatoriamente (modifiche a auth.interceptor.ts, auth.guard.ts, gestione token, log di PII). - Aggiungere al gate qualità: prima di merge su main, esegui security-review.

🟢 Da sistemare (P2 — cleanup)

M1 — .claude/settings.local.json cleanup

✅ Fatto in questo round: rimosso Bash(git *) generico, separato i permessi committabili da quelli personali.

M2 — angular-developer skill non customizzata

La skill ufficiale Google va wrappata con un overlay specifico al progetto: - NO SSR (l'app è SPA, niente Angular Universal). - NO Tailwind (usa SCSS + PrimeNG). - Reactive Forms obbligatori (non Template-driven). - resource() / httpResource() / linkedSignal non in uso — solo quando viene presa una decisione esplicita.

Da fare: un file .claude/skills/angular-developer/OVERLAY.md letto in prepend dalla skill.

Symlink verificati, funzionanti e tracciati da Git (.cursor/agents -> ../.claude/agents, .cursor/skills -> ../.claude/skills). Documentati in docs/getting-started/ai-agents-and-skills.md. Script di ripristino per clone nuovi o symlink rotti: scripts/align-cursor-claude.sh.

M6 — Sintassi CLI graphify errata nelle rules ✅ (fatto)

CLAUDE.md, _agent-protocol.md, orchestration.md, lib-dev.md, e le skill generate-ai-driven-test-spec/people-feature-docs usavano graphify query "graphify-out/graph.json" "<...>" (path come argomento posizionale) e /graphify . --update: sintassi non valida per il CLI installato. Corretto in graphify query "<...>" (path di default già graphify-out/graph.json) e graphify update .. Rimossa da .claude/settings.json la voce Skill(graphify) (nessuna skill Claude Code con quel nome è mai stata installata via graphify claude install); aggiunti i permessi Bash(graphify update *), Bash(graphify path *), Bash(graphify explain *).

M4 — SCSS reference cita @use "@styles/..." che è un alias TS

Verificare che SCSS risolva @styles/.... Se non lo fa, gli esempi nelle rules styling.md vanno corretti (sostituire con path relativi o configurare un resolver SCSS).

M5 — Rollback policy nel CLAUDE.md

Già coperto in orchestration.md §rollback. Verificare durante un task reale.

Ordine di attacco proposto

  1. B4 (test-dev + testing.md) — più valore production
  2. F2 (graph staleness hooks) — abilita il resto
  3. F5a (a11y) — richiesta legale (EAA, GDPR)
  4. M2 (angular-developer overlay) — cleanup veloce
  5. F5b (perf) — dopo bundle baseline
  6. F5c (security) — prima di andare live
  7. M4 — quando capita