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

Breeze doesn’t have a public roadmap. Work is captured as plan documents in docs/superpowers/plans/. 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 roadmap — it’s what there is to build.
• The approval — if a plan exists and is in the open lane, 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

Open plans live in one folder:

The open lanedocs/superpowers/plans/open/ — plans that are up for grabs right now.

Everything in the plans/ root (400+ files) is completed, shipped work kept for history — ignore it when looking for something to do. Only open/ is live.

1. Browse docs/superpowers/plans/open/. Each file is a complete work order: goal, architecture, tech stack, a linked design spec, and - [ ] task checkboxes.

2. Pick one that fits your appetite. The plan’s own header tells you the blast radius — some are small UI/CRUD jobs, some touch deeper systems.

3. Give Todd a heads-up that you’re taking it (so two people don’t grab the same plan). Then start.

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. Drop the finished plan in docs/superpowers/plans/open/ and share it with Todd.

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 you implemented in the PR description.

4. Open it against main. Once it merges, the plan moves out of open/ into the plans/ archive — the open lane always reflects only what’s still available.

Note

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