install-maintenance-graft-rtk-ponytail-lite

Prompt

# Installazione e Manutenzione Verificata — Graft + RTK + Ponytail lite

Stai lavorando nel repository corrente per installare, aggiornare, riparare o verificare questo stack:

- Graft: comprensione del codice, grafo locale e arricchimento LSP.
- RTK: riduzione del rumore nel terminale.
- Ponytail: policy lite, con integrazione nativa quando compatibile.

Inizia con un inventario in sola lettura. Poi poni le domande mancanti qui sotto.
Dopo le risposte, esegui le operazioni autorizzate fino ai controlli finali.

Non iniziare l'installazione prima di aver determinato i client e l'ambito.
Non chiedere nuovamente una decisione già presa in questa conversazione.

## 1. Inventario, poi scelta utente

### Inventario senza modifiche

Identifica:

- OS, architettura, shell, ambiente: macchina locale, WSL, SSH, container;
- root del repository, worktree, stato Git e operazioni Git in corso;
- percorsi attuali, versioni e metodo di installazione di Git, Node, npm,
  RTK, Graft e client disponibili;
- Claude Code, Codex, Kimi, Cursor Agent CLI e Cursor IDE separatamente;
- Gemini, Copilot CLI o altri client già presenti come target opzionali;
- directory di configurazione effettivamente usate, variabili di reindirizzamento,
  e qualsiasi orchestratore come AgentsRoom;
- configurazioni esistenti di utente, progetto, plugin e hook ereditati.

Verifica l'identità di `agent` prima di considerarlo come Cursor.
Un binario presente non prova autenticazione, funzionalità degli hook,
o caricamento MCP.

Non avviare aggiornamenti automatici, connessioni o installazioni durante questo inventario.
Non pubblicare alcun valore segreto.

Presenta una tabella breve:
Client | Binario/versione | Configurazione effettiva | Stato noto.

### Domande da porre in un unico blocco

Poni solo le domande per cui manca la risposta:

1. Operazione:
   - Installa componenti mancanti e mantieni versioni compatibili.
   - Aggiorna lo stack a versioni stabili verificate.
   - Ripara l'installazione esistente mantenendo le sue versioni.
   - Verifica soltanto, senza modifiche.

2. Client:
   - Tutti i client rilevati.
   - Una selezione dalla lista effettivamente rilevata.
   - Prepara anche la configurazione per alcuni client assenti.

3. Ambito di integrazione:
   - Progetto condiviso: configurazioni portabili destinate al repository.
   - Progetto personale: attivazione per questo repository, file locali non versionati.
   - Utente globale: attivazione per i progetti di questo utente.
   - Misto: scelta distinta per client o componente.

Se l'ambito è misto, chiedi solo i chiarimenti necessari.

Per un aggiornamento, chiedi anche eventuali vincoli di versione se non già noti.
Altrimenti, proponi versioni stabili esplicite.

Non installare o aggiornare le applicazioni client stesse:
l'operazione riguarda Graft, RTK, Ponytail e le loro dipendenze necessarie.
Un client obsoleto viene segnalato con la versione richiesta e l'azione residua.

### Rendi concrete le scelte

Prima di scrivere, mostra il risultato pianificato:

Componente/client | Versione target | Ambito | File target | Effetto condiviso | Fallback

Spiega in particolare:

- Un eseguibile installato a livello utente può servire più repository.
- Aggiornare questo eseguibile influenza tutti i suoi utenti locali.
- Un plugin può avere una cache globale ma attivazione per progetto.
- Un hook per progetto può comunque usare uno stato condiviso.
- L'indice Graft rimane specifico per repository/worktree.
- Una configurazione globale fornita da un orchestratore può essere isolata
  a un progetto: verifica il suo ambito effettivo, non solo il nome.

Una volta ottenute le scelte, procedi senza conferme ripetute.
Richiedi una nuova decisione solo se una limitazione richiede
un'estensione dell'ambito o un cambiamento materiale della soluzione.

## 2. Regole di esecuzione

Ordine:
inventario → scelta → backup → RTK → Graft/LSP → Ponytail →
istruzioni → verifiche → report.

Rispetta le istruzioni del repository e le policy amministrate.
Se un file è gestito da AgentsRoom o altro orchestratore,
usa il suo meccanismo ufficiale; non modificare direttamente i file generati.

Prima di ogni modifica:

- valida il formato E la struttura delle configurazioni JSON/JSONC/TOML;
- esegui il backup dei file interessati fuori dal repository, con accesso ristretto;
- registra versioni ed elementi necessari per il rollback;
- rivedi il dry-run dell'installer quando esiste.

