lsaint/aikito

¿Qué hace aikito?

Propósito

Usa Aikito como la fuente canónica y gestionada con Git para recursos duraderos de agente y sincroniza esos recursos en los agentes de codificación y proyectos compatibles.

Modelo Mental

Mantén la fuente del CLI y el espacio de trabajo del usuario separados:

~/aikito-src   copia del repositorio del CLI
~/aikito       espacio de trabajo canónico del usuario

El espacio de trabajo contiene las fuentes de verdad:

~/aikito/
├── agents.toml
├── skills.toml
├── subagents.toml
├── mcps/
├── global/AGENTS.md
├── skills/
├── memory/
└── projects/<name>/

Los directorios de configuración de agentes y los directorios .agents/ de proyectos son puntos de entrada de ejecución, no fuentes independientes. Modifica primero los archivos canónicos del espacio de trabajo, luego sincronízalos con el CLI.

Usa AIKITO_DIR cuando el espacio de trabajo no sea ~/aikito. Usa el comando aikito instalado en lugar de asumir que el CLI reside dentro del espacio de trabajo.

Inicialización

Cuando el CLI no esté instalado, usa el repositorio fuente oficial y mantén su copia separada del futuro espacio de trabajo:

git clone https://github.com/lsaint/aikito.git "$HOME/aikito-src"
export PATH="$HOME/aikito-src/bin:$PATH"

Antes de clonar, verifica que el destino no contenga datos de usuario no relacionados. No sobrescribas una copia existente sin la instrucción del usuario.

Inicializa e inspecciona un espacio de trabajo:

aikito init workspace ~/aikito
aikito status

aikito init workspace rechaza el árbol fuente del CLI, otra copia del repositorio fuente y un directorio no vacío no reconocido. No intentes eludir estas protecciones. Después de la inicialización, inspecciona los archivos generados antes de sincronizar cualquier cosa.

Protocolo de Seguridad

• Comienza con descubrimiento de solo lectura: inspecciona los archivos canónicos relevantes, ejecuta aikito status y usa comandos de estado específicos de recursos.
• Ejecuta aikito adopt sin --apply primero. Muestra al usuario el plan de adopción, los conflictos y el manejo de credenciales antes de aplicarlo.
• Usa --dry-run para comandos de sincronización que lo soporten.
• Trata los destinos no gestionados y las instrucciones conflictivas como decisiones para el usuario. No los sobrescribas silenciosamente.
• Mantén las claves API, tokens, contraseñas y material OAuth fuera del espacio de trabajo de Aikito y de Git. Almacena referencias a variables de entorno en la configuración canónica de MCP.
• Advierte antes de cualquier operación explícita de forzado o poda y limítala al destino revisado.
• No trates un repositorio Git local como seguro para publicar. Revisa la memoria y la configuración en busca de datos privados antes de agregar un remoto o hacer push.
• Preserva los cambios no relacionados del usuario tanto en el espacio de trabajo como en la configuración del agente destino.

Enrutamiento de Recursos

Instrucciones y Habilidades Globales

Fuentes canónicas:

~/aikito/global/AGENTS.md
~/aikito/skills.toml
~/aikito/skills/<nombre-habilidad>/

Después de revisar los cambios:

aikito sync global --dry-run
aikito sync global
aikito status
aikito show skills
aikito show skill <destino>
aikito edit skill <destino>

No edites las entradas de instrucciones o habilidades nativas del agente generadas como fuentes independientes.

Al agregar, renombrar o eliminar una habilidad global, trata el cambio como una migración entre entornos de ejecución en lugar de una edición solo de directorio:

• Actualiza skills.toml, la lista blanca de exportación pública y las referencias al nombre antiguo de la habilidad.
• Verifica que cada agente compatible que cargue habilidades globales tenga el skills_path correcto en agents.toml y en la plantilla aikito init. No asumas que el CLI de un agente y su IDE usan el mismo directorio de habilidades global.
• Ejecuta las pruebas relevantes, luego ejecuta aikito sync global y aikito status.
• Inspecciona cada destino de agente gestionado y confirma que la nueva habilidad sea visible y que cualquier enlace obsoleto para el nombre antiguo haya desaparecido.
• Mantén una habilidad global fuera de los archivos agent.toml del proyecto a menos que el proyecto la sobrescriba o copie intencionadamente.

