Contributing To Kairo

Keep contributions small, local-first, and easy to verify.

Before You Change Code

Read AGENTS.md for repo rules and package boundaries.
Read docs/SRS.md when behavior, privacy, storage, or product scope is involved.
Read docs/SDD.md when architecture, package boundaries, or runtime design is involved.
Check TASKS.md for the current phase and acceptance criteria.

For full repository setup, use docs/developer.md.

corepack enable
pnpm install
pnpm run doctor

Keep apps thin. Put reusable logic in packages/core, packages/shared, or packages/utils.
Define shared types and schemas once in @kairohq/shared.
Put pure cross-package helpers in @kairohq/utils.
Keep observation, event, session, memory, and render logic in @kairohq/core.
Do not add web frameworks, ORMs, queues, or new dependencies without a clear task requirement.
Do not observe outside the project root.
Do not log secrets.

Run the smallest relevant check first:

pnpm --filter @kairohq/core test event-store
pnpm --filter @kairohq/core typecheck

Use broader checks when touching shared packages or release-level behavior:

pnpm --filter @kairohq/shared test
pnpm --filter @kairohq/utils test
pnpm run doctor

Run pnpm run doctor before a release, a phase boundary, or a broad shared change.

Update the root README only for setup changes.
Add product requirements to docs/SRS.md.
Add architecture or implementation decisions to docs/SDD.md or docs/decisions/.
Add source adapter guidance to docs/sources/adapter-authoring.md.
Add benchmark notes to docs/benchmarks/.

Public packages use Changesets.

pnpm changeset
pnpm version-packages
pnpm release

CI runs pnpm install --frozen-lockfile and pnpm run doctor.