Skip to content

installation-guide.md

Latest commit

 

History

History
492 lines (352 loc) · 12.8 KB

installation-guide.md

File metadata and controls

492 lines (352 loc) · 12.8 KB

Installation guide — AITEAM-X

Version: 1.0
Updated: 2026-03-18
Audience: Developers installing AITEAM-X on a new machine or project

Table of contents

  1. Prerequisites
  2. Quick install
  3. Web setup assistant
  4. Manual configuration
  5. Environment variables
  6. System status page
  7. Created file layout
  8. Advanced scenarios
  9. Troubleshooting

1. Prerequisites

Before installing AITEAM-X you need:

Requirement Required How to check
Node.js 18+ Yes node --version
Agents pack (aiteam-x-agents/ or legacy bmad/) Yes e.g. aiteam-x-agents/_cfg/manifest.yaml
Cursor IDE Yes Required for Cursor Agent CLI
Git Yes git --version

About the agents pack

AITEAM-X reads agent definitions from the aiteam-x-agents/ folder at the configured project root (some repos still use the legacy bmad/ layout). The root that contains that folder is set via agentsRoot in aiteam.config.json or environment variables AITEAM_AGENTS_ROOT / AITEAM_BMAD_ROOT (legacy alias).

Expected pack layout:

your-project/
├── aiteam-x-agents/          (or bmad/ on legacy repos)
│   ├── _cfg/
│   │   ├── manifest.yaml          ← pack version id
│   │   └── agent-manifest.csv     ← available agents
│   ├── core/
│   │   └── config.yaml            ← main config (user_name, language)
│   └── {module}/
│       └── config.yaml            ← per-module config (project_name)
└── .cursor/
    └── rules/
        └── aiteam-x/              (or bmad/ on legacy repos)
            └── {module}/
                └── agents/
                    └── {agent}.mdc  ← agent personas

About Cursor Agent CLI

AITEAM-X uses the Cursor Agent CLI to run agents. It is installed when you open the project in Cursor IDE for the first time.

  • Windows: %LOCALAPPDATA%\cursor-agent\versions\{version}\
  • macOS/Linux: ~/.cursor-agent/versions/{version}/

2. Quick install

Option A — One command (recommended)

npx aiteam-x@latest

Creates the project in the current directory (must be empty). To create a named folder:

npx aiteam-x@latest my-project

The command downloads the template, installs dependencies, runs the setup wizard, and starts the server.

Option B — Manual install

# 1. Clone the repository
git clone https://github.com/INOSX/AITeam.git
cd AITeam

# 2. Install dependencies
npm install

# 3. Run the setup wizard
npm run setup

# 4. Start the server
npm run dev

Open http://localhost:3000. The dashboard loads automatically if setup completed successfully.

3. Web setup assistant

npm run setup opens the web assistant at /setup (three phases: machine scan, review, configuration). All interaction happens in the browser.

Phase 1 — Scan

Automatically detects the agents pack under ./ (aiteam-x-agents/ or bmad/), Cursor Agent CLI, and existing config. The panel shows status (e.g. pack version and agent count).

Phase 2 — Review

Confirm or adjust the project root that contains the pack (same as agentsRoot).

Phase 3 — Configuration

  • Project info (name, user, language for talking to agents)
  • Module placement in the virtual office (conference, office, kitchen, workspace)
  • Provider APIs (when applicable)
  • Creates .memory/ and writes aiteam.config.json

Suggested rooms per module:

Room Suggested use
conference Main / master agent
office Development team
kitchen Design / game dev
workspace Builders / tools

Files created or updated:

  • .memory/_project.md — shared project context (injected into every new agent session)
  • .memory/{agent-id}.md — per-agent memory bank
  • aiteam.config.json — AITEAM-X configuration (gitignored)

Tip: If the pack lives elsewhere, use AITEAM_AGENTS_ROOT or AITEAM_BMAD_ROOT in .env.local, or set the correct root in the web assistant.

4. Manual configuration