Proyectos

Un espacio de trabajo es la fuente central de verdad y normalmente existe una vez. Un registro de proyecto representa un directorio de código y sus recursos de agente específicos del proyecto. Cuando una instrucción, selección de habilidad o memoria solicitada sea específica del proyecto y el directorio de código actual no esté registrado, pregunta si el usuario quiere registrarlo. No registres un proyecto para un recurso global.

Después de la confirmación, inicializa el proyecto desde su directorio de código:

aikito init project

El nombre del directorio y la ruta actual son los valores predeterminados. Usa argumentos explícitos cuando sea necesario:

aikito init project <nombre> <ruta>

Este comando crea el esqueleto del proyecto canónico y sincroniza su entorno de ejecución .agents/. Trata los recursos de ejecución no gestionados existentes o un nombre de proyecto vinculado a otra ruta como conflictos para el usuario; no los eludas.

La configuración del proyecto pertenece a:

~/aikito/projects/<nombre>/agent.toml
~/aikito/projects/<nombre>/AGENTS.md
~/aikito/projects/<nombre>/memory/

Sincroniza y verifica con:

aikito show projects
aikito show project <nombre>
aikito sync project <nombre> --dry-run
aikito sync project <nombre>
aikito status
aikito diff
aikito show memory

Las instrucciones y la memoria del proyecto permanecen vinculadas a las fuentes canónicas. Las habilidades del proyecto siguen sync_mode: link mantiene enlaces simbólicos; copy genera copias gestionadas para el seguimiento Git del proyecto. Usa aikito status para detectar desviaciones en habilidades copiadas y aikito diff para compararlas con la habilidad canónica. La sincronización se niega a reemplazar copias desviadas; fusiona los cambios que deban persistir, o usa aikito sync project <nombre> --force solo después de revisar.

Los directorios destino .agents/skills/ y .agents/memory/ son gestionados exclusivamente por Aikito. Las entradas desconocidas son conflictos y nunca se eliminan mediante la sincronización de proyectos. No almacenes archivos no relacionados allí.

Servidores MCP

Fuente canónica:

~/aikito/mcps/*.toml

Previsualiza, aplica y verifica:

aikito sync mcp --dry-run
aikito sync mcp
aikito show mcp

Usa aikito show mcp --live solo cuando las comprobaciones en vivo del agente sean útiles. Usa aikito auth mcp <agente> <servidor> para flujos de autenticación compatibles. Nunca imprimas, persistas ni confirmes credenciales capturadas.

Subagentes

Fuentes canónicas:

~/aikito/subagents.toml
~/aikito/subagents/

Previsualiza, aplica y verifica:

aikito sync subagents --dry-run
aikito sync subagents
aikito show subagents
aikito show subagent <destino>
aikito edit subagent <destino>

Revisa los archivos gestionados huérfanos antes de usar --prune. Nunca fuerces un destino no gestionado solo para que el estado aparezca en verde.

Memoria

La memoria global pertenece a ~/aikito/memory/. La memoria específica de un proyecto pertenece a ~/aikito/projects/<nombre>/memory/.

aikito show memory [destino]
aikito edit memory <destino>

Usa la habilidad separada durable-memory para decidir cuándo el conocimiento es lo suficientemente duradero como para persistir, qué ámbito lo posee y cómo versionarlo.

Adopción

Previsualiza la configuración existente del agente antes de importarla:

aikito adopt

Solo después de que el usuario revise el plan y resuelva los conflictos de instrucciones:

aikito adopt --apply

La aplicación crea copias de seguridad con marca de tiempo en ~/.aikito/backups/adopt_<marca_tiempo>. La adopción importa recursos al espacio de trabajo; la configuración nativa del agente cambia solo durante la sincronización explícita.

Verificación y Comportamiento Actual

Después de cada escritura, ejecuta el comando de estado más específico relevante e inspecciona los destinos reportados. Usa aikito <comando> --help como la autoridad para las opciones soportadas por la versión instalada. Cuando trabajes desde una copia del repositorio fuente, consulta su README raíz y la documentación vinculada relevante para la arquitectura actual y el modelo de seguridad.