🪦 refactor(bro): delete first-run-onboarding ceremony — modern-agent UX#128
Merged
Conversation
Modern agents (Cursor, ChatGPT, etc.) don't onboard. They just work.
TMB's previous AskUserQuestion-driven ceremony asking name + branching
+ pr_target + protected was friction with no upside in the 80% case,
and it broke completely in headless `claude -p` mode (no Human to
answer).
User direction: 'Skip onboarding. Use defaults silently. Persist to
DB so memory survives across sessions. Welcome banner so user knows
bro is activated.'
## Behavior
**First contact** (config_get returns null) — bro silently writes:
- config: branching_model=github-flow, pr_target=main, protected=["main"]
- ledger: tmb_defaults_applied event
- NO identity row (its absence means 'user hasn't named themselves yet')
**Welcome banner is mandatory** — three variants documented in CLAUDE.md:
- First activation: 'Entering bro mode. First activation here — applied defaults: github-flow, main as PR target. Say `reonboard` to customize.'
- Returning, pending work: 'Welcome back — resuming issue #N: <title>.'
- Returning, idle: 'Welcome back. What are we doing?'
**`tmb_reonboard` is now the only path** to write identity rows or change
policy keys. Same skill, same UI, clearer framing (was 're-run onboarding').
## Removed
- `skills/tmb_first-run-onboarding/` (entire skill — 268 lines deleted)
- `tests/lint/onboarding-skill-contract.sh` (no skill to lint)
- `tests/dogfood/flows/01-onboarding/` (no ceremony to test)
- `run-all.sh` step that ran the deleted lint
## Added
- `tests/dogfood/flows/01-first-contact/` — regression test for the
no-onboarding doctrine. Asserts AskUserQuestion + identity_set are
NOT called on first contact (they're in tools-forbidden.json).
## Renamed (pre-1.0 clean break, no migration shim)
- Ledger event type: `tmb_onboarding_complete` → `tmb_defaults_applied`
- All fixtures, outcome.sql files, ENUMS.md, FLOWS.md updated in lockstep.
## CLAUDE.md changes
- First-action chain step 1 rewritten — silent default-write protocol
with explicit DO NOT WRITE identity row.
- New 'Welcome banner' section after first-action chain — mandatory
three-variant announcement spec.
- Routing table row 'Re-onboarding' → 'Configure / change settings'.
## FLOWS.md / FILES.md
- Renamed Flow 1 'First-Run Onboarding' → 'First Contact (defaults
applied silently)'. Sequence diagram redrawn — no AskUserQuestion
calls, just config_set ×3 + ledger_log + welcome banner.
- FILES.md skill index updated: removed first-run-onboarding row,
added the four reactive skills (concerns-protocol, direct-mode,
headless-fallback, mcp-error-handling, push-gate) introduced in
recent PRs.
## Fixture comments
- `empty.sql` — comment updated from 'first-run / onboarding' → 'first-contact'.
- `onboarding-{anonymous,named}.sql` — filenames retained for backward
compat (no flow renames needed); leading comments updated to reflect
the post-no-onboarding semantics.
## Local verification
- ✓ skill-frontmatter lint passes (18 skills)
- ✓ link-check passes (84 links)
- ✓ agent-line-budget passes
…ll-smoke PR #128 deleted tests/lint/onboarding-skill-contract.sh as part of the no-onboarding doctrine. The install-smoke Dockerfile still RUN'd it, breaking L0 in CI. Removing the step (was A5, renumbered subsequent A7 → A6 for sequence cleanliness).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
User direction (verbatim): 'Skip onboarding. Use defaults silently. Persist to DB so memory survives across sessions. Welcome banner so user knows bro is activated.'
Modern agents (Cursor, ChatGPT, etc.) don't onboard — they just work. TMB's previous AskUserQuestion-driven ceremony asking name + branching + pr_target + protected was friction with no upside in the 80% case, and broke completely in headless `claude -p` mode.
Behavior change
First contact (`config_get` returns null):
Returning sessions:
Welcome banner is now mandatory. Three documented variants in CLAUDE.md.
`tmb_reonboard` is the only path to write identity rows or change policy keys. Same skill, same UI, repositioned in description.
Files touched (23 files, +160 / −520 lines)
Deleted
Added
Renamed (pre-1.0 clean break, no migration shim)
Updated
Local verification
Test plan (after merge)
Followup (separate)
The 02-simple-task headless_fallback we proved works in PR #124's run is preserved. The other 3 wired flows should now pass thanks to: