Skip to content

CLAUDE.md

Latest commit

 

History

History
517 lines (435 loc) · 34.2 KB

CLAUDE.md

File metadata and controls

517 lines (435 loc) · 34.2 KB
Raw

CLAUDE.md

GBrain is a personal knowledge brain and GStack mod for agent platforms. Pluggable engines: PGLite (embedded Postgres via WASM, zero-config default) or Postgres + pgvector

  • hybrid search in a managed Supabase instance. gbrain init defaults to PGLite; suggests Supabase for 1000+ files. GStack teaches agents how to code. GBrain teaches agents everything else: brain ops, signal detection, content ingestion, enrichment, cron scheduling, reports, identity, and access control.

North Star

gbrain aims to be the next Postgres for memory: the most well-tested, widest-coverage, best-for-the-most-at-the-least retrieval + agent memory system for company brains and personal AI, built to serve a billion people. Every feature and every eval is judged against this bar. "gbrain is best" is a WHOLE-SYSTEM claim — proven across the full BrainBench suite (retrieval, longmemeval, calibration, …) — not by any single feature. When scoping an eval, prove the FEATURE delivers value to gbrain users; do not waste it proving that gbrain's particular algorithm beats some other algorithm (a research bake-off, off-mission).

Two organizational axes (read this first)

GBrain knowledge is organized along two orthogonal axes. Users AND agents must understand both, or queries misroute silently.

  • Brain — WHICH DATABASE. Your personal brain is host. You can mount additional brains (team-published, each with their own DB and access policy) via gbrain mounts add (v0.19+). Routing: --brain, GBRAIN_BRAIN_ID, .gbrain-mount dotfile.
  • Source — WHICH REPO INSIDE THE DATABASE. A brain can hold many sources (wiki, gstack, openclaw, essays). Slugs scope per source. Routing: --source, GBRAIN_SOURCE, .gbrain-source dotfile.

Both axes follow the same 6-tier resolution pattern. Read docs/architecture/brains-and-sources.md for topology diagrams (personal, team mount, CEO-class with multiple team brains) and skills/conventions/brain-routing.md for the agent-facing decision table.

Architecture

Contract-first: src/core/operations.ts defines 100+ shared operations (including volunteer_context — push-based context, see docs/guides/push-context.md — and the seven frozen MEMORY_VERBS recall/remember/entity/synthesize/forget/context_pack/delta — the last two are v0.45.7 ambient-recall boundary verbs (budget-packed pack + "what changed since"), all seven stamp protocol_version: 1, servable alone via gbrain serve --surface verbs, see docs/protocol/MEMORY_VERBS_v1.md + docs/guides/ambient-recall.md). CLI and MCP server are both generated from this single source. Engine factory (src/core/engine-factory.ts) dynamically imports the configured engine ('pglite' or 'postgres'). Skills are fat markdown files (tool-agnostic, work with both CLI and plugin contexts).

Trust boundary: OperationContext.remote distinguishes trusted local CLI callers (remote: false set by src/cli.ts) from untrusted agent-facing callers (remote: true set by src/mcp/server.ts). Security-sensitive operations like file_upload tighten filesystem confinement when remote=true and default to strict behavior when unset.

