onboard

Files (1)

• SKILL.md

SKILL.md (first lines)

<!-- 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](#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)

From xoai/sage, MIT.

More from xoai/sage