stack/README.md

# Mosaic Stack

Self-hosted, multi-user AI agent platform. One config, every runtime, same standards.

Mosaic gives you a unified launcher for Claude Code, Codex, OpenCode, and Pi — injecting consistent system prompts, guardrails, skills, and mission context into every session. A NestJS gateway provides the API surface, a Next.js dashboard gives you the UI, and a plugin system connects Discord, Telegram, and more.

## Quick Install

```bash
bash <(curl -fsSL https://git.mosaicstack.dev/mosaic/mosaic-stack/raw/branch/main/tools/install.sh)
```

This installs both components:

| Component               | What                                                             | Where                |
| ----------------------- | ---------------------------------------------------------------- | -------------------- |
| **Framework**           | Bash launcher, guides, runtime configs, tools, skills            | `~/.config/mosaic/`  |
| **@mosaicstack/mosaic** | Unified `mosaic` CLI — TUI, gateway client, wizard, auto-updater | `~/.npm-global/bin/` |

After install, set up your agent identity:

```bash
mosaic init          # Interactive wizard
```

### Requirements

- Node.js ≥ 20
- npm (for global @mosaicstack/mosaic install)
- One or more runtimes: [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), [OpenCode](https://opencode.ai), or [Pi](https://github.com/mariozechner/pi-coding-agent)

## Usage

### Launching Agent Sessions

```bash
mosaic pi                    # Launch Pi with Mosaic injection
mosaic claude                # Launch Claude Code with Mosaic injection
mosaic codex                 # Launch Codex with Mosaic injection
mosaic opencode              # Launch OpenCode with Mosaic injection

mosaic yolo claude           # Claude with dangerous-permissions mode
mosaic yolo pi               # Pi in yolo mode
```

The launcher verifies your config, checks for `SOUL.md`, injects your `AGENTS.md` standards into the runtime, and forwards all arguments.

### TUI & Gateway

```bash
mosaic tui                   # Interactive TUI connected to the gateway
mosaic login                 # Authenticate with a gateway instance
mosaic sessions list         # List active agent sessions
```

### Management

```bash
mosaic doctor                # Health audit — detect drift and missing files
mosaic sync                  # Sync skills from canonical source
mosaic update                # Check for and install CLI updates
mosaic wizard                # Full guided setup wizard
mosaic bootstrap <path>      # Bootstrap a repo with Mosaic standards
mosaic coord init            # Initialize a new orchestration mission
mosaic prdy init             # Create a PRD via guided session
```

## Development

### Prerequisites

- Node.js ≥ 20
- pnpm 10.6+
- Docker & Docker Compose

### Setup

```bash
git clone git@git.mosaicstack.dev:mosaic/mosaic-stack.git
cd mosaic-stack

# Start infrastructure (Postgres, Valkey, Jaeger)
docker compose up -d

# Install dependencies
pnpm install

# Run migrations
pnpm --filter @mosaicstack/db run db:migrate

# Start all services in dev mode
pnpm dev
```

### Infrastructure

Docker Compose provides:

| Service               | Port      | Purpose                |
| --------------------- | --------- | ---------------------- |
| PostgreSQL (pgvector) | 5433      | Primary database       |
| Valkey                | 6380      | Task queue + caching   |
| Jaeger                | 16686     | Distributed tracing UI |
| OTEL Collector        | 4317/4318 | Telemetry ingestion    |

### Quality Gates

```bash
pnpm typecheck               # TypeScript type checking (all packages)
pnpm lint                    # ESLint (all packages)
pnpm test                    # Vitest (all packages)
pnpm format:check            # Prettier check
pnpm format                  # Prettier auto-fix
```

### CI

Woodpecker CI runs on every push:

- `pnpm install --frozen-lockfile`
- Database migration against a fresh Postgres
- `pnpm test` (Turbo-orchestrated across all packages)

npm packages are published to the Gitea package registry on main merges.

## Architecture

```
mosaic-stack/
├── apps/
│   ├── gateway/             NestJS API + WebSocket hub (Fastify, Socket.IO, OTEL)
│   └── web/                 Next.js dashboard (React 19, Tailwind)
├── packages/
│   ├── cli/                 Mosaic CLI — TUI, gateway client, wizard
│   ├── mosaic/              Framework — wizard, runtime detection, update checker
│   ├── types/               Shared TypeScript contracts (Socket.IO typed events)
│   ├── db/                  Drizzle ORM schema + migrations (pgvector)
│   ├── auth/                BetterAuth configuration
│   ├── brain/               Data layer (PG-backed)
│   ├── queue/               Valkey task queue + MCP
│   ├── coord/               Mission coordination
│   ├── forge/               Multi-stage AI pipeline (intake → board → plan → code → review)
│   ├── macp/                MACP protocol — credential resolution, gate runner, events
│   ├── agent/               Agent session management
│   ├── memory/              Agent memory layer
│   ├── log/                 Structured logging
│   ├── prdy/                PRD creation and validation
│   ├── quality-rails/       Quality templates (TypeScript, Next.js, monorepo)
│   └── design-tokens/       Shared design tokens
├── plugins/
│   ├── discord/             Discord channel plugin (discord.js)
│   ├── telegram/            Telegram channel plugin (Telegraf)
│   ├── macp/                OpenClaw MACP runtime plugin
│   └── mosaic-framework/    OpenClaw framework injection plugin
├── tools/
│   └── install.sh           Unified installer (framework + npm CLI)
├── scripts/agent/           Agent session lifecycle scripts
├── docker-compose.yml       Dev infrastructure
└── .woodpecker/             CI pipeline configs
```

### Key Design Decisions

- **Gateway is the single API surface** — all clients (TUI, web, Discord, Telegram) connect through it
- **ESM everywhere** — `"type": "module"`, `.js` extensions in imports, NodeNext resolution
- **Socket.IO typed events** — defined in `@mosaicstack/types`, enforced at compile time
- **OTEL auto-instrumentation** — loads before NestJS bootstrap
- **Explicit `@Inject()` decorators** — required since tsx/esbuild doesn't emit decorator metadata

### Framework (`~/.config/mosaic/`)

The framework is the bash-based standards layer installed to every developer machine:

```
~/.config/mosaic/
├── AGENTS.md              ← Central standards (loaded into every runtime)
├── SOUL.md                ← Agent identity (name, style, guardrails)
├── USER.md                ← User profile (name, timezone, preferences)
├── TOOLS.md               ← Machine-level tool reference
├── bin/mosaic             ← Unified launcher (claude, codex, opencode, pi, yolo)
├── guides/                ← E2E delivery, orchestrator protocol, PRD, etc.
├── runtime/               ← Per-runtime configs (claude/, codex/, opencode/, pi/)
├── skills/                ← Universal skills (synced from agent-skills repo)
├── tools/                 ← Tool suites (orchestrator, git, quality, prdy, etc.)
└── memory/                ← Persistent agent memory (preserved across upgrades)
```

### Forge Pipeline

Forge is a multi-stage AI pipeline for autonomous feature delivery:

```
Intake → Discovery → Board Review → Planning (3 stages) → Coding → Review → Remediation → Test → Deploy
```

Each stage has a dispatch mode (`exec` for research/review, `yolo` for coding), quality gates, and timeouts. The board review uses multiple AI personas (CEO, CTO, CFO, COO + specialists) to evaluate briefs before committing resources.

## Upgrading

Run the installer again — it handles upgrades automatically:

```bash
bash <(curl -fsSL https://git.mosaicstack.dev/mosaic/mosaic-stack/raw/branch/main/tools/install.sh)
```

Or use the CLI:

```bash
mosaic update                # Check + install CLI updates
mosaic update --check        # Check only, don't install
```

The CLI also performs a background update check on every invocation (cached for 1 hour).

### Installer Flags

```bash
bash tools/install.sh --check        # Version check only
bash tools/install.sh --framework    # Framework only (skip npm CLI)
bash tools/install.sh --cli          # npm CLI only (skip framework)
bash tools/install.sh --ref v1.0     # Install from a specific git ref
```

## Contributing

```bash
# Create a feature branch
git checkout -b feat/my-feature

# Make changes, then verify
pnpm typecheck && pnpm lint && pnpm test && pnpm format:check

# Commit (husky runs lint-staged automatically)
git commit -m "feat: description of change"

# Push and create PR
git push -u origin feat/my-feature
```

DTOs go in `*.dto.ts` files at module boundaries. Scratchpads (`docs/scratchpads/`) are mandatory for non-trivial tasks. See `AGENTS.md` for the full standards reference.

## License

Proprietary — all rights reserved.