instalar-mantenimiento-graft-rtk-ponytail-lite

Prompt

# Instalación y Mantenimiento Verificados — Graft + RTK + Ponytail lite

Estás trabajando en el repositorio actual para instalar, actualizar, reparar o verificar esta pila:

- Graft: comprensión de código, grafo local y enriquecimiento LSP.
- RTK: reducción de ruido en terminal.
- Ponytail: política lite, con integración nativa cuando es compatible.

Comienza con un inventario de solo lectura. Luego haz las preguntas faltantes a continuación.
Después de las respuestas, realiza las operaciones autorizadas hasta las verificaciones finales.

No inicies la instalación antes de determinar los clientes y el alcance.
No vuelvas a preguntar por una decisión ya dada en esta conversación.

## 1. Inventario, luego elección del usuario

### Inventario sin modificación

Identifica:

- SO, arquitectura, shell, entorno: máquina local, WSL, SSH, contenedor;
- raíz del repositorio, worktree, estado de Git y operaciones Git en curso;
- rutas reales, versiones y método de instalación de Git, Node, npm,
  RTK, Graft y clientes disponibles;
- Claude Code, Codex, Kimi, Cursor Agent CLI y Cursor IDE por separado;
- Gemini, Copilot CLI u otros clientes ya presentes como objetivos opcionales;
- directorios de configuración realmente usados, variables de redirección,
  y cualquier orquestador como AgentsRoom;
- configuraciones existentes de usuario, proyecto, plugin y hooks heredados.

Verifica la identidad de `agent` antes de considerarlo como Cursor.
Un binario presente no prueba autenticación, funcionalidad del hook,
o carga de MCP.

No inicies actualizaciones automáticas, conexiones o instalaciones durante este inventario.
No publiques ningún valor secreto.

Presenta una tabla corta:
Cliente | Binario/versión | Configuración efectiva | Estado conocido.

### Preguntas para hacer en un solo lote

Pregunta solo las preguntas para las que falta respuesta:

1. Operación:
   - Instalar componentes faltantes y mantener versiones compatibles.
   - Actualizar la pila a versiones estables verificadas.
   - Reparar la instalación existente manteniendo sus versiones.
   - Solo verificar, sin modificar.

2. Clientes:
   - Todos los clientes detectados.
   - Una selección de la lista detectada.
   - También preparar configuración para algunos clientes ausentes.

3. Alcance de integración:
   - Proyecto compartido: configuraciones portables destinadas al repositorio.
   - Proyecto personal: activación para este repositorio, archivos locales no versionados.
   - Usuario global: activación para los proyectos de este usuario.
   - Mixto: elección distinta por cliente o componente.

Si el alcance es mixto, pregunta solo las aclaraciones necesarias.

Para una actualización, también pregunta por cualquier restricción de versión si no se conoce ya.
De lo contrario, propone versiones estables explícitas.

No instales ni actualices las aplicaciones cliente en sí:
la operación concierne a Graft, RTK, Ponytail y sus dependencias necesarias.
Un cliente desactualizado se reporta con la versión requerida y la acción pendiente.

### Hacer concretas las elecciones

Antes de escribir, muestra el resultado planeado:

Componente/cliente | Versión objetivo | Alcance | Archivos objetivo | Efecto compartido | Alternativa

Explica notablemente:

- Un ejecutable instalado a nivel de usuario puede servir a múltiples repositorios.
- Actualizar este ejecutable afecta a todos sus usuarios locales.
- Un plugin puede tener una caché global pero activación por proyecto.
- Un hook por proyecto puede usar aún un estado compartido.
- El índice de Graft sigue siendo específico del repositorio/worktree.
- Una configuración global proporcionada por un orquestador puede aislarse
  a un proyecto: verifica su alcance real, no solo su nombre.

Una vez obtenidas las elecciones, procede sin confirmaciones repetidas.
Solicita una nueva decisión solo si una limitación requiere
una extensión de alcance o un cambio material en la solución.

## 2. Reglas de ejecución

Orden:
inventario → elección → respaldos → RTK → Graft/LSP → Ponytail →
instrucciones → verificaciones → reporte.

Respeta las instrucciones del repositorio y las políticas administradas.
Si un archivo es gestionado por AgentsRoom u otro orquestador,
usa su mecanismo oficial; no modifiques directamente sus archivos generados.

Antes de cada modificación:

