Add Kiro CLI render adapter for steering, skills, MCP, and custom agents

[kelos-bot]

🤖 Kelos Strategist Agent @gjkim42

Area: Integration Opportunities

Summary

Add an opt-in kiro render adapter for Kiro CLI, the successor/update path for Amazon Q Developer CLI. Kiro is a strong Kanon target because its configuration is file-backed, has both global and project scopes, and maps directly to settings Kanon already models:

• instructions.files -> Kiro steering / AGENTS.md-compatible context
• skills -> Kiro Agent Skills folders
• mcp.servers -> Kiro settings/mcp.json
• compatible hooks -> Kiro custom-agent hooks
• future permission/model/resource settings -> Kiro custom-agent fields once the shared Kanon schema exists

This should be a render-first adapter named kiro. Keep it opt-in so existing kanon.yaml files do not suddenly start writing a third agent's files.

Why this is strategically valuable

Kiro is not just another editor adapter. It covers a terminal agent with project and user scopes, custom agents, MCP, skills, steering, hooks, and headless automation. It also matters for the Amazon Q installed base: AWS docs now say the Q CLI has become the Kiro CLI, and Kiro docs describe it as the next update of Q CLI while preserving Q workflows and configuration.

That gives Kanon a migration and growth story:

1. Teams already using Amazon Q/Q CLI can centralize the settings they are moving into Kiro.
2. Teams standardizing on Kiro CLI get the same shared Kanon repo that already feeds Codex and Claude.
3. Kiro's global/project split matches Kanon's existing user vs --project rendering model.
4. Kiro's file-backed MCP and skills surfaces mean Kanon can add value without automating a UI or depending on extension storage paths.

Evidence from the current codebase

Kanon has the adapter shape but no Kiro target today:

• Config currently contains instructions, skills, mcp, hooks, and metadata; there is no Kiro-specific config or agent list (internal/core/types.go).
• The only agent constants are codex, claude, and all (internal/core/types.go).
• adaptersFor dispatches only Codex and Claude (internal/core/render.go).
• validateTargets and the CLI --agent guard only accept Codex/Claude/all (internal/core/config.go, internal/cli/root.go).
• renderSkills already copies complete SKILL.md directories into an adapter-provided target root, which is exactly what a Kiro skill renderer needs (internal/core/render.go).
• Co-owned merge strategies exist for Codex TOML and Claude JSON only; Kiro mcp.json will need a JSON map merge that updates Kanon-owned mcpServers while preserving manually configured servers (internal/core/merge.go).
• Current import supports Codex and Claude destinations only (internal/core/codex.go, internal/core/claude.go). Kiro import can wait until render behavior settles.

External signal

Official docs make the Kiro target concrete:

• AWS says “The Q CLI has become the Kiro CLI”: https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line.html
• Kiro migration docs say Kiro CLI is the next update of Q CLI, retains advanced Q CLI functionality like MCP, steering, custom agents, and hooks, and remains backwards-compatible with Q entry points/configuration: https://kiro.dev/docs/cli/migrating-from-q/
• Kiro configuration has global, project, and agent scopes. MCP servers live at ~/.kiro/settings/mcp.json and .kiro/settings/mcp.json; custom agents, steering, prompts, skills, and settings have documented paths and precedence: https://kiro.dev/docs/cli/chat/configuration/
• Kiro MCP config supports mcpServers in user/workspace settings/mcp.json, plus agent-level mcpServers and includeMcpJson: https://kiro.dev/docs/cli/mcp/
• Kiro skills use .kiro/skills/ and ~/.kiro/skills/; default agents auto-load both, while custom agents load skills through skill:// resources: https://kiro.dev/docs/cli/skills/
• Kiro steering files live in .kiro/steering/ or ~/.kiro/steering/, and Kiro also supports the AGENTS.md standard: https://kiro.dev/docs/cli/steering/
• Kiro custom agents are JSON files in .kiro/agents/ or ~/.kiro/agents/ and can configure prompt, MCP servers, tools, allowed tools, resources, hooks, model, and UI affordances: https://kiro.dev/docs/cli/custom-agents/configuration-reference/

Existing issue overlap check

I reviewed open generated-by-kelos issues and searched all issues for Kiro, Amazon Q, q developer, q cli, .amazonq, .kiro, project rules, custom agents, and mcp.json. I did not find an existing Kiro/Amazon Q render-target issue.

This is distinct from:

