Kiro

Vendor: AWS Install name: kiro Status: GA Native config: <project>/.kiro/steering/apothem-rules.md

InstallationCopy Anchor Link

apothem install --harness kiro --project /path/to/project

The adapter writes one project-scope Kiro steering file from the shared Apothem rules and governance surface, Apothem's helpers as Kiro custom agent files in the project (see Custom agent files), and one hook (see Hooks).

It also writes Apothem's skills, and the rules and templates they cite, to your user home, before it touches the project (see Files outside the project).

Files written:

• <project>/.kiro/steering/apothem-rules.md, the steering file.
• <project>/.kiro/agents/<name>.md for each Apothem helper, in the project.
• <project>/.kiro/hooks/apothem.json, the hook file, in the project. Your own hook files in that folder are not touched.
• <project>/.apothem/support/kiro/hooks/, the hook scripts, in the project.
• ~/.kiro/skills/<name>/SKILL.md for each Apothem skill and command, in your user home.
• ~/.config/apothem/rules/ and ~/.config/apothem/templates/, in your user home.

Files outside the projectCopy Anchor Link

The install also writes Apothem's skills to your user home, before it changes anything in the project:

These folders are shared. They are not private to the project:

• Every project you install kiro into uses the same copy of ~/.kiro/skills/, and the install writes the same files into it each time. Kiro is the only tool that reads that folder. The rules and templates under ~/.config/apothem/ are written by the other tools' installs as well, with the same files.
• --project chooses the steering file to write and which project the install belongs to. It does not change where the skills go.
• The install adds no skill or rule file to your repository. The project gets the steering file, the custom agent files in .kiro/agents/, the hook file .kiro/hooks/apothem.json, plus the .apothem/ folder every project install creates, which also holds the hook scripts.
• The home folders are written first. If that fails, for example because a folder in the path is a link that leaves your home directory (a link that stays inside it is followed) or cannot be written, the install stops with the error before anything in the project changes.
• A skill folder with an Apothem skill's name that Apothem did not write is left alone, and the install prints a warning that names it. Rename or move it, then run apothem update. apothem verify fails while that name is held.
• The files add up to a few megabytes.

The install prints a note that names the folders it writes outside --project, and --dry-run lists them.

Custom agent filesCopy Anchor Link

Kiro reads a custom agent from a Markdown file in <project>/.kiro/agents/, per the Kiro custom agent documentation. The install writes one file per Apothem helper into that folder, all fourteen. It targets Kiro IDE 1.0 and Kiro CLI V3 (kiro-cli --v3), the versions that read the Markdown format. It writes no JSON profile and none of the older CLI 2.x keys, because V3 skips a JSON profile that has allowedTools and no permissions block. It installs for the project only: the user folder ~/.kiro/agents/ is not written.

Each file keeps the helper's instructions unchanged and carries these frontmatter keys:

Kiro has one list for tools, so the helper's allowed and denied tools become that list. The categories are read, write, shell, web and subagent:

A tool with no category (TodoWrite, Monitor, Artifact, TaskCreate, TaskUpdate, an MCP entry) is left out. A category is left out when the helper is denied any tool in it, so a helper never gains a tool it was denied: a helper that cannot edit files gets no write category. A helper whose allowed tools all drop out is written with tools: [], so it is not given every tool. Two helpers (mcp-builder and refactor-surgeon) carry write, nine carry shell, and three carry web. The install writes no model key, so a helper runs on the model Kiro selects, and none of permissions, excludedTools, resources, mcpServers or hooks.

Things to know:

• Kiro does not load a workspace's custom agent files until you trust the workspace. Kiro CLI 2.33 and later asks "Trust this workspace?" the first time you start an interactive V3 session in a folder. If Kiro lists none of the helpers, trust the folder and start a new session.
• Apothem has not confirmed whether Kiro CLI 2.x loads a V3 Markdown agent. Use the IDE, or run kiro-cli --v3.
• The agent files are ordinary project files. Commit them with the project or list .kiro/agents/ in .gitignore; Apothem does not choose for you.
• A file of yours with an Apothem helper's name is saved under ~/.apothem/backups/ and then replaced. The uninstall does not put it back. Files with other names, JSON profiles included, are never touched.
• Kiro's pages disagree on whether a custom agent sees the skills in ~/.kiro/skills/ by default: the skills page says an agent needs a skill:// resource, while the configuration reference says an agent inherits the default skills. The install adds no resources key, so the helpers see the skills only if the second reading holds.
• Kiro's Built-in tools page lists the tools each category commonly includes. The read category includes the file search and text search tools (the CLI 2.x glob and grep), which is why Glob and Grep map there. It also includes code (code analysis by syntax tree) and introspect (answers questions about Kiro itself), so a helper with read can use both. The page lists code under write too, and does not say whether the tool edits files.
• Apothem has not confirmed what Kiro does with an omitted tools key, or which frontmatter keys Kiro requires beyond name.

HooksCopy Anchor Link

Kiro runs hooks from JSON files in <project>/.kiro/hooks/, per the Kiro hooks documentation. The install writes one file there, apothem.json (hook file version v1), with one hook:

The hook adds context for the model. It does not block a tool call or a session.

Apothem registers no PreToolUse or PostToolUse hook on Kiro. Kiro adds a command's output to the model's context for SessionStart and UserPromptSubmit only and ignores it for tool events. A guard registered on a tool event would cost a process start on every tool call and deliver nothing, so the write, edit and shell guards, the context-size advisory and the session-end protocol stay on the tools that deliver them. The install writes no hook for UserPromptSubmit, and it writes no hook to the user folder ~/.kiro/hooks/.

Where the files go

The command in the hook file looks like this, with your interpreter and project path in place of the two paths:

"/path/to/python" "/path/to/project/.apothem/support/kiro/hooks/dispatch.py" --contract kiro SessionStart

--contract kiro makes the dispatcher print the context as plain text, which is what Kiro adds to the context for SessionStart. Kiro documents no shell for command actions on Windows. The command is written for sh and cmd.exe, with a forward-slash interpreter path in quotes; if Kiro runs it under PowerShell on your machine, the quoted path needs a call operator (&) in front, and you can add it by hand.

Trust the workspace. Kiro CLI 2.33 and later loads a workspace's hooks only after you trust the workspace: it asks "Trust this workspace?" the first time you start an interactive V3 session (kiro-cli --v3) in a folder. Kiro Web sessions run no hooks. The install prints this as a note.

Commit with care. The command names the interpreter Apothem found when it ran and the absolute path of the project, so the file is specific to your machine, and the scripts it runs are in .apothem/, which a project's .gitignore snippet ignores. If you commit .kiro/hooks/apothem.json, a teammate's checkout gets a hook that points at nothing: Kiro shows a warning for the failed command and the session goes on. Add .kiro/hooks/apothem.json to .gitignore, or commit it only for a team that shares the same layout. The install does not edit .gitignore.

Your own hooks. Hook files of yours in .kiro/hooks/ are never read or changed. A hook you add to apothem.json itself stays: an update and an uninstall replace or remove only the hooks whose command runs the Apothem dispatcher (.apothem/support/kiro/hooks/dispatch.py with --contract kiro, whichever project path it was written under). A hook of yours that only shares the name, or that runs python -m apothem.conformity.gate, is never taken for Apothem's. A file that is not valid JSON is saved under ~/.apothem/backups/ and replaced.

Paths the shell would misread. A project or interpreter path that contains $, a backtick, a double quote or a backslash is refused before anything is written: inside the quoted command it would run a different file, or break the JSON the command is written into. The error names the path; move or rename the project and run the install again. A space or an apostrophe in a path is fine.

Turning the hook off. Set APOTHEM_HOOKS_DISABLE=1 in Kiro's environment to silence the Apothem hook. An update rewrites the Apothem entry, so an edit to it does not last, with one exception: set "enabled": false on it, which Kiro documents as skipping a hook without deleting it, and an update keeps that.

Profile-to-native-config mappingCopy Anchor Link

The adapter reads Apothem's shared profile and renders the project steering file on every apothem install or apothem update run. The shared profile is the source of truth; project-local edits to the generated file are backed up before the next sync replaces the Apothem-managed content.

