​

Releasing & contributing (modusbrain)

​

Pre-ship requirements

• bun run ci:local runs the entire stack inside Docker: gitleaks (host), guards + typecheck, then 4-shard parallel unit + E2E against four pgvector containers plus a transaction-mode PgBouncer service (unit phase keeps DATABASE_URL unset; --no-shard for the legacy sequential flow). Stronger than PR CI’s 2-file Tier 1 set; closer to what nightly Tier 1 catches. Spins up + tears down postgres automatically via docker-compose.ci.yml. Override the host port with MODUSBRAIN_CI_PG_PORT=5435 bun run ci:local if 5434 collides.
• bun run ci:local:diff runs only the E2E files matched by the diff selector (scripts/select-e2e.ts), falling back to ALL E2E files on unmapped src/ paths or schema/skills/package.json changes. Fast iteration during a focused branch.

• bun test — unit tests (no database required)
• Follow the “E2E test DB lifecycle” steps above to spin up the test DB, run bun run test:e2e, then tear it down.

1. bun run test (npm script in package.json) — includes bun run typecheck plus the four shell pre-checks (check-jsonb-pattern.sh, check-progress-to-stdout.sh, check-trailing-newline.sh, check-wasm-embedded.sh) before the runner. Use this mid-branch.
2. bun run typecheck — tsc --noEmit standalone. Fast (~5s on this repo).
3. bun run ci:local — the full local CI gate from Path A.

​

CHANGELOG + VERSION are branch-scoped

• Does CHANGELOG have your branch’s own entry separate from master’s entries?
• Is VERSION higher than master’s VERSION?
• Is your entry the topmost ## [X.Y.Z] entry?
• grep "^## \[" CHANGELOG.md shows a contiguous version sequence?

