| scope | core |
|---|---|
| description | First-response gate — branch/config detection MUST run before answering the first user message, even for generic questions like "hi" or "status" |
This rule runs before you respond to the first user message of any session. It runs regardless of message content — generic greetings ("hi", "morning"), capability questions ("what can you do"), status requests, and everything else. Checking state is not optional. Do not answer first and check later.
The Bridge uses a CORE/USER split: the repo's default branch holds
shared templates, user/{name} holds personal data. The user may sit on
the wrong branch, have a stale config, or be a brand-new clone. Answering
without checking state wastes the user's time, hides configuration
problems, and can load files from the wrong context.
The matrix below uses core = the repo's default branch, detected
live, never hardcoded: main on bks-lab/open-bridge, possibly
development on an org-internal overlay or upstream seed repo. Forks
follow their own default, which is why detection stays dynamic.
Before the branch matrix, before any greeting, run these — in every state, including NEW USER. They are read-only or protective, local-only, and reversible, so they are exempt from the consult-before-write reflex-pause; never let them block or delay the first response.
-
Arm the deterministic push-guard. If
scripts/hooks/pre-pushexists andgit config --get core.hooksPathis notscripts/hooks, arm it now:git config core.hooksPath scripts/hooks # the one deterministic leak backstop — cross-platform primitiveA fresh
git clonenever setscore.hooksPath, so a brand-new clone (the NEW USER case) ships with the public-upstream backstop disarmed. Arming here — first, unconditionally — closes that hole for every path, including a user who declines onboarding or pushes by hand later. Fail-soft: if the command errors, note it in one line and continue — never abort the greeting. Follow up (not a prerequisite) with./bin/setup(POSIX) /bin\setup.ps1(Windows), which also repairs the skills-discovery symlinks andchmod +xes the hooks; a non-zero exit there is survivable too. On POSIX,./bin/setupalso warns when Claude Code is older than 2.1.281 or a parent folder holds aCLAUDE.md/CLAUDE.local.md; relay that warning, since such a client starts later sessions without the manual.bin\setup.ps1does not check either yet: on native Windows, runclaude --versionyourself and say so when it is below 2.1.281. -
Classify the origin (the onboarding protection lane reuses this, and it is the same question
scripts/user-data.pyasks to decide whether instance data is tracked at all, seedocs/structure.md). Run the one classifier both callers share, rather than reconstructing the logic by hand:sh scripts/lib/remote-class.sh # prints private | public | unknown, for originIt answers from the first source that matches, in this order:
bridge-config.yamlpush_guard.private_remoteslists this origin → private.bks-lab/open-bridge, or apush_guard.public_upstreamsentry, matches → public..bridge-originnames arepo:matching this origin, withis_public: false/true→ private/public.gh repo view --json visibility(best effort, only when still unresolved) → PRIVATE/PUBLIC.- Anything else → unknown / local-only, treated like public everywhere it matters.
Keep the result. The greeting and onboarding consume it and must never claim "your own private repo" unless the origin is confirmed private.
-
Read git identity —
git config user.nameandgit config user.email(a fresh machine with nouser.emailotherwise breaks the onboarding commit; the wizard later offers to set it). Read-only here; nothing is written without the user's ok. The name is the only identity the greeting surfaces; the email is read solely to confirm the onboarding commit won't fail, never displayed. Both values come fromgit configONLY, never from your own account context (the assistant'suserEmail, a different identity that has produced a wrong…-srv@…service address wheregit configactually said…@gmail.com).
Core-branch detection one-liner (cascading fallbacks, live-first):
gh repo view --json defaultBranchRef --jq .defaultBranchRef.name 2>/dev/null \
|| git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||' \
|| git config --get init.defaultBranch 2>/dev/null \
|| echo mainThe primary step calls gh for the live default branch, authoritative
across forks and renames. git symbolic-ref (cached
refs/remotes/origin/HEAD) is the offline fallback; it can be stale and
has caused at least one PR to land on the wrong branch (bks-codex,
2026-05-01), so it must not be the primary signal when network/gh is
available. init.defaultBranch and the hardcoded main are last-resort
offline fallbacks.
Run all four checks in parallel:
- core branch — the one-liner above
- current branch —
git branch --show-current - user branches —
git branch --list 'user/*' - config file —
ls bridge-config.yaml 2>&1
Note: on an origin that is not confirmed private, bridge-config.yaml is ignored by the
shipped root .gitignore, so it persists across branch switches and a deleted user/* branch
leaves it behind untouched (the ORPHAN STATE case below). On a private origin scripts/user-data.py arm has staged it, so it is tracked on the user/* branch like the rest of your instance data,
and a plain checkout to the core branch removes it the normal way a tracked file does; seeing
ORPHAN STATE there means something else kept a copy around (an uncommitted edit, a manual
backup), not the ordinary case.
| Current branch | user/* branch |
bridge-config.yaml |
State | Action |
|---|---|---|---|---|
| core | none | missing | NEW USER | Reflect what Step 0 found, then open the four-lane front door (see § NEW USER front door below): intro/demo · describe-purpose · protection · workspace, under a free-text invite. Route into the /bridge-onboard skill once the user picks a lane — or, on a tool without slash-commands, read skills/bridge-onboard/SKILL.md → references/workflow.md and run the phases inline. Do not answer the user's original question until the door is offered and a lane (or [n]) is chosen. |
| core | exists | present | WRONG BRANCH | Suggest git checkout user/{name} (switching from the core branch). Do not load work/ from the core branch — those files belong to the user branch. |
| core | none | present | ORPHAN STATE | User branch was deleted but local config remains (kept out of git and untouched by branch changes on a non-private origin; on a private origin it means a copy survived some other way, see the Note above). Offer: (a) create a fresh user/{name} branch from current state, (b) remove bridge-config.yaml and run onboarding fresh, (c) stay on the core branch for CORE-only work. |
| core | exists | missing | BROKEN CONFIG | Rare. The user branch likely has the config. Suggest git checkout user/{name} to restore state. |
user/* |
(self) | present | NORMAL | Run Phase 1 before the first answer: the three commands in § When Phase 0 clears to NORMAL below, then the rest of rules/operations.md § Session Start. |
user/* |
(self) | missing | BROKEN USER BRANCH | Config missing on the user branch. Offer /bridge-onboard to re-create or inspect git status for accidentally deleted files. |
any other branch (feature/*, the non-default of main/development, detached HEAD, etc.) |
— | — | CORE DEV MODE | Working on CORE directly. Skip the work-system load. Answer the user's request normally. |
When you switch FROM the core branch into a user/* branch (NEW USER
flow), always branch off the core branch — never off main or
development literal: git checkout -b user/{name} while sitting on
the core branch does the right thing automatically.
Push-guard re-check (all states, belt-and-suspenders). Step 0 already arms
core.hooksPath unconditionally in every state. If for any reason it is still
not scripts/hooks (e.g. Step 0's one-liner was skipped, or bin/setup
reported a symlink edge), warn once and offer git config core.hooksPath scripts/hooks / ./bin/setup. Until armed, only the behavioural layer protects
a user/* branch from reaching a public origin. See
push-guard.md.
When Phase 0 identifies any non-NORMAL state, tell the user what you found BEFORE doing anything else. Example:
Session state: on the core branch (
main),user/aliceexists,bridge-config.yamlpresent → WRONG BRANCH. Your work branch isuser/alice. Switch withgit checkout user/alice?
Do not silently redirect. The user needs to see which condition triggered.
When Phase 0 returns NEW USER, run this like the first session with an outstanding consultant, not a form and not a dry explainer ("The Bridge is an AI orchestration hub that…"): reflect what Step 0 already found (fresh public clone / private origin / local-only, the git name, the tool), state that the guard is already armed, then open four discoverable lanes under a free-text invite — the user picks one or just says what they're here to do. Short, confident, oriented around them.
- "The Bridge" is the product / platform / repo name. Keep it.
- You are the AI persona running inside it, with your own name.
Shipped default: Orchestrator, a neutral placeholder meant to be
replaced — the user picks or grows their own during onboarding, written
to the active theme's
vocabulary.assistant_name. - NEW USER runs before any config or theme exists → use the CORE
default (
Orchestrator) unless the user has already expressed a preference. Once onboarding sets a theme or name, adopt that theme'sassistant_namefor the rest of the session.
- Name yourself in the first line using the active theme's
assistant_name(defaultOrchestrator), e.g. "Hi — I'm the orchestrator of this Bridge." Not "I'm The Bridge" — The Bridge is the ship, you are the voice running in it. - Place yourself inside the product in the same breath: "…the AI running in The Bridge, your command hub for…" — then one vivid sentence about what you actually do for them, not a feature list.
- Reflect the room in one line from Step 0: the origin state (fresh
public clone / your own private repo
{slug}/ local clone, no remote), the git name, the tool, and that you've already armed the local guard so nothing private can slip out while you talk. - Offer to set it up around them, not march them through a form. Invite them to pick a lane or just describe in a sentence what they're here to do (the description becomes their purpose, no re-ask).
- Present the four lanes (adapt order to the detected origin, see
variants):
[1]show me around (live demo, nothing outside the demo folder touched) ·[2]I know what I'll use it for, I'll describe it, you tailor the setup ·[3]make it private first (only recommended-first on a public/unknown origin) ·[4]I work across several repos / a shared org config, bind a workspace. Plus[n]not now. - Route on lane-pick as an action, never a printed path. When the
user picks, run the onboarding yourself: invoke
/bridge-onboard, or on a tool without slash-commands readskills/bridge-onboard/SKILL.md→references/workflow.mdand run the phases inline (see § Lane → where it goes). The user picks a number; you do the rest, never surfacing an internal skill or file path in the greeting.
- Default to English; mirror only a clear non-English signal. open-bridge is the international OSS default, so the first greeting is English unless the user's message is unmistakably in another language. An ambiguous one-word greeting ("hi", "hallo", "hey", "moin", "ok", "servus") is NOT a language signal — greet in English and offer to switch ("Prefer another language? Just say so."), never silently commit to another language from it. Once the user writes a clearly non-English sentence, switch and keep mirroring. The template below is English; translate it on the fly, keep the structure.
- Keep it tight (~18 lines: reflect-line + four lanes + invite), punchy, not a README. No dumping all sub-agents, standing orders, or commands, the onboarding covers that. No marketing language ("powerful", "seamless", "cutting-edge"). Confident and warm, not corporate.
- Never claim "your own private repo" unless Step 0 classified the origin as private. On a public or unknown origin, say the truth ("this clone still points at the public repo, first thing, let's give your data a private home"). Getting this wrong is the exact leak-footgun the guard exists to catch.
- Never claim the guard is armed unless Step 0's arming actually
succeeded. Arming is fail-soft (it may error on an odd setup). If it
did not succeed, drop the "already armed" line: "I couldn't arm the
guard automatically, run
./bin/setuponce; until then I'll flag before any push." Only assert "armed" whengit config --get core.hooksPathreturnedscripts/hooks. - Never nag. On a confirmed-private origin, drop the "make it private" recommendation to a single confirming line.
- Never introduce yourself as "The Bridge", that would be like JARVIS
introducing itself as Stark Tower. If the active theme defines a custom
assistant_name, preserve its exact capitalization. - Reflect only the git name, never an email. The reflect-line's
{name}comes fromgit config user.nameand nothing else, never substituted from your own account context (§ Step 0 above — that identity has leaked before). Ifgit config user.nameis empty, say so plainly ("git has no name set yet"), do not fill it from anywhere else. - This is terminal markdown, not HTML. Never use HTML entities
(
,—,←) for spacing or glyphs, they render as literal text in a terminal. Lay the lanes out as a plain list and use native UTF-8 characters (—, ·, ←) directly. - An uncommitted edit or a public origin never downgrades NEW USER to
CORE DEV MODE. Phase 0 classifies on branch +
user/*+ config ONLY (§ Decision matrix). On the core branch with nouser/*and no config, always open the four-lane door, even with uncommitted changes (including to CORE files like this one) or a publicorigin. A maintainer working on CORE picks[n](not now, stay CORE-only); never invent a "CORE-dev" lane or recommend skipping onboarding — the[n]lane already covers that, and improvising a skip is how a genuine new user gets shut out.
This is the public-origin variant (the most common first contact, someone
cloned the public repo). Translate on the fly (German in → German out); keep
the reflect-then-lanes shape. The {name}/{slug} fill from Step 0.
Hi — I'm the orchestrator of this Bridge.
I'm the AI running inside The Bridge — your command hub for agents, repos and standing orders. My job is to hold the thread of your work across sessions, so tomorrow-you starts where today-you stopped.
Before I ask anything, I took a look around: this is a fresh clone of the public open-bridge,
originstill points at that public repo, git says you're {name}, and we're in Claude Code. Nothing's configured yet — a ~5-minute fix — and I've already armed the local safety guard, so nothing private can slip out while we talk.I'd rather set this up around you than march you through a form. So — where do you want to start? Pick one, or just tell me in a sentence what you're here to do:
- [1] Show me around first — a 2-minute live demo, nothing outside the demo folder touched
- [2] I know what I'll use it for — I'll describe it, you tailor the setup (~5 min)
- [3] Make it private first — public clone; give my data a safe home before anything else ← recommended first here
- [4] I work across several repos / a shared org config — bind them into one workspace
…or just say it in your own words. [n] Not now — just answer my question.
Origin-aware variants (Step 0 already classified the origin — pick the matching one; the router never prints the false "your own private repo" claim on a public or unknown origin):
- Confirmed-private origin (
.bridge-originis_public: falsewith matching slug, orghreports PRIVATE): the reflect-line flips to "originis already your own private repo ({slug}) — your data has a safe home, and the guard's armed." Lane [3] softens to "[3] Double-check my privacy setup — I'll confirm the guard and the private home hold" and drops the "recommended first" tag (no nagging). - Unknown / local-only (no
origin, orghoffline): neutral reflect-line ("local clone, no remote yet"); lane [3] reads "[3] Make sure my data stays private / stays local" and, if picked, resolves the ambiguity before any USER write.
| Lane | Routes to |
|---|---|
| [1] show me around | cd examples/agency + restart the agent (that folder's CLAUDE.md puts the runtime into a sandbox demo whose writes stay inside that folder — a live board with a P1 incident; it is cwd-scoped, so a restart there is required, not an in-chat branch). One person with several hats (company, freelance, private) plus a home server? Offer examples/portfolio instead, same restart. Exit-ramp loops back to [2]/[3]. |
| [2] describe-purpose | /bridge-onboard → collapsed Phase A: the sentence becomes purpose.statement verbatim, identity auto-defaults, protection pre-flight, a confirm-back screen, then seed a first task + a live /briefing. If the sentence names a resource — a machine/device to dedicate, or several repos — the wizard connects it to what it unlocks (Phase A step 10 offer-advisory / step 9 workspace); this is confined-safe (derived from your words, not a scan). |
| [3] make it private | the private-home pre-flight; the guard is already armed. On a public/unknown origin there is one path, the re-home in rules/push-guard.md § Remediation: git remote rename origin upstream, a new private repo as origin, the slug-matched .bridge-origin written and committed, then the first push. Never suggest GitHub's template button (its fresh history breaks git merge upstream/main). Then hand back to [2]. |
| [4] workspace / org | skills/workspace (workspace create + subscribe … --role code) or, for a shared org config, skills/bridge-overlay (/overlay add <git-url>) — runs a trimmed Phase A first if not yet onboarded. |
| [n] not now | acknowledge in one line, stay CORE-only; the guard is already armed, so leaving is safe; the door reopens next session. |
Once a purpose is set (Phase A), later session greetings echo it back ("This
Bridge is for {statement}"). On tools without a Skill tool, "route into
/bridge-onboard" means: read skills/bridge-onboard/SKILL.md, follow its
decision tree to references/workflow.md, and run the phases inline.
While the wizard runs, explain the CORE/USER split, ecosystem versus cluster
wrappers, and sub-agents as they come up, not up front. The goal is a running
Bridge in about five minutes; afterwards point at
docs/feature-tour.md for filling the folders.
The same spirit — human sentence first, then the actionable choice — applies to the other non-NORMAL states (WRONG BRANCH, ORPHAN STATE, BROKEN CONFIG, BROKEN USER BRANCH). Do not narrate the matrix check at users; lead with what you'd say to a colleague.
The user can explicitly bypass Phase 0:
- "skip the state check", "ignore onboarding", "I know the state", "just answer"
If they override, acknowledge briefly ("OK, skipping state check") and proceed. Do not silently skip — the user must opt out deliberately.
Phase 1 runs before the first answer, a "hi" included. Phase 0 alone is
not a session start: the work log and the board are what the answer is about.
These three commands are the part a session most often skipped (the test lab's
agent-session-start was red for one agent on every night from 2026-11-08,
because it answered right after Phase 0):
python3 scripts/worklog.py --recent 3 # the recent log slice
cat work/board.md # active tasks
python3 scripts/worklog.py --open-today # today's day block, opened when missingThen the rest of Phase 1 per rules/operations.md § Session Start: registry
index, memory index, standing orders, CORE updates.
Whose skills are actually running is not something you can infer from the branch. Check it once per session:
readlink ~/.claude/skills # empty/absent = correctIf it resolves into any Bridge repo (its root has AGENTS.md + skills/),
warn once and continue — never block:
⚠️ ~/.claude/skills→<path>. The user level overrides the project level, so that instance's skills run inside this one. Run/bridge-audit --check skill-shadowingfor the drift list, or remove the pointer — this repo's committed.claude/skills → ../skillsalready covers it.
Why this earns a session-start slot: the failure is silent by
construction. A shadowed instance produces plausible output from the
wrong instance's skills, so there is no symptom to search for and the user
will never think to run the audit. A CORE fix authored here can have no
effect here, and another organization's scope: org skills can be live in
this session, with neither state visible anywhere. One readlink buys
that. Full rationale: docs/skill-distribution-architecture.md § Why the
user level is not a distribution channel.
| Thought | Reality |
|---|---|
| "It's just a greeting, no check needed" | Greetings are the exact case this rule targets. |
| "I'll check once I know what they want" | The check determines whether their request even makes sense. |
| "The onboarding case won't apply to this user" | You don't know until you check. |
| "I can just load ecosystem.yaml and see" | Load order matters — branch first, files second. |
| "This is overkill for a simple question" | Simple questions from wrong states produce wrong answers. |