Team Onboarding

Set up RaiSE for your team from absolute zero. This guide starts from "I have no organization" and ends with a fully configured team where new developers join with a single skill.

The Journey¶

             You (right now)
                  │
    ┌─────────────┴──────────────┐
    │  Phase 0: Create Your Org  │  ← raise.sh signup (2 min)
    └─────────────┬──────────────┘
                  │
    ┌─────────────┴──────────────┐
    │  Phase 1: First Dev Setup  │  ← /rai-onboard-repo (5 min)
    └─────────────┬──────────────┘
                  │
    ┌─────────────┴──────────────┐
    │  Phase 2: Team Joins       │  ← /rai-onboard-repo (2 min each)
    └────────────────────────────┘

Phase 0: Create Your Organization¶

Before anyone can connect, you need an org on the RaiSE server.

Go to raise.sh/signup and create your organization:

Your name — how Rai addresses you
Email — receives the verification link
Organization name — your team or company name (e.g., "Acme Engineering")

This creates:

A community plan org (free, 5 seats, 1 year)
An org slug derived from your name (e.g., acme-engineering)
You as the admin of the org

2. Verify your email¶

Check your inbox for the welcome email and click the verification link. This activates your org.

3. Note your org slug¶

You'll need the slug for rai connect. It's shown in the welcome email and on the dashboard. Example: acme-engineering.

Community vs Pro

The signup creates a Community plan (free, 5 seats). This includes everything needed for onboarding: server connection, config sync, project-scoped patterns. Upgrade to Pro for team awareness, shared semantic memory, and dedicated infrastructure.

Phase 1: First Developer Setup¶

The team lead (or first adopter) installs the CLI, connects to the org, and configures the project.

1. Install the CLI¶

cd your-project
curl -LsSf https://docs.raiseframework.ai/install.sh | bash

2. Set Atlassian credentials (if using Jira/Confluence)¶

Add to .bashrc / .zshrc for persistence:

export JIRA_URL="https://yoursite.atlassian.net"
export JIRA_API_TOKEN="your-api-token"
export JIRA_USERNAME="[email protected]"

# Optional — Confluence
export CONFLUENCE_URL="https://yoursite.atlassian.net/wiki"
export CONFLUENCE_API_TOKEN="your-api-token"
export CONFLUENCE_USERNAME="[email protected]"

Credentials are never stored in config files

YAML config contains site URLs, project keys, and workflow mappings — never tokens or passwords. Each developer uses their own API token via environment variables.

3. Run the onboarding skill¶

/rai-onboard-repo

The skill runs 8 checks and shows your status:

--- RaiSE Setup Status ---
✗ Developer profile not created
✗ Not connected to a RaiSE server
✗ Project not initialized
✗ Adapters not configured
✗ Repository not registered
✗ Project not linked
⊘ Config not shared with team
⊘ Governance not set up

6 steps remaining + 2 optional. Continue? [Y/n]

It then walks you through each missing step:

Step 1 — Profile: The skill asks your name (only mandatory question) and creates your developer profile at ~/.rai/developer.yaml. Optional: language and style preferences.

