[FEATURE] Kiro Support

[TibRib]

Greetings,

In my org, we’re exploring Kiro (Amazon’s spec‑driven development editor) alongside GitHub Copilot and other tools. So far we've seen excellent results with the Spec-Driven approach. We are looking into APM as the solution to centralize and distribute context and instructions across tools.

Kiro relies on a specific layout for agent instructions, steering, and skills.
Supporting Kiro in APM would help establish APM as a common standard for packaging and distributing agent instructions, as more organizations are adopting the tool.

Kiro uses a specific layout for its prompts, steering, skills.
Kiro layout overview:

• Root folder: .kiro/
• Steering files (agent instructions / prompts): .kiro/steering/
  https://kiro.dev/docs/steering/
• Skills: .kiro/skills/
  https://kiro.dev/docs/skills/
• MCP configuration: .kiro/mcp.json
• Hooks: .kiro/hooks

Happy to provide examples, feedback from usage, or help with documentation if this is something you’d consider.
Thank you for your time and for maintaining APM !

[sergio-sisternes-epam]

Triage: needs-design

Thanks for this well-structured request, @TibRib! We've done an architecture analysis and Kiro is a great fit for APM's multi-target model.

Architecture assessment

APM's target system is designed for exactly this kind of extension. Each AI tool is registered as a TargetProfile in a central registry, mapping APM primitives (instructions, skills, hooks, etc.) to the tool's native layout. Adding a new target does not require new integrator classes — just a new registry entry plus any format-specific transformations.

Kiro primitive mapping (proposed)

APM Primitive	Kiro Directory	New Transformer?	Notes
Instructions	.kiro/steering/	Likely yes (kiro_steering)	Depends on whether Kiro uses path-scoped rules (like Claude's paths: or Cursor's globs:). If plain markdown, identity transform suffices
Skills	.kiro/skills/	No — reuses skill_standard	Verbatim copy, same as all other targets
Hooks	.kiro/hooks/	Minimal	Hook integrator already supports merged-JSON pattern (Claude/Cursor/Codex)
MCP	.kiro/mcp.json	Separate concern	MCP integrator handles this independently

Questions for @TibRib

To move forward with the design, we need clarity on a few points:

1. Steering file format: does Kiro use any frontmatter or path-scoping mechanism in .kiro/steering/ files, or are they plain markdown? This determines whether we need a frontmatter transformer or a simple identity copy. A sample steering file or pointer to format docs would help.
2. Kiro skills layout: does .kiro/skills/ follow the same SKILL.md + resources pattern, or does Kiro have its own skill structure (e.g. spec.md + workflow files)?
3. User-scope support: does Kiro support a user-level config directory (like ~/.claude/ or ~/.cursor/)?

@danielmeppiel, this needs more design and final sign-off from your side to accept this into the roadmap.

Related: #737 (.agents/skills install target) touches similar territory.

[TibRib]

Thanks for the thorough analysis @sergio-sisternes-epam! Here are the answers to your three questions:

1. Steering file format

Steering file format: does Kiro use any frontmatter or path-scoping mechanism in .kiro/steering/ files, or are they plain markdown? This determines whether we need a frontmatter transformer or a simple identity copy. A sample steering file or pointer to format docs would help.

Steering files are not plain markdown. They use optional YAML frontmatter (enclosed in ---) to control when the file gets loaded. There are four inclusion modes:

---
inclusion: always          # default, loaded in every interaction
---

---
inclusion: fileMatch
fileMatchPattern: "components/**/*.tsx"   # also supports arrays
---

---
inclusion: manual          # loaded on-demand via #filename in chat
---

inclusion: auto
name: api-design
description: REST API design patterns. Use when creating or modifying API endpoints.
---

So you will likely need a kiro_steering transformer that generates the appropriate frontmatter based on APM primitive metadata (for example, mapping glob/path-scoping to fileMatch, or defaulting to always).

Worth noting: Kiro also supports AGENTS.md files (always included, no frontmatter needed), placed either at the workspace root or in ~/.kiro/steering/.

Docs: https://kiro.dev/docs/steering/

2. Skills layout

Kiro skills layout: does .kiro/skills/ follow the same SKILL.md + resources pattern, or does Kiro have its own skill structure (e.g. spec.md + workflow files)?

Kiro follows the open Agent Skills standard (agentskills.io). The structure being:
Docs: https://kiro.dev/docs/skills/

my-skill/
├── SKILL.md # Required: YAML frontmatter (name, description) + markdown body
├── scripts/ # Optional executable code
├── references/ # Optional documentation
└── assets/ # Optional templates

SKILL.md frontmatter example:

---
name: pr-review
description: Review pull requests for code quality, security issues, and test coverage.
---

This matches the SKILL.md + resources pattern, so the existing skill_standard transformer should work as-is or with minimal changes.

3. User-scope support

User-scope support: does Kiro support a user-level config directory (like ~/.claude/ or ~/.cursor/)?

Yes, Kiro has a user-level config directory at ~/.kiro/. Specifically:

Concern User-level path

• Global steering ~/.kiro/steering/
• Global skills ~/.kiro/skills/
• MCP config ~/.kiro/settings/mcp.json

Workspace configs take precedence over global on conflicts, similar to how other targets handle it.
Bonus: Hooks format

Kiro hooks are individual JSON files in .kiro/hooks/, each following this schema:

{
  "name": "Lint on Save",
  "version": "1.0.0",
  "when": {
    "type": "fileEdited",
    "patterns": ["*.ts", "*.tsx"]
  },
  "then": {
    "type": "runCommand",
    "command": "npm run lint"
  }
}

Supported event types: fileEdited, fileCreated, fileDeleted, userTriggered, promptSubmit, agentStop, preToolUse, postToolUse, preTaskExecution, postTaskExecution.

