Contributing

Constellation uses a develop → release/* → main GitFlow. The full rules live in the root CLAUDE.md; the shape is summarised here.

Branches

Branch	Purpose	Merges to
main	Production	—
develop	Integration — all feature work	main via release branch
feat/* / fix/* / refactor/*	Short-lived	develop via PR
release/*	Release stabilisation	main + back-merge to develop
hotfix/*	Emergency production fixes	main + back-merge to develop

Always cut new feature/fix/refactor branches from a fresh origin/develop into a fresh worktree — that keeps your main checkout usable for the next task and avoids stash/checkout churn:

git fetch origin
git worktree add -b feat/my-feature ../constellation-my-feature origin/develop
cd ../constellation-my-feature
# If you have a .mcp.json (Claude Code / Cursor / any MCP-using agent), mirror it; otherwise skip:
test -f ../constellation/.mcp.json && cp ../constellation/.mcp.json .
npm install

First-time MCP setup (if you don't have a .mcp.json yet): see tools/mcp-server/README.md.

After the PR merges, update your main checkout's local develop before deleting the branch (otherwise git branch -d fails with "not fully merged"):

cd ../constellation
git fetch origin
git checkout develop && git pull --ff-only origin develop
git worktree remove ../constellation-my-feature
git branch -d feat/my-feature

See CLAUDE.md "Task lifecycle" for the full PT → spec → worktree → PR → cleanup flow.

Release (release/*) and hotfix (hotfix/*) branches are exempt from the worktree rule and continue to use git checkout -b.

PR requirements

Every PR to develop must satisfy the Quality Gates CI job:

1. Ticket reference — #123 or ABC-123 in the PR title or body. Escape with [skip ticket].
2. Changeset fragment — a new file under .changeset/ describing user-visible impact. Escape with [skip changeset].
3. Spec for feat: PRs — at least one file added/modified under .ai/specs/ or .kiro/specs/. Escape with [skip spec].
4. SonarCloud green — bugs, vulnerabilities, high/medium code smells must be resolved.

Commits

Use Conventional Commits (feat:, fix:, chore:, refactor:, docs:). Include the task key in the PR title (e.g. feat(catalog): bulk import [CAT-12]) so the GitHub webhook auto-closes the linked Project Tracker task on merge.

Pre-push checklist

npx prettier --check "**/*.{ts,tsx,js,jsx,json,md}"
npx turbo run lint typecheck build test
npm run check:routes

All three must pass.