Contributing Code with Claude Code

This guide is for people who want to write code for Breeze. It assumes you’ll work with Claude Code (or a compatible agent) — the repo ships a CLAUDE.md and a set of skills that hand the agent almost all the project’s conventions automatically. Your job is to point it at the right work and to hand back finished, self-reviewed, green PRs.

If you only want to report a bug or pitch an idea, you don’t need any of this — see the top of CONTRIBUTING.md.

The one idea to internalize

Work on Breeze is captured as plan documents. A plan spells out the goal, the architecture, the tech stack, and a checklist of tasks — it’s a ready-to-implement work order, written for an agent to execute.

That means a plan is two things at once:

• The work definition — it’s what there is to build.
• The approval — if a plan exists and has been approved, the what and the how are already agreed. You don’t need a separate sign-off to start.

Don't write feature code without an approved plan

The plan is the approval gate. If there’s no plan for what you want to do, the first deliverable is the plan — not the code. Write it, get a 👍, then build. This is the whole point of the workflow: we agree on the approach before anyone spends effort, so nothing gets built the wrong way.

1. Find something to build

Work tracking is moving to GitHub

This guide used to point at a folder of open plan documents in the repo. That folder has been reorganized and no longer reflects what’s actually up for grabs, so don’t mine docs/superpowers/plans/ for work — it’s an archive of completed, shipped plans kept for history. A GitHub-native replacement (issues, milestones, and a public roadmap) is in the works and this section will be updated when it lands.

Until then, find work on the issue tracker:

Help wantedOpen issues tagged for outside contributors.

Good first issuesSmaller, well-scoped starters.

1. Browse the open issues above, or any open issue that interests you.

2. Pick one that fits your appetite — some are small UI/CRUD jobs, some touch deeper systems.

3. Comment on the issue that you’re taking it (so two people don’t grab the same one). Then start with a plan, as below.

2. …or propose your own

Want to scratch your own itch? Great — but the plan comes first.

1. From the repo root, run Claude Code and use the brainstorming skill to pin down intent and requirements, then writing-plans to produce the plan document.

2. Share the finished plan with Todd — attach it to the GitHub issue you’re working from (open one if there isn’t one yet).

3. Wait for approval on the plan. Once it’s a 👍, it’s an open work order like any other — go build it.

Tip

Proposing via a plan doc — not a draft PR — keeps the PR queue meaning exactly one thing: “ready to merge.” Planning and in-progress work never sit in a PR.

3. Build it

1. Run Claude Code from the repo root so it loads CLAUDE.md and the project skills automatically. Don’t re-explain the conventions — they’re already in context.

2. Follow the plan’s REQUIRED SUB-SKILL note (usually subagent-driven-development or executing-plans). Work the - [ ] tasks in order and check them off.

3. Write tests as you go — the breeze-testing and test-driven-development skills cover the repo’s patterns (Drizzle mocks, Go table tests, the coverage checklist). New features are expected to ship with tests.

Some surfaces are Todd's call

CLAUDE.md flags high-blast-radius areas — tenant isolation / RLS, database migrations, auth, billing, and the org-erasure cascade contracts. If a plan leads you into one of these, follow the contract in CLAUDE.md exactly and flag it in the PR rather than improvising. When in doubt, ask before you touch it.

4. Before you hand it over

Two things are your responsibility, not Todd’s. A PR that skips them isn’t ready.

1. Make CI green yourself. Mirror the gate locally and get it passing before you open anything — test-api, test-web, and test-agent are the required jobs. You fix your own reds; a red PR isn’t on anyone’s plate yet.

2. Self-review your own diff. Run /code-review (or the pr-review-toolkit agents) against your changes, address what it finds, and then request a human review.

Local CI gate — exact commandsThe functional + security preflight that mirrors CI, in CONTRIBUTING.md.

5. Open the PR

A PR means done, green, self-reviewed, ready to merge — not a discussion venue and not work-in-progress.

1. Branch, and use Conventional Commits (feat:, fix:, docs:, …).

2. Keep it to one concern. Don’t mix a feature, a refactor, and a docs sweep in one PR — small, single-purpose PRs review fast.

3. Reference the plan and the issue you implemented in the PR description (Closes #NNN if the PR completes the issue).

4. Open it against main.

Note

Squash-merge is the norm on this repo; merge commits are disabled. Todd handles the merge.