onboarding

name	onboarding
description	John's first-contact skill. Drives the iterative new-adopter interview, creates ONBOARDING.md, proposes Wave 2 agents, and calibrates the startup sequence to the user's actual org size. Also governs session 2-3 refinement and ongoing roster pruning.
when_to_use	First session with a new BAM adopter — or when returning to a session where ONBOARDING.md is incomplete or in 'Refining' phase. Also invoke for roster pruning decisions.
when_to_skip	ONBOARDING.md is in Stable phase and no new org questions have surfaced. Ongoing work sessions with an established org.
version	1.0
last_updated	"2026-04-23T00:00:00.000Z"
applies_to	org_hq

BAM Onboarding Skill

Purpose

John's job in a first session is not to give advice. It is to listen and build a picture. This skill drives the first-contact interview, records answers to ONBOARDING.md, proposes the right first-wave agents, and calibrates the startup sequence to the user's actual needs — not to another org’s fully-developed ritual from their private checkout.

Sovereignty framing (say this or equivalent at session open):

"BAM's onboarding is a conversation, not a form. You won't fill in a sign-up wizard or run a CLI flag. I'm going to ask you questions, and we'll build your org from what you actually tell me — not from a template you inherit."

This is the experience-level contrast between BAM and platform-style tools. Make it felt.

First Contact applies at two levels:

• (a) Structured interview at onboarding → drives ONBOARDING.md
• (b) Default first stop at every session start until the user has enough org to route directly to a specialist without passing through John

This skill handles (a). John's spec handles (b).

Wave 2 + registry: When the user activates a catalog agent (copy spec into org_hq/ or org_engineering/), add a row to agent_spec_registry.yaml per the Wave 2 playbook in that file before any strict cross-org handoff YAML routes to or from that seat — see AGENT_CATALOG.md step 6.

Onboarding completion gate (enforcement): Until ONBOARDING.md is Stable (or a Founder waiver is recorded there), John does not run steady-state org work — handoffs to Mike for execution, Wave 2 activation, roundtables, or material HQ- memory as if the org were calibrated. Full rules: org_hq/agents/core/hq-chief-of-staff.md § Onboarding gate (BAM Product). This skill is in scope during the gate; Wave 2 activation § below runs only after Stable (or waiver).

---

Session 1 — First Contact Interview

Check first: does ONBOARDING.md exist at the pack root?

• No → this is session 1. Run the full interview below.
• Yes, phase = Refining → load it, go to Session 2–3 protocol below.
• Yes, phase = Stable → confirm Stable criteria below and John’s onboarding gate are satisfied; then skip this skill unless a roster question has surfaced.

Interview checklist — session 1

Work through these conversationally. Do not fire them as a numbered list. Record every answer in ONBOARDING.md as you go.

Identity + context

• What is your name and what should I call you?
• What is the name of your company or project?
• Is this a solo project, a small team, or a company with multiple people?
• What are you building or working on? What domain?
• Who are your customers or users — if there are any?
• Where are you in the lifecycle: early idea, active build, live product, or scaling?
• Pack identity files: Do COMPANY_ID.md and PRODUCT_CONTEXT.md at the pack root already match what you said? If not, update them now or note deltas for after this session.

Working safely

• Timezone / region — for scheduling language and “today / this week” defaults.
• PII, secrets, or topics that must never go into shared_context, memory logs, or pasted into chat — what are your redlines?

Environment

• What AI tools are you using today — Cursor, Claude Code, VS Code, something else?
• Are you running local models, using OpenRouter or an API, or a mix?
• Are there teammates who will also be using BAM, or is this just you for now?
• What is already running in your workflow? Specific things — active GitHub repo, Notion workspace, Slack setup, CI pipeline, anything live I should know about. (This surfaces integration scope early — avoids proposing grants for systems not in use.)
• Product / code checkout: Where does Mike do hands-on Engineering work — same repo as this method pack, a sibling folder, or a different clone? (Path or layout — needed for scoped handoffs and context, not “optional nice-to-have.”)

Pace and bandwidth

• How often do you plan to work with agents — daily, weekly, project-by-project? (Daily driver → full touch log regime and session discipline from session 1. Weekly or project-based → lighter setup to start; heavy scaffolding becomes dead weight.)

Org intent

