Lesson 1: Team Setup & Roles

Organisation Setup

Creating a team workspace starts with the org command:

rearch org create --name "Acme Engineering"

This creates a shared workspace that all team members can access. The creator becomes the Owner by default.

Inviting Team Members

Invite developers by email or GitHub username:

# By email
rearch org invite --email developer@acme.com --role developer

# By GitHub username
rearch org invite --github octocat --role developer

# Bulk invite from a file
rearch org invite --file team-members.csv

Example CSV:

email,role,teams
alice@acme.com,lead,frontend
bob@acme.com,developer,"frontend,backend"
carol@acme.com,developer,backend
dave@acme.com,viewer,

Roles and Permissions

ReArch uses a hierarchical role system:

Role	Create Tasks	Review Output	Manage Agents	Manage Team	Billing
Owner	Yes	Yes	Yes	Yes	Yes
Admin	Yes	Yes	Yes	Yes	No
Lead	Yes	Yes	Yes	No	No
Developer	Yes	Yes	No	No	No
Viewer	No	Yes	No	No	No

Custom Roles

Define custom roles for fine-grained control:

.rearch/roles/junior-dev.yaml

role:
  name: junior-developer
  inherits: developer
  permissions:
    create_tasks: true
    max_task_scope: small # Cannot create large-scope tasks
    allowed_pipelines:
      - bugfix
      - docs
    blocked_pipelines:
      - refactor
      - migration
    require_approval: true # Tasks need lead approval before running

Teams and Projects

Organise members into teams and assign them to projects:

# Create teams
rearch org team create --name frontend
rearch org team create --name backend
rearch org team create --name platform

# Assign members
rearch org team add-member --team frontend --user alice@acme.com
rearch org team add-member --team frontend --user bob@acme.com

# Link teams to projects
rearch org project assign --project web-app --team frontend
rearch org project assign --project api-server --team backend

Project-Level Configuration

Each project can have its own agent settings while inheriting org-wide defaults:

# Project: web-app
project:
  name: web-app
  team: frontend
  inherit: org-defaults # Inherits org-level prompts and pipelines

  overrides:
    agent:
      temperature: 0.1 # More deterministic for the frontend
    pipeline:
      test_command: "pnpm vitest run"
      lint_command: "pnpm biome check"

Shared Conventions

The most powerful team feature is shared prompts. Instead of each developer maintaining their own prompts, the team shares a single source of truth:

.rearch/
├── prompts/
│   ├── org-standards.md       # Org-wide coding standards
│   ├── frontend.md            # Frontend-specific conventions
│   ├── backend.md             # Backend-specific conventions
│   └── security.md            # Security requirements (always included)

Configure prompt inheritance:

.rearch/config.yaml

prompts:
  base: org-standards # Always included
  security: security # Always included
  team_specific: true # Includes the team's prompt file

Every task will include org-standards.md + security.md + the team-specific prompt, ensuring consistent output across the organisation.

Onboarding New Team Members

Create an onboarding checklist for new developers:

# Generate a personalised setup guide
rearch org onboard --user new-hire@acme.com --team frontend

This generates:

1. An invite link with the correct role and team
2. A pre-configured .rearch/ directory for their local machine
3. A set of starter tasks to familiarise them with the codebase

What’s Next

In the next lesson, you will set up AI-assisted code review agents that automatically review pull requests.

---