• Grow beyond Codex + Claude: prioritized render-adapter roadmap (Gemini CLI, Cursor, opencode, Copilot CLI) #7/Render adapters: Cursor, opencode, Copilot CLI (+ Gemini import parity) #23 adapter roadmap: covers Gemini CLI, Cursor, opencode, Copilot CLI, and Gemini import parity. It mentions Aider as a poor fit but does not cover Kiro.
• Add Goose render adapter for hints, skills, MCP extensions, and hook plugins #79 Goose, Add JetBrains Junie render adapter for guidelines, skills, MCP, and startup hooks #74 Junie, Add VS Code Copilot workspace adapter for file-backed customizations #73 VS Code Copilot, Add Cascade (Devin/Windsurf) render adapter for rules, skills, MCP, and hooks #72 Cascade/Windsurf, Add Roo Code render adapter for project rules, skills, and MCP #66 Roo Code, Add Continue render adapter for IDE and CLI rules + MCP blocks #62 Continue: separate agent/editor surfaces.
• Manage subagents (and legacy commands) as new managed-settings types — subagents first #10 subagents/commands: Kiro custom agents overlap in concept, but this issue should first render current Kanon primitives into Kiro. Full custom-agent/subagent modeling can follow the shared setting design.
• Manage model and provider defaults for agent sessions #59 model/provider defaults: Kiro custom agents support model, but this adapter should not invent model schema in v1.
• Manage context-exclusion patterns for sensitive and noisy files #69 context exclusions: Kiro ignore/exclusion behavior should be handled by the shared context-exclusions model if added later.
• Make hooks portable by rendering managed hook scripts and assets #31 portable hook scripts: Kiro hook commands may need script assets later, but v1 can render command hooks that already work from stable paths.

Proposed target and mapping

Use kiro as the canonical target:

targets: [kiro]

Recommended MVP mapping:

Kanon source	Kiro user destination	Kiro project destination	Notes
instructions.files	~/.kiro/steering/kanon.md	.kiro/steering/kanon.md or root AGENTS.md	Prefer .kiro/steering/kanon.md initially to avoid duplicate-path collisions with Codex AGENTS.md.
skills[]	~/.kiro/skills/<name>/...	.kiro/skills/<name>/...	Reuse renderSkills, but add Kiro-specific frontmatter validation for description and name format.
mcp.servers	~/.kiro/settings/mcp.json	.kiro/settings/mcp.json	Merge only Kanon-owned mcpServers entries and preserve unmanaged Kiro settings/servers.
compatible hooks[]	~/.kiro/agents/kanon.json	.kiro/agents/kanon.json	Render only when hooks are configured for kiro; users select the kanon custom agent.

Example source:

version: 1

instructions:
  files:
    - instructions/shared.md
    - instructions/aws-platform.md

skills:
  - name: pr-review
    targets: [kiro, claude, codex]
  - name: cdk-deploy
    targets: [kiro]

mcp:
  servers:
    aws-docs:
      command: uvx
      args: [awslabs.aws-documentation-mcp-server@latest]
      env:
        FASTMCP_LOG_LEVEL: ERROR
      targets: [kiro]

    github:
      type: http
      url: https://api.githubcopilot.com/mcp/
      targets: [kiro, claude]

hooks:
  - name: audit-bash
    targets: [kiro]
    event: preToolUse
    matcher: execute_bash
    type: command
    command: hooks/audit-bash.sh

Expected project render tree:

.kiro/steering/kanon.md
.kiro/settings/mcp.json
.kiro/skills/pr-review/SKILL.md
.kiro/skills/cdk-deploy/SKILL.md
.kiro/agents/kanon.json        # only if hooks/custom-agent resources are needed

Rendered Kiro MCP shape:

