From 785d30e065791e79822c7876c7e10cbe4273e935 Mon Sep 17 00:00:00 2001 From: Jarvis Date: Thu, 2 Apr 2026 19:12:28 -0500 Subject: [PATCH] docs: add project README with install, usage, architecture, and dev guide --- README.md | 244 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 244 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..5c907c2 --- /dev/null +++ b/README.md @@ -0,0 +1,244 @@ +# 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/` | +| **@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 @mosaic/cli 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 # 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 @mosaic/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 `@mosaic/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. -- 2.49.1