Context Onboarding

Goal

Working context system, user-approved, in under 30 minutes.

Claude does the drafting. The user reviews and corrects. No questionnaires, no choices to make.

How It Works

Claude asks ONE direct question upfront — "what kind of project is this?" — and uses the answer to pick the right template + pattern doc. After that, Claude figures out the rest from what the user says and what's in the repo. No long path-chooser; just one gate that routes scaffolding correctly.

Signals → What to do

Step 0: Identify Project Type + Discover Sources

Two short AskUserQuestion gates, in order: what kind of project this is (0a), then where the knowledge lives (0b). Pre-fill both from what you can see before asking — the user confirms or overrides.

0-pre. CLAUDE.md self-heal (silent)

Before anything else, run once per onboarding session to make sure the BCOS-managed instructions are present in CLAUDE.md. This catches the git clone-without-install.sh case: if CLAUDE.md exists but lacks the <!-- BCOS:CORE:START --> / <!-- BCOS:CORE:END --> markers, the framework section is missing or unstructured. The helper below splices it in.

"$CLAUDE_PROJECT_DIR/.claude/bin/python3" .claude/scripts/_claude_md.py \
  --target CLAUDE.md \
  --source .claude/bcos-claude-reference.md \
  --recovery .claude/bcos-claude-reference.md

If .claude/bcos-claude-reference.md doesn't exist yet (fresh clone), point --source at the upstream template available in this repo's tree (the same file install.sh would have copied). If neither is available, skip — update.py will fix it on the next refresh.

Action handling (silent unless something happened):

• unchanged — say nothing, continue.
• created — mention in one line that CLAUDE.md was created.
• spliced — mention in one line: "Added the BCOS instructions block to your CLAUDE.md (your existing content is preserved)."
• replaced — mention in one line: "Refreshed the BCOS instructions block; previous version saved to .claude/bcos-claude-reference.md."

Do not block onboarding on this step. If the helper errors, log a one-line warning and continue.

0a. Project type

Before anything else, ask what kind of project this is. The answer picks the template + pattern doc Claude uses for the rest of onboarding. This is the one question that isn't inferred silently — one direct question is the ceremony.

Pre-fill suggestion first: glance at any URLs the user shared, files they dropped, README contents, repo structure (frontend code? Dockerfile + cron? marketing copy? client names? spec docs + ADRs? runbooks and on-call docs? pricing / enablement / battlecards?). Use that to pick the most likely answer as the suggested option, but still ask.

Two levels, only ask the follow-up when needed.

Level 1 — always ask. Use the AskUserQuestion tool:

• Question: "What's this repo primarily about? (This picks the scaffolding — you can change it later.)"
• Options:
  • Product (external product, service, or company context)
  • Product development (R&D, specs, architecture, engineering roadmap)
  • Internal tool (dashboards, scripts, internal apps, developer tools)
  • Marketing (marketing site, campaigns, content strategy)
  • GTM / sales (pricing, positioning, sales enablement, partnerships)
  • Operations (ops runbooks, processes, infrastructure docs)
  • Client work (agency engagement scoped to one client)
  • Team playbook / personal (team practices, ops runbook, personal projects)

Level 2 — only when the Level 1 answer is ambiguous. Skip if repo signals already disambiguate.

• If the user picked "Product" (and the repo doesn't obviously lean one way — e.g. marketing site + pricing page → external product; spec docs + ADRs + architecture → R&D), ask:
  • Question: "External-facing product/service, or product development (R&D)?"
  • Options:
    • External product / service (the product as sold — brand, positioning, customers)
    • Product development (how the product is built — specs, architecture, roadmap)
• If the user picked "Internal tool" (and the repo doesn't make the sub-shape obvious — e.g. a React frontend → app; cron config + Dockerfile with no UI → automation), ask:
  • Question: "Is it more of an app or an automation?"
  • Options:
    • App with UI + internal users (web dashboard, internal admin tool, back-office app)
    • Automation / CLI / pipeline / service (no UI — scripts, ETL, cron jobs, backend services)

Claude should silently pre-fill the Level 1 option based on inference, and skip Level 2 entirely when pre-fill confidence is high on the sub-shape. Carry the resolved profile through to Step 1 (profile → template + pattern mapping) and Step 2 (cluster naming).

0b. Source discovery

Now find out where the knowledge lives.

ALWAYS use the AskUserQuestion tool — even if files already exist in _inbox/:

If files are already in _inbox/, acknowledge them first ("I can see X files in your inbox"), then ask:

• Question: "I found [N] files in your inbox. Anything else to include before I start? Website URL, Google Drive docs, other materials?"
• Options:
  • That's everything (proceed with what's in the inbox)
  • Here's more (I'll share URLs, drop more files, or point you to a connected system)
  • Check my connected systems too (Google Drive, Notion, Confluence via MCP)

If NO files in _inbox/, ask:

• Question: "Where does your business knowledge live right now?"
• Options:
  • I have files to share (drop them in docs/_inbox/ or point me to them)
  • Connected system (Google Drive, Notion, Confluence — I can browse via MCP)
  • Both (local files + connected systems)
  • Starting from scratch (no existing docs — let's create from conversation)

Based on the answer:

First-run routing principle: onboarding is allowed to identify all BCOS zones, but it should only create active data points after the user approves the architecture. Route material by what it is, not by file type alone: