Contributing

ZeroStarter develops on canary (the default branch, and the one every PR targets). main is release-only: changes reach it through the release process, never a direct commit. So a contribution has one shape: branch off canary, keep the docs in the same commit as the code, and open a PR back into canary.

Where to start

Read AGENTS.md (symlinked to CLAUDE.md) first. It holds the repo's load-bearing conventions for humans and agents alike: @/ imports, single-line comments, and the design skill for anything UI. Then run the codebase-map skill to orient; it maps where things live and how a change flows across the stack. From there, load the task skill that fits (api-endpoint, db-migration, ...).

Make the change

Branch off canary with a descriptive name (feat/..., fix/...), then run the checks before you push:

bun audit --audit-level high   # the first CI gate
bun run format
bun run lint
bun run check-types
bun run test
bun run build

Two rules from AGENTS.md are non-negotiable:

• Docs move with code. When you change a convention, structure, or tooling, update its doc and skill in the same change. Docs must never drift: it's the rule the whole agent workflow rests on.
• No co-author trailer. Never add Co-authored-by to a commit message.

Commit with Conventional Commits: feat, fix, docs, refactor, chore, and the rest. Commitlint enforces the type on the commit-msg hook, so a malformed message is rejected before it lands.

Open the PR

Describe the change and its motivation, note any migration steps, and link related issues. For a breaking change or a large feature, open an issue first to agree on the approach. By contributing you agree to the MIT license.

Next

• Code Quality: the lint, format, and commit hooks your PR runs through.
• Release Management: how canary becomes a versioned main release.