{
  "mcpServers": {
    "aws-docs": {
      "command": "uvx",
      "args": ["awslabs.aws-documentation-mcp-server@latest"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "disabled": false
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp"
    }
  }
}

Rendered kanon custom agent shape when hooks are present:

{
  "name": "kanon",
  "description": "Kanon-managed agent context and hooks",
  "prompt": "file://../steering/kanon.md",
  "includeMcpJson": true,
  "resources": [
    "file://../steering/**/*.md",
    "skill://../skills/*/SKILL.md"
  ],
  "hooks": {
    "preToolUse": [
      {
        "matcher": "execute_bash",
        "command": "hooks/audit-bash.sh"
      }
    ]
  }
}

Guardrails

• Keep Kiro opt-in. Do not expand current default --agent all behavior to include Kiro until the adapter opt-in semantics from Grow beyond Codex + Claude: prioritized render-adapter roadmap (Gemini CLI, Cursor, opencode, Copilot CLI) #7/Render adapters: Cursor, opencode, Copilot CLI (+ Gemini import parity) #23 are settled.
• Do not overwrite whole settings/mcp.json. Add a FileMergeKiroMCP strategy that updates only Kanon-owned mcpServers and preserves unmanaged servers and Kiro settings.
• Do not silently drop unsupported MCP fields. Map command, args, env, type: http, url, and tool_timeout_sec where compatible. Fail or warn clearly for headers, env_headers, enabled_tools, disabled_tools, OAuth fields not represented in Kanon, and mismatched timeout semantics.
• Kiro enabled: false should render disabled: true; omitted enabled renders disabled: false.
• Kiro skills require stronger frontmatter than current Kanon validation. For Kiro-targeted skills, require SKILL.md frontmatter with name and description, validate Kiro's documented name constraints, and fail with the skill name and file path.
• Do not render model defaults, keyboard shortcuts, welcome messages, tool aliases, allowed tools, or toolsSettings in v1. Those should wait for shared Kanon schema such as Add a 'native passthrough' managed-settings type to manage permissions (and other non-portable settings) without a lossy neutral schema #18, Manage model and provider defaults for agent sessions #59, Add setting-level ownership and review metadata for governed agent config #76, or a future custom-agent/native block.
• For hooks, accept only Kiro-supported trigger names (agentSpawn, userPromptSubmit, preToolUse, postToolUse, stop) and only simple command hooks. Fail on unsupported async, unsupported event names, or hook argument semantics Kanon cannot faithfully translate.
• Avoid duplicate instruction output when Codex and Kiro are both enabled for a project. In v1, .kiro/steering/kanon.md is safer than also writing root AGENTS.md for Kiro.
• Defer import until render/merge behavior is stable. Kiro has multiple scopes and custom-agent files, so import should be a separate pass.

Suggested MVP scope

1. Add AgentKiro and target validation for kiro, gated by adapter opt-in/default behavior.
2. Implement kiroAdapter.Render for steering, skills, and settings/mcp.json.
3. Add FileMergeKiroMCP for co-owned JSON mcpServers preservation.
4. Add Kiro-specific skill frontmatter validation for Kiro-targeted skills.
5. Add custom-agent kanon.json rendering only for supported Kiro hooks, or defer hooks to a second PR if the custom-agent surface needs more design.
6. Add tests for user/project paths, MCP merge preservation, unsupported MCP fields, skill validation, hook event mapping, target filtering, and explicit --agent kiro behavior.
7. Run make verify.

Use cases unlocked

• Amazon Q to Kiro migration: teams can keep one Kanon source while developers transition from Q CLI to Kiro CLI.
• AWS-heavy platform teams: shared steering, AWS documentation MCP, CDK deployment skills, and safe Kiro hooks can be rolled out across laptops and project repos.
• Terminal-agent standardization: Kiro CLI users get the same managed instructions, skills, MCP servers, and hooks as Codex/Claude users.
• Project-scoped team context: repositories can carry .kiro/ steering, skills, and MCP config generated from the same Kanon source used for AGENTS.md and CLAUDE.md.
• Headless automation: Kiro CLI's automation story can consume a deterministic Kanon-rendered project/user config before non-interactive agent runs.

Backward compatibility

• Existing kanon.yaml files are unchanged.
• Kiro is opt-in and should not affect current Codex/Claude output.
• Existing Codex/Claude render and import behavior remains unchanged.
• Existing Kiro settings/mcp.json files keep unmanaged server entries.
• Import support is deferred, so existing Kiro files are not normalized in the first increment.

Non-goals

• Do not implement Amazon Q legacy .amazonq rendering in this issue unless Kiro compatibility testing proves it is still necessary.
• Do not manage Kiro model/provider defaults in v1; keep that with the shared model-defaults work.
• Do not manage Kiro knowledge bases, prompts, code-intelligence settings, or session settings in v1.
• Do not build a full neutral custom-agent schema here; render only the parts needed by current Kanon primitives.
• Do not add import parity in the first pass.

[kelos-bot]

🤖 Kelos Task Status

Task kanon-triage-issues-9ca2aede4109 has succeeded. ✅

[kelos-bot]

🤖 Kelos Agent @gjkim42

Kanon Triage Report

Kind: kind/api
Priority: priority/important-longterm — Valuable new adapter and migration path, but not urgent and depends on target/opt-in API design.
Actor: actor/human — This adds a new user-facing kiro target for kanon.yaml and --agent, so maintainer review is required before implementation.

Status: STILL VALID

Evidence:

• No merged PRs referencing Add Kiro CLI render adapter for steering, skills, MCP, and custom agents #91 were found by gh pr list --state merged --search "91", and recent git history has no Add Kiro CLI render adapter for steering, skills, MCP, and custom agents #91 or Kiro adapter commits.
• Current code still defines only codex, claude, and all agents in internal/core/types.go:5-8, with no Kiro config field in Config at internal/core/types.go:11-18.
• Rendering still dispatches only Codex and Claude in internal/core/render.go:57-65; there is no kiroAdapter.
• Target validation still rejects anything other than all, codex, or claude in internal/core/config.go:284-289, and the CLI --agent guard does the same in internal/cli/root.go:557-559.
• Merge support currently covers Codex TOML and Claude JSON only in internal/core/merge.go:12-24; no Kiro settings/mcp.json merge strategy exists.
• External target signal is still current: AWS docs say the Q CLI has become Kiro CLI (https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line.html), and Kiro docs describe .kiro config scopes, skills, MCP, hooks, and custom-agent files (for example https://kiro.dev/docs/cli/chat/configuration/ and https://kiro.dev/docs/cli/skills/).
• Related open issues Grow beyond Codex + Claude: prioritized render-adapter roadmap (Gemini CLI, Cursor, opencode, Copilot CLI) #7 and Manage subagents (and legacy commands) as new managed-settings types — subagents first #10 are not duplicates: Grow beyond Codex + Claude: prioritized render-adapter roadmap (Gemini CLI, Cursor, opencode, Copilot CLI) #7 is a broader adapter roadmap that does not include Kiro, and Manage subagents (and legacy commands) as new managed-settings types — subagents first #10 concerns managed subagents/commands rather than a Kiro render adapter.

Duplicates found: None found

Recommendation: KEEP OPEN