217 lines
8.2 KiB
Markdown
217 lines
8.2 KiB
Markdown
# Mosaic Agent Framework
|
|
|
|
Universal agent standards layer for Claude Code, Codex, OpenCode, and Pi.
|
|
|
|
One config, every runtime, same standards.
|
|
|
|
> **This is the framework component of [mosaic-stack](https://git.mosaicstack.dev/mosaicstack/stack).** No personal data, credentials, user-specific preferences, or machine-specific paths should be committed. All personalization happens at install time via `mosaic init` or by editing files in `~/.config/mosaic/` after installation.
|
|
|
|
## Quick Install
|
|
|
|
### Mac / Linux
|
|
|
|
```bash
|
|
curl -fsSL https://mosaicstack.dev/install.sh | bash
|
|
```
|
|
|
|
Or use the direct URL:
|
|
|
|
```bash
|
|
bash <(curl -fsSL https://git.mosaicstack.dev/mosaicstack/stack/raw/branch/main/tools/install.sh)
|
|
```
|
|
|
|
### Windows (PowerShell)
|
|
|
|
```powershell
|
|
# PowerShell installer coming soon — use WSL + the bash installer above.
|
|
```
|
|
|
|
### From Source (any platform)
|
|
|
|
```bash
|
|
git clone git@git.mosaicstack.dev:mosaicstack/stack.git ~/src/stack
|
|
cd ~/src/stack && bash tools/install.sh
|
|
```
|
|
|
|
The installer:
|
|
|
|
- Downloads the framework from the monorepo archive
|
|
- Installs it to `~/.config/mosaic/`
|
|
- Installs `@mosaicstack/mosaic` globally via npm (unified `mosaic` CLI — TUI, gateway client, wizard)
|
|
- Adds `~/.config/mosaic/bin` to your PATH
|
|
- Syncs runtime adapters and skills
|
|
- Runs a health audit
|
|
- Detects existing installs and preserves local files (SOUL.md, USER.md, etc.)
|
|
|
|
## First Run
|
|
|
|
After install, open a new terminal (or `source ~/.bashrc`) and run:
|
|
|
|
```bash
|
|
mosaic init
|
|
```
|
|
|
|
If Node.js 18+ is installed, this launches an interactive wizard with two modes:
|
|
|
|
- **Quick Start** (~2 min): agent name + communication style, sensible defaults for everything else
|
|
- **Advanced**: full customization of identity, user profile, tools, runtimes, and skills
|
|
|
|
The wizard configures three files loaded into every agent session:
|
|
|
|
- `SOUL.md` — agent identity contract (name, style, guardrails)
|
|
- `USER.md` — your user profile (name, timezone, accessibility, preferences)
|
|
- `TOOLS.md` — machine-level tool reference (git providers, credentials, CLI patterns)
|
|
|
|
It also detects installed runtimes (Claude, Codex, OpenCode, Pi), configures sequential-thinking MCP, and offers curated skill selection from 8 categories.
|
|
|
|
### Non-Interactive Mode
|
|
|
|
For CI or scripted installs:
|
|
|
|
```bash
|
|
mosaic init --non-interactive --name Jarvis --style direct --user-name Jason --timezone America/Chicago
|
|
```
|
|
|
|
All flags: `--name`, `--role`, `--style`, `--user-name`, `--pronouns`, `--timezone`, `--mosaic-home`, `--source-dir`.
|
|
|
|
### Legacy Fallback
|
|
|
|
If Node.js is unavailable, `mosaic init` falls back to the bash-based `mosaic-init` script.
|
|
|
|
## Launching Agent Sessions
|
|
|
|
```bash
|
|
mosaic pi # Launch Pi with full Mosaic injection (recommended)
|
|
mosaic claude # Launch Claude Code with full Mosaic injection
|
|
mosaic codex # Launch Codex with full Mosaic injection
|
|
mosaic opencode # Launch OpenCode with full Mosaic injection
|
|
mosaic yolo claude # Launch Claude in dangerous-permissions mode
|
|
mosaic yolo pi # Launch Pi in yolo mode
|
|
```
|
|
|
|
The launcher:
|
|
|
|
1. Verifies `~/.config/mosaic` exists
|
|
2. Verifies `SOUL.md` exists (auto-runs `mosaic init` if missing)
|
|
3. Injects `AGENTS.md` into the runtime
|
|
4. Forwards all arguments to the runtime CLI
|
|
|
|
You can still launch runtimes directly (`claude`, `codex`, etc.) — thin runtime adapters will tell the agent to read `~/.config/mosaic/AGENTS.md`.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
~/.config/mosaic/
|
|
├── AGENTS.md ← THE source of truth (all standards, all runtimes)
|
|
├── SOUL.md ← Agent identity (generated by mosaic init)
|
|
├── USER.md ← User profile and accessibility (generated by mosaic init)
|
|
├── TOOLS.md ← Machine-level tool reference (generated by mosaic init)
|
|
├── STANDARDS.md ← Machine-wide standards
|
|
├── guides/ ← Operational guides (E2E delivery, PRD, docs, etc.)
|
|
├── bin/ ← CLI tools (mosaic launcher, mosaic-init, mosaic-doctor, etc.)
|
|
├── tools/ ← Tool suites: git, orchestrator, prdy, quality, etc.
|
|
├── runtime/ ← Runtime adapters + runtime-specific references
|
|
│ ├── claude/ ← CLAUDE.md, RUNTIME.md, settings.json, hooks
|
|
│ ├── codex/ ← instructions.md, RUNTIME.md
|
|
│ ├── opencode/ ← AGENTS.md, RUNTIME.md
|
|
│ ├── pi/ ← RUNTIME.md, mosaic-extension.ts
|
|
│ └── mcp/ ← MCP server configs
|
|
├── skills/ ← Universal skills (synced from mosaic/agent-skills)
|
|
├── skills-local/ ← Local cross-runtime skills
|
|
├── memory/ ← Persistent agent memory (preserved across upgrades)
|
|
└── templates/ ← SOUL.md template, project templates
|
|
```
|
|
|
|
### How AGENTS.md Gets Loaded
|
|
|
|
| Launch method | Injection mechanism |
|
|
| ------------------- | ----------------------------------------------------------------------------------------- |
|
|
| `mosaic pi` | `--append-system-prompt` with composed runtime contract + skills + extension |
|
|
| `mosaic claude` | `--append-system-prompt` with composed runtime contract (`AGENTS.md` + runtime reference) |
|
|
| `mosaic codex` | Writes composed runtime contract to `~/.codex/instructions.md` before launch |
|
|
| `mosaic opencode` | Writes composed runtime contract to `~/.config/opencode/AGENTS.md` before launch |
|
|
| `claude` (direct) | `~/.claude/CLAUDE.md` thin pointer → load AGENTS + runtime reference |
|
|
| `codex` (direct) | `~/.codex/instructions.md` thin pointer → load AGENTS + runtime reference |
|
|
| `opencode` (direct) | `~/.config/opencode/AGENTS.md` thin pointer → load AGENTS + runtime reference |
|
|
|
|
## Management Commands
|
|
|
|
```bash
|
|
mosaic help # Show all commands
|
|
mosaic init # Interactive wizard (or legacy init)
|
|
mosaic doctor # Health audit — detect drift and missing files
|
|
mosaic sync # Sync skills from canonical source
|
|
mosaic bootstrap <path> # Bootstrap a repo with Mosaic standards
|
|
mosaic upgrade # Upgrade installed Mosaic release
|
|
mosaic upgrade check # Check upgrade status (no changes)
|
|
```
|
|
|
|
## Upgrading
|
|
|
|
Run the installer again — it handles upgrades automatically:
|
|
|
|
```bash
|
|
curl -fsSL https://mosaicstack.dev/install.sh | bash
|
|
```
|
|
|
|
Or use the direct URL:
|
|
|
|
```bash
|
|
bash <(curl -fsSL https://git.mosaicstack.dev/mosaicstack/stack/raw/branch/main/tools/install.sh)
|
|
```
|
|
|
|
Or from a local checkout:
|
|
|
|
```bash
|
|
cd ~/src/stack && git pull && bash tools/install.sh
|
|
```
|
|
|
|
The installer preserves local `SOUL.md`, `USER.md`, `TOOLS.md`, and `memory/` by default.
|
|
|
|
### 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
|
|
```
|
|
|
|
## Universal Skills
|
|
|
|
The installer syncs skills from `mosaic/agent-skills` into `~/.config/mosaic/skills/`, then links each skill into runtime directories.
|
|
|
|
```bash
|
|
mosaic sync # Full sync (clone + link)
|
|
~/.config/mosaic/bin/mosaic-sync-skills --link-only # Re-link only
|
|
```
|
|
|
|
## Health Audit
|
|
|
|
```bash
|
|
mosaic doctor # Standard audit
|
|
~/.config/mosaic/bin/mosaic-doctor --fail-on-warn # Strict mode
|
|
```
|
|
|
|
## MCP Registration
|
|
|
|
### sequential-thinking MCP (Hard Requirement)
|
|
|
|
sequential-thinking MCP is required for Mosaic Stack. The installer registers it automatically.
|
|
To verify or re-register manually:
|
|
|
|
```bash
|
|
~/.config/mosaic/bin/mosaic-ensure-sequential-thinking
|
|
~/.config/mosaic/bin/mosaic-ensure-sequential-thinking --check
|
|
```
|
|
|
|
### Claude Code MCP Registration
|
|
|
|
**MCPs must be registered via `claude mcp add` — not by hand-editing `~/.claude/settings.json`.**
|
|
|
|
```bash
|
|
claude mcp add --scope user <name> -- npx -y <package>
|
|
claude mcp add --scope user --transport http <name> <url> --header "Authorization: Bearer <token>"
|
|
claude mcp list
|
|
```
|