Coding agents

The single source of truth for humans and coding agents (Copilot, Claude, Cursor, Hermes, etc.) working on Kailash OS is AGENTS.md in the kailash-os repository (default branch master). The companion guide for the kailash-packages overlay repo is AGENTS.md there. Tool-specific files (CLAUDE.md, .github/copilot-instructions.md) point at these; when anything disagrees, AGENTS.md wins.

Read them at the source — the GitHub-rendered pages are always current:

• kailash-os: project map, layer model and the manifest single-home rule, TDD standard with the layer map, the ADR process (docs/adr/), PR contract, labels, security rules (the distribution packages offensive tooling — the safety posture is deliberate and testable).
• kailash-packages: the overlay flake — pins, packaging shapes and the manifest rules that every other artifact generates from.

Architecture Decision Records

Structural changes carry an ADR in the same PR. Most slices are leaf-sized — the issue’s plan reference IS the design record, no ADR needed — write one only when the change introduces a new persistent artifact or removes or changes one: a manifest schema field whose semantics lock, a profile contract, a wire format, a gate script.

The record home is deliberately single: kailash-os docs/adr/ — the process and the record format. Overlay decisions land there too, with the PR that makes the change.

Rules with teeth:

• Accepted ADRs are immutable. A change that contradicts an accepted ADR supersedes it with a new one; the accepted record is never rewritten.
• Never invent discussion, deciders or quotes. Cite commit/issue permalinks, or write “No substantive technical discussion recorded”.
• Dependency bumps, docs and CI tweaks don’t need ADRs.

This page intentionally does not mirror either file: a mirror drifts the moment the repos move, and the source-of-truth rule (AGENTS.md wins) already says where to look.