If you prefer not to use the wizard, create aiteam.config.json at the project root:

{
  "agentsRoot": "./",
  "locations": {
    "core": "conference",
    "bmm": "office",
    "bmgd": "kitchen",
    "bmb": "workspace"
  },
  "projectName": "My Project",
  "user": "Alex",
  "language": "en",
  "setupComplete": true
}

Legacy: older files may use bmadRoot instead of agentsRoot; AITEAM-X accepts both on load.

Note: aiteam.config.json is in .gitignore — each developer creates their own locally.

aiteam.config.json fields

Field Type Default Description
agentsRoot string "./" Root directory that contains aiteam-x-agents/ or bmad/
bmadRoot string — (legacy) same meaning as agentsRoot
locations object see below Room per module (core, bmm, bmgd, bmb)
projectName string "" Project name (shown in UI)
user string "" User name (used by agents)
language string "pt-br" Agent communication language
setupComplete boolean false If false, redirects to /setup

Default locations:

{
  "core": "conference",
  "bmm": "office",
  "bmgd": "kitchen",
  "bmb": "workspace"
}

5. Environment variables

Create .env.local at the project root:

# Overrides agentsRoot / bmadRoot from aiteam.config.json (recommended)
# Useful for: CI/CD, pack in another directory, multiple projects
AITEAM_AGENTS_ROOT=/absolute/path/to/project-with-pack

# Legacy alias (same as AITEAM_AGENTS_ROOT)
# AITEAM_BMAD_ROOT=/absolute/path/to/project-with-pack

Configuration priority

The pack root (agentsRoot) resolves in this order (highest first):

AITEAM_AGENTS_ROOT or AITEAM_BMAD_ROOT (env)
  ↓ if unset
aiteam.config.json → agentsRoot or bmadRoot (legacy)
  ↓ if missing
"./" (current directory)

When to use environment variables

Pack in another directory (monorepo):

AITEAM_AGENTS_ROOT=../my-project-with-pack

CI/CD (no config file):

AITEAM_AGENTS_ROOT=/home/runner/work/project

Multiple AITEAM-X instances:

# Terminal 1 — Project A
AITEAM_AGENTS_ROOT=../project-a npm run dev

# Terminal 2 — Project B (different port)
AITEAM_AGENTS_ROOT=../project-b PORT=3001 npm run dev

6. System status page

If AITEAM-X detects incomplete setup, it redirects to http://localhost:3000/setup.

When redirect happens

Redirect occurs if any of the following is true:

  • aiteam.config.json does not exist
  • aiteam.config.json exists but setupComplete is false
  • Agents pack not found at the configured path
  • No agents discovered

Reading the /setup page

┌─────────────────────────────────────────┐
│ AITEAM-X — Setup                        │
│                                         │
│ SYSTEM STATUS                           │
│ ✓ Pack   v2025.3.1 — 14 agents in .    │
│ ✗ Cursor Not found                      │
│ ⚠ Config Using defaults                 │
│                                         │
│ ACTIONS NEEDED                          │
│ ✗ Cursor Agent CLI not found            │
│   → Install Cursor and open the project │
│ ⚠ aiteam.config.json missing            │
│   → Run npm run setup                   │
│                                         │
│ HOW TO CONFIGURE                        │
│ npm run setup                           │
│                                         │
│ [↻ Check again]                         │
└─────────────────────────────────────────┘
Icon Meaning
Green ✓ Component OK
Yellow ⚠ Warning — not blocking but recommended
Red ✗ Error — blocks operation

After fixing issues, click ↻ Check again to re-check without a full reload.

7. Created file layout

After complete setup, these files exist:

your-project/
├── aiteam.config.json          ← AITEAM-X config (gitignored)
├── .env.local                  ← environment variables (gitignored, optional)
└── .memory/
    ├── _project.md             ← shared context (injected into every new session)
    ├── bmad-master.md          ← bmad-master agent memory
    ├── dev.md                  ← dev agent memory
    ├── pm.md                   ← pm agent memory
    └── ...                     ← one file per discovered agent