Un file non valido non deve mai essere sostituito da una configurazione vuota.

Unisci le configurazioni preservando altri MCP, hook, permessi,
istruzioni, commenti quando possibile e linee di stato.
Non modificare regole di approvazione o fingerprint di fiducia.

Preserva le modifiche Git preesistenti. Nessun commit, push, reset,
pulizia, stash o modifiche al codice applicativo.
In caso di conflitto irrisolto o operazione Git in corso, sospendi
le scritture nel repository; continua con diagnostica indipendente.

Non installare Graphify, CodeGraph, Caveman o Headroom.
Una vecchia integrazione in conflitto viene rimossa solo dopo identificazione precisa,
backup e nell'ambito autorizzato.
Non disinstallare globalmente uno strumento usato altrove.

Un errore blocca i passaggi dipendenti, non altri client indipendenti.
Non dichiarare un passaggio riuscito per bypassare una limitazione.

## 3. Capacità e ambito: verifica prima di configurare

Consulta l'aiuto delle versioni installate e i documenti corrispondenti
alle versioni pubblicate che userai:

- https://github.com/rtk-ai/rtk
- https://github.com/trailhq/Graft
- https://github.com/DietrichGebert/ponytail
- documentazione ufficiale di ogni client selezionato.

Il branch main/develop può descrivere funzionalità assenti in una release.
Per un'opzione dubbia, verifica la release, l'aiuto o il codice fornito.

Stabilisci per ogni integrazione:

Client | Hook di progetto disponibili | Installer compatibile |
Ambito di attivazione | Ambito di stato | Prova

Non confondere:
"il client accetta hook di progetto"
e "l'installer di questo strumento sa come installarli a livello di progetto."

Punti di controllo da riconfermare nelle versioni attuali:

- Claude: impostazioni utente, progetto condiviso e progetto locale.
- Cursor: hook utente e progetto; testare IDE e CLI separatamente.
- Codex: configurazioni utente/progetto e attivazione plugin;
  verificare i meccanismi di hook effettivamente disponibili.
- Kimi: non presumere una configurazione hook per progetto;
  distinguere configurazione utente, istruzioni di progetto e opzioni di avvio.
- Gemini/Copilot: verificare i propri meccanismi se selezionati.

Se l'installer non rispetta l'ambito richiesto:

1. Cercare un'opzione ufficiale appropriata.
2. Altrimenti, usare una configurazione manuale documentata dello stesso adapter,
   solo se il suo protocollo e i percorsi rimangono compatibili.
3. Altrimenti, usare il fallback tramite istruzioni/prefisso esplicito.
4. Mai passare silenziosamente a globale.

Ispezionare gli hook globali ereditati prima di aggiungere i loro equivalenti locali:
possono accumularsi invece di sostituirsi a vicenda.
Preservare gli hook di sicurezza. Segnalare gli effetti globali che rimangono attivi.

## 4. RTK

Controllare l'origine `rtk-ai/rtk`, la versione, l'aiuto, la configurazione
e `rtk gain`. Un fallimento di `gain` può derivare dalla base o dai permessi:
questo non è una prova sufficiente di un pacchetto difettoso.

Installare o aggiornare con il gestore già usato, se appropriato.
Controllare l'origine della formula o del pacchetto e la versione ottenuta.
Evitare installazioni concorrenti e modifiche inutili del PATH.
Non eseguire a occhi chiusi `cargo install rtk`.

Consultare `rtk init --help` per la versione scelta.
Selezionare opzioni per client e ambito; non copiare sistematicamente
`-g` da un esempio di documentazione.

Non presumere che l'integrazione Codex sia sempre una semplice istruzione,
né che abbia sempre un hook: questo dipende dalla versione di RTK.
Verificare anche le incompatibilità tra opzioni di inizializzazione.

Nella configurazione effettivamente letta, unire le esclusioni:

    [hooks]
    exclude_commands = ["graft", "curl", "playwright"]

Preservare le esclusioni esistenti e verificarne la considerazione.
Se questa impostazione è globale, indicare questo effetto prima di modificarla.
Disabilitare la telemetria opzionale con il meccanismo documentato,
all'interno dell'ambito consentito.

RTK è l'unico componente autorizzato a riscrivere comandi shell.
Rimangono applicabili gli hook di sicurezza, audit e approvazione.

