AGENTS.md · kirodotdev/KiroCrew

Sections

1. What this is
2. Read before you touch
3. Security invariants (do NOT weaken)
4. Never hardcode a model id
5. Harness parity
6. Specs and docs
7. Git
8. CHANGELOG.md
9. The gate before you commit
10. Cross-platform
11. LLM-facing capabilities
12. Injected messages are not the user
13. Harness safety

First lines (shown under the repo's Apache-2.0 license)

# Rules for AI Assistants

**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](#read-before-you-touch). The frontend has its own router,
[`website/AGENTS.md`](website/AGENTS.md).

## What this is

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_crew` in `src/kiro_crew/`. **Frontend:** React
  + TS + Vite SPA in `website/`, built into `src/kiro_crew/static/dist/` and served
  by the backend.
- **Data home:** `~/.kiro/crew`, overridden with `KIROCREW_HOME`.
- **Distribution:** public GitHub, plain setuptools, public PyPI / public npm.

Full map: [overview](docs/architecture/overview.md). This repo is the de-Amazoned
public fork of an internal package; what must never come back is
[oss-fork-boundaries](docs/system-specs/oss-fork-boundaries.md), gated by
the `internal-content-scan` check (blocking on pull requests, forks included) and
the
`no-new-builtin-apps` rule in `AUTOSDE.yaml`.

## Read before you touch

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](docs/system-specs/modules/platform-context.md) + [governance](docs/system-specs/modules/governance.md) |
| `security.py`, `hooks.py`, `hook_runtime/`, denied commands, sensitive paths | [security](docs/system-specs/modules/security.md) + [sel](docs/system-specs/modules/sel.md) |
| `config/` — the live watcher, `restart=True` marks, appliers, `config.json` writes | [config](docs/system-specs/modules/config.md) |
| the security model as a whole, threat boundaries | [security-deep-dive](docs/architecture/security-deep-dive.md) |
| `computer_use/` | [computer-use](docs/system-specs/modules/computer-use.md) |
| monitoring loops, `monitoring/`, `irq.py`, watches | [monitor-architecture](docs/system-specs/modules/monitor-architecture.md) (the paradigm) + [agent-interrupt-controller](docs/system-specs/modules/agent-interrupt-controller.md) + [babysit-pr-watch](docs/system-specs/modules/babysit-pr-watch.md) |
| `acp/`, kiro-cli transport, providers | [acp-client](docs/system-specs/modules/acp-client.md) + [providers](docs/system-specs/modules/providers.md) |
| picking or defaulting a model anywhere | [model-selection](docs/system-specs/common/model-selection.md) + [model-fallback](docs/system-specs/modules/model-fallback.md) |
| adding or adapting an agent harness (BYO, KAS, claude) | [harness-parity](docs/system-specs/modules/harness-parity.md) (invariants) + [harness-parity-gate](docs/ci/harness-parity-gate.md) (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](src/kiro_crew/docs/agent-spec-fields.md) (what each field does, per backend) + [agent-host-contract](docs/system-specs/modules/agent-host-contract.md) (the per-harness table) |
| the publicly selectable Claude backend | [claude-code-provider](docs/system-specs/modules/claude-code-provider.md) |
| sessions, slots, session keys, PIDs | [session](docs/system-specs/modules/session.md) + [history](docs/system-specs/modules/history.md) |
| `shared_crew/`, attributing work to a person, per-person fair admission, presence, shared approvals | [shared-crew](docs/system-specs/modules/shared-crew.md) |
| 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](docs/system-specs/modules/runtime-ownership.md) |
| session summaries, the chat summary panel, intent extraction | [session-summary](docs/system-specs/modules/session-summary.md) |
| memory, embeddings, vectors, lessons, skills, hooks | [memory-skills-hooks](docs/system-specs/modules/memory-skills-hooks.md) |
| `context.py`, `context_blocks.py`, `context_assembly/`, what reaches the model's context | [context-management](docs/architecture/context-management.md) + [memory-skills-hooks: Context Builder](docs/system-specs/modules/memory-skills-hooks.md#context-builder-contextpy) (module ownership) |
| MCP servers or tools (adding, changing, statelessness) | [mcp](docs/architecture/mcp.md) |
| `mcp_gateway/` — `gatewayd.py`, `daemon/`, the daemon's lifecycle and facade | [mcp-gateway-daemon-lifecycle](docs/system-specs/modules/mcp-gateway-daemon-lifecycle.md) + [mcp](docs/architecture/mcp.md) |
| apps, App Kit, manifests, app agents | [app-kit-platform](docs/system-specs/modules/app-kit-platform.md) + [app-kit/](docs/app-kit/README.md) |
| artifacts, companion chat | [artifacts](docs/system-specs/modules/artifacts.md) |
| `stt/`, `transcribe.py` and its `transcribe_*.py` owners, `voice_reply.py`, the mic, dictation, TTS | [stt-streaming](docs/system-specs/modules/stt-streaming.md) + [voice-streaming](docs/system-specs/modules/voice-streaming.md) |
| cron, learn, dashboard handlers | [learn-cron-dashboard](docs/system-specs/modules/learn-cron-dashboard.md) |
| Slack, Discord, any channel, messaging, approvals | [messaging](docs/system-specs/modules/messaging.md) + [slack-gateway](docs/system-specs/modules/slack-gateway.md) |
| subagents, spawn, orphan recovery | [subagent](docs/system-specs/modules/subagent.md) |
| crews, `select_crew`, crew bindings, Crew Mode slots | [crew-mode](docs/system-specs/modules/crew-mode.md) |
| the pipeline conductor agent or its skill | [pipeline-conductor](docs/system-specs/modules/pipeline-conductor.md) |
| task runner | [task](docs/system-specs/modules/task.md) + [taskrunner](docs/system-specs/modules/taskrunner.md) |
| `workflows/` (the dynamic-workflow engine) | [workflows](docs/system-specs/modules/workflows.md) |
| themes | [themes](docs/system-specs/modules/themes.md) + [theming-contract](website/docs/theming-contract.md) |
| anything under `website/` | [`website/AGENTS.md`](website/AGENTS.md) |
| user-facing strings, dates, numbers, sort order | [i18n-catalog](website/docs/i18n-catalog.md) (authoring) + [i18n-gates](docs/ci/i18n-gates.md) (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](docs/system-specs/common/testing-conventions.md) + the [writing-tests](src/kiro_crew/builtin_skills/kirocrew-dev/writing-tests/SKILL.md) skill; frontend and Electron tests: [website/docs/testing.md](website/docs/testing.md) |
| browser E2E | [e2e-gate](docs/ci/e2e-gate.md) |
| proving a worktree change against an isolated running gateway | [worktree-verification-recipes](docs/guides/worktree-verification-recipes.md) |
| CI, PR flow, review gates (a lane says PASS or BLOCK, with a Trigger and an Outcome), commit messages | [ci-and-reviews](docs/ci/ci-and-reviews.md) + [CONTRIBUTING.md](CONTRIBUTING.md) |
| a PR that hides, deletes, tightens or migrates something (the `Reader:` list) | [take-away-changes](docs/system-specs/common/take-away-changes.md) |
| constants, comments, lint, code style, the brand name | [code-style](docs/system-specs/common/code-style.md) |
| connections, connectors, an external account link | [connections](docs/system-specs/modules/connections.md) |
| the connector campaign's manifest schema or work-stream DAG | [connector-capability-manifest](docs/system-specs/modules/connector-capability-manifest.md) |
| the GitHub connector's operation data or wire parsing (pagination, rate limits, error mapping) | [connector-github](docs/system-specs/modules/connector-github.md) |
| `connections/vendors/microsoft/graph/`, the Microsoft Graph runtime base (locator, payload shaping, `@odata.nextLink` paging) | [microsoft-graph-runtime](docs/system-specs/modules/microsoft-graph-runtime.md) |
| `connections/vendors/zoom/` — Zoom identity/paging/processing/errors contract logic | [connector-zoom](docs/system-specs/modules/connector-zoom.md) |
| a POSIX call: locks, signals, PIDs, chmod, RSS | [platform-compat](docs/system-specs/common/platform-compat.md) + [windows-install](docs/guides/windows-install.md) |
| injected `[Cron notification]` / `[Subagent completion event]` | [injected-messages](docs/system-specs/common/injected-messages.md) |
| build, install, dev mode | [CONTRIBUTING.md](CONTRIBUTING.md) + [install](docs/guides/install.md) |
| cutting a release | [release](docs/build/release.md) |
| `CHANGELOG.md` | [changelog](docs/build/changelog.md) |
| a user-facing label, wording, placement or behaviour a person may already have decided | [docs/decisions/README.md](docs/decisions/README.md) |
| errors, retries, user-facing failure text | [error-handling](docs/system-specs/common/error-handling.md) |
| what this public fork must never re-introduce | [oss-fork-boundaries](docs/system-specs/oss-fork-boundaries.md) |
| any doc: moving, renaming, indexing it | [docs/README.md](docs/README.md) |

The whole doc tree is indexed from [`docs/README.md`](docs/README.md). User-facing
docs that ship in the package live in `src/kiro_crew/docs/` and are indexed by
[its README](src/kiro_crew/docs/README.md).

## Security invariants (do NOT weaken)

Detail and rationale: [security](docs/system-specs/modules/security.md),
[governance](docs/system-specs/modules/governance.md),
[computer-use](docs/system-specs/modules/computer-use.md).

- **Keystone.** `security_policy.json`, `profiles/`, `admission_policy.json` and
  `computer_use.json` under the data home are the ceiling the agent is governed by.
  **The enforcement point is the OS layer in `sandbox.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), or `VISIBLE`
  (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 an `open()` 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.py`
  pins the union of the three dispositions equal to the crew-home half of
  `security.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.key` is `VISIBLE`, 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 a `SCOPE_CATALOG` data change, never
  an evaluator edit.
- **`CONTRACT_VERSION` stays pinned at 1 pre-launch.**
- **Never restate the denied-rule count in prose.**
  `test/test_denied_commands_security.py` pins it, and a restated count goes stale
  silently.
- **A cron script body is never a shell-gate subject.** `is_sensitive_bash_command`
  and `is_denied` read a SHELL COMMAND LINE; `mcp_cron._vet_script_contents` scans 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 stop
  `open(a + b)`. Do not add a `subject_is_*` flag, a `_traversal_subjects`
  re-pointing, or an `is_sensitive_source_body` back. A new script detector is a
  whole-body match in `_vet_script_contents`, or a sandbox mask. Pinned by
  `test_the_shell_gate_has_no_source_body_entry_point` and
  `test_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`/`busybox` before restructuring).
- **The sandbox's SCOPE is the operator's to widen, never yours.** What
  `sandbox.py` and its `sandbox_*` 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