Skip to content

README.md

Latest commit

 

History

History
63 lines (54 loc) · 4.09 KB

README.md

File metadata and controls

63 lines (54 loc) · 4.09 KB
Raw

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.
feature-map/ Every dashboard feature, mapped to the nav path, page, and handler that own it. A lookup index.
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).
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, plus the dated implementation plans that execute them under plans/.
decisions/ The append-only record of product and design decisions a person on the team made. One immutable file per decision; grep it before changing a user-facing label, placement or behaviour.
blog/ Essays on direction and design philosophy. Arguments, not contracts.
reference/ A mirror of upstream kiro-cli documentation, with named local exceptions.
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. It walks four trees: this one, the packaged ../src/kiro_crew/docs/, ../website/docs/, and the markdown a builtin app ships under src/kiro_crew/apps/builtins/. That fourth tree is link-checked and fact-checked but exempt from the index rules, because an app's README, agent briefs and SKILL.md files are curated by its app.json rather than by a documentation index.

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.