Kiro Crew Documentation

This directory is the contributor and architecture documentation. It is not shipped to users: the docs that ship inside the Python package live in ../src/kiro_crew/docs/, and frontend-specific docs live in ../website/docs/.

New here? Start with guides/install.md, then architecture/overview.md.

Where things live

Directory	What it is for
guides/	Install, run, and operate Kiro Crew. Task-oriented.
architecture/	How the system fits together, one doc per cross-cutting concern.
build/	Packaging, signing, and releasing.
ci/	Everything that gates a pull request.
app-kit/	Building apps that run inside Kiro Crew (third-party developer docs).
design/	Proposals for changes agreed before they are built.
system-specs/	Change-control contracts. The doc a code change MUST update in the same commit.
request-for-change/	Proposals and decision records for large or contested changes.
blog/	Essays on direction and design philosophy. Arguments, not contracts.
reference/	Upstream documentation we mirror but do not author.
task-specs/	Archived per-task specs. Not current context.

The rule for changing docs

A code change that alters documented behavior MUST update the docs in the same commit. Concretely:

1. Find the one owning doc. Every subsystem has exactly one. The routing table in ../AGENTS.md maps subsystem to doc; system-specs/modules/ is the usual home.
2. Update it, do not add a second doc. Prefer editing the existing doc over creating a new one. Two docs on one subject diverge, and then a reader cannot tell which is true.
3. Update every index that points at it when you add, move, rename, or delete a doc: this file, the directory's own README.md, and any doc that links to it.
4. Do not write a changelog into a doc. No Last Updated: line, no "previously/used to/we now" narration, no PR numbers or commit SHAs. Git records history; the doc states current behavior in present tense.
5. Run the gate: ./scripts/docs-lint.sh. It fails on a broken internal link, a doc no index reaches, a directory with no index, a code comment citing a doc that does not exist, a renamed doc whose filename is hardcoded in code, and a git conflict marker left at the start of a line.

Two constraints that are easy to miss:

• src/kiro_crew/docs/ filenames are an API. That tree is packaged, is read at runtime by tips.py (gated by tips_allowlist.py), and specific filenames are hardcoded in dashboard Settings panels. Renaming a file there is a code change. The tree is also flat by design: setup.cfg's package_data glob does not recurse, so a subdirectory would ship in the sdist but not the wheel.
• User-facing docs belong in that packaged tree, not here. An internal engineering note that lands in it ships to every pip install.