The file opens with its inclusion: always front matter, because Kiro requires the inclusion configuration to be the first content in the file. The Apothem-managed block follows it; text you add after the block is kept on every sync.

Compatibility notesCopy Anchor Link

Kiro's steering surface is project-scoped under .kiro/steering/. The adapter writes a dedicated apothem-rules.md steering file with inclusion: always front matter and never clobbers Kiro's operator-authored foundation files (product.md, tech.md, structure.md). Kiro specs (.kiro/specs/) are operator-owned; Apothem does not write them. It writes one hook file, .kiro/hooks/apothem.json, and no other file in .kiro/hooks/.

Kiro documents ~/.kiro/skills/ for global skills and does not mention ~/.agents/skills/, so the install writes the Kiro folder and not the cross-tool one. A workspace skill with the same name wins over the global one. Apothem has not confirmed how Kiro treats a SKILL.md header key it does not list.

VerificationCopy Anchor Link

apothem verify --harness kiro --project /path/to/project

The verify command confirms that:

1. The native config exists at the expected path.
2. Each managed target exists, the .kiro/agents/ folder included; managed files are non-empty, and JSON or YAML configs parse. Add --profile PATH to also confirm that the installed files match that profile. For .kiro/agents/ the check is that the folder exists, not that each helper file is in it; apothem diff --harness kiro --project /path/to/project lists the helper files that are missing or out of date. The hook file .kiro/hooks/apothem.json must exist, be non-empty and parse as JSON and hold a hook that runs the Apothem dispatcher, and the hook scripts must be in .apothem/support/kiro/hooks/. The check does not run the hook.
3. Every Apothem skill folder is in place with a SKILL.md, whichever install wrote it, and no skill folder with an Apothem name belongs to something Apothem did not write. A failed check names the missing or foreign folders.
4. The adapter-specific verification routine reports success.

UpdatingCopy Anchor Link

apothem update --harness kiro --project /path/to/project

Re-derives the project steering file from the current shared profile state.

The update also rewrites any skill folder whose files differ from the current ones. If you installed with an earlier release that wrote no skills, the update adds them. It rewrites custom agent files that differ from the current ones, and adds any that are missing. It also refreshes the hook scripts and the Apothem hook in .kiro/hooks/apothem.json, keeping any hook of yours in that file.

UninstallingCopy Anchor Link

apothem uninstall --harness kiro --project /path/to/project

Removes the Apothem block, and the front matter Apothem wrote above it, from <project>/.kiro/steering/apothem-rules.md and keeps any other text in it. The file is deleted only when nothing else remains in it. Before the change, a timestamped copy of the file is saved under ~/.apothem/backups/; no backup file is left in the project. The shared profile YAML and Apothem engine are unaffected.

The uninstall also removes the custom agent files it wrote in <project>/.kiro/agents/ and keeps any other file there; the folder is removed when it is left empty. It removes the Apothem hook from <project>/.kiro/hooks/apothem.json, recognising it by the dispatcher path in its command, so it works without an install record, and keeps any hook of yours in that file. The file is deleted when nothing else is in it, and your other hook files are not touched. If the file has comments the uninstall cannot read, it leaves the file as it is and reports the hook as skipped, with the reason; remove the Apothem hook by hand. The hook scripts in <project>/.apothem/support/kiro/hooks/ go too. It removes the skill folders it wrote in ~/.kiro/skills/ and the rules and templates in ~/.config/apothem/, but only when no other Apothem install still uses them. Another project, or another tool that shares the folder, may. In that case the uninstall keeps the folders, prints which install uses them, and the last uninstall removes them. Files you added to those folders stay, and a folder left empty is removed. Each folder is backed up under ~/.apothem/backups/ before it is removed.

Conformity gateCopy Anchor Link

python -m apothem.conformity.gate --all .

TroubleshootingCopy Anchor Link

Configuration knobsCopy Anchor Link

See alsoCopy Anchor Link

• All harnesses — the full catalog of supported tools
• Install guide — install Apothem into this harness
• apothem harnesses reference — list and inspect adapters from the CLI