People — modus operandi agent-based

Documento agent-first. Pubblico: coding agent (Cursor o Claude Code) che sta per eseguire un task su People. Questo file è il manuale operativo: chi fa cosa, in che ordine, quale file aprire, cosa è vietato. Le convenzioni di codice non sono qui. Vivono in .claude/rules/ di ciascun repository. Non copiarle in un prompt, in una skill o in questo documento: linkale. Non riaprire le decisioni della sezione «Vincoli bloccati».

0. Istruzioni per l'agente — leggi prima di agire

Chi sei, in questo momento

Se…	Allora sei	Cosa fai
Stai ricevendo la richiesta dell'utente e devi coordinare	Orchestratore	Analizzi, instradi, rifiuti Output Contract illegali, lanci review e gate. Non implementi un layer che ha un agent
Ti hanno spawnato con uno dei nomi in §7	Agent di layer	Carichi `_agent-protocol.md` + `code-quality.md` + le rules del tipo di file. Termini solo con `=== AGENT OUTPUT ===`
Il task è un processo (review, nuovo endpoint, doc MkDocs, playbook Playwright)	Esecutore di skill	Apri il `SKILL.md` e lo segui alla lettera. Non inventare un processo parallelo

Se non sei sicuro: sei l'orchestratore. Non scrivere codice di un layer finché non hai verificato che nessun agent lo possiede.

Cosa non è questo file