Non copiare un hook Claude in un altro client senza compatibilità documentata.
Senza riscrittura effettiva, configurare il prefisso esplicito `rtk`.
Evitare hook doppi e prefissi doppi.

## 5. Graft con LSP

### Installazione e privacy

Verificare l'identità del pacchetto `@nanonets/graft`, la versione pubblicata
e i requisiti Node.

Installare fuori dalle dipendenze dell'applicazione, in una posizione adatta.
Non modificare package.json o il lockfile del progetto per installare Graft.

Applicare `DO_NOT_TRACK=1` dal primo avvio e nell'MCP.
Usare il comando ufficiale per disabilitare la telemetria se disponibile.

Non attivare Brain, account, arricchimento LLM o `--deep`.
Non promettere zero rete senza verificarlo.

Non eseguire automaticamente `graft init`.
Favorire il wiring esplicito; il suo installer può scrivere fuori dal repository.

### LSP veramente operativo

Prima di esplorare il codice dell'applicazione, rispettare le regole Graft del repository.
Quindi identificare i linguaggi utili e consultare le integrazioni LSP
della versione Graft scelta.

Riutilizzare server compatibili già presenti.
Installare solo i server necessari, con versioni registrate,
fuori dalle dipendenze dell'applicazione quando possibile.

Controllare:

- l'eseguibile e la sua versione;
- la sua disponibilità nel PATH del processo Graft/MCP;
- prerequisiti di linguaggio e workspace;
- il suo supporto da questa versione di Graft.

Dopo aver letto l'aiuto, usare in particolare, se disponibili, queste opzioni:

    graft build --lsp --no-ignore --no-gitignore
    graft check
    graft ask "Where are the main entry points and API routes, if any?" --source

Applicare DO_NOT_TRACK a questi comandi con la sintassi shell corrente.

Controllare il significato delle opzioni: in alcune versioni,
`--no-ignore` e `--no-gitignore` impediscono la scrittura di file di esclusione;
non significano "indicizzare file ignorati."

Gestire esplicitamente l'esclusione Git di `/graft/` secondo l'ambito scelto.
Verificarla con Git. Non rimuovere automaticamente file già tracciati.
Preservare annotazioni e contenuti umani.

Una build con `--lsp` e codice di uscita 0 non prova l'uso di LSP.
Cercare prove mirate: server effettivamente avviato, risultato di risoluzione,
archi arricchiti o diagnostica documentata.

Segnalare per linguaggio:
LSP verificato / disponibile senza arricchimento osservato / non disponibile / non supportato.

Mai caricare l'intero grafo o wiring.json nel contesto.
Verificare anche se l'arricchimento LSP persiste dopo un aggiornamento automatico;
se non garantito, documentare la ricostruzione esplicita necessaria.

### MCP e freschezza

Configurare una singola entry Graft efficace per client.
Scoprire il file, lo schema e l'ambito effettivamente supportati.

Per ogni server, verificare:
comando installato, argomenti MCP, DO_NOT_TRACK, PATH e directory di lavoro.

Non presumere che un file `.kimi-code/mcp.json`, `.mcp.json` o altro sia caricato automaticamente: confermare il meccanismo client o l'opzione di avvio necessaria.

Una configurazione MCP globale è accettabile solo se il processo target indirizza correttamente ogni repository. Altrimenti, mantenere l'MCP a livello di progetto.

Non usare `npx -y ...@latest` ad ogni avvio.
Non versionare percorsi personali assoluti o segreti.
Non inventare una variabile universale `${workspaceFolder}`.

In questo profilo, non aggiungere hook Graft.
Nessun smart-grep, grep-redirect o intercettazione shell Graft.

Controllare l'aggiornamento e l'assenza di disabilitazioni involontarie.
Un aggiornamento fallito vieta di presentare il grafo come fresco.

Ispezionare vecchie integrazioni e metadati di wiring automatico prima della migrazione.
Rimuovere solo elementi identificati e salvati.
Verificare che non ricompaiano dopo l'avvio e la query MCP.

### Statistiche Graft

Separare operazione, uso osservato e raccolta statistiche.

A seconda della versione, `graft stats` dipende dai session hooks.
Senza questi hook, è possibile aspettarsi il messaggio "no session recorded yet" nonostante richieste Graft riuscite.

Non fabbricare statistiche né eseguire `graft init` per far sparire questo messaggio.

Se l'utente richiede statistiche native, esponi la compatibilità degli hook di misurazione disponibili e richiedi esplicitamente l'evoluzione del profilo senza hook prima di qualsiasi attivazione.