- valida el formato Y la estructura de configuraciones JSON/JSONC/TOML;
- respalda los archivos afectados fuera del repositorio, con acceso restringido;
- registra versiones y elementos necesarios para revertir;
- revisa la ejecución simulada del instalador cuando exista.

Un archivo inválido nunca debe ser reemplazado por una configuración vacía.

Fusiona configuraciones preservando otros MCPs, hooks, permisos,
instrucciones, comentarios cuando sea posible y líneas de estado.
No cambies reglas de aprobación ni huellas de confianza.

Preserva cambios Git preexistentes. No hacer commit, push, reset,
clean, stash ni cambios en código de aplicación.
En caso de conflicto no resuelto u operación Git en curso, suspende
escrituras en el repositorio; continúa diagnósticos independientes.

No instales Graphify, CodeGraph, Caveman ni Headroom.
Una integración antigua conflictiva se elimina solo tras identificación precisa,
respaldo y dentro del alcance autorizado.
No desinstales globalmente una herramienta usada en otro lugar.

Un error bloquea sus pasos dependientes, no otros clientes independientes.
No declares un paso exitoso para evitar una limitación.

## 3. Capacidades y alcance: verificar antes de configurar

Consulta la ayuda de las versiones instaladas y los documentos correspondientes
a las versiones publicadas que usarás:

- https://github.com/rtk-ai/rtk
- https://github.com/trailhq/Graft
- https://github.com/DietrichGebert/ponytail
- documentación oficial de cada cliente seleccionado.

La rama main/develop puede describir características ausentes en una versión.
Para una opción dudosa, verifica la versión, la ayuda o el código entregado.

Establece para cada integración:

Cliente | Hooks de proyecto disponibles | Instalador compatible |
Alcance de activación | Alcance del estado | Prueba

No confundas:
"el cliente acepta hooks de proyecto"
y "el instalador de esta herramienta sabe cómo instalarlos a nivel de proyecto."

Puntos de control para reverificar en las versiones presentes:

- Claude: configuraciones de usuario, proyecto compartido y proyecto local.
- Cursor: hooks de usuario y proyecto; probar IDE y CLI por separado.
- Codex: configuraciones de usuario/proyecto y activación de plugins;
  verificar los mecanismos de hook realmente disponibles.
- Kimi: no asumir una configuración de hook por proyecto;
  distinguir configuración de usuario, instrucciones del proyecto y opciones de lanzamiento.
- Gemini/Copilot: verificar sus propios mecanismos si están seleccionados.

Si el instalador no respeta el alcance solicitado:

1. Buscar una opción oficial apropiada.
2. De lo contrario, usar una configuración manual documentada del mismo adaptador,
   solo si su protocolo y rutas siguen siendo compatibles.
3. De lo contrario, usar un fallback mediante instrucciones/prefijo explícito.
4. Nunca cambiar silenciosamente a global.

Inspeccionar hooks globales heredados antes de añadir sus equivalentes locales:
podrían acumularse en lugar de reemplazarse mutuamente.
Preservar hooks de seguridad. Reportar efectos globales que permanezcan activos.

## 4. RTK

Verificar el origen `rtk-ai/rtk`, la versión, la ayuda, la configuración
y `rtk gain`. Un fallo en `gain` puede provenir de la base o permisos:
esto no es prueba suficiente de un paquete defectuoso.

Instalar o actualizar con el gestor ya usado, si es apropiado.
Verificar el origen de la fórmula o paquete y la versión obtenida.
Evitar instalaciones concurrentes y cambios innecesarios en PATH.
No ejecutar a ciegas `cargo install rtk`.

Consultar `rtk init --help` para la versión elegida.
Seleccionar opciones por cliente y alcance; no copiar sistemáticamente
`-g` de un ejemplo de documentación.

No asumir que la integración de Codex es siempre una instrucción simple,
ni que siempre tenga un hook: esto depende de la versión de RTK.
También verificar incompatibilidades entre opciones de inicialización.

En la configuración realmente leída, fusionar exclusiones:

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

Preservar exclusiones existentes y verificar su consideración.
Si esta configuración es global, indicar este efecto antes de modificarla.
Desactivar la telemetría opcional mediante el mecanismo documentado,
dentro del alcance permitido.

RTK es el único componente autorizado para reescribir comandos shell.
Los hooks de seguridad, auditoría y aprobación siguen siendo aplicables.

