Guide de migration

Suivez ces étapes dans l'ordre pour mettre à niveau de CLI 2.x vers 3.0.

Le format des données de session a changé et les sessions existantes ne sont pas migrées automatiquement. Sauvegardez vos données de session avant la mise à niveau :

# Back up your session directory
cp -r ~/.kiro/sessions ~/.kiro/sessions-v2-backup

Après la mise à niveau, des capacités d'importation de session seront disponibles pour restaurer les sessions clés. Les sessions complexes avec un historique de résultats d'outils étendu pourraient perdre certaines sorties d'outils historiques — le déroulement de la conversation et les décisions sont préservés.

Les Hooks sont passés d'une configuration d'agent intégrée à des fichiers autonomes.

Ancien format — ne pas utiliser en 3.0 (montré à titre de référence pour la migration seulement) :

{
  "hooks": {
    "agentSpawn": [{"command": "echo 'starting'", "matcher": ".*"}],
    "preToolUse": [{"command": "npm run lint", "matcher": "Write|Edit"}],
    "fileEdited": [{"command": "prettier --write", "matcher": "\\.ts$"}]
  }
}

Nouveau format (.kiro/hooks/my-hooks.json) :

{
  "version": "v1",
  "hooks": [
    {
      "name": "lint-on-save",
      "trigger": "PostFileSave",
      "matcher": "\\.ts$",
      "action": { "type": "command", "command": "npm run lint" },
      "timeout": 30,
      "enabled": true
    },
    {
      "name": "format-on-save",
      "trigger": "PostFileSave",
      "matcher": "\\.ts$",
      "action": { "type": "command", "command": "prettier --write {{filePath}}" },
      "timeout": 10,
      "enabled": true
    }
  ]
}

Correspondance des noms de déclencheurs :

Nouveaux déclencheurs en 3.0 :

Avant de migrer manuellement, exécutez kiro-cli agent migrate — il convertit automatiquement les règles compatibles et signale ce qui nécessite une attention manuelle. Passez en revue le résultat, puis appliquez les changements restants ci-dessous.

Pour les pipelines de CI, --trust-all-tools fonctionne toujours comme substitution à l'échelle de la session. Autrement, créez ~/.kiro/settings/permissions.yaml avec capability: all, effect: allow dans votre environnement de CI.

Ancienne approche :

kiro-cli --trust-all-tools
kiro-cli --trust-tools shell,write

/tools trust write
/tools trust-all

Nouvelle approche (~/.kiro/settings/permissions.yaml pour la portée utilisateur) :

rules:
  - capability: shell
    match: ["git *", "npm *", "npx *"]
    effect: allow

  - capability: fs_write
    match: ["src/**", "tests/**"]
    effect: allow

  - capability: fs_read
    effect: allow

  - capability: mcp
    match: ["my-server/*"]
    effect: allow

Pour la référence complète — changements de comportement, définitions de portée et table de conversion des motifs — consultez Migration des permissions →.

Les profils d'agent sont rétrocompatibles — les configurations existantes continuent de fonctionner. Le harnais d'agent unifié ajoute de nouveaux champs facultatifs et une option de format Markdown.

Ancien format (.kiro/agents/my-agent.json) :

{
  "name": "backend-dev",
  "description": "Backend development agent",
  "prompt": "You are a backend developer.",
  "model": "claude-sonnet-4",
  "tools": ["fs_read", "fs_write", "execute_bash", "grep", "glob"],
  "toolsSettings": {
    "execute_bash": {
      "allowedCommands": ["^git status$", "^npm test"],
      "deniedCommands": ["^rm -rf"],
      "denyByDefault": false
    },
    "fs_read": { "allowedPaths": ["src/**"], "deniedPaths": [".env"] },
    "fs_write": { "allowedPaths": ["src/**"] }
  }
}

Nouveau format (.kiro/agents/backend-dev.json) :

{
  "name": "backend-dev",
  "description": "Backend development agent",
  "prompt": "file://resources/PROMPT.md",
  "model": "claude-sonnet-4",
  "tools": ["read", "write", "shell"],
  "permissions": {
    "rules": [
      { "capability": "shell", "match": ["git status", "git diff", "npm test*"], "effect": "allow" },
      { "capability": "shell", "match": ["rm -rf*"], "effect": "deny" },
      { "capability": "fs_read", "match": [".env", "secrets/**"], "effect": "deny" },
      { "capability": "fs_write", "match": ["*.lock"], "effect": "deny" }
    ]
  }
}

Le champ tools utilise maintenant des étiquettes (noms de catégories comme read, write, shell) au lieu d'identifiants d'outils individuels. Le bloc toolsSettings est remplacé par le tableau permissions.rules.

Migration de toolsSettings vers permissions :

Remarque : V2 allowedCommands/deniedCommands utilisait des motifs regex. V3 utilise glob — les motifs simples se traduisent directement (retirez les ancres ^/$, remplacez .* par *). Les regex complexes doivent être réécrites en plusieurs règles glob.

Nouveau format — Markdown (.kiro/agents/backend-dev.md) :

---
name: backend-dev
description: Backend development agent
model: claude-sonnet-4-20250514
tools: ["read", "write", "shell", "grep"]
excludedTools: ["knowledge"]
includeMcpJson: true
includePowers: false
mcpServers:
  postgres:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-postgres"]
    env:
      DATABASE_URL: "${DATABASE_URL}"
resources:
  - file://./ARCHITECTURE.md
  - skill://backend-patterns
permissions:
  rules:
    - capability: shell
      match: ["npm *", "node *"]
      effect: allow
welcomeMessage: "Ready to work on backend code."
---

You are a backend developer focused on Node.js and TypeScript.
Always use async/await. All database queries must be parameterized.

Référence des nouveaux champs :

Serveurs MCP dans les profils d'agent — prend en charge stdio et HTTP :

{
  "mcpServers": {
    "local": { "command": "npx", "args": ["-y", "@org/server"], "env": {} },
    "remote": { "url": "https://api.example.com/mcp", "headers": { "Authorization": "Bearer ${TOKEN}" } }
  }
}

Les variables d'environnement utilisent la syntaxe ${VAR} et sont développées à l'exécution.

L'outil intégré aws_tool a été retiré. Configurez plutôt un serveur MCP AWS. Consultez le registre des serveurs MCP pour les serveurs AWS disponibles, ou utilisez un serveur communautaire :

.kiro/settings/mcp.json :

{
  "mcpServers": {
    "aws": {
      "command": "npx",
      "args": ["-y", "@aws/aws-mcp-server"],
      "env": { "AWS_PROFILE": "${AWS_PROFILE}", "AWS_REGION": "${AWS_REGION}" }
    }
  }
}

Par exemple, @aws/aws-mcp-server est le paquet officiel. Consultez le registre MCP → pour d'autres options.

Si vous avez des hooks, permissions ou scripts qui référencent des identifiants d'outils, mettez-les à jour :

Les anciens identifiants en camelCase et les nouveaux identifiants sont tous les deux acceptés dans les profils d'agent et les permissions. Utilisez les nouveaux identifiants à l'avenir.

• Migration des permissions — conseils détaillés sur la migration des indicateurs de confiance vers permissions.yaml
• Migration des hooks — correspondance complète des déclencheurs et référence du nouveau format

kiro-cli diagnostic

Ceci vérifie : les schémas de hooks invalides, les configurations d'agent référençant des outils retirés (y compris aws_tool), et les erreurs de syntaxe du fichier de permissions. Corrigez tous les avertissements signalés avant de déployer en CI.