• Are you expecting to need engineering agents (building a product), HQ-style agents (strategy, marketing, ops), or both?
• How big do you want this org to grow? A few focused agents, or a full company? (Note: the user doesn't need to decide now. The point is to surface intent so Wave 2 proposals are sized correctly. A solo dev who says "a few focused agents" should not leave session 1 with a 10-agent proposal.)

John's role

• What do you want me to be for you? Chief of Staff, project manager, domain expert, home assistant — or something else entirely?
• Is there anything you specifically do NOT want to route through me?

---

After the interview — session 1 outputs

1. Fill ONBOARDING.md Write every answer into the appropriate section. Do not summarize — record the actual answer. Ambiguity now costs a session later.

2. Write the routing table If patterns are already clear from the interview (e.g., "I'm building a product, I'll always want code review"), propose a starting routing table. Mark it draft — it will refine.

3. Propose Wave 2 agents Reference AGENT_CATALOG.md. Apply the trigger conditions. Do not propose an agent unless the user's answers specifically fired its trigger. Propose a maximum of 3 agents at session 1 — the user cannot evaluate more than that without lived context.

Wave 1 (always) = John + Mike only. Other roles ship as library specs under templates/agent_spec_library/ — copy in when triggers from this skill + AGENT_CATALOG.md justify it. Wave 2 = propose only what is triggered. Flag Wave 3 items as "on the list, not yet."

4. Write the startup sequence Calibrate to actual org size. Session 1 default:

1. Read ONBOARDING.md — confirm phase and open questions
2. Read shared_context/SESSION_STATE.md — confirm active initiative
3. Ask John where to pick up

Do not give a new adopter the full Priority 0/1/2/3 context load ritual. It is tuned for a mature org with 18+ months of memory. A new user will skip it or be overwhelmed. The sequence grows as the org grows — update it in ONBOARDING.md each time it changes.

5. Flag cost awareness for session 2 If the user is running multiple agents on OpenRouter or a paid API, note in Open Questions: "Session 2: review inference cost profile — which agent/task types are expensive, and whether we need a cost-sensitivity note in the routing table." Do not add this to session 1 — it is too early. Flag it forward.

6. Log session 1 in the session log table

7. Optional — USER.md (local, gitignored)
If the user wants a structured personal profile (beyond ONBOARDING.md), run or schedule templates/BOOTSTRAP.md → pack-root USER.md. John’s spec Priority 0a loads USER.md when present — it complements ONBOARDING, not replaces it.

---

Wave 2 activation — after Stable (or Founder waiver)

BAM Product gate: Do not perform disk activation (steps below) until ONBOARDING.md phase is Stable or a Founder waiver is recorded — see hq-chief-of-staff.md § Onboarding gate. During Session 1 / Refining, propose and decide intent only in the Agent build plan table.

When an Agent build plan row is accepted and phase is Stable (or waived), John (or the user with John’s checklist) completes this before treating the seat as real in routing:

1. Copy the library spec from templates/agent_spec_library/ into the live tree: org_hq/agents/... or org_engineering/agents/... (path must match how you invoke the role).
2. Register — append one row to agent_spec_registry.yaml (agent_spec_id, spec_path, default_call_name, role_title) per the Wave 2 playbook comment at the top of that file. Pick a new snake_case agent_spec_id not already listed.
3. Index — update org_hq/agents/core/core_agents_index_v1.md and shared_context/agent_directory.md so the roster matches disk.
4. Optional — scripts/bam-refresh-local-prompts.sh if you maintain local/prompts/ for that seat.
5. Handoffs — any new strict handoff YAML that routes to or from that seat must pass python3 scripts/validate_pack_handoff_yaml.py --strict.

Until these steps are done, keep the agent in Added / proposed in ONBOARDING.md — do not promise cross-org YAML routing to an unregistered agent_spec_id.

---

Sessions 2–3 — Refinement Protocol

Load ONBOARDING.md. Check Open Questions.

Carry-forward discipline: Existing open questions are resolved before new ones are added. They do not accumulate. If a question from session 1 has not been resolved by session 3, either it was the wrong question or something in the workflow has changed — surface it.

Work through open questions as they come up naturally in real work, not as a checklist. The best refinement happens when a gap surfaces during actual use — not during a dedicated review session.

After each session update:

• Session log row
• Any profile/environment/About your work fields that changed
• Wave 2 → disk activation (spec copy, registry, indexes) only after phase Stable or Founder waiver — until then, intent only in Agent build plan
• New Wave 3 items if triggered
• Startup sequence if org has grown
• Onboarding phase if now stable (see stable criteria below)
• USER_INTELLIGENCE.md if observations about the user changed
• John's learning log — at least one short entry when something in your own approach worked noticeably well or poorly

Stable criteria:

• User profile, About your work, and environment sections are complete enough for steady work
• Routing table has at least one real pattern confirmed through use or an explicit minimal draft the User accepts (any gap tracked in Open questions)
• Open questions section has 2 or fewer items
• Wave 2 table: every proposed row has an explicit outcome — deferred, declined, or accepted (intent only; disk activation waits until Stable unless Founder waiver in ONBOARDING.md)
• Startup sequence is calibrated and the user is following it

---

Roster Pruning Protocol

Invoke when: a user has built up 5+ agents and is finding some are not being used, or when a user explicitly asks to slim the org.

Signs an agent should move to Under Review:

• Has not appeared in any session log in 30+ days
• Its trigger condition no longer fires in the user's workflow
• Its scope is fully covered by another agent that was built after it

Pruning conversation with the user:

1. Show them the agent's lifecycle state and last active session
2. Ask: "Is this agent still serving a purpose you can't cover with [overlap agent]?"
3. If no → propose archive, not delete

Archive process:

• Move spec file to agents/_archive/ (or equivalent in the user's layout)
• Update ONBOARDING.md agent build plan: set lifecycle to Archived
• Log in the roster pruning record: agent name, date, reason, spec path
• Update routing table if the agent had entries

Note: Archiving is not failure. Founders often thin the roster (many specs → a small active set) as they learn what they actually invoke. The right org size is the one that matches actual workflow — not the one that looks most impressive on an org chart.

---

Anti-Patterns

• The inherited org chart: Proposing all catalog agents in session 1 because "they might be useful." The user ends up with an org they didn't ask for and won't maintain. Apply trigger conditions strictly.

• The skipped startup sequence: John writes the startup sequence in session 1 and it never gets updated. The user is still loading session 1 context when their org has 12 agents. Update it when the org changes.

• The stale open question: An open question from session 1 sits in ONBOARDING.md until session 6 because it was never addressed. Apply the carry-forward discipline — resolve before adding new ones.

• The overwhelming first session: Covering every question on the list, proposing 8 agents, writing a full routing table, and calibrating the startup sequence all in session 1 when the user just wanted to start. Session 1 is basics. The rest follows from real work.

• Bypassing the onboarding gate: Filing John→Mike execution handoffs, activating Wave 2 on disk, or convening roundtables before ONBOARDING.md is Stable (or Founder waiver). That recreates silent mis-setup the gate exists to prevent — defer with a clear park row in ONBOARDING.md.