No copiar un hook de Claude a otro cliente sin compatibilidad documentada.
Sin reescritura efectiva, configurar el prefijo explícito `rtk`.
Evitar hooks dobles y prefijos dobles.

## 5. Graft con LSP

### Instalación y privacidad

Verificar la identidad del paquete `@nanonets/graft`, su versión publicada
y sus requisitos de Node.

Instalar fuera de las dependencias de la aplicación, en una ubicación adecuada.
No modificar package.json ni el lockfile del proyecto para instalar Graft.

Aplicar `DO_NOT_TRACK=1` desde el primer lanzamiento y en el MCP.
Usar el comando oficial para desactivar telemetría si está disponible.

No activar Brain, cuenta, enriquecimiento LLM ni `--deep`.
No prometer cero red sin verificarlo.

No ejecutar automáticamente `graft init`.
Favorecer el cableado explícito; su instalador puede escribir fuera del repositorio.

### LSP verdaderamente operativo

Antes de explorar el código de la aplicación, respetar las reglas de Graft del repositorio.
Luego identificar lenguajes útiles y consultar las integraciones LSP
de la versión de Graft elegida.

Reutilizar servidores compatibles ya presentes.
Instalar solo servidores necesarios, con versiones registradas,
fuera de las dependencias de la aplicación cuando sea posible.

Verificar:

- el ejecutable y su versión;
- su disponibilidad en el PATH del proceso Graft/MCP;
- prerrequisitos de lenguaje y espacio de trabajo;
- su soporte por esta versión de Graft.

Tras leer la ayuda, usar notablemente, si estas opciones están disponibles:

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

Aplicar DO_NOT_TRACK a estos comandos con la sintaxis shell actual.

Verificar el significado de las opciones: en algunas versiones,
`--no-ignore` y `--no-gitignore` evitan escribir archivos de exclusión;
no significan "indexar archivos ignorados."

Gestionar explícitamente la exclusión Git de `/graft/` según el alcance elegido.
Verificarlo con Git. No eliminar automáticamente archivos ya rastreados.
Preservar anotaciones y contenido humano.

Una compilación con `--lsp` y código de salida 0 no prueba el uso de LSP.
Buscar prueba dirigida: servidor realmente lanzado, resultado de resolución,
aristas enriquecidas o diagnósticos documentados.

Reportar por lenguaje:
LSP verificado / disponible sin enriquecimiento observado / no disponible / no soportado.

Nunca cargar el grafo completo o wiring.json en el contexto.
También verificar si el enriquecimiento LSP persiste tras una actualización automática;
si no está garantizado, documentar la reconstrucción explícita necesaria.

### MCP y frescura

Configurar una única entrada Graft efectiva por cliente.
Descubrir el archivo, esquema y alcance realmente soportados.

Para cada servidor, verificar:
comando instalado, argumentos MCP, DO_NOT_TRACK, PATH y directorio de trabajo.

No asumir que un archivo `.kimi-code/mcp.json`, `.mcp.json` u otro se carga automáticamente: confirmar el mecanismo del cliente o la opción de lanzamiento necesaria.

Una configuración MCP global es aceptable solo si el proceso objetivo aborda correctamente cada repositorio. De lo contrario, mantener el MCP a nivel de proyecto.

No usar `npx -y ...@latest` en cada inicio.
No versionar rutas personales absolutas ni secretos.
No inventar una variable universal `${workspaceFolder}`.

En este perfil, no añadir hooks Graft.
No smart-grep, grep-redirect ni interceptación shell de Graft.

Verificar la actualización y la ausencia de desactivación no intencionada.
Una actualización fallida prohíbe presentar el grafo como fresco.

Inspeccionar integraciones antiguas y metadatos de auto-cableado antes de la migración.
Solo eliminar elementos identificados y respaldados.
Verificar que no reaparezcan tras el inicio y consulta del MCP.

### Estadísticas de Graft

Separar operación, uso observado y recopilación de estadísticas.

Dependiendo de la versión, `graft stats` depende de los hooks de sesión.
Sin estos hooks, puede esperarse el mensaje "no session recorded yet" a pesar de solicitudes Graft exitosas.

No fabrique estadísticas ni ejecute `graft init` para hacer desaparecer este mensaje.

Si el usuario requiere estadísticas nativas, exponga la compatibilidad de los hooks de medición disponibles y solicite explícitamente la evolución del perfil sin hooks antes de cualquier activación.

## 6. Ponytail lite

