lsaint/aikito

Que fait aikito ?

Objectif

Utilisez Aikito comme source canonique, gérée par Git, pour des ressources d'agent durables, et synchronisez ces ressources dans les agents de codage et projets pris en charge.

Modèle mental

Conservez le source du CLI et l'espace de travail utilisateur séparés :

~/aikito-src   clone du source CLI
~/aikito       espace de travail utilisateur canonique

L'espace de travail contient les sources de vérité :

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

Les répertoires de configuration d'agent et les répertoires .agents/ des projets sont des points d'entrée d'exécution, pas des sources indépendantes. Modifiez d'abord les fichiers canoniques de l'espace de travail, puis synchronisez-les avec le CLI.

Utilisez AIKITO_DIR lorsque l'espace de travail n'est pas ~/aikito. Utilisez la commande aikito installée plutôt que de supposer que le CLI se trouve dans l'espace de travail.

Amorçage

Lorsque le CLI n'est pas installé, utilisez le dépôt source officiel et conservez son clone séparé du futur espace de travail :

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

Avant de cloner, vérifiez que la cible ne contient pas de données utilisateur non liées. N'écrasez pas un clone existant sans instruction de l'utilisateur.

Initialisez et inspectez un espace de travail :

aikito init workspace ~/aikito
aikito status

aikito init workspace refuse l'arborescence source du CLI, un autre clone source, et un répertoire non vide non reconnu. N'essayez pas de contourner ces gardes-fous. Après initialisation, inspectez les fichiers générés avant de synchroniser quoi que ce soit.

Protocole de sécurité

• Commencez par une découverte en lecture seule : inspectez les fichiers canoniques pertinents, exécutez aikito status, et utilisez les commandes d'état spécifiques aux ressources.
• Exécutez aikito adopt sans --apply d'abord. Montrez à l'utilisateur le plan d'adoption, les conflits et la gestion des identifiants avant de l'appliquer.
• Utilisez --dry-run pour les commandes de synchronisation qui le prennent en charge.
• Traitez les cibles non gérées et les instructions contradictoires comme des décisions pour l'utilisateur. Ne les écrasez pas silencieusement.
• Gardez les clés API, tokens, mots de passe et matériel OAuth hors de l'espace de travail Aikito et de Git. Stockez les références de variables d'environnement dans la configuration MCP canonique.
• Avertissez avant toute opération explicite de force ou d'élagage et limitez-la à la cible examinée.
• Ne traitez pas un dépôt Git local comme sûr à publier. Examinez la mémoire et la configuration pour les données privées avant d'ajouter un dépôt distant ou de pusher.
• Préservez les modifications utilisateur non liées à la fois dans l'espace de travail et dans la configuration de l'agent cible.

Routage des ressources

Instructions globales et compétences

Sources canoniques :

~/aikito/global/AGENTS.md
~/aikito/skills.toml
~/aikito/skills/<nom-compétence>/

Après avoir examiné les modifications :

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

Ne modifiez pas les entrées d'instruction ou de compétence générées par l'agent natif en tant que sources indépendantes.

Lors de l'ajout, du renommage ou de la suppression d'une compétence globale, traitez le changement comme une migration inter-environnements plutôt qu'une simple édition de répertoire :

• Mettez à jour skills.toml, la liste d'autorisation d'exportation publique et les références à l'ancien nom de compétence.
• Vérifiez que chaque agent pris en charge qui charge les compétences globales a le bon skills_path dans agents.toml et dans le modèle aikito init. Ne supposez pas qu'un agent CLI et son IDE utilisent le même répertoire de compétences globales.
• Exécutez les tests pertinents, puis exécutez aikito sync global et aikito status.
• Inspectez chaque cible d'agent gérée et confirmez que la nouvelle compétence est visible et que tout lien obsolète pour l'ancien nom a disparu.
• Gardez une compétence globale hors des fichiers agent.toml de projet, sauf si le projet la remplace ou la copie intentionnellement.

Projets

Un espace de travail est la source de vérité centrale et existe normalement une fois. Un enregistrement de projet représente un répertoire de code et ses ressources d'agent spécifiques au projet. Lorsqu'une instruction, une sélection de compétence ou une mémoire demandée est spécifique au projet et que le répertoire de code actuel n'est pas enregistré, demandez si l'utilisateur souhaite l'enregistrer. N'enregistrez pas un projet pour une ressource globale.

Après confirmation, initialisez le projet à partir de son répertoire de code :

aikito init project

Le nom du répertoire et le chemin actuel sont les valeurs par défaut. Utilisez des arguments explicites si nécessaire :

aikito init project <nom> <chemin>

Cette commande crée le squelette de projet canonique et synchronise son environnement d'exécution .agents/. Traitez les ressources d'exécution non gérées existantes ou un nom de projet lié à un autre chemin comme des conflits pour l'utilisateur ; ne les contournez pas.

La configuration du projet se trouve sous :

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

Synchronisez et vérifiez avec :

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

Les instructions et la mémoire du projet restent liées aux sources canoniques. Les compétences du projet suivent sync_mode : link conserve les liens symboliques ; copy génère des copies gérées pour le suivi Git du projet. Utilisez aikito status pour détecter la dérive des compétences copiées et aikito diff pour les comparer avec la compétence canonique. La synchronisation refuse de remplacer les copies dérivées ; fusionnez les modifications qui doivent survivre, ou utilisez aikito sync project <nom> --force seulement après examen.

Les répertoires .agents/skills/ et .agents/memory/ de la cible sont exclusivement gérés par Aikito. Les entrées inconnues sont des conflits et ne sont jamais supprimées par la synchronisation de projet. N'y stockez pas de fichiers non liés.

Serveurs MCP

Source canonique :

~/aikito/mcps/*.toml

Prévisualisez, appliquez et vérifiez :

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

Utilisez aikito show mcp --live uniquement lorsque les vérifications en direct de l'agent sont utiles. Utilisez aikito auth mcp <agent> <serveur> pour les flux d'authentification pris en charge. N'imprimez, ne persistez et ne commettez jamais les identifiants capturés.

Sous-agents

Sources canoniques :

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

Prévisualisez, appliquez et vérifiez :

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

Examinez les fichiers gérés orphelins avant d'utiliser --prune. Ne forcez jamais une cible non gérée simplement pour rendre le statut vert.

Mémoire

La mémoire globale se trouve sous ~/aikito/memory/. La mémoire spécifique au projet se trouve sous ~/aikito/projects/<nom>/memory/.

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

Utilisez la compétence séparée durable-memory pour décider quand la connaissance est suffisamment durable pour être persistée, quelle portée la possède et comment la versionner.

Adoption

Prévisualisez la configuration d'agent existante avant de l'importer :

aikito adopt

Seulement après que l'utilisateur a examiné le plan et résolu les conflits d'instructions :

aikito adopt --apply

L'application crée des sauvegardes horodatées sous ~/.aikito/backups/adopt_<horodatage>. L'adoption importe les ressources dans l'espace de travail ; la configuration native de l'agent ne change que lors d'une synchronisation explicite.

Vérification et comportement actuel

Après chaque écriture, exécutez la commande d'état la plus étroite pertinente et inspectez les cibles signalées. Utilisez aikito <commande> --help comme autorité pour les options prises en charge par la version installée. Lorsque vous travaillez à partir d'un clone source, consultez son README racine et la documentation liée pertinente pour l'architecture et le modèle de sécurité actuels.