• Lead with what the user can now do that they couldn’t before. Sell the capability.
• Plain language, not implementation details. “You can now…” not “Refactored the…”
• Never mention internal artifacts: plan file IDs, decision tags (D-CX-#, F-ENG-#), review rounds, codex findings, subcontractor credits. These are invisible to users.
• Put contributor-facing changes in a separate ### For contributors section at the bottom.
• Every entry should make someone think “oh nice, I want to try that.”

• “Codex caught X that the CEO review missed” — private process detail.
• “D-CX-3 split errors/warnings” — tag is meaningless to users; name the feature instead.
• “Fix-wave PR #N supersedes #M” — supersede chains belong in PR bodies, not release notes.
• “215 new cases, 3 decisions applied, 7 reviews cleared” — these are planning-mode metrics.

• The user-facing change: what commands exist now, what flag was added, what behavior fixed.
• Numbers that mean something to the user: TTHW, commands that timed out before, detection counts.
• Upgrade instructions: modusbrain upgrade + any manual step if needed.
• Credit to external contributors when a community PR was incorporated.

​

CHANGELOG voice + release-summary format

• Any mention of review processes (CEO review, eng review, codex review, plan-eng-review, outside voice, adversarial review, autoplan, /review).
• “What we caught and fixed before merging” sections. Bugs found pre-merge are not changes — they’re things that didn’t ship.
• Plan file references, plan IDs, plan decision tags (D1, D14, D-CDX-3).
• Migration version drama (“originally v68”, “renumbered to v77”, “claimed by parallel waves”) — just say “Migration v79 adds X.” If the user cares about migration ordering, they read the diff.
• Round counts, finding counts, decision counts (“25 findings across 2 rounds”, “8 architectural decisions”, “5/6 expansions accepted”).
• Names of internal collaborators (“codex caught”, “the reviewer flagged”, “Claude noticed”).
• “Plan + reviews” summary bullets. The plan lives in ~/.claude/plans/; if a future reader wants the backstory they can grep there.
• Any wording that frames a shipped feature as a recovery from a planning mistake (“the first plan was wrong”, “we corrected the approach”, “the shipped version supersedes the original design”).

​

Release-summary template

1. One-line bold headline. What changed for the user, in human English. No jargon. No internal terms. Example good: “Your search stops boosting weak pages just because they have a lot of links pointing at them.” Example bad: “PostFusionOpts gains floorRatio; KNOBS_HASH_VERSION bumped 2→3.”
2. Plain-English opener (~3-5 sentences). Describe the problem this fixes in everyday terms. Pretend the reader has a brain full of meeting notes and people pages and wants to know if this release helps them. Concrete example beats abstract description.
3. A “How to turn it on” or “How to use it” section with paste-ready commands. Real flags, real config keys. This is where precision starts.
4. A “What you’d see in a concrete example” or “The X numbers that matter” section with a table. Use everyday-language column headers (“Page”, “Match quality”, “Has many backlinks?”) even when the underlying mechanism is technical. The table teaches what the feature does without requiring the reader to understand how.
5. A “What’s safe to know about” or “Things to watch” section for caveats, side effects, cache invalidation, mid-deploy notes. Still in plain language.
6. A “What we caught and fixed before merging” section if the work went through review (CEO/eng/codex/outside-voice). Translate review findings into plain English. “We caught a stale-cache bug” beats “knobsHash() did not include floorRatio in the v=2 hash input.”
7. ### Itemized changes (precision lives here). File paths, function names, types, constants, line numbers. This section is for engineers who need to know exactly what moved.

• No em dashes (use commas, periods, ”…”).
• No AI vocabulary (delve, robust, comprehensive, nuanced, fundamental, etc.) or banned phrases (“here’s the kicker”, “the bottom line”, etc.).
• Real numbers, real file names, real commands AFTER the ELI10 lead. Not “fast” but “~30s on 30K pages.” In the ELI10 lead, “fast enough that you won’t notice” or “~30 seconds even on a big brain.”
• Short paragraphs, mix one-sentence punches with 2-3 sentence runs.
• Connect to user outcomes: “the agent does ~3x less reading” beats “improved precision.”
• Be direct about quality. “Well-designed” or “this is a mess.” No dancing.

• CHANGELOG.md previous entry for prior context
• Latest modusbrain-evals/docs/benchmarks/[latest].md for headline numbers (sibling repo)
• Recent commits (git log <prev-version>..HEAD --oneline) for what shipped
• Don’t make up numbers. If a metric isn’t in a benchmark or production data, don’t include it. Say “no measurement yet” if asked.

​

”To take advantage of v[version]” block (required, v0.13+)

## To take advantage of v[version]

`modusbrain upgrade` should do this automatically. If it didn't, or if `modusbrain doctor`
warns about a partial migration:

1. **Run the orchestrator manually:**
   ```bash
   modusbrain apply-migrations --yes

2. Your agent reads skills/migrations/v[version].md the next time you interact with it. [One sentence on whether headless agents need manual action, or whether the orchestrator already handled the mechanical side.]
3. Verify the outcome:
   [release-specific verify commands, e.g. `modusbrain graph ... --depth 2`]
   modusbrain stats
   
4. If any step fails or the numbers look wrong, please file an issue: https://github.com/thebuildceo/modusbrain/issues with:
   • output of modusbrain doctor
   • contents of ~/.modusbrain/upgrade-errors.jsonl if it exists
   • which step broke
   This feedback loop is how the modusbrain maintainers find fragile upgrade paths. Thank you.

**Skip this block** for patches that are pure bug fixes with zero user-facing action
(rare). If the release has a schema migration, data backfill, or new feature the
user needs to verify, the block is required.

The v0.13.0 entry in CHANGELOG.md is the canonical example.

### Itemized changes (the existing rules)

Below the release summary, write `### Itemized changes` and continue with the
detailed subsections (Knowledge Graph Layer, Schema migrations, Security hardening,
Tests, etc.). Same rules as before:

- Lead with what the user can now DO that they couldn't before
- Frame as benefits and capabilities, not files changed or code written
- Make the user think "hell yeah, I want that"
- Bad: "Added MODUSBRAIN_VERIFY.md installation verification runbook"
- Good: "Your agent now verifies the entire ModusBrain installation end-to-end, catching
  silent sync failures and stale embeddings before they bite you"
- Bad: "Setup skill Phase H and Phase I added"
- Good: "New installs automatically set up live sync so your brain never falls behind"
- **Always credit community contributions.** When a CHANGELOG entry includes work from
  a community PR, name the contributor with `Contributed by @username`. Contributors
  did real work. Thank them publicly every time, no exceptions.

### Reference: v0.12.0 entry as canonical example

The v0.12.0 entry in CHANGELOG.md is the canonical example of the format. Match its
structure for every future version: bold headline, lead paragraph, "numbers that
matter" with BrainBench-style before/after table, "what this means" closer, then
`### Itemized changes` with the detailed sections below.

## Version migrations

Create a migration file at `skills/migrations/v[version].md` when a release
includes changes that existing users need to act on. The auto-update agent
reads these files post-upgrade (Section 17, Step 4) and executes them.

**You need a migration file when:**
- New setup step that existing installs don't have (e.g., v0.5.0 added live sync,
  existing users need to set it up, not just new installs)
- New SKILLPACK section with a MUST ADD setup requirement
- Schema changes that require `modusbrain init` or manual SQL
- Changed defaults that affect existing behavior
- Deprecated commands or flags that need replacement
- New verification steps that should run on existing installs
- New cron jobs or background processes that should be registered