Actions are either askAgent (with a prompt field) or runCommand (with a command field). The merged-JSON hook integrator you already have should map well to this.

Glad to help on this issue, let me know if there is anything (Kiro has helped for this answer as well 😃 )

[github-actions]

Triage decision

needs-design

Proposed labels

theme/portability
area/multi-target
area/mcp-config
type/feature
status/needs-design

Milestone

null

Suggested next action

Share concrete examples of Kiro's .kiro/mcp.json schema and .kiro/hooks format so the adapter design can begin; confirm whether .kiro/steering/ maps 1:1 to APM instructions or requires a transform.

Suggested issue comment

Thanks for filing this, `@TibRib`! Kiro is a great fit for APM's multi-target model -- the `.kiro/` directory structure (steering, skills, mcp.json, hooks) follows the same pattern as Cursor, Claude, and VS Code targets that APM already supports.

To unblock the implementation, we need format specs for the pieces that are not yet public or stable:

1. **`.kiro/mcp.json` schema**: Does Kiro use the same MCP JSON shape as VS Code (`.vscode/mcp.json`) or a custom variant? If you have a working example, please share it here.
2. **`.kiro/hooks` format**: Is this a single file or a directory? JSON, YAML, or shell scripts?
3. **`.kiro/steering/` vs instructions**: Do steering files map directly to APM `instructions/` primitives, or does Kiro expect a specific front-matter format?

Once we have working examples, adding the Kiro target follows an established pattern in the codebase -- the skeleton (target constant, integrators, MCP adapter) can likely be drafted in a weekend. We welcome your offer to help with documentation once the format is confirmed.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The request is to add Kiro as a new --target for apm compile / apm install, deploying to .kiro/steering/, .kiro/skills/, .kiro/mcp.json, and .kiro/hooks. This maps directly to APM's multi-target portability model and the user task: "manage agent instructions once, deploy everywhere." The framing is on-point. The author is using Kiro alongside GitHub Copilot, which is exactly the cross-tool scenario APM is built for.

Supply Chain Security Expert -- Risk-Surface Reviewer

Adding a new deploy target does not introduce new security surfaces beyond existing file-deployment controls. However, the Kiro MCP config format (kiro/mcp.json) schema is unknown -- if Kiro supports OAuth or other auth schemes beyond stdio, a new MCP adapter needs to handle credential fields safely (no logging, no embedding in files). The existing path_security.py guardrails apply. No blocking security concern; format specs are needed to assess the MCP adapter scope.

OSS Growth Hacker -- Contributor-Tone Reviewer

TibRib has author_association=NONE on microsoft/apm and explicitly offers to provide examples and help with documentation. This is the ideal new-contributor engagement pattern: motivated, specific domain knowledge (active Kiro user), willing to contribute. The reply should warmly accept the offer and give them a concrete next step (share the format examples). This thread could evolve into TibRib contributing the Kiro adapter PR itself.

Python Architect -- Architecture Reviewer

Kiro target addition follows the established BaseIntegrator pattern: new target constant in targets.py, new integrators (or extension of SkillIntegrator/AgentIntegrator for .kiro/skills/ and .kiro/steering/), new MCP adapter for .kiro/mcp.json, and target detection logic. The pattern is well-understood from Cursor, Claude, and VS Code targets. The main unknown is the exact format specs. Once confirmed, this is a medium-effort, low-risk addition. status/needs-design pending format specs.

Doc Writer -- Documentation Reviewer

A new target needs a row in the multi-target reference table, an installation guide section for Kiro, and potentially a Kiro-specific getting-started note. area/docs-site as a secondary label ensures the implementing PR includes the documentation work. The author's offer to help with documentation is valuable -- they are already using Kiro and can validate accuracy.

APM CEO -- Triage Arbiter

Strong strategic fit. Kiro is Amazon's entry into the spec-driven development editor space, and supporting it makes APM the neutral cross-editor standard -- exactly the positioning we want. The direction is clear; the design is blocked only on format specs, not on whether to do it. needs-design with a warm and specific ask for the format examples. Once those are in-hand, this likely moves to accepted quickly.

{
  "decision": "needs-design",
  "decision_detail": "Format specs for .kiro/mcp.json schema and .kiro/hooks format are needed before the adapter and integrator can be designed.",
  "theme": "theme/portability",
  "areas": ["area/multi-target", "area/mcp-config"],
  "type": "type/feature",
  "status": "status/needs-design",
  "priority": null,
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Share concrete examples of .kiro/mcp.json schema and .kiro/hooks format; confirm whether .kiro/steering/ maps 1:1 to APM instructions primitives.",
  "comment_markdown": "Thanks for filing this, `@TibRib`! Kiro is a great fit for APM's multi-target model -- the `.kiro/` directory structure (steering, skills, mcp.json, hooks) follows the same pattern as Cursor, Claude, and VS Code targets that APM already supports.\n\nTo unblock the implementation, we need format specs for the pieces that are not yet public or stable:\n\n1. **`.kiro/mcp.json` schema**: Does Kiro use the same MCP JSON shape as VS Code (`.vscode/mcp.json`) or a custom variant? If you have a working example, please share it here.\n2. **`.kiro/hooks` format**: Is this a single file or a directory? JSON, YAML, or shell scripts?\n3. **`.kiro/steering/` vs instructions**: Do steering files map directly to APM `instructions/` primitives, or does Kiro expect a specific front-matter format?\n\nOnce we have working examples, adding the Kiro target follows an established pattern in the codebase -- the skeleton (target constant, integrators, MCP adapter) can likely be drafted in a weekend. We welcome your offer to help with documentation once the format is confirmed."
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · ● 2.2M · ◷