## 6. Ponytail lite

Preferisci un'integrazione ufficiale compatibile con il client e l'ambito.
Controlla il suo manifest, eventi e dipendenze.

Distingui:
installazione del plugin, attivazione, modalità predefinita e stato della modalità corrente.

Ispeziona le fonti effettivamente lette:
configurazione, `PONYTAIL_DEFAULT_MODE`, stato persistente e dati del plugin.
`defaultMode: lite` non prova che un vecchio stato completo sia stato sostituito.

Se la modalità è condivisa tra conversazioni, indicarlo.
In ambito progetto, non cambiare silenziosamente il default globale.
Usa un meccanismo locale documentato o la policy lite tramite istruzioni.

Per client:

- Claude/Codex: installazione e attivazione ufficiale nell'ambito disponibile.
  Controlla i sottocomandi prima di usarli.
  Le approvazioni degli hook restano all'utente.
- Cursor: adapter ufficiale, o regola di istruzione; evita la loro accumulazione.
  Se esiste `scripts/cursor-hooks.js install --project`, esegui lo script
  dalla root del repository target usando il percorso di checkout ufficiale.
  Senza `--project`, controlla la destinazione utente.
  Ispeziona i percorsi generati: un hook di progetto contenente un percorso assoluto
  a un checkout personale non è portabile e non deve essere committato.
- Kimi: cerca un adapter ufficiale compatibile. Altrimenti, policy lite
  in AGENTS.md; aggiungi una skill locale minima solo se utile
  e se il suo formato e caricamento sono confermati.
  Identificalo come un adattamento, senza promettere comandi o statistiche native.
- Altri client selezionati: applica la stessa verifica, senza trasporre automaticamente
  eventi Claude/Codex.

Mantieni il checkout dell'adapter a una versione o commit identificato.
Non eseguire git pull su un checkout modificato.
Non aggiungere statusline o indicatori visivi.

Testa la modalità effettiva in una nuova sessione.

## 7. Istruzioni comuni compatte

Unisci un blocco delimitato da:

    <!-- agent-stack:start -->
    ...
    <!-- agent-stack:end -->

in AGENTS.md. Conserva tutto il contenuto esterno e le aggiunte umane.
Non copiare questo prompt di installazione nelle istruzioni dell'agente.

Il blocco deve esprimere:

### Graft

Per comprendere o modificare il codice, prima esplorazione dell'applicazione:
`graft ask "<domanda precisa>" --source`, o effettivamente lo strumento MCP Graft esposto.

Istruzioni, skill, Git, configurazioni e scoperta MCP possono precedere.
Dopo l'orientamento, leggi direttamente le porzioni utili.
Per i chiamanti, usa comandi/strumenti di tracciamento disponibili.

In caso di grafo obsoleto: verifica, ricostruzione adattata con LSP, poi nuova query.
Dopo una ricerca infruttuosa: grep mirato con graft, poi lettura diretta
o rg limitato con spiegazione del limite.

Un file fornito, uno stack trace, una configurazione o un linguaggio non indicizzato
permettono lettura mirata diretta.
L'assenza nel grafo non prova assenza di codice o chiamanti.

Dopo modifiche: graft blast, base Git verificata e test rilevanti.
Niente --name, niente caricamento completo del grafo.
Riporta il numero effettivo di chiamate e eventuali errori.

### RTK

Hook verificato: lascia agire la riscrittura senza doppio prefisso.
Altrimenti: prefissa esplicitamente comandi compatibili.
Mai passare Graft attraverso RTK.

Per output completo: richiama --full se disponibile, o proxy.
Non rieseguire automaticamente un comando con effetti collaterali.
Conserva pipeline e redirezioni.

Prima della validazione: diff reali non compressi, diff --cached,
diff --check e ispezione separata di nuovi file.
Niente staging automatico.

### Ponytail lite

Implementa correttamente la richiesta e riusa l'esistente.
Riporta brevemente una soluzione significativamente più semplice.
Conserva validazione, sicurezza, permessi, accessibilità, transazioni
e test necessari. Verifica gli usi prima di cancellare o incorporare.

Full solo su richiesta esplicita, mai ultra di default.
Un audit non innesca una riprogettazione.
La correzione ha priorità per sicurezza, parser, concorrenza e migrazioni.

Non affermare che una modalità condivisa sia locale a una conversazione.
Dopo un full autorizzato, verifica il ritorno a lite.
Off non rimuove istruzioni già iniettate.

### Caricamento

