xoai/onboard

<!-- sage-metadata cost-tier: sonnet activation: manual tags: [setup, onboarding, initialization, context] inputs: [codebase-or-nothing] outputs: [sage-directory, claude-md, conventions] -->

Onboard

Set up Sage for a project. Detect what exists, configure what's needed, generate the agent instructions. This is the FIRST thing that runs.

Core Principle: A beginner should go from "I have a project" (or "I have an idea") to "Sage is configured and ready" in under 3 minutes.

When to Use

• First time using Sage on a project (no .sage/ directory exists)
• User says "set up sage", "onboard", "initialize", or "get started"
• Sage detects no .sage/ directory and prompts: "This project isn't set up with Sage yet. Want me to set it up? (Takes ~2 minutes)"

Process

Step 0: Detect Project State

Check what exists:

• Does .sage/ exist? → Already onboarded. Offer to re-scan or update.
• Does package.json / requirements.txt / pubspec.yaml exist? → Existing project.
• Is the directory empty or near-empty? → New project (greenfield).

Branch accordingly:

---

Path A: Existing Project

A1. Scan the Stack

Read dependency files to detect the tech stack:

package.json  → detect: next, react, vue, svelte, express, supabase, firebase
pubspec.yaml  → detect: flutter, firebase
requirements.txt / pyproject.toml → detect: django, flask, fastapi
go.mod → detect: gin, echo, fiber

Produce a stack summary:

DETECTED STACK:
  Frontend: Next.js 14 (App Router), React 19, Tailwind CSS 4
  Backend:  Supabase (@supabase/ssr, @supabase/supabase-js)
  Testing:  Vitest, Testing Library
  Build:    Turbopack

Show to user: "I detected this stack. Anything I missed or got wrong?"

A2. Select Packs

Based on detected stack, select which packs activate:

PACKS TO LOAD:
  L1: web (web application detected)
  L1: baas (Supabase detected)
  L2: nextjs (Next.js detected)
  L2: react (React detected)
  nextjs surfaces integration/supabase-integration.md (Supabase detected)

Show to user: "These packs will guide code quality. Look right?"

A3. Discover Conventions

Scan the codebase for established patterns:

• File naming (kebab-case? PascalCase? camelCase?)
• Component structure (co-located files? flat directories?)
• State management approach
• Test patterns and locations
• Import style (absolute? relative? aliases?)
• Formatting (Prettier? ESLint config?)

Save to .sage/conventions.md.

A4. Generate Configuration

Create the .sage/ directory and all files. See Output below.

---

Path B: New Project (Greenfield)

B1. Ask What They're Building

One question: "What are you building? Describe it in a sentence or two."

Examples of what they might say:

• "A task management app for my team"
• "An e-commerce site for my bakery"
• "A mobile app for tracking workouts"
• "A SaaS dashboard for analytics"

B2. Guide Tech Stack Selection

Based on what they described, recommend a stack. Ask focused questions:

Question 1: Platform "Is this a web app, mobile app, or both?"

• Web only → React/Next.js path
• Mobile only → Flutter or React Native path
• Both → Next.js (web) + React Native (mobile) or Flutter (both)

Question 2: Backend complexity "Will this need complex backend logic (custom algorithms, complex queries, multi-step workflows), or is it mostly storing/fetching data with user accounts?"

• Mostly CRUD + auth → Supabase or Firebase (BaaS path)
• Complex backend → Custom API (Express/Django + database)

Question 3: Scale expectation (only if unclear) "Is this an MVP/prototype, or do you need it production-ready from day one?"

• MVP → optimize for speed, BaaS recommended
• Production → optimize for control, consider custom backend

Based on answers, recommend:

RECOMMENDED STACK:
  You're building a web app with user accounts and data storage.
  For fast MVP delivery, I recommend:

  Frontend: Next.js (App Router) + React + Tailwind CSS
  Backend:  Supabase (auth, database, storage — no backend to build)
  Testing:  Vitest + Testing Library
  Deploy:   Vercel

  This gets you from idea to deployed app fastest.
  Ready to go with this, or want to explore alternatives?

If user wants alternatives, explain trade-offs briefly. Don't overwhelm.

B3. Scaffold the Project

After stack approval, create the project structure:

• Run the framework's project creator (npx create-next-app, flutter create, etc.)
• Set up initial dependencies
• Create initial configuration files
• Set up testing infrastructure

B4. Generate Configuration

Same as A4 — create .sage/ directory. Conventions will be minimal for a new project (establish them as the first code is written).

---

Output

Create .sage/ Directory

.sage/
├── config.yaml           # Project configuration
├── conventions.md         # Discovered or established patterns
├── decisions.md           # Shared decision log (agent + human)
├── docs/                  # Project-level knowledge (flat, skill-prefixed)
├── work/                  # Per-initiative (YYYYMMDD-slug/ subfolders)
└── gates/                 # Quality gate scripts and config

.sage/config.yaml

sage-version: "<stamped by sage init from the framework's VERSION file>"
project-name: "<detected or provided>"
mode-default: build
packs:
  enabled:
    - web
    - baas
    - nextjs
    - react
constitution:
  base: sage/core/constitution/base.constitution.md
  preset: startup  # or enterprise, opensource

.sage/decisions.md

# Decisions

Shared log for significant decisions and context.
Both the AI agent and human collaborators write here.

### YYYY-MM-DD — [Decision title]
[What was decided, why, alternatives considered.]

.sage/conventions.md

# Project Conventions

Discovered by Sage onboard on <date>.
Update this file as conventions evolve.

## Naming
- Files: <detected pattern>
- Components: <detected pattern>
- Variables: <detected pattern>

## Structure
- Components: <detected layout>
- Tests: <detected location and framework>
- Styles: <detected approach>

## Patterns
- State management: <detected or TBD>
- Data fetching: <detected or TBD>
- Error handling: <detected or TBD>

Generate the platform instructions file

Normally sage init / sage update generate the platform's instructions file (CLAUDE.md / AGENTS.md / GEMINI.md) from the shared body in runtime/platforms/_shared/instructions-body.sh with the merged constitution spliced in — you do not hand-assemble it during onboarding.

If you must produce one directly, the template is core/capabilities/context/context-loader/templates/main-instructions.template.md:

• Replace {{CONSTITUTION}} with the loaded constitution principles
• Replace {{NAVIGATOR_PATH}} with the sage-navigator skill path
• Replace {{AVAILABLE_SKILLS}} and {{COMMANDS_TABLE}} from the enabled skills

Save to project root as the platform's instructions file (e.g. CLAUDE.md).

Discover MCP Tools (if configured)

If .claude/mcp.json or .sage/mcp.json exists, run tool discovery:

bash sage/runtime/mcp/discover.sh .

This connects to each configured MCP server, lists available tools, and caches the manifest at .sage/mcp-manifest.json. The CLAUDE.md generation includes a lightweight tool summary (~50 tokens per server) so you know what's available without consuming context with full schemas.

If no MCP config exists, skip this step. Layer 1 tools (bash scripts) are always available regardless of MCP configuration.

Show the user: "Sage is set up. Here's what I configured: [summary]. Tell me what to build, or say 'sage help' for guidance on what to do next."

Rules

MUST (violation = broken setup or confused user):

• MUST NOT skip user confirmation on detected stack or recommended stack.
• MUST generate .sage/ directory and CLAUDE.md — they're the minimum viable setup.
• MUST detect packs from the stack — don't ask the user to pick packs manually.

SHOULD (violation = suboptimal experience):

• SHOULD NOT overwhelm with options — recommend ONE stack, explain alternatives only if asked.
• SHOULD recommend BaaS (Supabase/Firebase) for MVPs, custom backend for complex products.
• SHOULD respect the existing stack — don't suggest rewriting what's already there.

MAY (context-dependent):

• MAY skip pack selection confirmation if only L1 packs apply (no framework-specific packs detected).
• MAY suggest additional packs if the user mentions planned additions ("we'll add Firebase later").

Failure Modes

• Can't detect stack: Ask the user directly. "I can't tell what framework this uses. What's the main technology?"
• Mixed/unusual stack: Load what you can detect, note gaps. "I found React but couldn't detect the backend. What are you using for data?"
• User wants a stack you don't have packs for: Proceed without L2/L3 packs. L1 packs (web, mobile, api, baas) still apply. "I don't have specialized guidance for [framework] yet, but general web/API best practices will still apply."