feat(kiro): add Kiro v3 support via native custom agent + Agent Skills - #2126
Open
abubeck wants to merge 8 commits into
Open
feat(kiro): add Kiro v3 support via native custom agent + Agent Skills#2126abubeck wants to merge 8 commits into
abubeck wants to merge 8 commits into
Conversation
Approved design specification and implementation plan for native Kiro
CLI v3 harness support, following the repository's existing
docs/superpowers/{specs,plans} convention.
The spec records that upstream has no Kiro support today and that the
contributor's prior v2 JSON agent is prior art rather than a
compatibility baseline, and marks decisions superseded during
implementation inline rather than in trailing addenda.
Repository-local Kiro v3 agent that loads the Superpowers bootstrap and a new canonical tool mapping as startup resources, and registers every skill for native Load skill discovery. Adds the agent/mapping contract test.
POSIX sh installer that fetches a tagged release archive without Git, validates it while staged, installs the payload under XDG_DATA_HOME, and generates a global agent with absolute resource URIs. Refuses unmanaged collisions on every destination it writes. Tests run fully offline using local archives and a stubbed curl.
README entry, a complete Kiro guide covering install, update, removal, permissions and limitations, and an executable documentation contract test. The guide states why v2 is unsupported: it is no longer extended, Kiro prompts migration via /upgrade-agent, and new capabilities land in v3 only.
Superpowers skills dispatch a general-purpose subagent and supply the persona, checklist and output format through a prompt template. Kiro exposes only purpose-built agents, so a code review dispatch had no neutral target and was served by a named reviewer, silently discarding the template's contract. Add superpowers-worker-default-model and superpowers-worker-lite-model: neutral executors with no role of their own, skill:// discovery, and pre-approval for reads and skill loading. The mapping now names them in the dispatch step and forbids substituting a purpose-built agent. Verified on Kiro CLI 2.16.2.
Local acceptance testing and review found three installer defects: - A same-named .json agent config takes precedence over the generated Markdown one, so installing beside a manual or older setup produced an agent that never loads. Now refused, naming both files. - A relative XDG_DATA_HOME installed into the current directory and emitted relative resource URIs while reporting success. Now refused. - Any failure resolving the latest release was reported as a malformed version argument. Now a distinct message. Also harden the download, register the port in the porting guide as a new agent-profile shape, and exclude .kiro from the Codex sync.
The installer previously embedded a second copy of each agent's frontmatter and body inline (heredoc for the main agent, printf builder for the workers), duplicating the tracked .kiro/agents/*.md and inviting drift. Generate each global agent by transforming the tracked profile shipped in the release payload instead: insert the install root into every file://\/skill:// resource URI and add the ownership marker. The tracked files become the single source of truth; worker model/description/resources are now just data. - Add the two worker files to the installer's required-files check and the test's release fixture, since generation now depends on them shipping. - Replace the hand-picked string assertions with a structural equivalence check (installed agent, minus install root and marker, must equal the tracked file), which catches any drift and let several now-redundant assertions be removed. - Installer drops from 116 to 95 non-comment lines.
Skills like requesting-code-review reference sibling files by bare name
(e.g. code-reviewer.md). Kiro only auto-loads reference files under a
references/ subdir referenced as references/<file>, so these bare-sibling
references are not resolved, and the agent fell back to its workspace-scoped
Glob tool — which cannot see the installed payload — then hunted ~/.kiro and
read whatever stale copy it found.
Give the agent an absolute anchor: the tracked .kiro/agents/*.md now carry a
commented instruction with a {{SUPERPOWERS_SKILLS_DIR}} placeholder, and the
installer substitutes it with <install_root>/skills during agent generation.
The agent then reads a skill's reference files directly from the payload.
- Placeholder + explanatory comment live in the tracked agents, so the
mechanism is visible in the repo; the installer just substitutes the path.
- Test reverses all three transforms (URIs, placeholder, marker) to prove the
installed agent still equals the tracked profile, plus asserts the absolute
skills dir is present and no placeholder leaks through.
abubeck
force-pushed
the
feature/kiro-v3-integration
branch
from
August 12, 2026 16:04
453e892 to
a4e14e7
Compare
|
Up |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Who is submitting this PR? (required)
What problem are you trying to solve?
Superpowers had no working Kiro integration. Kiro users had to hand-adapt files,
and every prior attempt (#618, #527, #363, #788, issue #503) targeted the Kiro
IDE Powers/steering model — which either duplicated skill content into steering
files or relied on onboarding writing into
~/.kiro/steering/. In #618 themaintainer named the blocker directly: a real integration must load the
using-superpowersbootstrap at session start, without copying skills orediting user config, and asked whether Kiro has a startup mechanism for that.
Kiro's v3 agent engine does. This PR uses it. Because the Kiro CLI (v3) and the
Kiro IDE (1.0) run the same v3 agent engine and agent format, a single
Markdown custom agent works on both surfaces with no per-surface code.
What does this PR change?
Adds a native Kiro v3 custom agent (
.kiro/agents/superpowers.md) whose manifestloads the
using-superpowersbootstrap and a Kiro tool-mapping reference asstartup
file://resources, then discovers all workflow skills through a nativeskill://glob. A small POSIX installer (scripts/install-kiro.sh) installs onetagged release and generates the global agent with absolute resource URIs; two
neutral worker agents give skills a general-purpose subagent dispatch target. The
same generated agent appears in both the CLI and the IDE agent selector.
The installer generates the global agents by transforming the tracked
.kiro/agents/*.md(single source of truth) rather than embedding copies: itsubstitutes a
{{SUPERPOWERS_SKILLS_DIR}}placeholder with the absolute skillsdirectory, makes resource URIs absolute, and adds an ownership marker. That
placeholder also gives the agent an absolute anchor so it reads a skill's own
reference files (e.g.
requesting-code-review/code-reviewer.md) straight from theinstalled payload instead of globbing the workspace.
Is this change appropriate for the core library?
Yes — it is harness support, the same category as the existing
.codex/,.opencode/, and Kimi integrations. It adds no new skills and modifies nobehavior-shaping skill content. It integrates no third-party service; Kiro is the
harness, mirrored on how other harnesses are already supported in core.
What alternatives did you consider?
copying skills or writing steering into user config, and duplicates bootstrap
text — the exact blockers the maintainer raised on feat(kiro): add Kiro IDE support via Power + native Skills #618. Powers also distribute
skills/MCP but not custom agents on the CLI, so a Power cannot ship this agent.
extended (Kiro prompts
/upgrade-agent); new capabilities land only in v3.~/.kiro/skills/. Rejected for themaintenance reasons obra cited (withdrawn skills, symlink limitations). The
skill://glob reads skills in place; removing a skill is just deleting a file.config-heavy; two neutral workers (default-model and a Sonnet-pinned lite) cover
the dispatch needs.
Does this PR contain multiple unrelated changes?
No. Every change serves the single goal of Kiro v3 support: the agent + tool
mapping, the installer, worker agents, tests, user docs, the porting-guide entry
(new "Shape D — agent-profile"), a
docs/testing.mdline, and a one-line/.kiro/exclusion in the Codex-plugin sync so the new directory is not mirroreddownstream.
Existing PRs
Prior attempts built on Kiro IDE Powers/steering and were blocked on bootstrap
loading and skill duplication. This PR is the first to use the Kiro v3
custom-agent manifest, which loads the
using-superpowersbootstrap at sessionstart as a declared startup resource — directly satisfying the requirement obra
stated on #618 — with zero skill copying and zero user-config edits, on both the
CLI and the IDE.
Environment tested
claude-opus-5, lite worker pinnedclaude-sonnet-5New harness support (required)
A working integration loads the
using-superpowersbootstrap at session start,which auto-triggers
brainstormingon the acceptance prompt.installed absolute-path profile from an unrelated project directory —
brainstormingauto-triggers before any code is written. Confirmed across twoclean runs on two different models (
claude-opus-4.8andgpt-5.6-sol), bothloading
brainstormingvia Kiro's native skill mechanism and opening with adesign question rather than writing code. Transcripts below are rendered from
Kiro's own persisted session log (
messages.jsonl), not scraped from the TUI.selector; after selecting it and starting a fresh session,
/context showlists the Superpowers skills and
brainstormingtriggers on the acceptanceprompt. Note: the IDE fixes the available agent/skill list at session start, so
a restart is required after install before skills appear — an initial "skills
not found" was traced to a missing restart, not the mechanism.
Honest scope: testing was done mainly on the CLI. The IDE received only smoke
testing (agent loads, skills discovered via
/context show, brainstormingtriggers); it was not exercised across the full range of skills and workflows.
Clean-session transcript for "Let's make a react todo list"
Both transcripts are rendered from Kiro's persisted conversation
(
~/.kiro/sessions/.../messages.jsonl), so they reflect exactly what the agentdid. In both, the first action after the prompt is loading the
brainstormingskill, and the agent asks a scoping question before writing any code.
Run 1 — model
claude-opus-4.8Run 2 — model
gpt-5.6-sol(same integration, different model)Evaluation
Let's make a react todo listin a clean v3 session.(on two different models), on top of roughly two weeks of daily use of this
setup as my primary Kiro workflow.
brainstormingloads before any file iscreated; without it, skills never trigger. The behavior held across both models
and across two weeks of real daily sessions, not just the acceptance prompt.
Worker dispatch verified — default worker resolved
claude-opus-5, the liteworker's pinned
claude-sonnet-5was accepted and an invalid-model probe failedloudly, proving the
model:field is honored. IDE smoke test confirmed the sameagent loads and triggers skills after a session restart.
Rigor
.jsonshadow guard, relative/quoted/newlineXDG_DATA_HOMErejection,invalid-archive preservation, resource-parity, Codex-sync
/.kiro/exclusion)Human review