Skip to content

Latest commit

 

History

History
408 lines (355 loc) · 29 KB

AGENTS.md

File metadata and controls

408 lines (355 loc) · 29 KB

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. The frontend has its own router, 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. 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.

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 + 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.

Security invariants (do NOT weaken)

Detail and rationale: security, governance, computer-use.

  • 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 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 made import kiro_crew.sandbox raise on main and failed every backend test at COLLECTION, including test_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 compatibility names 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 with capabilities.computer_use (rfc-crew-enterprise-edition, appendix "Desktop control"). Never add finer computer_use.* scopes, more capability rows, approval ordinals or pointer permits. Its refusals run in band on tools._dispatch, never at the fail-OPEN hooks gate, 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.

Never hardcode a model id

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.

Harness parity

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.

No built-in apps

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.

Specs and docs

  • 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. Treat docs/task-specs/ as an archive, never as current context.

Git

  • Do NOT proactively git commit. Commit only when asked.
  • Do NOT git push unless the user explicitly says to push. Being asked to commit is NOT permission to push.
  • main is 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 with git checkout <ref> -- .. To bring the main clone current, follow the kirocrew-worktree-dev skill.
<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.

PR description

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".

PR goal is frozen

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.

A review finding is a class, not a line

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.

CHANGELOG.md

  • 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.

The gate before you commit

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.py

The 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-ini MUST keep -n auto --dist loadgroup --max-worker-restart=2; a bare override silently drops --dist loadgroup and scatters @pytest.mark.xdist_group tests 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.

Cross-platform

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.

LLM-facing capabilities

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.

Injected messages are not the user

[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.

Harness safety

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.