# Mosaic Orchestrator

Agent orchestration service for Mosaic Stack built with NestJS.

## Overview

The Orchestrator is the execution plane of Mosaic Stack, responsible for:

- Spawning and managing Claude agents
- Task queue management (Valkey-backed)
- Agent health monitoring and recovery
- Git workflow automation
- Quality gate enforcement callbacks
- Killswitch emergency stop

## Architecture

Part of the Mosaic Stack monorepo at `apps/orchestrator/`.

Controlled by `apps/coordinator/` (Quality Coordinator).
Monitored via `apps/web/` (Agent Dashboard).

## Development

```bash
# Install dependencies (from monorepo root)
pnpm install

# Run in dev mode (watch mode)
pnpm --filter @mosaic/orchestrator dev

# Build
pnpm --filter @mosaic/orchestrator build

# Start production
pnpm --filter @mosaic/orchestrator start:prod

# Test
pnpm --filter @mosaic/orchestrator test

# Generate module (NestJS CLI)
cd apps/orchestrator
nest generate module <name>
nest generate controller <name>
nest generate service <name>
```

## NestJS Architecture

- **Modules:** Feature-based organization (spawner, queue, monitor, etc.)
- **Controllers:** HTTP endpoints (health, agents, tasks)
- **Services:** Business logic
- **Providers:** Dependency injection

## Configuration

Environment variables loaded via @nestjs/config.
See `.env.example` for required vars.

## Documentation

- Architecture: `/docs/ORCHESTRATOR-MONOREPO-SETUP.md`
- API Contracts: `/docs/M6-ISSUE-AUDIT.md`
- Milestone: M6-AgentOrchestration (0.0.6)