This file is a ROUTER, not a manual. It carries only the rules whose violation
causes damage before a pointer could be read. Everything else is a link you MUST
open before touching that subsystem: see
Read before you touch. The frontend has its own router,
website/AGENTS.md.
Kiro Crew is an open-source personal AI agent: chat from the web dashboard, the CLI, or a messaging channel like Slack and Discord; run multi-step tasks unattended; schedule cron jobs; keep memory across sessions.
Kiro Crew's sole LLM provider speaks ACP. Its default backend runs kiro-cli
over ACP JSON-RPC; other verified ACP harnesses are selected with
agent.acp_backend. MCP tools supply the agent's host capabilities.
- Backend: Python package
kiro_crewinsrc/kiro_crew/. Frontend: React- TS + Vite SPA in
website/, built intosrc/kiro_crew/static/dist/and served by the backend.
- TS + Vite SPA in
- Data home:
~/.kiro/crew, overridden withKIROCREW_HOME. - Distribution: public GitHub, plain setuptools, public PyPI / public npm.
Full map: overview. This repo is the de-Amazoned
public fork of an internal package; what must never come back is
oss-fork-boundaries, gated by
the internal-content-scan check (blocking on pull requests, forks included) and
the
no-new-builtin-apps rule in AUTOSDE.yaml.
Load the doc for the row you are working in before you change code. Update it in the same commit when you change what it documents.
| If you are touching… | Read first |
|---|---|
platform/, editions, CPP seam, governance |
platform-context + governance |
security/, hooks.py, hook_runtime/, denied commands, sensitive paths |
security + sel |
config/ — the live watcher, restart=True marks, appliers, config.json writes |
config |
| the security model as a whole, threat boundaries | security-deep-dive |
computer_use/ |
computer-use |
monitoring loops, monitoring/, irq.py, watches |
monitor-architecture (the paradigm) + agent-interrupt-controller + babysit-pr-watch |
acp/, kiro-cli transport, providers |
acp-client + providers |
| picking or defaulting a model anywhere | model-selection + model-fallback |
| adding or adapting an agent harness (BYO, KAS, claude) | harness-parity (invariants) + harness-parity-gate (CI) |
an agent spec: agent_discovery.py and its agent_discovery_parts/ owners, agent_spec_format.py, agent.py's spec writers, its agent_parts/ owners and agent_materialization/, acp/kas_agents.py, or any field a spec carries |
agent-spec-fields (what each field does, per backend) + agent-host-contract (the per-harness table) |
| the publicly selectable Claude backend | claude-code-provider |
| sessions, slots, session keys, PIDs | session + history |
shared_crew/, attributing work to a person, per-person fair admission, presence, shared approvals |
shared-crew |
killing a runtime, leases and tenancies, sweeps and reapers, runtime_ownership.py, runtime_reconcile.py, the kill paths of session_pid.py and its session_pid_*.py owners |
runtime-ownership |
| session summaries, the chat summary panel, intent extraction | session-summary |
| memory, embeddings, vectors, lessons, skills, hooks | memory-skills-hooks |
context.py, context_blocks.py, context_assembly/, what reaches the model's context |
context-management + memory-skills-hooks: Context Builder (module ownership) |
| MCP servers or tools (adding, changing, statelessness) | mcp |
mcp_gateway/ — gatewayd.py, daemon/, the daemon's lifecycle and facade |
mcp-gateway-daemon-lifecycle + mcp |
| apps, App Kit, manifests, app agents, where a new app ships | app-kit-platform + app-kit/ + No built-in apps |
| artifacts, companion chat | artifacts |
stt/, transcribe.py and its transcribe_*.py owners, voice_reply.py, the mic, dictation, TTS |
stt-streaming + voice-streaming |
| cron, learn, dashboard handlers | learn-cron-dashboard |
| Slack, Discord, any channel, messaging, approvals | messaging + slack-gateway |
| subagents, spawn, orphan recovery | subagent |
crews, select_crew, crew bindings, Crew Mode slots |
crew-mode |
| the pipeline conductor agent or its skill | pipeline-conductor |
| task runner | task + taskrunner |
workflows/ (the dynamic-workflow engine) |
workflows |
| themes | themes + theming-contract |
anything under website/ |
website/AGENTS.md |
| user-facing strings, dates, numbers, sort order | i18n-catalog (authoring) + i18n-gates (CI) |
tests: flakes, hangs, speed, memory, fixtures, sharding, side effects, host state (~/.kiro, Path.home(), the systemd user manager), conftest isolation, monkeypatch.undo(), env-var leaks, host-dependent tests (Windows, Python 3.13, per-user tools, version-manager shims), spawning a real child or reaping one, .worktrees/ in a repo-wide scan, what TMPDIR must not be, what a worker costs, collection-time probes that build a singleton, a MagicMock the code converts with int(), sizing a ReDoS / complexity guard, clocks and time, sleeps, ordering and timestamp ties, ports, timezone and locale, randomness, repeat and shuffle proof, a flaky CI red |
testing-conventions + the writing-tests skill; frontend and Electron tests: website/docs/testing.md |
| browser E2E | e2e-gate |
| proving a worktree change against an isolated running gateway | worktree-verification-recipes |
| CI, PR flow, review gates (a lane says PASS or BLOCK, with a Trigger and an Outcome), commit messages | ci-and-reviews + CONTRIBUTING.md |
a PR that hides, deletes, tightens or migrates something (the Reader: list) |
take-away-changes |
| constants, comments, lint, code style, the brand name | code-style |
| connections, connectors, an external account link | connections |
| the connector campaign's manifest schema or work-stream DAG | connector-capability-manifest |
| the GitHub connector's operation data or wire parsing (pagination, rate limits, error mapping) | connector-github |
connections/vendors/microsoft/graph/, the Microsoft Graph runtime base (locator, payload shaping, @odata.nextLink paging) |
microsoft-graph-runtime |
connections/vendors/zoom/ — Zoom identity/paging/processing/errors contract logic |
connector-zoom |
| a POSIX call: locks, signals, PIDs, chmod, RSS | platform-compat + windows-install |
injected [Cron notification] / [Subagent completion event] |
injected-messages |
| build, install, dev mode | CONTRIBUTING.md + install |
| cutting a release | release |
CHANGELOG.md |
changelog |
| a user-facing label, wording, placement or behaviour a person may already have decided | docs/decisions/README.md |
| errors, retries, user-facing failure text | error-handling |
| what this public fork must never re-introduce | oss-fork-boundaries |
| any doc: moving, renaming, indexing it | docs/README.md |
The whole doc tree is indexed from docs/README.md. User-facing
docs that ship in the package live in src/kiro_crew/docs/ and are indexed by
its README.
Detail and rationale: security, governance, computer-use.
- Keystone.
security_policy.json,profiles/,admission_policy.jsonandcomputer_use.jsonunder the data home are the ceiling the agent is governed by. The enforcement point is the OS layer insandbox.py, not a text matcher. Every crew-home leaf carries one of three dispositions, and which one it has IS the statement of what is guaranteed:HIDDEN(bind-masked in every mode — the credential homes,.env,live_target.json),READONLY(in-sandbox code reads it and a write would let the agent choose its own ceiling — the four leaves above), orVISIBLE(in-sandbox code needs read and write, so no OS rule applies and it rests on the tool gate alone). Precisely, then: the agent cannot write its own ceiling in any sandbox mode, and it can read it, deliberately — masking a policy file makes it resolve to the permissive standalone default, so hiding a ceiling REMOVES it instead of protecting it. Do not restore a read block by pattern-matching command text: a spawned shell reaches a file through anopen()that never routes through the tool gate, so a path fenced only there is readable in any sandbox mode whatever the matcher recognises, and each spelling closed (/./, a glued redirect, a variable,cd,pushd) narrows an unbounded set by exactly one.test_sandbox_governance_mask.pypins the union of the three dispositions equal to the crew-home half ofsecurity.sensitive_home_dirs(), so a new leaf cannot land in none of them — that pin, not a regex, is what keeps the ceiling un-disableable. One residual worth carrying:sel_hmac.keyisVISIBLE, so the SEL audit key has no OS fence; closing that means moving its in-sandbox reader behind the gateway, never another matcher. An ENFORCED harness is the one exception —tool_gate's credential mask keeps that leaf, and the other credential-bearing crew leaves, from a foreign child (sandbox._CREW_CHILD_WITHHELD_LEAVES), which is why the features whose in-sandbox readers need them do not work there. - Governance is
POLICY ∩ PROFILE, tightest-wins, enforced at Kiro Crew's OWN PreToolUse gate even when the kiro agent config granted the call. The evaluator is scope-name-agnostic, so adding a scope is aSCOPE_CATALOGdata change, never an evaluator edit. CONTRACT_VERSIONstays pinned at 1 pre-launch.- Never restate the denied-rule count in prose.
test/test_denied_commands_security.pypins it, and a restated count goes stale silently. - A cron script body is never a shell-gate subject.
is_sensitive_bash_commandandis_deniedread a SHELL COMMAND LINE;mcp_cron._vet_script_contentsscans a Python source body with whole-body, source-aware detectors only (credential path, secret env name, exfil URL) and the sandbox is the runtime control. Handing the body to the shell gate was tried (#4243 → #8811) and every shell-grammar pass produced a permanent false denial on ordinary scripts (#7912, #8563, #8643, #8812), each patched with another AST layer that still could not stopopen(a + b). Do not add asubject_is_*flag, a_traversal_subjectsre-pointing, or anis_sensitive_source_bodyback. A new script detector is a whole-body match in_vet_script_contents, or a sandbox mask. Pinned bytest_the_shell_gate_has_no_source_body_entry_pointandtest_script_body_is_never_a_shell_gate_subject. - A regex spelling-chase is a review smell, not a fix. When a security review
finds "X also reaches the fence via spelling Y", ask first whether the SUBJECT is
wrong (a document handed to a command-line matcher) or whether the sandbox
already covers it. Add a table entry only when the subject is genuinely a shell
command line and the OS sandbox does not hold the path (#7441 went four rounds
of
command/exec -a/nice/env -i/timeout/busyboxbefore restructuring). - The sandbox's SCOPE is the operator's to widen, never yours. What
sandbox.pyand itssandbox_*owners seal, mask or no-follow pin decides which of the operator's own files their agent can still reach, so a widening they did not ask for surfaces days later as work that stopped, with no record that anyone chose to lose it. Never add a seal, mask or refusal a task did not ask for, never tighten a fence past the threat the change names, and never harden merely because a review round said "spelling Y reaches it too" — a review comment is not authorization, and #12103 spent eleven rounds on one span that way. Cite the seal that fails on a path the change already touches, or keep the code and rebut. The same holds when you are the REVIEWER: asking for a wider fence is outside what review decides. An added invariant ships with its own data in the SAME commit, and an import-time one silences its own witness — #11556 asserted over five sealed leaves carrying wording for two, which madeimport kiro_crew.sandboxraise on main and failed every backend test at COLLECTION, includingtest_every_strict_leaf_of_either_shape_is_covered_by_the_delegated_guard, the test written to catch exactly that gap. - A tightened credential rule sweeps the clients outside this repo. When a
change narrows what a credential accepts and that credential crosses a process
boundary (minted by one program through a public endpoint, presented by
another), the writer sweep under
## Backwards compatibilitynames the clients that are NOT in this repository, or the PR ships a rollback plan that names them. A sweep proving every in-tree mint was updated proves nothing about an installed app minting through the same endpoint. Reviewers hold the PR to this; #14436 had to revert a tightening whose sweep missed such a client. - Computer use is governed by one on/off row only: the operator opt-in on the
keystone
computer_use.json, ANDed withcapabilities.computer_use(rfc-crew-enterprise-edition, appendix "Desktop control"). Never add finercomputer_use.*scopes, more capability rows, approval ordinals or pointer permits. Its refusals run in band ontools._dispatch, never at the fail-OPENhooksgate, because a pre-authorized tool can skip that gate.click_method: "auto"must NEVER resolve onto"global": that is the only thing between an ordinary click and the operator's real cursor.
claude-*, opus*, sonnet*, haiku*, gpt-* or fable* as a default or
fallback fails at runtime for anyone not entitled to it, silently until the first
prompt. The default is "auto"; resolve a substitute choice through
acp.client.resolve_usable_model; pin a cheaper model for the worker roles only
via agent.role_models.<role> (and, for one mate's dispatched sessions, via
that mate's worker_model). code-review.yml fails on a newly added hardcoded
literal. Rules and the one exception:
model-selection.
Never express "this is the Kiro harness" as the ABSENCE of another one. A negative
test fails toward the permissive answer, so nothing goes red until an operator who
never opted into that harness pays for it — and every id in
acp_backends.BASELINE_SELECTABLE_BACKENDS is selectable on a plain public build,
so not is_claude_backend is already wrong on the non-Claude ones. Identity is
positive: is_kiro_backend, == ACP_BACKEND_KIRO, or membership in a named
ACP_BACKENDS_* set.
An added harness ADAPTS to the seams the Kiro path already runs through; it never
moves, widens or generalizes them, and it is selected at agent.acp_backend —
agent.provider stays enum=["acp"]. Invariant ids (cite them bare, H7),
capability sets and the CI half:
harness-parity. Run the added-line
gate locally with
HARNESS_BASE_REF=origin/main python3 scripts/check_harness_parity.py.
Kiro Crew accepts no new built-in app. Never add an app under
src/kiro_crew/apps/builtins/, an app.json outside docs/app-kit/examples/ and
test fixtures, a per-app page under website/src/apps/<app>/, a per-app row in a
core built-in table (BUILTIN_NAMES, apps/manager_builtins.py, the
website/src/apps/ registries), or an app-specific MCP tool (mcp_tools/apps.py)
or internal-secret path row (dashboard/server_internal_paths.py) in core. A new
app, first-party included, ships from a dedicated GitHub repository listed in the
official registry (kirodotdev/KiroCrewApps).
The built-ins that still ship are being moved out under #26967; fixing one in place
until it leaves is fine. An app moves out COMPLETELY: no part of it (backend, UI,
scripts, CI, specs) stays in core, and core never imports or hard-codes a specific
app (kiro_crew.apps.builtins.<app>, an app id) outside the built-in tables being
emptied. A capability an app cannot get from outside core is an App Kit seam gap:
fix it with a generic, app-agnostic seam, never put the app in core. Rule:
no-new-builtin-apps in AUTOSDE.yaml; decision:
2026-11-01;
seams: app-kit-platform.
- MUST read the owning spec under
docs/system-specs/before changing the code it covers, and MUST update it in the SAME commit. - MUST NOT create additional markdown files unless explicitly instructed.
- MUST grep
docs/decisions/before changing a recorded label, placement or behaviour; an entry is reversed only by a new superseding entry a maintainer wrote, never by an edit, a friction report or a review finding. - Everything else about adding, moving, indexing and linting a doc — including
scripts/docs-lint.sh— is docs/README.md. Treatdocs/task-specs/as an archive, never as current context.
- Do NOT proactively
git commit. Commit only when asked. - Do NOT
git pushunless the user explicitly says to push. Being asked to commit is NOT permission to push. mainis the default branch; changes land through a GitHub PR. The full flow: CONTRIBUTING.md.- Never
git stash(every worktree shares one stash list) and never overlay a whole tree withgit checkout <ref> -- .. To bring the main clone current, follow thekirocrew-worktree-devskill.
<type>: <summary — max 72 chars, imperative, lowercase, no period>
<body — what and why, not how; wrapped at 72>
Types the PR-title gate in code-review.yml accepts: feat, fix, docs,
style, refactor, perf, test, chore, ci, build, revert. One
logical change per commit, and at most two commits per PR.
gh pr create --body / --body-file bypasses the GitHub template, so build the
body from .github/PULL_REQUEST_TEMPLATE.md yourself: keep every heading
verbatim and fill in the **Goal:** line. PR Hygiene fails a body missing the
required sections; check it before opening with
out="$(mktemp)"; PR_BODY="$(cat <file>)" GITHUB_OUTPUT="$out" bash .github/scripts/pr-description-check.sh; cat "$out".
The **Goal:** line, ## Why it matters and ## Not a goal are written once,
when the PR opens. Never edit them on your own, not even to match the diff. A
finding outside the goal is rebutted or deferred, never absorbed by widening the
goal. A defect in code this PR adds or changes is always in scope and gets fixed;
'out of goal' applies only to new scope — a new feature, surface, or hardening this
PR does not need. Edit them only when a human explicitly asks, and say why in a PR
comment.
Before you edit for a review finding, name the class it belongs to and list every site of it. Fix or test all of them in the same push. When a finding names the same root cause as an earlier one, in any file or spelling, treat it as the same finding and change the approach instead of patching a third spelling: remove the second writer, narrow the scope, or defer it with an issue and a pinning test. On the fifth fix only narrowing or deferral remain. Two or more PRs that need the same new helper module share one owner PR; the others import it, name the merge order in their body, and carry no copy. Keep going; no one needs to approve that. Details: kirocrew-prepare-pr.
- Your feature PR does not touch
CHANGELOG.md. The release PR writes the section covering everything that shipped. - Never delete or edit a shipped section. A release PR prepends one section and leaves every earlier one byte-identical. This has already cost 322 lines of released history once, which no test caught.
- A stable release must never ship a version carrying a prerelease suffix.
When, how, the heading shape and the format budget: changelog. Cutting a release, and the one escape hatch from the suffix rule: release.
python3 scripts/check_black_formatting.py && python3 scripts/check_subprocess_encoding.py && isort src/kiro_crew test conftest.py xdist_budget.py
flake8 src/kiro_crew test conftest.py xdist_budget.py && mypy src/kiro_crew
BASE="$(git merge-base HEAD origin/main)" && COMMENT_HISTORY_BASE_REF="$BASE" python3 scripts/check_comment_history.py && BRAND_BASE_REF="$BASE" python3 scripts/check_brand_name.py
python3 scripts/local-gate.pyThe third line runs the two diff-scoped Fast Gate checks most often red on a
PR: history narration in an added comment, and a misspelled product name on an
added line. If check_black_formatting.py reports a baselined file as now
black-clean (formatting what you touched does that), run it with
--update-baseline and commit the shorter baseline.
local-gate.py runs the tests related to your diff on both surfaces with a
bounded worker count; the full suite is CI's job and never runs locally unless a
human passes --full. See
kirocrew-prepare-pr.
To run the cheap CI gates in one go and record that you did, use the optional pre-push gate. It is advisory: nothing refuses a push without it.
- On macOS, run
mypy --platform linux src/kiro_crew. Without it a local run reports errors you did not cause and MISSES the Linux-only errors CI fails on, so a clean local run is a false green. - Never run bare
black src/kiro_crew test. It reformats every baselined file and buries your diff. Format only what you touched:black --target-version py310 <the files you changed>. - Frontend:
cd website && npm run build && npm run test. - A multi-test
--override-iniMUST keep-n auto --dist loadgroup --max-worker-restart=2; a bare override silently drops--dist loadgroupand scatters@pytest.mark.xdist_grouptests into flaky races.
No hand-written file over 2,000 lines; put new code in a new module. A new
responsibility gets a new module, never a new section in a large file, and a change
that takes a code file past 1,600 lines splits it in the same PR or in one before it.
Split by responsibility, moving whole definitions into a sibling module, and keep the
original path as the import path callers use. scripts/check_file_line_cap.py
enforces the cap in CI's lint jobs; run it before you push. The files already over
are listed in .github/file-line-cap-baseline.txt, which only shrinks, so never add
a row. How to split without losing a patch seam:
code-style § Splitting a file.
Gates, the seven flake classes, the conftest isolation floor and the traps that are
invisible when reading a test: code-style +
testing-conventions. A test that
can block forever is a lost RUN, not a failed test: on Windows pytest-timeout kills
the xdist worker, and with --max-worker-restart=0 one unbounded await aborts the
whole job (class 6). Frontend and Electron: website/docs/testing.md.
Tests MUST be deterministic: wait on a signal, never sleep as a barrier; never sleep
to make timestamps differ (set them); one clock, injected or frozen at the module's
own binding; never assert an order you did not define; no literal port for a real
listener (bind 0); no network beyond loopback; every self-unblocked await bounded.
AUTOSDE.yaml's tests-are-deterministic rule blocks these in review, the SAST
job's semgrep/test-determinism.yaml refuses the commonest on a new line, and
test/test_flake_pattern_ratchet.py counts per file the clock, wait, port, environment
and module-cache shapes those patterns miss, failing a change that adds one to a file
(measured against its merge-base; a deliberate one carries # flake-ok: <reason>).
Fast Gate's flake-pattern-ratchet job runs it on every pull request and fails when it
compares nothing (why: testing-conventions.md "Determinism contract"); run
python -m pytest -n0 test/test_flake_pattern_ratchet.py before pushing to see it first.
Contract:
testing-conventions § Determinism contract.
Route POSIX calls through platform_compat: fcntl, termios, resource and
pty do not exist on Windows, and os.kill(pid, 0) TERMINATES the target
there — it is not a liveness probe. The full helper-per-call table:
platform-compat. Verify process,
signal, file-lock and metrics changes on macOS + Linux.
A new LLM-facing CLI command MUST also ship as an MCP tool, MCP tools MUST be
stateless (no module global holds per-caller data), and a skill any shipped
feature, tool or doc references MUST live in src/kiro_crew/builtin_skills/ — the
only tree bundled into the package. Why, plus the session-key gate:
mcp +
memory-skills-hooks.
[Cron notification from "job"], [Subagent completion event] and
[auto-nudge cycle N] arrive from automation. Process them; do NOT answer them as
if a human typed them — the user may not be present. Envelopes:
injected-messages.
kirocrew gateway --approval yolo auto-approves ALL tools and refuses to start
unless KIROCREW_HOME is explicitly set to a non-default path. Never point it at
~/.kiro/crew. All harness flags: cli.