Cross-cutting invariants (must-never-violate, regardless of which file you touch). Per-file detail is in docs/architecture/KEY_FILES.md.

  • Trust is fail-closed. OperationContext.remote is REQUIRED on the type. Anything not strictly false is treated as remote/untrusted (ctx.remote === false for trusted-only sites; ctx.remote !== false for untrust-unless-explicit-false). Don't default it falsy.
  • Source isolation. Every read-side op routes through sourceScopeOpts(ctx); precedence is federated array (ctx.auth.allowedSources) > scalar (ctx.sourceId) > nothing. Don't hand-roll source filtering — a missed thread is a cross-source data leak. Corollary (unscoped-check/scoped-write): engine.getPage with no opts matches ANY source while putPage defaults to 'default' — an existence check + write pair must scope the read to the write's source (getPage(slug, { sourceId: x ?? 'default' })). Guarded by scripts/check-getpage-scoped-write.mjs (opt-out marker gbrain-allow-unscoped-getpage for read-only first-match sites).
  • JSONB: never JSON.stringify into a ::jsonb cast. postgres.js double-encodes it (a jsonb string scalar); PGLite hides the bug. This bites BOTH spellings — the template form (${JSON.stringify(x)}::jsonb) AND the positional form (executeRaw(\…$N::jsonb`, [JSON.stringify(x)]), the #2339 class that aborted every sync). Fix: pass a raw object to engine.executeRaw/ useexecuteRawJsonb/sql.json(); or for the positional path bind through $N::text::jsonb(binds as text, the cast parses it). Guarded byscripts/check-jsonb-pattern.sh(template grep) +scripts/check-jsonb-params.mjs(positional AST scanner); the real backstop is the DATABASE_URL-gated e2e parity tests, since PGLite can't surface the bug. Full rule indocs/ENGINES.md`.
  • Engine-live paths avoid runtime dynamic import() for helper dependencies. In both engines, src/core/migrate.ts, src/core/engine-sql/ and src/core/schema-migrations/, helpers use static top-level imports. Exceptions: the snapshot loader's lazy require() cluster in pglite-engine.ts:tryLoadSnapshot (lazy so production builds skip the test-fixture path; the snapshot hash reads the FILE BYTES of the schema import closure, src/core/snapshot-schema-inputs.ts, never loaded modules, so coverage can't skew it) and the four ai/gateway.ts lookups in both engines' initSchema() and _upsertChunksOnce(), each lazy inside a local try/catch because eagerly evaluating the gateway's large provider/config closure could turn a recoverable default/config-row fallback into a module-load failure. Each exception carries engine-dynamic-import-ok on the import line; scripts/check-engine-dynamic-import.sh enforces the rule (it matches require() too). For history use git log -G'await[[:space:]]+import\\(', not -S: a dynamic-to-static rewrite can keep the token while changing its context.
  • Engine parity. Both engines implement every BrainEngine method. A migrated storage domain's SQL lives once in src/core/engine-sql/<domain>.ts and both engines delegate to it (domains: the migrated rows of scripts/engine-sql-baseline.tsv; check:engine-sql-ratchet fails on new SQL in an engine; mark truly dialect-specific code // engine-sql-ok: <reason>). Executor contract, RLS read brands, capabilities: docs/ENGINES.md ("Storage domains and engine-sql"). Pinned by test/e2e/engine-parity.test.ts. Forward-referenced columns/indexes go in src/core/engine-sql/bootstrap.ts (guarded by test/schema-bootstrap-coverage.test.ts).
  • Contract-first. src/core/operations.ts is the single source; CLI + MCP are generated from it. Every op carries scope: 'read'|'write'|'admin' + optional localOnly. HTTP dispatch enforces scope/localOnly before the handler runs.
  • Migrations + schema text. One file per schema migration in src/core/schema-migrations/ (bun run new:migration <name>; migrate.ts is the runner; regenerate registry.generated.ts, never hand-merge it). Fresh-install DDL has one hand-edited copy, src/schema.sql + its TS fragments; bun run build:schema generates both engine blobs. CREATE INDEX CONCURRENTLY needs transaction: false (pre-drop invalid remnants on Postgres; plain CREATE INDEX on PGLite via sqlFor.pglite).
  • Multi-source. Slug uniqueness is (source_id, slug), not slug. Key batch ops and reverse-writes on the composite key; validateSourceId before any source_id path join.
  • One canonical chat-pricing table. All paid-cloud chat/completion prices live ONCE in src/core/model-pricing.ts (CANONICAL_PRICING + canonicalLookup). Every other table (anthropic-pricing.ts's ANTHROPIC_PRICING, the contradictions/cross-modal/skillopt cost views) is a DERIVED view, never a hand-copied duplicate — so cross-table price drift is structurally impossible (takes-quality reads pricing.overrides, then canonical). Update a price in model-pricing.ts only; each consumer keeps its own miss policy, not its own numbers. Pinned by test/model-pricing.test.ts (drift guard asserts each view equals canonical). Embeddings price separately in embedding-pricing.ts (different unit).
  • Module-size ratchet. scripts/module-size-limits.tsv pins per-file line ceilings (check:module-size in verify): growth over a ceiling, >50 lines of stale slack after a shrink, a row for a deleted file, and any UNLISTED src file over 1,500 lines all fail. Raise a ceiling only via a reviewer-visible TSV edit in the same commit; lower it in the same commit as any peel. check:function-size ratchets functions the same way (scripts/function-size-baseline.tsv): no new function over 300 lines.
  • Peeled façades keep their surface. operations.ts (src/core/ops/*), both engines (src/core/engine-sql/*, src/core/{postgres,pglite}-engine/*), migrate.ts (src/core/schema-migrations/*), doctor.ts (src/commands/doctor/registry.ts + checks/*), sync.ts (src/commands/sync/*; reusable clusters in src/core/sync-*), serve-http.ts (serve-http-<area>.ts mount<Area>(app, ctx) modules), cli.ts (src/cli/command-table.ts + src/cli/commands/*), jobs.ts (src/commands/jobs/*, handlers in src/core/minions/handlers/*), hybrid.ts (src/core/search/hybrid/* stages), autopilot.ts and skillpack.ts (src/commands/skillpack/*) re-export everything they always exported — import sites and published package exports never chase the peel. New code goes in the module dirs, not back into the façades (CONTRIBUTING.md "Where does my change go?"). Engine modules take narrow explicit deps (never an engine-shaped bag); source-text guards read test/helpers/source-surface.ts, and the flag-registry generator's facadeExpansion keeps peeled flag text in each command's scan surface.
  • Coverage is measured, honestly. CI merges per-lane lcov (scripts/merge-lcov.ts) into a PR-corpus report on every run (advisory until the diff gate graduates via COVERAGE_GATE_ENFORCE) and a nightly fullCorpus number incl. the full e2e glob. bun facts: unique --coverage-dir per process (reuse overwrites lcov.info), line records only (JSC omits function names), no subprocess coverage (cli.ts is exempt as a documented undercount), never-loaded files are a count+list, never fake all-files math.

Reference map (load on demand)

CLAUDE.md is the always-loaded orientation + dispatcher. Detailed reference loads on demand — read the linked doc before working in that area.

When you're working on... Read first
any file in src/ (what it does + its invariants) docs/architecture/KEY_FILES.md — choose the subsystem, then find the file's entry
search / ranking / hybrid / retrieval docs/architecture/RETRIEVAL.md + the search/* entries in KEY_FILES.md
search modes / cost knobs docs/guides/search-modes.md
engine detection / Postgres adoption / DB-access repair / degraded serve (engine status, db-repair, init --prefer-postgres, GBRAIN_DB_ACCESS) docs/ENGINES.md ("Engine detection and access repair" + "Local Postgres")
embedding spend gates / cost gate / spend.posture / off switches docs/operations/spend-controls.md
the monthly backup-coverage check (gbrain backup, render channels, nag budget) docs/operations/backup-check.md + the backup/* entries in KEY_FILES.md
push-based context (volunteer/watch/reflex window) docs/guides/push-context.md
checkpoint compaction / compiled context files (gbrain compile-context) docs/guides/checkpoint-compaction.md + docs/guides/ambient-recall.md
ambient memory writeback (opt-in unprompted fact capture — memory.auto_writeback, harness instruction blocks, Stop-hook backstop, read-time TTL) docs/guides/ambient-writeback.md + the ambient-writeback cluster in KEY_FILES.md
Memorable integration / session receipts / relay consent (integrations.memorable.*) docs/memorable-agents.md + the hook-heartbeat/capture-spec/codex-hooks entries in KEY_FILES.md
chat connectors (live ChatGPT/Claude history sync — gbrain connectors) docs/guides/chat-connectors.md + the src/core/connectors/* entries in KEY_FILES.md
schema packs / page types / extraction docs/architecture/schema-packs.md, type-taxonomy.md, lens-packs.md
thin-client / remote MCP / cross-modal docs/architecture/thin-client.md
publishing the brain's MCP server to other devices and agents (gbrain mcp expose, Tailscale default, Grok Bot / Muse hosted path) docs/guides/remote-mcp.md + docs/mcp/DEPLOY.md + the remote-mcp skill
memory verbs / MCP tool surface (--surface) / conformance docs/protocol/MEMORY_VERBS_v1.md + the verbs*/surface.ts/protocol.ts entries in KEY_FILES.md
the CLI surface (commands + flags) gbrain --help / gbrain --tools-json, plus the relevant KEY_FILES.md entry
adding a storage method, migration, doctor check, CLI-only command, HTTP route or sync phase CONTRIBUTING.md ("Where does my change go?"); branches from before refactor wave 1: docs/architecture/wave-1-porting.md
running, writing or retiring tests docs/TESTING.md (authoring gate, retiring)
bulk-command progress wiring docs/progress-events.md
eval methodology / metrics docs/eval/
brains vs sources / topology docs/architecture/brains-and-sources.md, topologies.md
google connector (Gmail/Calendar/Contacts, OAuth) / credential vault docs/guides/google-connect.md + the creds/* + google/* entries in KEY_FILES.md
open loops / gbrain waiting / commitment extraction docs/guides/open-loops.md + the loops* entries in KEY_FILES.md
skill routing skills/RESOLVER.md
agent bootstrap (paste-in install, hooks, gbrain bootstrap, sweep, keyless) docs/guides/bootstrap.md + docs/designs/AGENT_BOOTSTRAP_PLAN.md + the KEY_FILES bootstrap cluster
shipping a release / CHANGELOG / PR conventions docs/RELEASING.md (ship IRON RULES stay inline below)

Maintaining CLAUDE.md and the reference docs

An append-only per-file index once grew CLAUDE.md to ~592KB. The rules that keep it from recurring:

  • CLAUDE.md is orientation, not the implementation spec. It carries the North Star, the two axes, architecture + cross-cutting invariants, the resolver, and the inline IRON RULES. Per-file/per-command/per-test detail lives in the reference docs and loads on demand.
  • Reference docs (key-files/*.md, thin-client.md, TESTING.md) describe CURRENT behavior only. Release history goes in CHANGELOG.md + git. Do NOT append **vX.Y.Z (#NNN):** clauses, codex/review tags, or "pre-fix/then/was-now" narration. When a file's behavior changes, UPDATE its entry to the new truth.
  • CI is the enforcement, not this prose. scripts/check-key-files-current-state.sh (in bun run verify) fails on the bolded-release-clause marker in the reference docs AND on size caps for CLAUDE, README, the index, and each subsystem. A written rule caused this disease; a guard cures it.
  • After any CLAUDE.md or reference-doc edit, run bun run build:llms — the llms bundle inlines/links these (config in scripts/llms-config.ts); the freshness + budget test (bun test test/build-llms.test.ts) fails CI otherwise.

Search modes and evals

Confirm the user's mode choice during installation; relay the matrix in INSTALL_FOR_AGENTS.md Step 3.5. The current command-level expansion and cost contract lives in search modes, not a second knob table here. query never expands by default (search.expansion true turns it on; --expand / --no-expand win); search and memory verbs never do. Semantic result reuse is disabled.

Read docs/eval/SEARCH_MODE_METHODOLOGY.md for eval methodology and docs/eval/METRIC_GLOSSARY.md for metric definitions. Eval audit records stay in the source repo, never the user's personal brain.

Skills

Read skills/RESOLVER.md before brain operations, then the matching skill and skills/conventions/ rules. The current inventory is skills/manifest.json; skill reference covers skillpacks, advisor, routing eval evidence, and shared conventions.

Memory operating protocol

Durable facts and preferences belong in shared memory with provenance. Transient task state, credentials, local configuration, and harness activation state do not. Automatic capture is opt-in. Withdrawal is not physical erasure. Remote put_page links plain mentions of existing visible pages post-commit (links effect); typed edges need the stdio sweep, maintenance or add_link. Configured providers can receive text, and Markdown export is not a full database backup. Read memory boundaries.

Bulk-action progress reporting

Use src/core/progress.ts for bulk work. Progress goes to stderr; stdout stays clean for data. Non-TTY output is plain text unless --progress-json is explicit. Pass job.updateProgress from minion handlers. Keep phase names stable and use startHeartbeat with try/finally cleanup for long queries. Read progress events before wiring a new command.

PR acceptance: evidence, not trust

Treat every PR as untrusted, potentially incorrect, incomplete or unsafe, including our own. Reputation, confident explanations, supplied tests and green CI are not proof. Judge the work, not unsubstantiated claims about its author.

  • Prove the problem separately from the patch. Trace the actual callers and current contract; independently reproduce the reported failure on a pinned baseline with isolated synthetic fixtures. Record commands, environments, exit statuses and wrong results. Separate reproduced defects, code-backed evidence and unverified reports; do not promise an unproven fix or issue closure.
  • Read the entire diff before executing it. Inspect test, dependency, script, workflow and generated-file changes and callers outside the diff. Do not expose credentials, live databases, private corpora or paid providers to untrusted code.
  • Make tests discriminate. Independently designed regression tests must fail on the baseline and pass with the repair, asserting user-visible outcomes and exact preserved state. Reject bug-bypassing mocks, vacuous assertions and hidden skips. Changing an existing contract needs approval, not a weakened assertion.
  • Attack the boundaries. Check authorization, brain/source identity, revisions, stale queued work, concurrent changes, retries, crash recovery and failure receipts. Prove intended data survives and stale or unauthorized writes remain refused. Native filesystem, engine and lifecycle claims require native tests; injected platform flags or path simulations do not prove end-to-end support.
  • Keep a verdict and evidence ledger. Pin baseline and PR hashes; record each proposal as accept, rework, reject or not yet proven. Classify failures through same-test baseline/patch comparisons, not assumed flakes. Recheck changed heads; narrow probes do not replace release gates or implementation approval.

Fix waves: ONE PR

A fix wave ships as ONE PR unless the user overrides this for that wave. Parallel tasks are fine; integrate reviewed work into one branch with reviewable commits. Do not open per-issue or per-task PRs, or a PR stack.

  1. Investigate the named issues and adjacent failures in the same safety boundary. Apply the acceptance standard above. Exclude unrelated features; record deferrals and unresolved reports rather than assuming closure.
  2. Run /plan-ceo-review and /plan-eng-review. Incorporate recommendations within the requested scope, respecting the user's directions on review decisions. Explain the revised plan in plain language (ELI10) and wait for approval before product implementation. A plan review is not implementation or merge consent.
  3. Implement only the approved scope, integrate and verify the whole wave, then use /ship and the full gates in docs/RELEASING.md, including the community-wave security scan. Publish one PR; do not merge without approval.

Capturing test output (NEVER pipe through tail / head)

Preserve full logs and the real exit status; piping tests into tail can hide failures. Save output first, then inspect the file:

bun test > /tmp/ship_units.txt 2>&1
rc=$?
cat /tmp/ship_units.txt
printf 'EXIT=%s\n' "$rc"
exit "$rc"

The same rule applies to typecheck, local CI, migrations, and evals. Keep every failure for triage; do not report a green check from truncated output.

Sync and backfill pacing

Read backfill pacing before tuning sync locks, checkpoint resume, or DB-contention-aware pace mode.

Build

bun build --compile --no-compile-autoload-bunfig --outfile bin/gbrain src/cli.ts

Version locations (single source of truth: VERSION file)

Every release updates the required version stamps in the table below. bun run release:restamp rewrites all of them, renumbers the branch's own schema migrations after master's and runs the auto-derived regenerations; run it when the PR is next to merge (how). Update TODOS only when filing new work. /ship's Step 12 idempotency check catches VERSION vs package.json drift; the canonical list lives here.

Version format is mandatory: MAJOR.MINOR.PATCH.MICRO (four numeric segments, dot-separated, no leading v). Every new release MUST use the 4-segment form. The .MICRO slot is the dot-suffix follow-up channel: a release whose commit subject shipped ahead of its VERSION bump is corrected as 0.31.4.1, not by churning the patch number to 0.31.5. Suffixes like -fixwave are still allowed as needed (0.31.1.1-fixwave), but the four numeric segments are required first. Historical 3-segment versions (0.31.3, 0.22.1) remain valid in git log and migration filenames (skills/migrations/v0.21.0.md); do NOT rewrite them. Going forward only.

Required (every release must update every row):

File What lives there Format
VERSION The single source of truth. Read first by /ship, the binary, and CI version-gate. Bare 4-segment string MAJOR.MINOR.PATCH.MICRO (e.g. 0.31.4.1), no leading v.
package.json Bun/npm package version. gbrain --version reads it via the compiled binary's bundled package metadata. CI version-gate cross-checks this against VERSION and fails if they drift. "version": "0.31.4.1"
CHANGELOG.md Top entry header ## [0.31.4.1] - YYYY-MM-DD plus the "To take advantage of v0.31.4.1" block. Standard Keep-a-Changelog header.
TODOS.md Any TODO entries that mention "follow-up from vX.Y.Z.W" use the version of the release that filed them. Update only when filing NEW follow-up TODOs. Inline vX.Y.Z.W references in TODO bodies.
openclaw.plugin.json OpenClaw plugin manifest (v0.45.6.0, #4033). Hand-maintained; test/openclaw-plugin-manifest.test.ts fails the suite if it drifts from package.json. Merges from master auto-resolve it to master's version — re-bump it with the trio. "version": "0.45.12.0"
.codex-plugin/plugin.json + .claude-plugin/plugin.json Codex + Claude Code plugin manifests. Hand-maintained; test/codex-plugin-manifest.test.ts fails the suite when either drifts from package.json (the bump is now a FIVE-file lockstep: VERSION, package.json, openclaw.plugin.json, and both plugin manifests). Merges from master auto-resolve them to master's version — re-bump with the version set. "version": "0.46.7.0"
BOOTSTRAP_FOR_AGENTS.md Runbook stamp on line 1. scripts/check-bootstrap-tag.sh (in bun run verify + CI) fails when it drifts from VERSION; refresh it in the same commit as the bump. <!-- gbrain-runbook-stamp: X.Y.Z.W -->
templates/bootstrap/template-repo/ Vendored template tree with an embedded version stamp. Auto-derived, but NOT by bun install: run bun run scripts/generate-template-repo.ts --out templates/bootstrap/template-repo after the bump; scripts/check-bootstrap-templates.sh fails CI on drift. <!-- gbrain-template-stamp: X.Y.Z.W --> in generated files.

Auto-derived (no manual edit; refreshed by their own commands):

  • plugin/ + plugin-variants/ — the committed codex/claude plugin skill tree AND the persona variant trees (gbrain-coding, gbrain-daily) embed a gbrain-plugin-tree-stamp: X.Y.Z.W (the variants' generated plugin manifests carry the version too), so every version bump drifts them. Regenerate after the bump: bun run scripts/generate-plugin-tree.ts --out plugin --variants-out plugin-variants (guarded by scripts/check-plugin-tree.sh in bun run verify; the release publish-codex-plugin job also drift-gates it before publishing).
  • bun.lock — root-package version is auto-pinned from package.json. After bumping package.json, run bun install to refresh the lockfile.
  • llms-full.txt / llms.txt — auto-generated documentation bundles. Any CLAUDE.md edit MUST be followed by bun run build:llms in the same commit (or a follow-up commit before push). The committed bundles are checked against fresh generator output by test/build-llms.test.ts, which runs in CI shard 1, not in verify: a clean typecheck does not mean a CLAUDE.md edit can be pushed.

Historical (DO NOT bump on release):

  • skills/migrations/v0.21.0.md — migration files use the version they shipped FROM as their filename. v0.21.0's migration always says v0.21.0.
  • src/commands/migrations/v0_21_0.ts — same: migration code references the schema version it migrates to.
  • test/migrations-v0_21_0.test.ts, test/migration-orchestrator-v0_21_0.test.ts, test/migrate.test.ts — migration tests reference historical migration versions; these are correct as-is and should not move.
  • src/core/db.ts, src/core/migrate.ts, src/core/import-file.ts, src/commands/reindex-code.ts — code comments cite the release that introduced a feature. Once written, these are historical record.
  • README.md — references the latest published feature names by version (e.g. "v0.21.0 Code Cathedral"); update only when the README's marketing copy is intentionally being refreshed, NOT on every micro/patch bump.

Always use PATCH without asking, including the initial release choice; override /ship's MINOR/MAJOR prompts. Auto-allocate past collisions, sync all version stamps and the PR title, then report the number. This changes numbering only: scope, merge, deployment, paid-work and validation approvals still apply. CI rejects mismatched VERSION/package.json or versions not newer than master.

Version consistency and conflict recovery

After version-related edits or merges, verify VERSION, package.json, and the top CHANGELOG entry agree before proceeding. Read the version recovery checklist for conflict resolution and the pre-push audit. Historical versions stay historical.

Conductor branch-name = workspace-name (IRON RULE)

In a Conductor workspace, the branch tail must match the workspace directory name before shipping or creating a PR. Check basename "$PWD" against git branch --show-current. Use the ship workflow to resolve a mismatch; do not silently rename unrelated branches or delete remote branches.

Releasing

Before shipping, read docs/RELEASING.md in full and use /ship. Never hand-roll ship operations. It owns version allocation, CHANGELOG, review, test coverage, and release documentation. Scope and consent still apply: shipping instructions do not authorize a merge, deployment, or release the user has excluded. Community waves also require bun run wave-security-scan <base>..<head>.

Post-ship requirements (MANDATORY)

Run /document-release after every /ship; the ship workflow's automatic run counts, but a skipped/failed run must be completed. Check README, the relevant docs/architecture/key-files/ entries, guides, CHANGELOG, and TODOS. Update CLAUDE only for always-loaded rules or routing changes. It is a map, not a log; per-file current behavior belongs in subsystem references, release history in CHANGELOG and Git.

"Say to your agent" rule: every feature doc addresses the END USER (IRON RULE)

Public feature docs need 1–3 natural-language prompts alongside CLI examples: **Say to your agent:** *"<outcome the user wants>"*. When a skill backs the feature, use phrases from its actual frontmatter triggers. For CLI-only features, name the command the agent will run rather than implying an unavailable skill. Use generic placeholders. A reader should know what to ask without translating flags into prose.

Privacy rule: scrub real names from public docs

Never reference real people, companies, funds, or private agent names in any public-facing artifact. Public artifacts include: CHANGELOG.md, README.md, docs/, skills/, PR titles + bodies, commit messages, and comments in checked-in code. Query examples, benchmark stories, and migration guides MUST use generic placeholders.

Why: gbrain runs a personal knowledge brain containing notes on real people and real companies (YC founders, portfolio companies, funds, investors, meeting attendees). When a doc copies a query like gbrain graph diana-hu --depth 2 or names a specific agent fork like Wintermute, that real name gets indexed by search engines, surfaced in cross-references, and distributed with every release.

Name mapping to use in examples:

  • Agent forks → your agent fork, a downstream agent, or agent-fork
  • Example person → alice-example, charlie-example, or a-founder
  • Example company → acme-example, widget-co, or a-company
  • Example fund → fund-a, fund-b, fund-c
  • Example deal → acme-seed, widget-series-a
  • Example meeting → meetings/2026-04-03 (generic date is fine)
  • Example user → you or the user, never a proper name

Specific rule: never say Wintermute in any CHANGELOG, README, doc, PR, or commit message. When the temptation is to illustrate with the real fork name:

  • Reader-facing copy → your OpenClaw (covers Wintermute, Hermes, AlphaClaw, and any other downstream OpenClaw deployment in one term the reader already recognizes).
  • First-person / origin-story copy → Garry's OpenClaw (honest that this is the production deployment driving the feature, without exposing the private agent's name).

Wintermute may appear in private artifacts (scratch plans under ~/.gstack/projects/…, memory files, conversation transcripts, CEO-review plans) — those aren't distributed. Anything checked into this repo or shipped in a release must use the OpenClaw phrasing above. Sweeping a stale reference is a small clean-up PR, not a debate.

When in doubt, ask yourself: "Would this query reveal private information about the user's contacts, investments, or portfolio if it were read by a stranger?" If yes, replace with generic placeholders.

Illustrative API examples with household-brand companies (Stripe, Brex, OpenAI, GitHub, etc.) are fine — they're public entities, not contacts in anyone's brain. Do not confuse illustrative API examples with queries that reveal real relationships.

Responsible-disclosure rule: don't broadcast attack surface in release notes

Describe security fixes functionally in public artifacts. Do not publish a curated list of sensitive tables, affected records, or exposure windows that helps probe unpatched installs. Describe the mechanism, upgrade/repair commands, and user impact; keep detailed exposure analysis in private investigation artifacts. A reader should learn how to update, not how to target old installs. This applies to README, CHANGELOG, docs, PRs, commits, issues, and release pages.

PR title format — version FIRST (IRON RULE)

PR titles and version-bump commit subjects start with the version, followed by the conventional-commit subject:

vMAJOR.MINOR.PATCH.MICRO <type>(<scope>): <summary> (#issue or wave ref)

Put the version first, never parenthesized at the end. Apply this when creating or editing a PR through the host's supported workflow.

Skill routing

When the user's request matches an available skill, ALWAYS invoke it using the Skill tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. The skill has specialized workflows that produce better results than ad-hoc answers.

NEVER hand-roll ship operations. Do not manually run git commit + push + gh pr create when /ship is available. /ship handles VERSION bump, CHANGELOG, document-release, pre-landing review, test coverage audit, and adversarial review. Manually creating a PR skips all of these. If the user says "commit and ship", "push and ship", "bisect and ship", or any combination that ends with shipping — invoke /ship and let it handle everything including the commits. If the branch name contains a version (e.g. v0.5-live-sync), /ship should use that version for the bump.

Key routing rules:

  • Product ideas, "is this worth building", brainstorming → invoke office-hours
  • Bugs, errors, "why is this broken", 500 errors → invoke investigate
  • Ship, deploy, push, create PR, "commit and ship", "push and ship" → invoke ship
  • QA, test the site, find bugs → invoke qa
  • Code review, check my diff → invoke review
  • Update docs after shipping → invoke document-release
  • Weekly retro → invoke retro
  • Design system, brand → invoke design-consultation
  • Visual audit, design polish → invoke design-review
  • Architecture review → invoke plan-eng-review
  • Save progress, checkpoint, resume → invoke checkpoint
  • Code quality, health check → invoke health

Shared knowledge and skills

New local brains keep knowledge and a useful memory skillpack in one recorded content root. Shared publication, own-principal following and editing have separate authority; ordinary memory writes never imply skill editing or script execution. Native router installation is not proof of native use. Read shared brain skills and its key-file contracts before changing this lifecycle.