Branch Workflow

All development happens on feature branches. Direct pushes to main are forbidden — enforced by GitHub branch protection.

Branch Naming

Lowercase, hyphen-separated, max 50 chars.

External Contributors (Fork & PR)

External contributors don't have write access to the repo. Use the fork-and-PR model:

# 1. Fork the repo (GitHub UI) and clone your fork
git clone https://github.com/<your-username>/Brain.git
cd Brain

# 2. Add upstream remote
git remote add upstream https://github.com/the-brain-dev/The-Brain.git

# 3. Sync and branch
git fetch upstream
git checkout -b feat/your-feature upstream/main

# 4. Work, test, commit, push to your fork
git push origin feat/your-feature

# 5. Open a PR against the-brain-dev/Brain:main

See Contributing for the full workflow including the contribution gate (lgtm/lgtmi).

Internal Agent Workflow

For maintainers and AI agents with repo access:

# Create branch
git checkout main && git pull origin main
git checkout -b <prefix>/<description>

# Work, test, lint
bun test && bun run lint

# Commit (conventional, targeted add only)
git add <specific-files>
git commit -m "type(scope): description"

# Push and open PR
git push origin <branch>

Multi-Session Branches

When working on the same feature across multiple sessions:

# Session start — sync with main
git checkout <my-branch>
git pull origin main --rebase

# Work, commit, push as usual
git push origin <my-branch>

Before opening a PR: rebase on latest main, resolve only conflicts in files you authored. Never force push.

Commit Convention

type(scope?): concise description

Types: feat, fix, refactor, docs, chore, test, perf

Examples:
  feat(harvester): add Gemini CLI harvester plugin
  fix(spm): prevent double-evaluation during promote()
  docs: update CLI reference with --reprocess flag

Forbidden Operations

These can destroy work or bypass review:

• git push origin main — blocked by branch protection
• git push --force / git push -f — rewriting shared history
• git reset --hard, git checkout ., git clean -fd — destroy uncommitted work
• git add -A / git add . — sweeps up changes from other contributors

Branch Protection Rules

GitHub Ruleset main enforces on ~DEFAULT_BRANCH:

CodeQL runs on every PR and push to main via .github/workflows/codeql.yml. Weekly scheduled scan on Mondays at 08:00 UTC.

CI runs bun test and bun run lint on every PR — both must pass before merge.

Releasing

the-brain uses Changesets for independent versioning — each package has its own version. Core can be 2.0 while a plugin stays at 1.4.

Creating a Changeset (per PR)

When your PR changes package code, run:

bunx changeset

The CLI will ask which packages changed, the bump type (patch/minor/major), and a description. Commit the generated .changeset/*.md file alongside your code.

How Releases Happen

1. Merge PRs with changesets → bot collects pending changes
2. Bot opens a "Version Packages" PR showing bump details and generated changelogs
3. Review and merge the Version Packages PR
4. On merge: npm publish + GitHub Release (automated)

No manual version bumps. No scripts/release.ts. The bot handles everything.

Bump Semantics

When in doubt: patch. Most changes are additive and non-breaking.