Prefiera una integración oficial compatible con el cliente y el alcance.
Revise su manifiesto, eventos y dependencias.

Distinga:
instalación del plugin, activación, modo por defecto y estado del modo actual.

Inspeccione las fuentes realmente leídas:
configuración, `PONYTAIL_DEFAULT_MODE`, estado persistente y datos del plugin.
`defaultMode: lite` no prueba que un estado completo antiguo haya sido reemplazado.

Si el modo es compartido entre conversaciones, indíquelo.
En el alcance del proyecto, no cambie silenciosamente el valor global por defecto.
Use un mecanismo local documentado o la política lite mediante instrucciones.

Por cliente:

- Claude/Codex: instalación y activación oficial en el alcance disponible.
  Verifique los subcomandos antes de usarlos.
  Las aprobaciones de hooks permanecen con el usuario.
- Cursor: adaptador oficial o regla de instrucción; evite su acumulación.
  Si existe `scripts/cursor-hooks.js install --project`, ejecute el script
  desde la raíz del repositorio objetivo usando la ruta oficial de checkout.
  Sin `--project`, verifique el destino del usuario.
  Inspeccione las rutas generadas: un hook de proyecto que contenga una ruta absoluta
  a un checkout personal no es portable y no debe ser comprometido.
- Kimi: busque un adaptador oficial compatible. De lo contrario, política lite
  en AGENTS.md; agregue una habilidad local mínima solo si es útil
  y si se confirma su formato y carga.
  Identifíquelo como una adaptación, sin prometer comandos o estadísticas nativas.
- Otros clientes seleccionados: aplique la misma verificación, sin transponer automáticamente
  eventos de Claude/Codex.

Mantenga el checkout del adaptador en una versión o commit identificado.
No haga git pull en un checkout modificado.
No agregue barra de estado ni indicador visual.

Pruebe el modo efectivo en una sesión nueva.

## 7. Instrucciones comunes compactas

Combine un bloque delimitado por:

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

en AGENTS.md. Preserve todo el contenido externo y las adiciones humanas.
No copie este prompt de instalación en las instrucciones del agente.

El bloque debe expresar:

### Graft

Para entender o modificar el código, primero exploración de la aplicación:
`graft ask "<pregunta precisa>" --source`, o la herramienta MCP Graft realmente expuesta.

Pueden preceder instrucciones, habilidades, Git, configuraciones y descubrimiento MCP.
Después de la orientación, lea directamente las porciones útiles.
Para llamadores, use comandos/herramientas de traza disponibles.

En caso de grafo obsoleto: verifique, reconstrucción adaptada con LSP, luego nueva consulta.
Después de una búsqueda fallida: grep graft dirigido, luego lectura directa
o rg acotado con explicación del límite.

Un archivo proporcionado, un stack trace, una configuración o un lenguaje no indexado
permiten lectura dirigida directa.
La ausencia en el grafo no prueba ausencia de código o llamadores.

Después de modificaciones: graft blast, base Git verificada y pruebas relevantes.
Sin --name, sin carga completa del grafo.
Reporte el número real de llamadas y cualquier error.

### RTK

Hook verificado: deje que la reescritura actúe sin prefijo doble.
De lo contrario: prefije explícitamente comandos compatibles.
Nunca pase Graft a través de RTK.

Para salida completa: recuerde --full si está disponible, o proxy.
No vuelva a ejecutar automáticamente un comando con efectos secundarios.
Preserve pipelines y redirecciones.

Antes de la validación: diffs reales sin comprimir, diff --cached,
diff --check e inspección separada de archivos nuevos.
Sin staging automático.

### Ponytail lite

Implemente la solicitud correctamente y reutilice lo existente.
Reporte brevemente una solución significativamente más simple.
Preserve validación, seguridad, permisos, accesibilidad, transacciones
y pruebas necesarias. Verifique usos antes de eliminar o insertar en línea.

Completo solo bajo solicitud explícita, nunca ultra por defecto.
Una auditoría no desencadena un rediseño.
La corrección tiene prioridad para seguridad, parsers, concurrencia y migraciones.

No afirme que un modo compartido es local a una conversación.
Después de un full autorizado, verifique el retorno a lite.
Off no elimina instrucciones ya inyectadas.

### Carga

Confirme cómo cada cliente carga realmente estas instrucciones.
Use importaciones/adaptadores mínimos documentados.
Evite duplicaciones e importaciones circulares.