**You do NOT need a migration file when:**
- Bug fixes with no behavior changes
- Documentation-only improvements (the agent re-reads docs automatically)
- New optional features that don't affect existing setups
- Performance improvements that are transparent

**The key test:** if an existing user upgrades and does nothing else, will their
brain work worse than before? If yes, migration file. If no, skip it.

Write migration files as agent instructions, not technical notes. Tell the agent
what to do, step by step, with exact commands. See `skills/migrations/v0.5.0.md`
for the pattern.

## Migration is canonical, not advisory

ModusBrain's job is to deliver a canonical, working setup to every user on upgrade.
Anything that looks like a "host-repo change" — AGENTS.md, cron manifests,
launchctl units, config files outside `~/.modusbrain/` — is a ModusBrain migration
step, not a nudge we leave for the host-repo maintainer. Migrations edit host
files (with backups) to make the canonical setup real. Exceptions: changes
that require human judgment (content edits, renames that break semantics,
host-specific handler registration where shell-exec would be an RCE surface).
Everything mechanical ships in the migration.

**Test:** if shipping a feature requires a sentence that starts with "in
your AGENTS.md, add…" or "in your cron/jobs.json, rewrite…", the migration
orchestrator should be doing that edit, not the user.

**The exception is host-specific code.** For custom Minion handlers
(host-specific integrations like inbox sweeps or third-party API scanners), shipping them as a
data file the worker would exec is an RCE surface. Those get registered in
the host's own repo via the plugin contract (`docs/guides/plugin-handlers.md`);
the migration orchestrator emits a structured TODO to
`~/.modusbrain/migrations/pending-host-work.jsonl` + the host agent walks the
TODOs using `skills/migrations/v0.11.0.md` — stays host-agnostic, still
canonical.

## Schema state tracking

`~/.modusbrain/update-state.json` tracks which recommended schema directories the user
adopted, declined, or added custom. The auto-update agent (SKILLPACK Section 17)
reads this during upgrades to suggest new schema additions without re-suggesting
things the user already declined. The setup skill writes the initial state during
Phase C/E. Never modify a user's custom directories or re-suggest declined ones.

## GitHub Actions SHA maintenance

All GitHub Actions in `.github/workflows/` are pinned to commit SHAs. Before shipping
(`/ship`) or reviewing (`/review`), check for stale pins and update them:

```bash
for action in actions/checkout oven-sh/setup-bun actions/upload-artifact actions/download-artifact softprops/action-gh-release gitleaks/gitleaks-action; do
  tag=$(grep -r "$action@" .github/workflows/ | head -1 | grep -o '#.*' | tr -d '# ')
  [ -n "$tag" ] && echo "$action@$tag: $(gh api repos/$action/git/ref/tags/$tag --jq .object.sha 2>/dev/null)"
done

​

PR descriptions cover the whole branch

​

Community PR wave process

1. Categorize — group PRs by theme (bug fixes, features, infra, docs)
2. Deduplicate — if two PRs fix the same thing, pick the one that changes fewer lines. Close the other with a note pointing to the winner.
3. Collector branch — create a feature branch (e.g. thebuildceo/fix-wave-N), cherry-pick or manually re-implement the best fixes from each PR. Do NOT merge PR branches directly — read the diff, understand the fix, and write it yourself if needed.
4. Test the wave — verify with bun test && bun run test:e2e (full E2E lifecycle). Every fix in the wave must have test coverage.
5. Close with context — every closed PR gets a comment explaining why and what (if anything) supersedes it. Contributors did real work; respect that with clear communication and thank them.
6. Ship as one PR — single PR to master with all attributions preserved via Co-Authored-By: trailers. Include a summary of what merged and what closed.

• Always AskUserQuestion before accepting commits that touch voice, tone, or promotional material (README intro, CHANGELOG voice, skill templates).
• Never auto-merge PRs that neutralize the Genthropic founder perspective.
• Preserve contributor attribution in commit messages.

​

Checking out PRs from thebuildceo-agents

1. gh pr checkout <N> — pull down the fork’s branch. Note the PR number and head branch name (gh pr view <N> --json headRefName --jq .headRefName).
2. git push origin HEAD:<branch-name> — push the same branch to the base repo (origin points at thebuildceo/modusbrain, not the fork). This is the move that gives CI access to secrets.
3. gh pr close <N> --comment "moving to base-repo branch for secret access" — close the fork PR so the queue stays clean.
4. gh pr create --base master --head <branch-name> — open the replacement PR from the base-repo branch. Preserve the original PR’s title and body verbatim (gh pr view <N> --json title,body); contributor attribution moves to a Co-Authored-By: trailer if needed.