Skip to content

Latest commit

 

History

History
383 lines (320 loc) · 23 KB

session-start.md

File metadata and controls

383 lines (320 loc) · 23 KB
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"

Session Start Detection (Phase 0)

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.

Why this rule exists

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.

Phase 0 — Detection

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.

Step 0 — Arm the guard, then classify (first, unconditional)

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.

  1. Arm the deterministic push-guard. If scripts/hooks/pre-push exists and git config --get core.hooksPath is not scripts/hooks, arm it now:

    git config core.hooksPath scripts/hooks   # the one deterministic leak backstop — cross-platform primitive

    A fresh git clone never sets core.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 and chmod +xes the hooks; a non-zero exit there is survivable too. On POSIX, ./bin/setup also warns when Claude Code is older than 2.1.281 or a parent folder holds a CLAUDE.md / CLAUDE.local.md; relay that warning, since such a client starts later sessions without the manual. bin\setup.ps1 does not check either yet: on native Windows, run claude --version yourself and say so when it is below 2.1.281.

  2. Classify the origin (the onboarding protection lane reuses this, and it is the same question scripts/user-data.py asks to decide whether instance data is tracked at all, see docs/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 origin

    It answers from the first source that matches, in this order:

    • bridge-config.yaml push_guard.private_remotes lists this origin → private.
    • bks-lab/open-bridge, or a push_guard.public_upstreams entry, matches → public.
    • .bridge-origin names a repo: matching this origin, with is_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.

  3. Read git identity — git config user.name and git config user.email (a fresh machine with no user.email otherwise 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 from git config ONLY, never from your own account context (the assistant's userEmail, a different identity that has produced a wrong …-srv@… service address where git config actually 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 main

The 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:

  1. core branch — the one-liner above
  2. current branch — git branch --show-current
  3. user branches — git branch --list 'user/*'
  4. 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.

Decision matrix

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.

Reporting the check

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/alice exists, bridge-config.yaml present → WRONG BRANCH. Your work branch is user/alice. Switch with git checkout user/alice?

Do not silently redirect. The user needs to see which condition triggered.

NEW USER front door

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.

Your name vs. the product name

  • "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's assistant_name for the rest of the session.

Required beats (in order)

  1. Name yourself in the first line using the active theme's assistant_name (default Orchestrator), 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.
  2. 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.
  3. 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.
  4. 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).
  5. 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.
  6. 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 read skills/bridge-onboard/SKILL.md → references/workflow.md and 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.

Rules

  • 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/setup once; until then I'll flag before any push." Only assert "armed" when git config --get core.hooksPath returned scripts/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 from git config user.name and nothing else, never substituted from your own account context (§ Step 0 above — that identity has leaked before). If git config user.name is 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 no user/* and no config, always open the four-lane door, even with uncommitted changes (including to CORE files like this one) or a public origin. 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.

Template — adapt the wording, keep the structure

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, origin still 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-origin is_public: false with matching slug, or gh reports PRIVATE): the reflect-line flips to "origin is 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, or gh offline): 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 → where it goes

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.

Override

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.

When Phase 0 clears to NORMAL

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 missing

Then the rest of Phase 1 per rules/operations.md § Session Start: registry index, memory index, standing orders, CORE updates.

Skill-shadowing tripwire (one command, cheap)

Whose skills are actually running is not something you can infer from the branch. Check it once per session:

readlink ~/.claude/skills    # empty/absent = correct

If 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-shadowing for the drift list, or remove the pointer — this repo's committed .claude/skills → ../skills already 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.

Red flags — rationalizations you must NOT use

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.