Contributing to kolu

In 2026, anyone can ask a coding agent for a 500-line PR in an afternoon. The bottleneck isn't who writes the code — it's who agrees to maintain the feature. So we keep the conversation about what to build separate from the conversation about how to build it.

TL;DR

• Trivial fix? Open a PR directly.
• New user-facing feature, behavior change, or anything reasonable people might disagree about? Open a proposal first.

1. Trivial PRs — open directly

No proposal needed for: bug fixes that restore obvious behavior, build/packaging/CI fixes, doc typos, behavior-preserving refactors, or tests for existing behavior.

2. Proposals — what and why, not how

Anything user-facing — new shortcuts, settings, UI, defaults, persisted data, or new runtime dependencies — needs a merged proposal before any implementation PR.

A proposal is an Atlas note — a markdown/MDX file in docs/atlas/src/content/atlas/. Pick the kind that fits what you're proposing and mark it status: proposed. Create <your-slug>.mdx with this frontmatter:

---
title: Your proposal, in Title Case
description: One line — what changes from the user's perspective.
kind: feature        # the category it belongs in — feature · bug · analysis · reference
status: proposed     # proposed → accepted → implemented (or superseded)
maturity: seedling
---

Then write the body — Summary · Motivation · User-facing behavior · Prototype (optional) · Implementation notes (optional) — run just atlas::build to render it, and open a PR adding the .mdx and its generated docs/atlas/dist/<slug>.html (the ci::atlas-sync gate checks the two stay in sync). Your note appears in the Atlas index under its category, flagged proposed — nothing to wire up, and authorship is just the git history.

Discuss on the PR. Once accepted, a maintainer flips the note to status: accepted — that's the whole graduation; the kind was right from the start. The note stays a living document afterward (git is its record — there is no frozen copy).

Your PR may optionally bundle an implementation alongside the proposal — but acceptance merges only the proposal. The implementation is reviewed and merged separately (by you or anyone, including a maintainer running /be), so the decision to ship the idea never rides on the state of the code.

Implementation details are optional — the "Implementation notes" section is for hints; skip it if you don't have an opinion. The implementer figures out the how.

Drafts welcome

Open the PR as a GitHub draft if you're still brainstorming or have open questions you want directional feedback on. Mark it ready for review when the questions narrow.

Why proposals matter

A merged proposal under your authorship is a substantial contribution in its own right — clarifying a vague idea into a concrete, debatable document is half the work, and the implementation usually follows mechanically. Proposals from people who never write the code are welcome and valued.

Feature PRs that skip the proposal step will be closed with a pointer back here. It's the only way to keep the project's surface area honest.

Using AI

Coding agents are great at fleshing out a proposal — motivation, alternatives, edge cases, open questions. Use them. What we don't want is an AI-drafted implementation of a feature nobody has agreed to ship.

Implementer notes

For /do, /test, /ci, formatter, and other implementer-side conventions, see .agency/do.md.