feat(targets): add Kiro IDE support#1741
Conversation
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Adds Kiro IDE as a first-class APM target across the target registry, instruction (steering) transforms, hook integration, MCP adapter + runtime detection, plus tests and documentation updates to reflect the .kiro/ layout.
Changes:
- Register
target: kiroand wire detection/validation paths so.kiro/is discoverable and selectable. - Implement Kiro-specific integrations: instruction -> steering transform (
kiro_steering), hook expansion to one JSON per action, and MCP config adapter for.kiro/settings/mcp.json/~/.kiro/settings/mcp.jsonwith${VAR}preservation. - Add unit/integration tests and broaden docs/guide references + changelog to include Kiro.
Show a summary per file
| File | Description |
|---|---|
| tests/unit/test_kiro_mcp.py | New unit tests for Kiro MCP adapter behavior (paths, placeholder preservation, stale cleanup). |
| tests/unit/integration/test_targets_registry_completeness.py | Ensures Kiro adapter is included in registry completeness assertions. |
| tests/unit/integration/test_kiro_target.py | New integration-style unit tests for Kiro target profile, steering transform, and hook expansion behavior. |
| tests/unit/integration/test_data_driven_dispatch.py | Adds instructions_kiro bucket to dispatch/partition parity coverage. |
| tests/unit/core/test_target_resolution_v2.py | Adds .kiro/ as a filesystem signal for target resolution. |
| tests/unit/core/test_target_detection.py | Adds explicit + auto-detect test coverage for --target kiro and .kiro/ detection. |
| tests/unit/core/test_scope.py | Adds kiro to known targets and asserts user-scope support metadata. |
| src/apm_cli/policy/policy_checks.py | Includes .kiro in policy script-scan directory list. |
| src/apm_cli/integration/targets.py | Adds kiro TargetProfile + adds kiro_steering to the transforming rule-format set. |
| src/apm_cli/integration/mcp_integrator.py | Adds Kiro stale MCP cleanup, runtime detection from scripts, and updates supported runtime messaging. |
| src/apm_cli/integration/mcp_integrator_install.py | Adds Kiro runtime discovery (including user-scope behavior) and threads user_scope into runtime discovery. |
| src/apm_cli/integration/kiro_hook_integrator.py | New module implementing Kiro hook expansion (one-file-per-action) and script copying. |
| src/apm_cli/integration/instruction_integrator.py | Adds kiro_steering converter and avoids broad legacy-delete behavior for .kiro/steering/. |
| src/apm_cli/integration/hook_integrator.py | Adds Kiro hook event mapping + routes kiro to the new Kiro hook integrator; updates script rewrite rules. |
| src/apm_cli/factory.py | Registers kiro client adapter in ClientFactory. |
| src/apm_cli/core/target_detection.py | Adds kiro throughout explicit/config/auto-detect + canonical target sets and descriptions. |
| src/apm_cli/core/apm_yml.py | Allows kiro as a valid manifest target. |
| src/apm_cli/compilation/agents_compiler.py | Includes kiro in agent compilation target set. |
| src/apm_cli/adapters/client/kiro.py | New Kiro MCP client adapter implementing project/user-scope config writes and placeholder-preserving formatting. |
| packages/apm-guide/.apm/skills/apm-usage/package-authoring.md | Documents Kiro-specific hook filename suffix handling and target lists. |
| packages/apm-guide/.apm/skills/apm-usage/dependencies.md | Documents ${VAR} placeholder handling for Kiro MCP. |
| packages/apm-guide/.apm/skills/apm-usage/commands.md | Updates CLI reference text to mention kiro target and global MCP behavior. |
| docs/src/content/docs/troubleshooting/compile-zero-output-warning.md | Adds .kiro/ as a canonical signal in troubleshooting guidance. |
| docs/src/content/docs/reference/targets-matrix.md | Adds Kiro to matrix + documents Kiro target details and conventions. |
| docs/src/content/docs/reference/manifest-schema.md | Adds kiro to allowed targets and documents MCP placeholder behavior including Kiro. |
| docs/src/content/docs/reference/cli/update.md | Adds kiro to apm update --target documentation. |
| docs/src/content/docs/reference/cli/uninstall.md | Adds .kiro/ to uninstall scope description. |
| docs/src/content/docs/reference/cli/targets.md | Adds Kiro to apm targets output examples and detection table. |
| docs/src/content/docs/reference/cli/install.md | Adds kiro to install target list and global MCP runtime description. |
| docs/src/content/docs/reference/cli/init.md | Adds kiro to apm init --target valid values. |
| docs/src/content/docs/reference/cli/deps.md | Adds kiro to apm deps update --target valid values. |
| docs/src/content/docs/reference/cli/compile.md | Adds kiro to compile docs and target lists. |
| docs/src/content/docs/producer/compile.md | Updates producer docs to include Kiro in compile reach and output mapping. |
| docs/src/content/docs/producer/author-primitives/skills.md | Documents .kiro/skills/<name>/SKILL.md as a target-native skill path. |
| docs/src/content/docs/producer/author-primitives/instructions-and-agents.md | Documents Kiro instruction/steering transform behavior and limitations. |
| docs/src/content/docs/producer/author-primitives/hooks-and-commands.md | Documents Kiro hook token + output location (needs a small filename-pattern fix). |
| docs/src/content/docs/integrations/ide-tool-integration.md | Adds Kiro to IDE integration guide and describes .kiro/ deployment surfaces. |
| docs/src/content/docs/getting-started/first-package.md | Adds .kiro/ to target auto-detection examples. |
| docs/src/content/docs/enterprise/security.md | Adds .kiro/ to allowed deploy-prefix documentation. |
| docs/src/content/docs/enterprise/policy-reference.md | Adds kiro to policy target allowlist docs. |
| docs/src/content/docs/consumer/run-scripts.md | Adds kiro to example runtime CLIs referenced in scripts. |
| docs/src/content/docs/consumer/install-packages.md | Adds .kiro/ to install integration directory list and idempotency note. |
| docs/src/content/docs/consumer/install-mcp-servers.md | Documents Kiro MCP config locations and -g routing behavior. |
| docs/src/content/docs/concepts/what-is-apm.md | Adds .kiro/ to the “compiled output lives in…” harness list. |
| docs/src/content/docs/concepts/primitives-and-targets.md | Adds Kiro to target list + expands compatibility matrix to include Kiro column. |
| docs/src/content/docs/concepts/lifecycle.md | Adds .kiro/ to lifecycle auto-detect signals list. |
| docs/src/content/docs/concepts/glossary.md | Adds kiro to glossary description of targets. |
| CHANGELOG.md | Adds an Unreleased entry for Kiro target support (needs PR-number formatting update). |
Copilot's findings
- Files reviewed: 48/48 changed files
- Comments generated: 2
| | gemini | `.gemini/settings.json` | merged | | ||
| | codex | `.codex/hooks.json` | merged | | ||
| | windsurf | `.windsurf/hooks.json` | merged | | ||
| | kiro | `.kiro/hooks/<pkg>-<event>.json` | one file per hook | |
| - Kiro IDE is now a first-class install target: APM deploys steering, skills, | ||
| hooks, and MCP config to the documented `.kiro/` layout. (closes #702) |
Folds copilot-pull-request-reviewer follow-ups: correct Kiro hook filename pattern in docs, changelog PR number. Refs #702 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
APM Review Panel:
|
| Persona | B | R | N | Takeaway |
|---|---|---|---|---|
| Python Architect | 0 | 0 | 1 | Registry + transform pattern followed exactly; hook helper correctly extracted to respect the file-length guard. |
| CLI Logging Expert | 0 | 0 | 1 | ASCII status symbols and _rich_* helpers used consistently; one broad-except swallows root cause to debug-only. |
| DevX UX Expert | 0 | 0 | 0 | Target selection/detection wired end to end; project-scope opt-in gate avoids clobbering non-Kiro workspaces. |
| Supply Chain Security | 0 | 0 | 0 | Path containment on every write, 0o600 config, ${VAR} never materialized -- negative secret-leak assertions present. |
| OSS Growth Hacker | 0 | 0 | 0 | New IDE target + community credit (@TibRib) is a clean adoption + contributor signal. |
| Test Coverage Expert | 0 | 0 | 1 | Profile/steering/hooks/MCP/scope/stale all covered with evidence; minor gaps on perms + omission paths. |
| Auth Expert | 0 | 0 | 0 | MCP header/env ${VAR} path confirmed to carry no materialized token into written config. |
| Doc Writer | 0 | 0 | 0 | Target row, compatibility matrix, and dedicated guide section all present and accurate. |
B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.
Top follow-ups
- [Test Coverage Expert] Add an assertion that
.kiro/settings/mcp.jsonis written0o600and thatautoApprove/disabledToolsare omitted when the registry omits them -- locks the secure-perms and carry-only-if-present contracts so a future refactor cannot silently regress them. - [Python Architect] Consider a thin protocol or documented seam for the
kiro_hook_integrator->HookIntegratorprivate-method reach-ins (_rewrite_hooks_data,_get_package_name,check_collision) -- keeps the extracted module's coupling intentional rather than incidental. - [CLI Logging Expert]
configure_mcp_server's broadexcept Exceptionlogs the cause only at debug while surfacing a generic error -- fine for now, but averbose-tier hint would speed Kiro MCP triage.
Architecture
classDiagram
class TargetProfile {
+name
+root_dir
+primitives
+user_supported
+compile_family
}
class PrimitiveMapping {
+subdir
+extension
+format_id
+output_compare
}
class CopilotClientAdapter
class KiroClientAdapter {
+supports_user_scope
+mcp_servers_key
+get_config_path()
+update_config()
+_format_server_config()
}
class InstructionIntegrator {
+_convert_to_kiro_steering()
}
class KiroHookIntegrator {
+integrate_kiro_hooks()
}
TargetProfile o-- PrimitiveMapping
CopilotClientAdapter <|-- KiroClientAdapter
TargetProfile ..> InstructionIntegrator
TargetProfile ..> KiroHookIntegrator
class KiroClientAdapter:::new
class KiroHookIntegrator:::new
flowchart TD
M[apm.yml target kiro] --> R[TargetProfile kiro]
R --> S[kiro_steering transform]
R --> K[skills copy skill_standard]
R --> H[kiro hook expansion]
D[mcp deps] --> C[KiroClientAdapter]
S --> O1[.kiro/steering/*.md]
K --> O2[.kiro/skills/name/SKILL.md]
H --> O3[.kiro/hooks/*.json]
C --> O4[.kiro/settings/mcp.json + ~/.kiro/settings/mcp.json]
Recommendation
Ship now. CI is green, the board-approved scope is fully delivered, and the panel found no blocking or recommended-severity issues -- only three minor polish nits, none of which gate merge. The highest-signal follow-up to track post-merge is the test-coverage hardening (assert 0o600 perms + field-omission), which can land as a fast follow. The human maintainer performs the protected-branch merge.
Full per-persona findings
Python Architect
- [nit] Module-level functions in
kiro_hook_integrator.pyreach intoHookIntegratorprivates (_rewrite_hooks_data,_get_package_name,check_collision,try_adopt_identical) by receivingintegratoras a positional arg atsrc/apm_cli/integration/kiro_hook_integrator.py.
This matches the established integrator pattern and was a deliberate extraction to stay under the source-length guard, so it is acceptable; documenting the seam (or a small protocol) would make the coupling intentional rather than incidental. TheTargetProfile/PrimitiveMappingregistry entry and thekiro_steeringaddition toRULE_FORMATSare exactly on-pattern.
CLI Logging Expert
- [nit]
configure_mcp_serverwraps the body inexcept Exceptionand emits a generic_rich_error, logging the actual cause only atlogger.debugatsrc/apm_cli/adapters/client/kiro.py.
Consistent with the Copilot adapter it subclasses, and ASCII status symbols /_rich_success/_rich_errorare used correctly throughout. A verbose-tier cause hint would speed triage but is not required.
DevX UX Expert
No findings. Target selection is wired through explicit --target kiro, the apm.yml targets: field, and .kiro/ auto-detection, with a clear get_target_description string. Project-scope writes are gated on an existing .kiro/ directory, so APM never creates Kiro output in a workspace that has not opted in -- the right default for a new harness.
Supply Chain Security
No findings. Every generated path passes through ensure_path_within (hook docs and copied scripts), the MCP config is written then os.chmod(..., 0o600), and ${VAR} placeholders are preserved rather than resolved to host values. Tests assert literal secrets never appear in the serialized config ("literal-secret" not in json.dumps(config)), closing the credential-materialization risk for both remote headers and stdio env.
OSS Growth Hacker
No findings. A new first-class IDE target is a direct adoption surface, and crediting @TibRib for the #702 layout spec converts community input into a visible contributor win. Recommend surfacing Kiro support in the release announcement.
Test Coverage Expert
- [nit] No assertion that
.kiro/settings/mcp.jsonis written with0o600permissions, and no test thatautoApprove/disabledToolsare omitted when the registry does not supply them attests/unit/test_kiro_mcp.py.
Coverage is otherwise comprehensive:test_kiro_target_profile_matches_ratified_layout,test_kiro_steering_maps_apply_to_to_file_match,test_kiro_steering_defaults_unscoped_instructions_to_always,test_kiro_hooks_expand_each_apm_hook_to_individual_json,test_kiro_hooks_skip_when_project_has_no_kiro_dir, plus remote/stdio/user-scope/stale/disabled MCP cases. The gaps are polish, not silent-drift risk.
Auth Expert
No findings. Activated because the diff touches MCP header/env ${VAR} handling (adapters/client/kiro.py, mcp_integrator_install.py). Confirmed no token is materialized into written config: remote headers and stdio env keep ${VAR} placeholders, the config file is 0o600, and negative assertions in test_kiro_mcp.py prove host secrets do not reach disk. No auth.py/token_manager.py/host-selection surfaces were touched.
Doc Writer
No findings. The new target ships its required docs: a row in the targets matrix and the primitive compatibility matrix (reference/targets-matrix.md, concepts/primitives-and-targets.md), a dedicated ## kiro reference section with file conventions and the v1 scope fence, and a Kiro IDE guide block in integrations/ide-tool-integration.md. Both Copilot inline nits (hook filename pattern, changelog (#1741) suffix) are already correct in the current revision.
Performance Expert -- inactive
Inactive: this is an additive target transform. The diff touches no deps/**, cache/**, install/phases/**, install/pipeline.py, install/resolve.py, or transport code, and claims no perf win.
This panel is advisory. It does not block merge. Re-apply the
panel-review label after addressing feedback to re-run.
APM Review Panel:
|
| Persona | B | R | N | Takeaway |
|---|---|---|---|---|
| Python Architect | 0 | 0 | 3 | Clean subclass addition; no architectural faults. Three optional nits on duplication and typing. |
| CLI Logging Expert | 0 | 0 | 1 | CLI logging patterns are consistent; hook display delegates through payloads. One minor error message could name the MCP server key. |
| DevX UX Expert | 0 | 0 | 2 | Target UX is coherent; unsupported-transport error wording is clear and actionable. |
| Supply Chain Security Expert | 0 | 1 | 1 | Kiro adapter follows established security patterns: path containment, 0o600 perms, slug sanitization. autoApprove passthrough is a cross-adapter hardening opportunity. |
| OSS Growth Hacker | 0 | 0 | 2 | Kiro as a first-class target strengthens the multi-harness story; no conversion regressions found. |
| Auth Expert | 0 | 0 | 1 | No auth regression: runtime env placeholders are preserved, config is chmod 0o600, and no token bypass was introduced. |
| Doc Writer | 0 | 1 | 2 | Kiro docs are mostly accurate and follow the target pattern; one AGENTS.md-read claim needs verification plus minor wording polish. |
| Test Coverage Expert | 0 | 1 | 0 | Kiro happy paths are covered; missing unit regression test for unsupported remote transport ValueError in KiroClientAdapter. |
| Performance Expert | 0 | 0 | 2 | No hot-path regression; adds O(1) stat calls to detection and bounded per-action file writes to materialization. |
B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.
Top 5 follow-ups
- [Test Coverage Expert] Add unit test for unsupported remote transport
ValueErrorinKiroClientAdapter-- Missing regression trap on a user-facing error path. The evidence block confirms no test exists; adding one prevents silent message-shape drift. - [Supply Chain Security Expert] Track cross-adapter policy follow-up for
autoApprovepassthrough -- Each new target widens the surface for registry-suppliedautoApproveto pre-approve tool invocations without policy consent. A single follow-up issue covering all adapters is the right scope. - [Doc Writer] Verify or soften the claim that Kiro reads root
AGENTS.md-- Code delivers via.kiro/steering/; theAGENTS.mdclaim is unverified against Kiro docs and could mislead producers into expecting dual consumption. - [OSS Growth Hacker] Reframe CHANGELOG entry to lead with user benefit:
apm install --target kiro-- CHANGELOG is the primary signal for users scanning releases; foregrounding the command they run improves conversion from skimmer to adopter. - [Supply Chain Security Expert] Consider chmod
0o600on.kiro/hooks/*.jsonfiles -- Hook files may containrunCommandstrings; tighter permissions reduce local tampering risk on shared workstations, matching the MCP config hardening.
Architecture
classDiagram
direction LR
class MCPClientAdapter {
<<Abstract>>
+get_config_path() str
+get_current_config() dict
+update_config(updates) bool
+configure_mcp_server(...) bool
}
class CopilotClientAdapter {
<<ConcreteAdapter>>
+_format_server_config(...) dict
+_supports_runtime_env_substitution bool
}
class KiroClientAdapter {
<<ConcreteAdapter>>
+get_config_path() str
+get_current_config() dict
+update_config(updates) bool
+configure_mcp_server(...) bool
+_format_server_config(...) dict
}
class TargetProfile {
<<ValueObject>>
+name str
+root_dir str
+primitives dict
}
class HookIntegrator {
+integrate_hooks_for_target(...) HookIntegrationResult
}
class InstructionIntegrator {
+_convert_to_kiro_steering(content) str
}
MCPClientAdapter <|-- CopilotClientAdapter
CopilotClientAdapter <|-- KiroClientAdapter
HookIntegrator ..> TargetProfile : reads
InstructionIntegrator ..> TargetProfile : transforms
class KiroClientAdapter:::touched
class TargetProfile:::touched
class HookIntegrator:::touched
class InstructionIntegrator:::touched
classDef touched fill:#fff3b0,stroke:#d47600
flowchart TD
A[apm install target kiro] --> B[TargetProfile kiro]
B --> C[InstructionIntegrator]
B --> D[skill_standard copy]
B --> E[kiro_hook_integrator]
B --> F[KiroClientAdapter]
C --> G[.kiro/steering/*.md]
D --> H[.kiro/skills/*/SKILL.md]
E --> I[.kiro/hooks/*.json]
F --> J[.kiro/settings/mcp.json]
F --> K[~/.kiro/settings/mcp.json]
Recommendation
Merge as-is. The PR is architecturally sound, security-consistent, well-tested on happy paths, and strategically valuable. The recommended follow-ups, especially the unsupported-transport unit test and cross-adapter autoApprove policy issue, should be tracked as immediate post-merge work but do not represent regressions or user-facing risk that should hold this contribution.
Full per-persona findings
Python Architect
- [nit] KiroClientAdapter duplicates CopilotClientAdapter logic for update_config, get_current_config, and configure_mcp_server at
src/apm_cli/adapters/client/kiro.py:44
KiroClientAdapter overrides JSON-read/write/merge logic already present in its parent. The only delta is path behavior, the opt-in gate, and os.chmod. Extracting the common merge loop into the base class with a post-write hook would reduce drift, but this is a minor DRY nit at current scope.
Suggested: Consider a future_post_write_hook(path)for chmod while sharing the read-merge-write cycle. - [nit] Kiro steering repeats the existing lazy yaml import pattern at
src/apm_cli/integration/instruction_integrator.py:629
_convert_to_kiro_steeringimports yaml inside the method, matching nearby rule converters. This is acceptable but worth keeping consistent if these transforms are later extracted. - [nit] configure_mcp_server parameters are untyped at
src/apm_cli/adapters/client/kiro.py:180
The public adapter method omits type annotations for its parameters. The base signature is currently loose too, so this is style debt rather than a PR correctness issue.
Suggested: If the adapter surface is tightened later, align the Kiro override with the base method's typed signature.
CLI Logging Expert
- [nit] Catch-all Kiro MCP error message does not name the config_key that failed at
src/apm_cli/adapters/client/kiro.py:219
Whenconfigure_mcp_servercatches an exception it logs details at debug but prints a generic user-facing error. Naming theconfig_keywould help users identify the failing server without verbose logs.
Suggested: Change to includeconfig_key, e.g.Failed to configure MCP server '<config_key>' for Kiro.
DevX UX Expert
- [nit] Supported-runtime warning list may grow unwieldy as runtimes are added at
src/apm_cli/integration/mcp_integrator.py:942
The supported runtimes warning list grows with each target and may wrap poorly as the ecosystem expands. Current size is acceptable.
Suggested: Consider deriving the runtime list dynamically or sorting it if it grows further. - [nit] Targets matrix is becoming harder to scan as columns grow at
docs/src/content/docs/reference/targets-matrix.md:31
The Kiro row is accurate, but the matrix now has enough columns that visual scanability is showing existing documentation debt rather than a Kiro-specific problem.
Supply Chain Security Expert
- [recommended] autoApprove passthrough from registry data lacks policy-layer gating at
src/apm_cli/adapters/client/kiro.py:97
Registry-suppliedautoApprovearrays are written directly into Kiro MCP config. This matches other adapters and is not a Kiro-specific regression, but adding a target widens the surface for a malicious package to pre-approve tool invocations.
Suggested: Track a cross-adapter policy follow-up that warns, strips, or deniesautoApproveunless enterprise policy explicitly permits it. - [nit] Hook JSON files use default umask permissions at
src/apm_cli/integration/kiro_hook_integrator.py:152
mcp.jsonis chmod0o600, but.kiro/hooks/*.jsonis written withPath.write_textdefault permissions. Hooks may containrunCommandstrings, so tighter permissions would reduce local tampering risk on shared workstations.
OSS Growth Hacker
- [nit] CHANGELOG entry could lead with user benefit at
CHANGELOG.md
The entry currently emphasizes implementation shape. A user-scannable entry should foreground that Kiro users can now runapm install --target kiro.
Suggested: Reframe as: Kiro IDE is now a first-class target -apm install --target kirodeploys skills, hooks, and MCP servers into.kiro/. - [nit] IDE integration page Kiro section has no link to Kiro itself at
docs/src/content/docs/integrations/ide-tool-integration.md
Kiro is newer than Claude/Cursor/Copilot. A single link helps readers unfamiliar with the IDE orient quickly.
Suggested: Link the first Kiro mention tohttps://kiro.dev.
Auth Expert
- [nit] Header mapping accepts values without explicit string coercion at
src/apm_cli/adapters/client/kiro.py:81
_header_mappingreturns header values as provided. Current call sites pass strings, but explicit coercion or documentation would make the boundary clearer if registry data ever carries non-string values.
Suggested: Consider coercing header values withstr(value)or documenting that registry headers must already be strings.
Doc Writer
- [recommended] Verify the 'Kiro reads root AGENTS.md' claim; the real delivery path is .kiro/steering/ at
docs/src/content/docs/producer/compile.md:354
producer/compile.mdlists Kiro among harnesses that readAGENTS.md, while code confirms Kiro instructions are delivered through.kiro/steering/<name>.md.AGENTS.mdis produced becausecompile_family='agents'as a cross-harness fallback, but no test or cited Kiro reference proves Kiro consumes rootAGENTS.md.
Suggested: Confirm against Kiro docs. If unconfirmed, soften prose to name.kiro/steering/as Kiro's instruction surface and describeAGENTS.mdas the cross-harness fallback. - [nit] ide-tool-integration says one JSON file per hook; code emits one file per hook action at
docs/src/content/docs/integrations/ide-tool-integration.md:252
kiro_hook_integratoremits one file per action, andhooks-and-commands.mdcorrectly says per hook action. The integration page should use the same phrasing.
Suggested: Change to one JSON file per hook action. - [nit] Kiro CLI scope caveat repeats across multiple pages at
docs/src/content/docs/reference/targets-matrix.md:615
The v1 IDE-only boundary appears in several pages.targets-matrixshould be the authoritative target reference, with other pages linking rather than repeating.
Suggested: Keep the full caveat intargets-matrixand cross-reference it elsewhere.
Test Coverage Expert
- [recommended] No regression-trap test for unsupported remote transport ValueError raised by KiroClientAdapter at
tests/unit/test_kiro_mcp.py
KiroClientAdapterraisesValueErrorfor unsupported remote transports. That user-facing failure path should have a unit test to preserve the error message shape. Grep oftests/unit/test_kiro_mcp.pyfound no existing test for this branch.
Suggested: Addtest_remote_unsupported_transport_raises_for_kiroassertingValueErrorwithUnsupported remote transportin the message.
Proof (missing at):tests/unit/test_kiro_mcp.py::test_remote_unsupported_transport_raises_for_kiro-- proves: User gets a clear ValueError when configuring Kiro with an unsupported remote transport. [devx]
with pytest.raises(ValueError, match='Unsupported remote transport'):
Performance Expert
- [nit] Per-action file materialization produces N filesystem writes vs one merged JSON at
src/apm_cli/integration/kiro_hook_integrator.py:153
Kiro's native one-JSON-per-hook-action model means K hook actions produce K writes under.kiro/hooks/. Typical packages are small and this matches Kiro's documented layout, so it is not a concern today. - [nit] Adoption check reads full file content before comparing at
src/apm_cli/integration/kiro_hook_integrator.py:153
The adoption check reads the target file viaread_textbefore comparing with rendered JSON. For these small hook files this is effectively free; a size-first guard would only matter if hook docs became much larger.
This panel is advisory. It does not block merge. Re-apply the panel-review label after addressing feedback to re-run.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Fold remaining apm-review-panel follow-ups for the Kiro target: write the .kiro MCP config and per-hook docs via atomic_write_text with 0o600 (no torn-write window), list `kiro` in `apm compile --target` and `apm install --runtime`/global-scope help, and note .kiro in the lifecycle compile doc. Adds focused regression tests for AGENTS.md kiro fallback and the install help surface. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
APM Review Panel:
|
| Persona | B | R | N | Takeaway |
|---|---|---|---|---|
| Python Architect | 0 | 0 | 0 | Kiro uses the established adapter strategy plus extracted hook-integrator module; no architectural concerns. |
| CLI Logging Expert | 0 | 0 | 0 | Help text and runtime messages are aligned; no new CLI output anti-patterns. |
| DevX UX Expert | 0 | 0 | 0 | Kiro is discoverable through help, docs, target detection, and user-scope MCP behavior. |
| Supply Chain Security Expert | 0 | 0 | 0 | Path containment, atomic writes, 0o600, and placeholder preservation are in place. |
| OSS Growth Hacker | 0 | 0 | 0 | README/docs/changelog surfaces credit the contributor and make Kiro visible to adopters. |
| Auth Expert | 0 | 0 | 0 | No credential leakage path; env placeholders are preserved for runtime resolution. |
| Doc Writer | 0 | 0 | 0 | Docs match the implementation and the v1 Kiro IDE scope fence. |
| Test Coverage Expert | 0 | 0 | 0 | Kiro detection, steering, hooks, MCP, permissions, help text, and user-scope flows are regression-trapped. |
| Performance Expert | 0 | 0 | 0 | No meaningful install hot-path regression; new work is bounded local integration I/O. |
B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.
Architecture
classDiagram
direction LR
class MCPClientAdapter {
<<Strategy>>
+get_config_path() str
+update_config(config_updates) bool
+configure_mcp_server(...) bool
}
class CopilotClientAdapter {
<<TemplateMethod>>
+_format_server_config(...) dict
+_resolve_environment_variables(...) dict
}
class KiroClientAdapter {
<<ConcreteStrategy>>
+get_config_path() str
+get_current_config() dict
+update_config(config_updates) bool
+_format_server_config(...) dict
}
class HookIntegrator {
<<Delegation>>
+integrate_hooks_for_target(...) HookIntegrationResult
}
class KiroHookIntegrator {
<<Module>>
+integrate_kiro_hooks(...)
+_kiro_then_from_action(...) dict
}
MCPClientAdapter <|-- CopilotClientAdapter
CopilotClientAdapter <|-- KiroClientAdapter
HookIntegrator ..> KiroHookIntegrator : delegates Kiro
flowchart TD
A["target: kiro"] --> B["TargetProfile .kiro"]
B --> C["steering transform"]
B --> D["skills copy"]
B --> E["hook JSON expansion"]
B --> F["Kiro MCP adapter"]
C --> G[".kiro/steering/*.md"]
D --> H[".kiro/skills/*/SKILL.md"]
E --> I[".kiro/hooks/*.json 0o600"]
F --> J[".kiro/settings/mcp.json 0o600"]
Recommendation
Ship now. The prior follow-ups were folded into this PR, local lint and Kiro regression suites are green, and the fresh panel found no remaining in-scope items. Human merge remains the final gate.
Full per-persona findings
Python Architect
No findings.
CLI Logging Expert
No findings.
DevX UX Expert
No findings.
Supply Chain Security Expert
No findings.
OSS Growth Hacker
No findings.
Auth Expert
No findings.
Doc Writer
No findings.
Test Coverage Expert
No findings.
Performance Expert
No findings.
This panel is advisory. It does not block merge. Re-apply the panel-review label after addressing feedback to re-run.
|
Thank you for adding Kiro support! Might be an issue as I do see kiro in most of the cli files... |
feat(targets): add Kiro IDE support
TL;DR
This PR adds Kiro IDE as a first-class APM target with steering, skills, hooks, and MCP support in the documented
.kiro/layout. It implements the board-ratified design for issue #702 and keeps the Kiro CLI divergence out of v1 scope.Note
Credit to @TibRib for the Kiro steering, skills, MCP, hooks, and user-scope format details in #702. Please validate the generated layout and co-author/follow up if the Kiro IDE behavior needs adjustment.
Closes #702.
Problem (WHY)
target: kiro, so APM could not act as the shared packaging layer for teams adopting Kiro alongside existing tools.inclusion: alwaysorinclusion: fileMatchfrontmatter, so copying.instructions.mdverbatim would miss the native loading semantics..kiro/hooks/, not a merged config file, so the existing merge-only target shapes did not match the documented Kiro IDE layout.${VAR}rather than baking local env values intomcp.json.Why this matters: the target model should let APM add a concrete harness through a bounded registry + transform path, matching Agent Skills' advice that "agents pattern-match well against concrete structures" and PROSE's rule that "Grounding outputs in deterministic tool execution transforms probabilistic generation into verifiable action."
Approach (WHAT)
kiroas a stable target with.kiro/steering/,.kiro/skills/, and.kiro/hooks/primitives.kiro_steeringinstruction transform that maps APMapplyTo:globs to KirofileMatchPatternand defaults unscoped files toalways..kiro/settings/mcp.jsonand~/.kiro/settings/mcp.json, preserving${VAR}runtime placeholders..kiro/hooks/<pkg>/.Implementation (HOW)
integration/targets.py,core/apm_yml.py,core/target_detection.py,compilation/agents_compiler.py, and policy scan dirs now knowkiro, including auto-detect from.kiro/, compile routing toAGENTS.md, and user-scope metadata.instruction_integrator.pyaddskiro_steering, a rule-format transform that strips APM frontmatter, emits Kiro inclusion frontmatter, and keeps source bodies intact after link resolution.hook_integrator.pyroutes Kiro tokiro_hook_integrator.py, which converts APM/Copilot/Claude hook shapes into Kirowhen/thenJSON files and copies referenced scripts.adapters/client/kiro.py,factory.py, andmcp_integrator*.pyadd project/user-scope Kiro config writes, stale cleanup, runtime detection, remote URL+headers support, and stdio command/args/env support.tests/unit/test_kiro_mcp.py,tests/unit/integration/test_kiro_target.py, and registry/detection updates cover Kiro profile shape, steering conversion, hook expansion, user scope, stale cleanup, and MCP schema.Diagrams
Legend: the diagram shows how
target: kironow flows from manifest selection into the four Kiro-specific deployment surfaces.flowchart LR subgraph Manifest[Manifest] T[target kiro] M[mcp deps] end subgraph Registry[Target registry] P[TargetProfile kiro]:::new end subgraph Deploy[Deploy] S[steering transform]:::new K[skills copy]:::new H[hook file expansion]:::new C[mcp settings adapter]:::new end T --> P M --> C P --> S P --> K P --> H classDef new stroke-dasharray: 5 5;Trade-offs
kiro_hook_integrator.py; rejected growinghook_integrator.pyfurther because the CI file-length guard is a hard gate..kiro/skills/; rejected cross-target.agents/skills/for Kiro because @TibRib confirmed Kiro follows the Agent SkillsSKILL.mdlayout under.kiro/skills/.${VAR}preservation for Kiro MCP; rejected install-time resolution to avoid writing local secrets to disk.Benefits
apm install --target kirocan now deploy instructions, skills, hooks, and MCP servers into a Kiro workspace.target: kiroand.kiro/auto-detection work through the same target-resolution path as existing harnesses.applyTo:metadata.${VAR}secrets.Validation
uv run --extra dev pytest tests/unit/test_kiro_mcp.py tests/unit/integration/test_kiro_target.py -q:uv run --extra dev pytest tests/unit -q:uv run --extra dev ruff check src/ tests/ && uv run --extra dev ruff format --check src/ tests/ && uv run --extra dev python -m pylint --disable=all --enable=R0801 --min-similarity-lines=10 --fail-on=R0801 src/apm_cli/ && bash scripts/lint-auth-signals.sh:source guard equivalents:Scenario Evidence
.kiro/primitive layouttests/unit/integration/test_kiro_target.py::test_kiro_target_profile_matches_ratified_layouttests/unit/integration/test_kiro_target.py::test_kiro_steering_maps_apply_to_to_file_matchtests/unit/integration/test_kiro_target.py::test_kiro_hooks_expand_each_apm_hook_to_individual_jsontests/unit/test_kiro_mcp.py::test_remote_config_uses_kiro_url_headers_and_tool_extensionstests/unit/test_kiro_mcp.py::test_user_scope_writes_without_existing_kiro_dirtests/unit/test_kiro_mcp.py::test_remote_unsupported_transport_raises_for_kiroHow to test
.kiro/, add an.apm/instructions/*.instructions.mdfile withapplyTo: "src/**/*.py", runapm install --target kiro, and confirm.kiro/steering/<name>.mdhasinclusion: fileMatch..apm/skills/demo/SKILL.md, runapm install --target kiro, and confirm.kiro/skills/demo/SKILL.mdexists unchanged..apm/hooks/, runapm install --target kiro, and confirm.kiro/hooks/contains individual Kirowhen/thenfiles.headers: {Authorization: "Bearer ${KIRO_TOKEN}"}, runapm install --target kiro --only mcp, and confirm.kiro/settings/mcp.jsonkeeps${KIRO_TOKEN}.apm install --target kiro --globaland confirm user-scope output lands under~/.kiro/.Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com