.memory/_project.md

Automatically injected at the start of every new conversation with any agent. Use for:

  • Project context (stack, goals, architectural decisions)
  • Team conventions
  • Important links
  • Current development state
# My Project

Shared context for all AITEAM-X agents.

## Stack
- Next.js 15 + TypeScript
- PostgreSQL + Prisma

## Architectural decisions
- ...

.memory/{agent-id}.md

Per-agent memory. Injected for that agent’s new sessions. Use for:

  • Relevant decision history
  • Learnings and patterns
  • Role-specific context

8. Advanced scenarios

New machine, same project

git clone https://github.com/your-org/your-project.git
cd your-project
npm install

# aiteam.config.json is NOT in git (gitignored)
# Run setup again:
npm run setup

npm run dev

The assistant detects the existing pack and recreates only aiteam.config.json and missing memory files (existing memories are preserved if .memory/ was committed).

New developer onboarding

git clone ...
cd project
npm install
npm run setup   # ← wizard guides ~5 minutes of config
npm run dev

Reconfigure module locations

npm run setup
# In the browser, go to the configuration phase and change rooms per module

Or edit aiteam.config.json directly:

{
  "locations": {
    "bmm": "conference"
  }
}

Pack in another directory

# Layout
projects/
├── my-project/       ← root with aiteam-x-agents/ or bmad/
│   └── aiteam-x-agents/
└── aiteam-x/         ← AITEAM-X app here

# .env.local inside aiteam-x/
AITEAM_AGENTS_ROOT=../my-project

You can set setupComplete: true manually in aiteam.config.json after configuring agentsRoot or the environment variable.

9. Troubleshooting

"Agents pack not found"

Symptom: Assistant does not detect the pack, or /setup shows pack missing.

Checks:

# Does the file exist?
ls aiteam-x-agents/_cfg/manifest.yaml
# or: ls bmad/_cfg/manifest.yaml

# Is AITEAM_AGENTS_ROOT / AITEAM_BMAD_ROOT correct?
echo $AITEAM_AGENTS_ROOT

# Is the path in config correct?
cat aiteam.config.json | grep -E 'agentsRoot|bmadRoot'

Fix: Set AITEAM_AGENTS_ROOT (or AITEAM_BMAD_ROOT) to the directory that contains aiteam-x-agents/ or bmad/, or fix agentsRoot in JSON.

"Cursor Agent CLI not found"

Symptom: /setup shows Cursor CLI missing. Agents error when sending messages.

Checks:

# Windows — check directory exists:
ls "$LOCALAPPDATA\cursor-agent\versions\"

# macOS/Linux:
ls ~/.cursor-agent/versions/

Fix:

  1. Install Cursor IDE
  2. Open the project in Cursor at least once
  3. CLI installs on first open
  4. Click ↻ Check again on /setup

Dashboard does not load — redirect loop

Symptom: Browser loops between / and /setup.

Cause: setupComplete is false in aiteam.config.json, or the pack is unreachable at the configured root.

Fix:

cat aiteam.config.json

# If setupComplete is false:
npm run setup

# If agentsRoot is wrong, edit aiteam.config.json:
{
  "agentsRoot": "/correct/path",
  "setupComplete": true
}

Agents do not appear on the dashboard

Symptom: Dashboard opens but agent list is empty.

Checks:

cat aiteam-x-agents/_cfg/agent-manifest.csv
# or: cat bmad/_cfg/agent-manifest.csv

head -1 aiteam-x-agents/_cfg/agent-manifest.csv

Likely cause: Malformed agent-manifest.csv or wrong agentsRoot / env var.

Agent memories do not load

Symptom: Agents lack context from previous conversations.

Checks:

ls .memory/
cat .memory/_project.md

Fix: Run npm run setup — the wizard creates missing files without overwriting existing ones.

To report issues, open an issue at github.com/INOSX/AITeam