Conferma come ogni client carica effettivamente queste istruzioni.
Usa import/adapter minimi documentati.
Evita duplicazioni e import circolari.

RTK resta l'unico riscrittore shell.
Nessun hook Graft in questo profilo.

## 8. Aggiornamento e Riparazione

Lo stesso prompt deve poter essere rieseguito senza duplicati.

In modalità aggiornamento:

1. Rileggi le scelte di ambito e lo stato precedentemente verificato.
2. Confronta versioni installate, versioni target e cambiamenti incompatibili.
3. Backup prima di qualsiasi migrazione.
4. Aggiorna solo i componenti selezionati.
5. Aggiorna plugin/adapter con il loro meccanismo ufficiale.
6. Rivaluta le capacità: un vecchio fallback può essere sostituito
   da un'integrazione nativa ora disponibile, nello stesso ambito.
7. Migra solo chiavi e blocchi appartenenti a questo stack.
8. Ricostruisci il grafo se necessario e ricontrolla l'LSP.
9. Riavvia i processi MCP/client necessari:
   un processo esistente potrebbe ancora eseguire la vecchia versione.
10. Riesegui controlli e test delle integrazioni modificate.

Non reinstallare inutilmente un componente già conforme.
Non lanciare un aggiornamento generale dei pacchetti della macchina.

In modalità riparazione, mantieni le versioni tranne in caso di incompatibilità dimostrata
e decisione esplicita di aggiornamento.

Prepara un rollback mirato: versioni precedenti, backup,
e comandi esatti. Non ripristinare ciecamente un file intero
se sono avvenute altre modifiche dal suo backup.

Una seconda esecuzione senza modifiche richieste non deve creare
hook, server MCP o sezioni di istruzioni duplicate.

## 9. Controlli e Prove

Testa separatamente:

- Esecuzione RTK e compressione esplicita;
- attivazione automatica degli hook, esclusioni e passaggio diretto raw;
- Graft: freschezza, risultato corrispondente al repository e arricchimento LSP;
- MCP: server funzionale E caricamento effettivo in ogni client;
- Ponytail: attivazione e modalità effettiva;
- assenza di duplicati e auto-collegamenti riapparsi;
- validità finale delle configurazioni e ambito effettivo.

Un file presente non è prova di caricamento.
Una sonda MCP esterna non è prova di caricamento nel client.
Un prefisso RTK esplicito non è prova di hook automatico.

Per ogni client disponibile e autenticato, aprire una nuova sessione
nel repository, con le sue protezioni abituali, e fornire questo ticket neutro:

"Senza modificare il codice, localizza i punti di ingresso principali.
Se esiste un'API, indica dove sono montate le sue rotte e traccia
un percorso verso la business logic. Cita file e linee."

Non aggiungere "usa Graft".
Ispeziona le chiamate agli strumenti visibili, non il ragionamento interno.
Mantieni evidenze minime e redigi dati sensibili.

Se manca approvazione, login o azione UI:
NON TESTATO / AZIONE UTENTE, mai successo presunto.

## 10. Deliverable

Nell'ambito autorizzato, conserva una breve documentazione di manutenzione:

- scelta operativa, client e ambito;
- versioni esatte, origine e data di verifica;
- meccanismi di configurazione e limiti;
- ricostruzione Graft/LSP;
- procedura di aggiornamento, verifica e rollback.

Per un'installazione condivisa, usa `docs/agent-stack.md`.
Per un'installazione personale/globale, tieni le informazioni specifiche della macchina
fuori dai file versionati.
In modalità solo verifica, consegna il report senza creare questi file.

Riporta comandi decisivi, loro risultati, file modificati,
backup e azioni utente esatte.

Inventaria gli hook finali:
client, origine, ambito, evento, matcher, ruolo e comando redatto.

Concludi con:

Client/versione | Ambito effettivo | Configurazione presente |
MCP caricato | Graft osservato alla prima esplorazione |
LSP | RTK | Ponytail | Prova/azione residua

Usa stati espliciti:
CONFIGURATO / CARICATO / USO OSSERVATO / NON TESTATO / BLOCCATO / NON APPLICABILE.

Classifica i file:
DA COMMITTARE DOPO REVISIONE / DA IGNORARE / CONFIGURAZIONE MACCHINA.

Percorsi personali, segreti, cache, grafici, backup e trascrizioni
non devono essere inclusi nei file da committare.

Mostra lo stato finale di Git e le modifiche introdotte da questo intervento,
distinguendole da modifiche preesistenti. Non committare nulla.

Tag