Non è CLAUDE.md / AGENTS.md (architettura prodotto).
Non è .claude/rules/ (come si scrive il codice).
Non è un playbook Playwright (reports/*.md).

Primo turno (obbligatorio)

Repo. FE (people-fe-v2), BE (people-be-v2), o entrambi. Un task API+UI = due orchestrazioni, non un agent che attraversa il confine.
Carica solo orchestration.md + _agent-protocol.md + code-quality.md di quel repo. Il resto on-demand (tabella in _agent-protocol.md).
Orienta. Cursor (entrambi i repo) e Claude sul FE: graphify query "<simbolo o concetto>" prima di Read/Grep/Glob. Claude agent sul BE: AGENTS.md §Architecture + Grep mirato — non un grafo (vedi §11).
Instrada (§6 → §7 → §8). Path diversi → agent in parallelo, un solo messaggio. Stesso path → un solo writer. Dipendenza esplicita → sequenziale.
Raccogli l'Output Contract. Senza il blocco === AGENT OUTPUT === l'agent è fallito: rilancialo.
Review del diff vs develop: FE → agent reviewer (skill angular-review); BE → skill be-review.
Gate npm run check (sul BE: enuncia il comando, attendi approvazione, poi esegui). Poi, sul FE dopo edit src/**: graphify update ..
Riporta solo se tutto è PASS.

Come si invoca — Cursor ≠ Claude Code

Azione	In Cursor	In Claude Code
Spawn agent	tool `Task`, `subagent_type` = nome agent. Nel prompt: scope, rules da caricare, istruzione graphify, Output Contract	file in `.claude/agents/`
Eseguire una skill	Read il `SKILL.md` e seguilo subito. Non esiste `Skill()`	tool `Skill(<nome>)`. Allowlist in `.claude/settings.json`
Rules always-on	iniettate da `.cursor/rules/*.mdc` (`alwaysApply`) — non rileggerle «per sicurezza»	non iniettate; carica on-demand come da protocollo
Hook	FE: `.cursor/hooks.json`. BE: nessun hook Cursor	`.claude/settings.json` → `.claude/hooks/*.sh`
Shell sul BE	`AGENTS.md` §Ground rules: enuncia il comando, attendi approvazione, poi esegui	uguale + hook `guard-dangerous.sh`

Collisioni di nome in workspace Cursor multi-root: FE e BE hanno entrambi un agent service-dev. Lo spawn Task con subagent_type: service-dev risolve la description FE. Per il layer service BE, nel prompt indica esplicitamente people-be-v2/.claude/agents/service-dev.md e lo scope *Service.ts / src/utils/ (tranne i tre file ACL). Non chiedere a service-dev FE di toccare un handler Lambda.

1. Identità — due repository, un applicativo

People è un gestionale interno (Paradigma). Il codice vive in due repository git distinti, non in un monorepo:

Repository	Ruolo	Stack
`people-fe-v2`	Frontend	Angular 19, PrimeNG wrappato in `src/lib/`, AWS Amplify
`people-be-v2`	Backend	Node 20, Serverless Framework, AWS Lambda, MongoDB/Mongoose

Il workspace Cursor è spesso multi-root. Ogni root ha la propria configurazione agent.

Lingua delle rules:

FE: italiano
BE: inglese (AGENTS.md e .claude/rules/)

Entry point caricato in automatico:

FE → CLAUDE.md
BE → AGENTS.md (CLAUDE.md è un symlink a AGENTS.md)

2. Vincoli bloccati

Decisione	Scelta	Perché
Sorgente unica di agent e skill	File veri solo in `.claude/`	Cursor e Claude Code cercano path diversi; due copie driftano
Come Cursor vede agent/skill	Symlink `.cursor/agents` → `../.claude/agents` e `.cursor/skills` → `../.claude/skills`	Un edit, due tool
Convenzioni di codice	Solo `.claude/rules/`	Agent e skill linkano, non riformulano
Chi scrive il codice	Agent di layer, non l'orchestratore	Scope stretto + Output Contract
Design System FE (`src/lib/`)	Solo `lib-dev`, e solo dopo decisione esplicita	Un atomo nuovo impatta tutti i consumer
Comandi infra/dati sul BE	Mai eseguiti dall'agent; `guard-dangerous.sh` li blocca o chiede conferma	Deploy, migration, `seed:policies`, Mongo, AWS mutante
Endpoint BE nuovo	Skill `add-endpoint` (sequenza multi-agent)	Un agent solo dimentica `serverless.local.ts` o l'ACL
`::ng-deep` / `/deep/` / `>>>`	Vietati in ogni file FE, incluso `:host ::ng-deep`	Nessuna eccezione «per far funzionare PrimeNG»

3. Chi sei tu (ruoli)

Utente
  └─ Orchestratore (Claude / Cursor — TU, se stai leggendo questo per eseguire un task)
        ├─ legge rules di orchestrazione
        ├─ instrada agli agent / skill
        ├─ raccoglie l'Output Contract
        ├─ lancia reviewer / skill di review
        └─ gate qualità (`npm run check`) — sul BE solo dopo approvazione esplicita del comando
              │
              ├─ Agent  = scrittore specializzato su un path. Non esce dallo scope.
              ├─ Skill  = procedura (review, docs, endpoint end-to-end). Non è un owner di path.
              ├─ Rules  = convenzioni vincolanti. Caricate on-demand.
              └─ Hook   = enforcement meccanico. Non è un suggerimento.

Orchestratore: analizza, spawna, integra, rifiuta Output Contract che violano le rules, riporta. Non implementa il codice di un layer se esiste un agent per quel layer.

Agent: carica _agent-protocol.md + code-quality.md + le rules del tipo di file toccato. Termina solo con il blocco === AGENT OUTPUT ===. Senza quel blocco l'orchestratore considera l'agent fallito.

Skill: si invoca quando il task è quel processo (review, nuova API, messaggio di errore, migrazione, doc MkDocs, AC Playwright). Non sostituisce l'agent: spesso lo sequenzia.

Hook: gira da solo su eventi del tool. Non va «ricordato» a mano; va rispettato se fallisce (exit 2 / followup_message = correggi e non chiudere).

Rule: vincolante. L'agent che accomoda una richiesta che la viola sta sbagliando. Override solo con motivazione tecnica esplicita, annotata rule override: <regola>: <motivo>.

4. Layout — `.claude` sorgente, `.cursor` in parte symlink

.cursor non è un symlink dell'intera cartella .claude. È una cartella vera, con file solo-Cursor e due symlink verso .claude.

<repo>/
├── .claude/                          ← SORGENTE. Qui si modifica.
│   ├── agents/*.md                   ← subagent (file veri)
│   ├── skills/<nome>/SKILL.md        ← skill (file veri)
│   ├── rules/*.md                    ← convenzioni (single source of truth)
│   ├── hooks/*.sh                    ← script hook Claude Code
│   └── settings.json                 ← allowlist permessi + wiring hook Claude Code
│
├── .cursor/                          ← cartella vera, non un symlink globale
│   ├── agents  →  ../.claude/agents  ← SYMLINK
│   ├── skills  →  ../.claude/skills  ← SYMLINK
│   ├── rules/*.mdc                   ← solo Cursor (file veri)
│   ├── hooks.json                    ← solo Cursor (FE)
│   ├── hooks/*.sh                    ← adattamenti payload Cursor (FE; non sono i file .claude)
│   └── settings.json                 ← plugin IDE (FE)
│
├── CLAUDE.md                         ← FE: orchestrazione. BE: symlink → AGENTS.md
└── AGENTS.md                         ← solo BE: architettura + ground rules

Cosa è symlink e cosa no

Path	Natura	Chi lo edita
`.claude/agents/`, `.claude/skills/`	File veri	Sempre questi
`.cursor/agents`, `.cursor/skills`	Symlink a `.claude/…`	Mai creare copie qui
`.claude/rules/`	File veri	Unica sede delle convenzioni
`.cursor/rules/*.mdc`	File veri Cursor (`alwaysApply`)	Solo Cursor; non sostituiscono `.claude/rules/`
`.claude/hooks/` + `.claude/settings.json`	Claude Code	Eventi `PostToolUse` / `Stop` / `SessionStart` / `PreToolUse`
`.cursor/hooks.json` + `.cursor/hooks/`	Cursor FE	Stessa intenzione, payload diverso (`.file_path` vs `tool_input.file_path`)

Stato attuale dei symlink:

FE — agents e skills symlink. Ripristino: ./scripts/align-cursor-claude.sh
BE — agents e skills symlink. Ripristino: ./scripts/align-cursor-claude.sh. .cursor/ ha anche rules/graphify.mdc. Non ha hooks.json né hook Cursor.

Ricreare i symlink

Dalla root di people-fe-v2 o people-be-v2:

./scripts/align-cursor-claude.sh

Equivalente:

rm -rf .cursor/agents .cursor/skills
ln -s ../.claude/agents .cursor/agents
ln -s ../.claude/skills .cursor/skills

I symlink sono tracciati da Git come link, non come copie. Su Windows: git config core.symlinks true e/o WSL.

Regola di edit: agent o skill → solo .claude/. Se editi il path .cursor/agents/… stai comunque scrivendo il file in .claude/ (è lo stesso inode). Non creare un secondo file.

5. Ordine di caricamento (token)

Non caricare «tutto per sicurezza».

Turno	FE	BE
Sempre (orchestratore)	`CLAUDE.md`, `.claude/rules/orchestration.md`, `_agent-protocol.md`, `code-quality.md`	`AGENTS.md`, `.claude/rules/orchestration.md`, `_agent-protocol.md`, `code-quality.md`
Sempre (agent)	`_agent-protocol.md`, `code-quality.md`	uguale
On-demand	tabella in `_agent-protocol.md` (components / templates / styling / forms / services / directives / lib)	tabella in `_agent-protocol.md` (handlers / services / data / acl / errors / testing / migrations / serverless-config)
Cursor, always-on	`.cursor/rules/cursor.mdc`, `graphify.mdc`, `no-regressions-dry.mdc`	`.cursor/rules/graphify.mdc`

Indice rules: .claude/rules/README.md di quel repo. L'indice FE elenca le convenzioni di codice; _agent-protocol.md esiste e si carica sempre, anche se non è una riga «convenzione UI».

Cosa non rileggere se sei in Cursor sul FE: cursor.mdc, graphify.mdc, no-regressions-dry.mdc sono già iniettati. Apri .claude/rules/ solo per ciò che il task tocca.

6. Albero decisionale del task

Richiesta
  ├─ Tocca people-fe-v2/src/lib/** (atomo nuovo)?
  │     → STOP. Chiedi all'utente. Solo dopo: lib-dev.
  ├─ Tocca people-fe-v2/src/lib/** (atomo esistente)?
  │     → lib-dev
  ├─ Tocca src/components/** ?
  │     → component-dev
  ├─ Tocca src/pages/** o la route della pagina?
  │     → page-dev  (app.routes.ts della sola pagina: sì; non riscrivere il router)
  ├─ Tocca services / models / guards / interceptors / pipes / utils / environments?
  │     → service-dev (FE)
  ├─ Tocca solo SCSS globale / tema PrimeNG / stile senza logica TS-HTML?
  │     → style-dev
  ├─ Doc MkDocs di una funzionalità app (docs/features/, italiano)?
  │     → tech-writer → skill people-feature-docs
  ├─ Review del diff FE vs develop?
  │     → reviewer → skill angular-review
  ├─ Decisione architetturale Angular (signals, DI, routing) — non scrittura codice?
  │     → skill angular-developer (overlay in cima al SKILL.md). Poi gli agent scrivono
  ├─ Playbook Playwright / AC agent-first?
  │     → skill generate-ai-driven-test-spec  (eseguire anche: run-ai-driven-test)
  ├─ Nuovo HTTP endpoint BE?
  │     → skill add-endpoint (NON un singolo agent)
  ├─ Stringa utente / response message BE?
  │     → skill add-response-message (tre file insieme)
  ├─ Test Jest BE?
  │     → skill write-endpoint-tests  oppure agent test-dev
  ├─ Migration BE (scaffold, non run)?
  │     → skill add-migration → migration-dev. Mai eseguire run.sh
  ├─ ACL / POLICY_DEFINITIONS / permissionPolicy?
  │     → acl-dev
  ├─ Handler / router / serverless.*.ts / middleware tranne acl.ts?
  │     → endpoint-dev
  ├─ *Service.ts / src/utils/** (BE, tranne i tre file ACL) / src/config/** ?
  │     → service-dev (BE) — vedi collisioni §0
  ├─ models / typings / validationSchemas?
  │     → model-dev
  ├─ Review del diff BE vs develop?
  │     → skill be-review  (nessun agent reviewer sul BE)
  └─ Doc tecnica BE (docs/, inglese)?
        → skill be-feature-docs  (nessun agent docs sul BE)

Conflitti (orchestration.md di ciascun repo):

Stesso path, agent diversi → un solo writer; gli altri tornano un diff testuale
Path diversi → parallelo, un solo messaggio
Dipendenza esplicita (tipo Zod che l'handler importa, metodo di servizio che la pagina usa) → sequenziale

Rollback: npm run check fallisce 3 volte → stop, niente commit. FAIL di un agent non si maschera.

7. Routing — quale agent

Ogni agent FE/BE è pinnato a model: sonnet nel frontmatter. Tool: Read, Write, Edit, Glob, Grep, Bash tranne style-dev (niente Bash) e reviewer / tech-writer (hanno anche Skill).

Frontend (`people-fe-v2/.claude/agents/`)

Agent	Path	Non tocca
`component-dev`	`src/components/**`	`src/lib/`, `src/pages/`, `src/services/`
`page-dev`	`src/pages/**` + route della pagina in `app.routes.ts`	componenti, servizi, DS
`service-dev`	`src/services/`, `src/models/`, `src/guards/`, `src/interceptors/`, `src/pipes/`, `src/utils/`, `src/environments/`	UI
`style-dev`	`src/styles/**`, SCSS di stile (non logica TS/HTML)	Bash; non lanciare lint da qui
`lib-dev`	`src/lib/**`	tutto il resto; creazione atomo solo dopo decisione utente
`reviewer`	nessuno (read-only)	non scrive codice; invoca `angular-review`
`tech-writer`	`docs/**`, `mkdocs.yml`	`src/**`; invoca `people-feature-docs`

Hard ban FE: ::ng-deep / /deep/ / >>> (anche :host ::ng-deep). Output Contract che li contiene → rifiuta, rimanda all'agent (styling.md).

God node FE (toccarli impatta tutto — Breaking changes obbligatorio nell'Output Contract): Button Component, TeamsDetailComponent, TeamsService, Skeleton Component, TableUsersComponent, TableRecrutingComponent, PeopleService.getPositionLabel. Lista aggiornata in CLAUDE.md e, per i servizi, in service-dev.md.

Backend (`people-be-v2/.claude/agents/`)

Ownership: match più specifico vince (_agent-protocol.md §Ownership). Esempio: acl-dev possiede tre file dentro src/utils/ anche se service-dev possiede src/utils/ in generale.

Agent	Path	Non tocca
`endpoint-dev`	`Handler.ts`, `src/handlers/`, `src/helper/`, middlewares tranne `acl.ts`, `serverless..ts`, `src/status.ts`	`*Service.ts`, models, tests
`service-dev`	`Service.ts`, `src/utils/` (tranne i tre file ACL), `src/config/*`, client di integrazione	handlers, models, tests
`model-dev`	`src/models/`, `src/typings/`, `src/validationSchemas/`	logica, test, serverless
`acl-dev`	`src/middlewares/acl.ts`, `policyDefinitions.ts`, `permissions.ts`, `src/v1/permissionPolicy/`, `scripts/updatePermissionPolicies.ts`	altri middleware; non esegue `seed:policies`
`test-dev`	`tests/**`	`src/` (un test rosso per bug di sorgente → `Open decisions`, non lo fixa lui)
`migration-dev`	`src/migrations/**`, `migrations/`	non esegue mai `run.sh` / mongosh

Nessun agent BE possiede docs/, AGENTS.md, package.json: docs → skill be-feature-docs; config di progetto → orchestratore via Open decisions.

src/config/responseMessages.json è condiviso: chi aggiunge un messaggio lo tocca, seguendo errors.md (skill add-response-message se il task è «aggiungi/cambia stringa»).

Output Contract (obbligatorio)

Formato in _agent-protocol.md di quel repo. Campi extra:

Campo	FE	BE
`Graph update needed`	sì	no
`Commands NOT run`	no	sì (tutto ciò che richiedeva approvazione e non è stato lanciato)

Pushback se l'istruzione viola una rule: Status: FAIL, Reason: rule conflict, cita file + sezione, non procedere.

Prompt minimo per uno spawn Cursor (Task):

Nome agent e path ownership
«Carica _agent-protocol.md + code-quality.md + [rules on-demand]. Non caricare le altre.»
Istruzione graphify (FE / Cursor) oppure AGENTS.md + Grep (BE Claude)
Hard ban ::ng-deep se tocca FE UI
«Termina solo con === AGENT OUTPUT ===.»

8. Routing — quale skill

Invoca la skill quando il tipo di lavoro coincide, anche se l'utente non usa la parola chiave. In Cursor: Read SKILL.md come prima azione. In Claude Code: Skill(<nome>).

FE (`.claude/skills/`)

Skill	Quando	In allowlist Claude Code (`.claude/settings.json`)
`angular-review`	review / qualità del diff vs `develop`	sì
`angular-developer`	decisione architetturale Angular. Overlay in cima al `SKILL.md`: Angular 19, Reactive Forms, no SSR, no Tailwind, no Signal Forms. Le `.claude/rules/` vincono in caso di conflitto. Non scrive il codice al posto degli agent	sì
`people-feature-docs`	doc MkDocs di una funzionalità (`docs/`, italiano)	sì
`generate-ai-driven-test-spec`	Playbook agent-first (`reports/<kebab>.md`): checkbox Playwright + `## Reports` nello stesso file	no — in Claude Code può chiedere conferma
`run-ai-driven-test`	genera (o riusa) il playbook e lo esegue via Playwright MCP, compilando Reports nello stesso file	no — in Claude Code può chiedere conferma

reviewer e tech-writer non reimplementano la skill: la invocano. Se la skill non è invocabile → FAIL, niente processo ad-hoc.

BE (`.claude/skills/`)

Tutte in allowlist Claude Code.

Skill	Quando
`be-review`	review del diff vs `develop`
`add-endpoint`	nuovo HTTP endpoint. Sequenza: `model-dev` → `service-dev` → `endpoint-dev` → `acl-dev` → `test-dev` (più `serverless.{service}.ts` e `serverless.local.ts`)
`add-response-message`	stringa utente: tre file insieme (`responseMessages.json`, `typings/responseMessage.ts`, `responseMessageService.ts`). Una chiave JSON mancante non throw-a: l'API restituisce il path letterale
`write-endpoint-tests`	test Jest su Mongo in-memory; la skill esegue la suite prima di chiudere
`add-migration`	scaffold `src/migrations/{stage,prod}/v{N}/` + `run.sh`. Non esegue la migration
`be-feature-docs`	doc tecnica in `docs/` (inglese)

Una skill non in permissions.allow può richiedere conferma. Non aggirare con un processo inventato.

9. Rules — single source of truth

Indice e «chi lo usa»: .claude/rules/README.md.

Aggiornare una convenzione = editare quel file in rules/. Non toccare gli agent (li rileggono all'avvio). Categoria nuova → riga nell'indice + riga nella tabella di caricamento di _agent-protocol.md + mapping nella skill di review.

Tone: vincolanti, non suggerimenti.

Debito legacy: enforce-forward sul codice nuovo o toccato. Niente sweep dell'intero repo. La review guarda il diff, non il progetto.

.cursor/rules/*.mdc non sono una seconda copia delle convenzioni. Sul FE, no-regressions-dry.mdc è uno specchio esplicito di code-quality.md §No regressions / §DRY per iniezione always-on Cursor. In caso di conflitto, vince .claude/rules/.

10. Hook — enforcement meccanico

Gli hook girano anche in modalità permissiva. Non dipendere dal fatto che l'agent «si ricordi».

Significato di exit 2 (Claude Code Stop / PreToolUse): l'agente non deve chiudere il turno. Corregge e riprova. Su Cursor Stop, lo script FE emette followup_message (JSON) e exit 0; hooks.json ha loop_limit: 2.

Claude Code — FE (`.claude/settings.json`)

Evento	Matcher	Script	Comportamento
`PostToolUse`	`Edit\\|Write\\|MultiEdit`	`format-touched.sh`	prettier sul file `src/*.{ts,html,scss}` toccato. Payload: `tool_input.file_path`. Mai blocca (`exit 0`)
`Stop`	—	`check-incremental.sh`	prettier --check + eslint sui `src/` cambiati vs `develop` + working tree. Guard `stop_hook_active`. Fallimento → `exit 2`. `tsc` non gira qui
`SessionStart`	—	`graph-staleness.sh`	warning se manca `graphify-out/graph.json` o è >48h. Non blocca

Cursor — FE (`.cursor/hooks.json`)

Stessa intenzione, script adattati al payload Cursor (non symlink di .claude/hooks/):

Evento	Script	Extra
`afterFileEdit`	`.cursor/hooks/format-touched.sh`	legge `.file_path`
`stop`	`.cursor/hooks/check-incremental.sh`	`timeout: 120`, `loop_limit: 2`; JSON `followup_message` se prettier/eslint falliscono
`sessionStart`	`.cursor/hooks/graph-staleness.sh`	emette `additional_context`

Claude Code — BE (`.claude/settings.json`)

Evento	Matcher	Script	Comportamento
`PreToolUse`	`Bash`	`guard-dangerous.sh`	Hard block (`exit 2`): deploy production, `migrations/prod/`, `MONGODB_URI` di prod, `--stage prod` / `NODE_ENV=production`. Ask: deploy non-prod, `seed:policies`, mongosh, `run.sh`, AWS mutante, `MONGODB_URI` remoto non-prod
`PostToolUse`	`Edit\\|Write`	`format-touched.sh`	prettier su `src/.ts` e `tests/.ts`; secondo `--write` se il primo non è idempotente. Mai blocca
`PostToolUse`	`Bash`	`layer-version-check.sh`	dopo `deploy:layer:*` ricorda di bumpare `layerVersion` in `serverless.config.ts`. Mai blocca
`Stop`	—	`check-incremental.sh`	prettier su `src\\|tests/*/.ts`; eslint solo su `src/` (i test non sono nel config ESLint)

Il BE non ha graph-staleness in Claude Code e non ha hook Cursor. Cursor sul BE ha comunque graphify.mdc always-on.

Ground rules BE (AGENTS.md): ogni comando shell richiede approvazione esplicita per-comando, anche se l'hook non scatta. Gli agent possono lanciare da soli solo check/lint/test/build e git in sola lettura — e sul BE l'orchestratore chiede comunque prima.

11. graphify

Entrambi i repo dichiarano un knowledge graph in graphify-out/ (gitignored, da generare in locale):

graphify extract . --code-only
graphify query "<simbolo o concetto>"
graphify path "<A>" "<B>"
graphify explain "<concept>"
graphify update .

Superficie	FE	BE
`.cursor/rules/graphify.mdc`	`alwaysApply: true`	`alwaysApply: true`
Agent Claude / protocol	`_agent-protocol.md`: `graphify query` prima di leggere file	`_agent-protocol.md` §Orientation: nessun grafo per gli agent Claude — `AGENTS.md` + Grep mirato
Hook SessionStart	`graph-staleness.sh` (Claude + Cursor)	assente
`AGENTS.md` / `CLAUDE.md`	sezione graphify in `CLAUDE.md`	sezione graphify in `AGENTS.md` (il grafo esiste; gli agent Claude non lo usano)

Regola operativa in Cursor: graphify.mdc è sempre iniettato in entrambi i repo. Interroga il grafo prima di Read/Grep/Glob, e passa la stessa istruzione a ogni subagent. Se graphify-out/graph.json non esiste, procedi con Grep e proponi graphify extract . --code-only. Non bloccare il task.

Regola operativa per un agent Claude spawnato sul BE: ignora il grafo. Orienta da AGENTS.md + Grep. Non è una contraddizione da «risolvere» nel prompt: sono due runtime.

Dopo edit su src/** (FE): graphify update ..

12. Gate qualità (oltre gli hook)

Gli hook coprono il file toccato. Prima di chiudere un task di sviluppo l'orchestratore lancia il gate full:

Repo	Comando	Cosa fa
FE	`npm run check`	lint + typecheck + format:check
BE	`npm run check`	lint → typecheck → format:check (si ferma al primo fallimento)
BE	`npm run test:{module}`	per ogni modulo toccato. Due test Libemax `finishedAt` su `develop` sono fallimenti noti (`leaveRequestService.test.ts:315` e `:341`): non inseguirli, non marcare FAIL il task per quelli

Sul BE non lanciare questi comandi di tua iniziativa: enunciali, attendi approvazione, poi eseguili.

Commit: solo se l'utente lo chiede. Mai --no-verify.

13. Task che attraversano FE e BE

Esempio: nuovo endpoint + bottone in UI.

BE prima se il contratto API non esiste: skill add-endpoint (schema → service → handler → ACL → test → entrambi i file serverless).
Capability visibile in UI → acl-dev deve aggiornare POLICY_DEFINITIONS, altrimenti l'API è protetta e il bottone non compare (sembra un bug FE).
FE dopo: service-dev (endpoint in src/utils/endpoints.ts + servizio), poi component-dev / page-dev.
Review separata per repo (be-review / angular-review).
Doc: be-feature-docs (inglese, people-be-v2/docs/) e/o tech-writer → people-feature-docs (italiano, MkDocs FE).

Non chiedere a page-dev di scrivere un handler Lambda, né a endpoint-dev di toccare un componente Angular.

14. Come estendere il sistema

Agent nuovo

Crea solo .claude/agents/<nome>.md (frontmatter name, description, tools, model + body corto).
Scope con esclusioni esplicite; rules da caricare; poi «workflow: _agent-protocol.md».
Aggiorna questo documento e, sul FE, CLAUDE.md §Agent disponibili. Sul BE, riga in _agent-protocol.md §Ownership.
Non creare file sotto .cursor/agents/. Se il nome collide con un agent dell'altro repo (come service-dev), scegline uno univoco.

Skill nuova

.claude/skills/<nome>/SKILL.md con name e description (obbligatori).
Reference/script nella stessa cartella.
Se deve essere auto-permessa in Claude Code: riga Skill(<nome>) in .claude/settings.json.
Non duplicare sotto .cursor/skills/.

Rule nuova

Vedi .claude/rules/README.md §Come aggiornare. Poi aggiorna questo file solo se cambia la struttura (nuovo agent, nuovo hook, nuovo path), non se cambia una convenzione di codice.

Hook nuovi: script in .claude/hooks/, wiring in .claude/settings.json. Per Cursor FE, uno script gemello in .cursor/hooks/ + voce in hooks.json (il payload non è lo stesso).

Cambiamento a rules o agent che cambia la struttura → questo file (orchestration.md FE lo richiede). Cambiamento di architettura BE → AGENTS.md §Maintenance, non una copia della rule.

15. Non fare

Implementare tu (orchestratore) un layer che ha un agent
Copiare una rule dentro un agent, una skill o questo documento
Accettare ::ng-deep da un agent FE
Eseguire deploy / migration / seed:policies / mongosh dal BE
Usare add-endpoint come se fosse un solo agent
Creare un atomo in src/lib/ senza decisione esplicita
Leggere l'intero codebase «per contesto»: grafo (FE / Cursor) o Grep mirato (BE agent Claude)
Trattare .cursor/ come se fosse interamente un symlink di .claude/
Inventare una review o una doc se la skill non è invocabile
Chiudere il turno dopo exit 2 di uno Stop hook (o dopo un followup_message Cursor): prima si corregge
Spawnare service-dev in un workspace multi-root senza dire quale repo
Aggiornare questo file quando cambia solo una convenzione di codice (si aggiorna .claude/rules/)

16. Riferimenti (non duplicare, aprire)

Cosa	FE	BE
Architettura prodotto	`CLAUDE.md`	`AGENTS.md`
Orchestratore	`.claude/rules/orchestration.md`	`.claude/rules/orchestration.md`
Protocollo agent	`.claude/rules/_agent-protocol.md`	`.claude/rules/_agent-protocol.md`
Indice convenzioni	`.claude/rules/README.md`	`.claude/rules/README.md`
Wiring hook + permessi	`.claude/settings.json`	`.claude/settings.json`
Hook Cursor	`.cursor/hooks.json`	—
Rules always-on Cursor	`.cursor/rules/*.mdc`	`.cursor/rules/graphify.mdc`
Allineamento symlink	`scripts/align-cursor-claude.sh`	`scripts/align-cursor-claude.sh`