RTK sigue siendo el único reescritor de shell.
No hay hook Graft en este perfil.

## 8. Actualización y Reparación

El mismo prompt debe poder ejecutarse de nuevo sin duplicados.

En modo actualización:

1. Relea las elecciones de alcance y el estado previamente verificado.
2. Compare versiones instaladas, versiones objetivo y cambios incompatibles.
3. Haga respaldo antes de cualquier migración.
4. Actualice solo los componentes seleccionados.
5. Actualice plugins/adaptadores con su mecanismo oficial.
6. Reevalúe capacidades: un fallback antiguo puede ser reemplazado
   por una integración nativa ahora disponible, dentro del mismo alcance.
7. Migre solo claves y bloques pertenecientes a esta pila.
8. Reconstruya el grafo si es necesario y vuelva a verificar el LSP.
9. Reinicie procesos MCP/cliente necesarios:
   un proceso existente puede estar aún ejecutando la versión antigua.
10. Reproduzca verificaciones y pruebas de integraciones modificadas.

No reinstale innecesariamente un componente que ya cumple.
No lance una actualización general de los paquetes de la máquina.

En modo reparación, mantenga versiones excepto por incompatibilidad demostrada
y decisión explícita de actualización.

Prepare un rollback dirigido: versiones previas, respaldos,
y comandos exactos. No restaure ciegamente un archivo completo
si han ocurrido otros cambios desde su respaldo.

Una segunda ejecución sin cambios solicitados no debe crear
ningún hook, servidor MCP o sección de instrucciones duplicada.

## 9. Verificaciones y Evidencias

Pruebe por separado:

- Ejecución RTK y compresión explícita;
- activación automática de hooks, exclusiones y paso directo en bruto;
- Graft: frescura, resultado que coincide con el repositorio y enriquecimiento LSP;
- MCP: servidor funcional Y carga real en cada cliente;
- Ponytail: activación y modo efectivo;
- ausencia de duplicados y auto-conexión reaparecida;
- validez final de configuraciones y alcance efectivo.

Un archivo presente no es prueba de carga.
Una sonda MCP externa no es prueba de carga en el cliente.
Un prefijo RTK explícito no es prueba de hook automático.

Para cada cliente disponible y autenticado, abre una nueva sesión
en el repositorio, con sus protecciones habituales, y entrega este ticket neutral:

"Sin modificar el código, localiza los puntos de entrada principales.
Si hay una API, indica dónde se montan sus rutas y traza
un camino hacia la lógica de negocio. Cita archivos y líneas."

No añadas "usar Graft".
Inspecciona llamadas visibles a herramientas, no razonamientos internos.
Mantén evidencia mínima y redacta datos sensibles.

Si falta aprobación, inicio de sesión o acción UI:
NO PROBADO / ACCIÓN DEL USUARIO, nunca se asume éxito.

## 10. Entregable

Dentro del alcance autorizado, mantén una documentación corta de mantenimiento:

- elección de operación, clientes y alcance;
- versiones exactas, origen y fecha de verificación;
- mecanismos de configuración y límites;
- reconstrucción Graft/LSP;
- procedimiento de actualización, verificación y reversión.

Para una instalación compartida, usa `docs/agent-stack.md`.
Para una instalación personal/global, mantén la información específica de la máquina
fuera de archivos versionados.
En modo solo verificación, entrega el informe sin crear estos archivos.

Reporta comandos decisivos, sus resultados, archivos modificados,
respaldos y acciones exactas del usuario.

Inventaría los hooks finales:
cliente, origen, alcance, evento, matcher, rol y comando redactado.

Termina con:

Cliente/versión | Alcance efectivo | Configuración presente |
MCP cargado | Graft observado en la primera exploración |
LSP | RTK | Ponytail | Prueba/acción restante

Usa estados explícitos:
CONFIGURADO / CARGADO / USO OBSERVADO / NO PROBADO / BLOQUEADO / NO APLICABLE.

Clasifica archivos:
PARA COMMIT DESPUÉS DE REVISIÓN / PARA IGNORAR / CONFIGURACIÓN DE MÁQUINA.

Rutas personales, secretos, cachés, gráficos, respaldos y transcripciones
no deben incluirse en archivos para commit.

Muestra el estado final de Git y los cambios introducidos por esta intervención,
distinguíendolos de cambios preexistentes. No hagas commit de nada.

Tags