Skip to content

Migrating from 2.x to 3.0

RaiSE 3.0 includes several breaking changes. This guide walks through each one with the exact steps to upgrade your project.

Who needs this: Anyone upgrading an existing project from RaiSE 2.4.x to 3.0.0.

Before You Start

  1. Back up your .raise/ directory (optional but recommended): 

    cp -r .raise/ .raise.backup-2.4/

  2. Check your current version: 

    rai --version

  3. Install 3.0: 

    curl -LsSf https://docs.raiseframework.ai/install.sh | bash -s -- --version 3.0.0
    Or for the latest pre-release: 
    curl -LsSf https://docs.raiseframework.ai/install.sh | bash -s -- --pre

Breaking Changes

BC1 — confluence.yaml renamed to docs.yaml

What changed: The documentation adapter config file was renamed from .raise/confluence.yaml to .raise/docs.yaml. The schema also changed: instances: is now targets:, default_instance: is now default_target:, and each target requires a type: field.

Is it auto-migrated? Yes — the first time you run rai docs write, RaiSE auto-creates docs.yaml from your confluence.yaml. However, the old file is not deleted, so you need to clean it up manually.

Fix:

# After running any rai docs command once (auto-migration creates docs.yaml):
git add .raise/docs.yaml
git rm .raise/confluence.yaml
git commit -m "chore: migrate confluence.yaml → docs.yaml (RaiSE 3.0)"

Before (.raise/confluence.yaml): 

default_instance: my-space
instances:
  my-space:
    url: https://company.atlassian.net/wiki
    space_key: ENG
    instance_name: my-space
    routing:
      adr:
        parent_title: Architecture
        labels:
          - adr

After (.raise/docs.yaml): 

default_target: my-space
targets:
  my-space:
    type: confluence
    url: https://company.atlassian.net/wiki
    space_key: ENG
    instance_name: my-space
    routing:
      adr:
        parent_title: Architecture
        labels:
          - adr

Verify: 

rai doctor

BC2 — /rai-story-run removed

What changed: The /rai-story-run skill has been removed. Story pipelines are now started through the pipeline_start MCP tool or the rai pipeline CLI.

Fix: Replace any /rai-story-run invocations with one of the following:

Option A — MCP tool (recommended, from Claude Code):

Ask your AI assistant to start the pipeline: 

Start the story pipeline for RAISE-1234
The assistant calls pipeline_start automatically and guides you through each phase.

Option B — Inside Claude Code via skill: 

/rai-story-start RAISE-1234
Then follow the pipeline phases manually with /rai-story-design, /rai-story-plan, etc.

Note: There is no rai pipeline CLI command — pipelines run exclusively through the MCP tool (pipeline_start, pipeline_advance, pipeline_status).

See also: Pipeline Quickstart

BC3 — SQLite replaces JSONL/JSON storage

What changed: All local RaiSE data (sessions, signals, patterns, artifacts, pipeline runs) has moved from flat files (.raise/rai/personal/*.jsonl, *.json, *.yaml) to a SQLite database at .raise/raise.db.

Is it auto-migrated? Yes — on the first rai command after upgrading, the migration runs automatically. Your old JSONL files are renamed *.migrated (not deleted).

Manual migration (if auto-migration didn't run): 

rai db migrate

Verify: 

rai db status
# Should show: schema_version=24, tables with row counts

Rollback: Your *.migrated files are preserved. To restore them, rename them back (contact support for the restore script).

BC4 — Global SQLite database

What changed: RaiSE 3.0 introduces a single global database at ~/.rai/raise.db that holds cross-project data. All project-scoped tables now have a project_id column.

Impact for most users: None — the rai CLI handles project_id filtering automatically.

Impact if you query SQLite directly (advanced users): 

-- Before (2.x): query worked without filtering
SELECT * FROM sessions;

-- After (3.0): must filter by project_id
SELECT * FROM sessions WHERE project_id = '<your-project-hash>';

To find your project ID: 

rai db status
# Shows: project_id: <hash>

BC5 — Session data location

What changed: Session state moved from a mix of ~/.rai/ global files and per-project JSONL into .raise/rai/personal/ (per-project) and ~/.rai/raise.db (global index).

Impact: If you had scripts reading ~/.rai/developer.yaml active session fields, those fields are no longer updated. Session data is now in SQLite.

Fix: 

# Query active session via CLI instead of reading YAML
rai session list
rai session info

Verify: 

rai session list
# Should show your recent sessions from SQLite

BC6 — schema.sum integrity gate

What changed: RaiSE 3.0 requires a .raise/schema.sum file that tracks migration hashes. The gate-schema-sum gate (triggered at story close) fails if this file is missing or stale.

Impact: If you skip this, rai-story-close will fail at the gate check.

Fix: 

# Generate schema.sum for your project
rai schema sum update

# Commit it
git add .raise/schema.sum
git commit -m "chore: add schema.sum integrity file (RaiSE 3.0)"

Verify: 

rai schema sum check
# ✓ schema.sum is up to date (V24)

BC7 — Use rai upgrade for existing projects

What changed: rai init is now for first-time setup only. Running it on an already-initialized project will show an error and suggest rai upgrade instead.

Before (2.x): Re-running rai init updated skills and framework files.

After (3.0): Use rai upgrade to update an existing project: 

# Update skills, framework files, and AGENTS.md
rai upgrade

# Preview what would change
rai upgrade --dry-run

# Also re-detect AI agents
rai upgrade --detect

BC8 — Backlog pending-ops dead-letter workflow

What changed: Failed backlog sync operations (e.g., Jira calls that failed during offline work) now go to a dead-letter queue instead of silently disappearing.

Impact: If you have unsynced backlog ops from 2.x that failed, they appear in the dead-letter queue after migration.

Check for dead-letter ops: 

rai backlog pending-ops list --dead

Drain (retry or purge): 

# Purge a specific failed op
rai backlog pending-ops purge --id <op-id>

# Purge all dead-letter ops (after reviewing them)
rai backlog pending-ops purge --yes

Post-Migration Verification

After completing all applicable steps above:

# Full diagnostics
rai doctor

# Check database state
rai db status

# Verify schema integrity
rai schema sum check

# List recent sessions (confirms SQLite is working)
rai session list

All checks should pass green. If rai doctor reports issues, follow the --fix suggestions:

rai doctor --fix

Getting Help