Step 2 — Connect: The skill prints instructions and stops — you must run rai connect <org-slug> manually (it opens a browser for device authorization). Once your org admin approves (that's you, the first time), run /rai-onboard-repo again.

rai connect acme-engineering
# Browser opens → log in → approve device → done

Step 3 — Initialize: The skill detects the project name from the directory and runs rai init --name <detected> --detect. This creates .raise/manifest.yaml with your project conventions (test runner, linter, formatter, type checker).

Step 4 — Auto-configure adapters: If your Atlassian env vars are set, the skill runs rai adapter setup auto. It discovers your Jira projects, workflows, and issue types, and writes .raise/backlog.yaml. Confluence is configured too if those env vars are present. Best-effort — skips if env vars are missing.

Step 5 — Register & link: The skill detects your git remote, registers the repo on the server, creates a project, and links them.

Step 6 — Share config: The skill detects you're the first dev (no config existed on the server) and runs rai project push-config automatically. This uploads your adapter config so joiners can pull it — credentials are stripped.

Step 7 — Governance (optional): The skill asks if you want to set up governance docs (vision, guardrails, architecture). Default is skip — you can always run /rai-project-onboard later.

Step 8 — Knowledge graph: The skill builds the knowledge graph from your project.

At the end:

--- RaiSE Setup Complete ---
✓ Developer: You (prefix: Y)
✓ Connected to api.raise.sh (org: acme-engineering)
✓ Project initialized (my-project)
✓ Adapters: Jira ✓  Confluence ✓
✓ Repository registered (my-project)
✓ Linked to project my-project (primary)
✓ Config shared with team
⊘ Governance: skipped (run /rai-project-onboard when ready)
✓ Knowledge graph: 47 nodes

Next: /rai-session-start

4. Commit to git¶

git add .raise/
git commit -m "chore: initialize RaiSE project"

5. Start working¶

rai session start

Phase 2: New Developer Joining¶

A new developer joins the team. They need the CLI, their own credentials, and the org slug. One skill handles everything else.

1. Install and configure¶

cd the-project
curl -LsSf https://docs.raiseframework.ai/install.sh | bash

Set their own Atlassian credentials (same env vars as Phase 1, with their personal API token).

2. Run the same skill¶

/rai-onboard-repo

The experience is identical — the skill runs the same 8 checks and handles each step. The key differences happen automatically:

Profile: Creates their own ~/.rai/developer.yaml
Connect: They run rai connect acme-engineering. The org admin approves the device.
Initialize: The skill detects that the server already has config (pushed by the first dev in Phase 1) and runs rai init --server — pulls manifest + adapter config in one shot. No prompts, no copying files.
Adapters: Skipped or runs rai adapter setup auto --force with their personal credentials.
Share config: Skipped — config came from server, nothing new to push.
Governance: Skipped — already exists in the repo.

3. Start working¶

rai session start

During session start, RaiSE automatically syncs patterns from the server — only for this project (not the entire org). They're ready to work.

What Gets Synced¶

What	Direction	Scope	When
Adapter config (Jira/Confluence setup)	Lead → Server → Joiner	Project	`push-config` / `init --server`
Patterns (learned best practices)	Bidirectional	Project-scoped	Every `session start` and `pattern sync`
Credentials (API tokens)	Never synced	Personal only	Env vars on each machine
Session state	Never synced	Local only	`.raise/rai/personal/`

Approving New Devices¶

When a team member runs rai connect, the org admin receives a device approval request. On the Community plan, approve via the dashboard at raise.sh. On Pro, approvals can be automated via SSO.

Tier Comparison¶

Feature	Community (free)	Pro
Seats	5	Unlimited
Server	`api.raise.sh` (shared)	Dedicated instance
`/rai-onboard-repo`	Yes	Yes
Config sync	Yes	Yes
Pattern sync (project-scoped)	Yes	Yes
Team awareness	—	Yes
Shared memory (semantic search)	—	Yes
Org governance	—	Enterprise
SSO / auto-approve devices	—	Yes

Both tiers use the same CLI and skills. The difference is in capacity and advanced capabilities.

Troubleshooting¶

"Organization 'xyz' not found"¶

The org slug doesn't exist. Check the slug in your welcome email or at raise.sh. Slugs are lowercase with hyphens (e.g., acme-engineering, not Acme Engineering).

"Not connected to a RaiSE server"¶

Run rai connect <org-slug> manually. The device flow requires a browser and admin approval — the skill intentionally does not attempt this automatically.

"No adapter config on server" during init --server¶

The team lead hasn't pushed config yet. Ask them to run rai project push-config.

"already exists. Use --force to overwrite"¶

Config files exist from a previous setup or from init --server. To regenerate:

rai adapter setup auto --force

"Skipping adapter auto-setup — no env vars"¶

Set JIRA_URL, JIRA_API_TOKEN, and JIRA_USERNAME in your environment. The skill checks for all three before attempting auto-config.

Under the Hood¶

The skill runs these commands for you. Here's what each step does if you need to debug or run manually:

Skill Step	CLI Equivalent	What it does
Profile	`rai session start --name` + edit `~/.rai/developer.yaml`	Creates developer identity
Check connection	`cat ~/.rai/server.json`	Reads server URL and org from local file
Connect	`rai connect <org-slug>`	Device flow auth (manual — browser required)
Initialize (first dev)	`rai init --name <name> --detect`	Creates `.raise/manifest.yaml` with conventions
Initialize (joiner)	`rai init --server`	Same + pulls adapter config from server
Auto-configure	`rai adapter setup auto`	Discovers Jira/Confluence, writes YAML config
Register repo	`rai repo register <name> --url <remote>`	Registers repo on server
Link project	`rai project create <name>` + `rai project link-repo`	Links repo to project
Share config	`rai project push-config --project <name>`	Uploads adapter config (first dev only)
Governance	`/rai-project-onboard` or `/rai-project-create`	6 governance docs (optional)
Build graph	`rai graph build`	Knowledge graph from project artifacts

Next Steps¶

Your First Story — Walk through the complete story lifecycle
Configuring Integrations — Deep dive into Jira/Confluence setup
Pipeline Quickstart — Run your first automated pipeline