feat: integrate framework files into monorepo under packages/mosaic/framework/
Moves all Mosaic framework runtime files from the separate bootstrap repo into the monorepo as canonical source. The @mosaic/mosaic npm package now ships the complete framework — bin scripts, runtime configs, tools, and templates — enabling standalone installation via npm install. Structure: packages/mosaic/framework/ ├── bin/ 28 CLI scripts (mosaic, mosaic-doctor, mosaic-sync-skills, etc.) ├── runtime/ Runtime adapters (claude, codex, opencode, pi, mcp) ├── tools/ Shell tooling (git, prdy, orchestrator, quality, etc.) ├── templates/ Agent and repo templates ├── defaults/ Default identity files (AGENTS.md, STANDARDS.md, SOUL.md, etc.) ├── install.sh Legacy bash installer └── remote-install.sh One-liner remote installer Key files with Pi support and recent fixes: - bin/mosaic: launch_pi() with skills-local loop - bin/mosaic-doctor: --fix auto-wiring for all 4 harnesses - bin/mosaic-sync-skills: Pi as 4th link target, symlink-aware find - bin/mosaic-link-runtime-assets: Pi settings.json patching - bin/mosaic-migrate-local-skills: Pi skill roots, symlink find - runtime/pi/RUNTIME.md + mosaic-extension.ts Package ships 251 framework files in the npm tarball (278KB compressed).
This commit is contained in:
Jason Woltje
345
packages/mosaic/framework/defaults/README.md
Normal file
345
packages/mosaic/framework/defaults/README.md
Normal file
@@ -0,0 +1,345 @@
|
||||
# Mosaic Agent Framework
|
||||
|
||||
Universal agent standards layer for Claude Code, Codex, and OpenCode.
|
||||
|
||||
One config, every runtime, same standards.
|
||||
|
||||
> **This repository is a generic framework baseline.** 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 -sL https://git.mosaicstack.dev/mosaic/bootstrap/raw/branch/main/remote-install.sh | sh
|
||||
```
|
||||
|
||||
### Windows (PowerShell)
|
||||
|
||||
```powershell
|
||||
irm https://git.mosaicstack.dev/mosaic/bootstrap/raw/branch/main/remote-install.ps1 | iex
|
||||
```
|
||||
|
||||
### From Source (any platform)
|
||||
|
||||
```bash
|
||||
git clone https://git.mosaicstack.dev/mosaic/bootstrap.git ~/src/mosaic-bootstrap
|
||||
cd ~/src/mosaic-bootstrap && bash install.sh
|
||||
```
|
||||
|
||||
If Node.js 18+ is available, the remote installer automatically uses the TypeScript wizard instead of the bash installer for a richer setup experience.
|
||||
|
||||
The installer will:
|
||||
|
||||
- Install the framework to `~/.config/mosaic/`
|
||||
- Add `~/.config/mosaic/bin` to your PATH
|
||||
- Sync runtime adapters and skills
|
||||
- Install and configure sequential-thinking MCP (hard requirement)
|
||||
- Run a health audit
|
||||
- Detect existing installs and prompt to keep or overwrite local files
|
||||
- Prompt you to run `mosaic init` to set up your agent identity
|
||||
|
||||
## 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), 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 claude # Launch Claude Code with full Mosaic injection
|
||||
mosaic codex # Launch Codex with full Mosaic injection
|
||||
mosaic opencode # Launch OpenCode with full Mosaic injection
|
||||
```
|
||||
|
||||
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/E2E-DELIVERY.md ← Mandatory E2E software delivery procedure
|
||||
├── guides/PRD.md ← Mandatory PRD requirements gate before coding
|
||||
├── guides/DOCUMENTATION.md ← Mandatory documentation standard and gates
|
||||
├── bin/ ← CLI tools (mosaic, mosaic-init, mosaic-doctor, etc.)
|
||||
├── dist/ ← Bundled wizard (mosaic-wizard.mjs)
|
||||
├── guides/ ← Operational guides
|
||||
├── tools/ ← Tool suites: git, portainer, authentik, coolify, codex, etc.
|
||||
├── runtime/ ← Runtime adapters + runtime-specific references
|
||||
│ ├── claude/CLAUDE.md
|
||||
│ ├── claude/RUNTIME.md
|
||||
│ ├── opencode/AGENTS.md
|
||||
│ ├── opencode/RUNTIME.md
|
||||
│ ├── codex/instructions.md
|
||||
│ ├── codex/RUNTIME.md
|
||||
│ └── mcp/SEQUENTIAL-THINKING.json
|
||||
├── skills/ ← Universal skills (synced from mosaic/agent-skills)
|
||||
├── skills-local/ ← Local cross-runtime skills
|
||||
└── templates/ ← SOUL.md template, project templates
|
||||
```
|
||||
|
||||
### How AGENTS.md Gets Loaded
|
||||
|
||||
| Launch method | Injection mechanism |
|
||||
| ------------------- | ----------------------------------------------------------------------------------------- |
|
||||
| `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 |
|
||||
|
||||
Mosaic `AGENTS.md` enforces loading `guides/E2E-DELIVERY.md` before execution and
|
||||
requires `guides/PRD.md` before coding and `guides/DOCUMENTATION.md` for code/API/auth/infra documentation gates.
|
||||
|
||||
## 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 check # Check release upgrade status (no changes)
|
||||
mosaic upgrade # Upgrade installed Mosaic release (keeps SOUL.md by default)
|
||||
mosaic upgrade --dry-run # Preview release upgrade without changes
|
||||
mosaic upgrade --ref main # Upgrade from a specific branch/tag/commit ref
|
||||
mosaic upgrade --overwrite # Upgrade release and overwrite local files
|
||||
mosaic upgrade project ... # Project file cleanup mode (see below)
|
||||
```
|
||||
|
||||
## Upgrading Mosaic Release
|
||||
|
||||
Upgrade the installed framework in place:
|
||||
|
||||
```bash
|
||||
# Default (safe): keep local SOUL.md, USER.md, TOOLS.md + memory
|
||||
mosaic upgrade
|
||||
|
||||
# Check current/target release info without changing files
|
||||
mosaic upgrade check
|
||||
|
||||
# Non-interactive
|
||||
mosaic upgrade --yes
|
||||
|
||||
# Pull a specific ref
|
||||
mosaic upgrade --ref main
|
||||
|
||||
# Force full overwrite (fresh install semantics)
|
||||
mosaic upgrade --overwrite --yes
|
||||
```
|
||||
|
||||
`mosaic upgrade` re-runs the remote installer and passes install mode controls (`keep`/`overwrite`).
|
||||
This is the manual upgrade path today and is suitable for future app-driven update checks.
|
||||
|
||||
## Upgrading Projects
|
||||
|
||||
After centralizing AGENTS.md and SOUL.md, existing projects may have stale files:
|
||||
|
||||
```bash
|
||||
# Preview what would change across all projects
|
||||
mosaic upgrade project --all --dry-run
|
||||
|
||||
# Apply to all projects
|
||||
mosaic upgrade project --all
|
||||
|
||||
# Apply to a specific project
|
||||
mosaic upgrade project ~/src/my-project
|
||||
```
|
||||
|
||||
Backward compatibility is preserved for historical usage:
|
||||
|
||||
```bash
|
||||
mosaic upgrade --all # still routes to project-upgrade
|
||||
mosaic upgrade ~/src/my-repo # still routes to project-upgrade
|
||||
```
|
||||
|
||||
What it does per project:
|
||||
|
||||
| File | Action |
|
||||
| ----------- | ------------------------------------------------------------- |
|
||||
| `SOUL.md` | Removed — now global at `~/.config/mosaic/SOUL.md` |
|
||||
| `CLAUDE.md` | Replaced with thin pointer to global AGENTS.md |
|
||||
| `AGENTS.md` | Stale load-order sections stripped; project content preserved |
|
||||
|
||||
Backups (`.mosaic-bak`) are created before any modification.
|
||||
|
||||
## Universal Skills
|
||||
|
||||
The installer syncs skills from `mosaic/agent-skills` into `~/.config/mosaic/skills/`, then links each skill into runtime directories (`~/.claude/skills`, `~/.codex/skills`, `~/.config/opencode/skills`).
|
||||
|
||||
```bash
|
||||
mosaic sync # Full sync (clone + link)
|
||||
~/.config/mosaic/bin/mosaic-sync-skills --link-only # Re-link only
|
||||
```
|
||||
|
||||
## Runtime Compatibility
|
||||
|
||||
The installer pushes thin runtime adapters as regular files (not symlinks):
|
||||
|
||||
- `~/.claude/CLAUDE.md` — pointer to `~/.config/mosaic/AGENTS.md`
|
||||
- `~/.claude/settings.json`, `hooks-config.json`, `context7-integration.md`
|
||||
- `~/.config/opencode/AGENTS.md` — pointer to `~/.config/mosaic/AGENTS.md`
|
||||
- `~/.codex/instructions.md` — pointer to `~/.config/mosaic/AGENTS.md`
|
||||
- `~/.claude/settings.json`, `~/.codex/config.toml`, and `~/.config/opencode/config.json` include sequential-thinking MCP config
|
||||
|
||||
Re-sync manually:
|
||||
|
||||
```bash
|
||||
~/.config/mosaic/bin/mosaic-link-runtime-assets
|
||||
```
|
||||
|
||||
## MCP Registration
|
||||
|
||||
### How MCPs Are Configured in Claude Code
|
||||
|
||||
**MCPs must be registered via `claude mcp add` — not by hand-editing `~/.claude/settings.json`.**
|
||||
|
||||
`settings.json` controls hooks, model, plugins, and allowed commands. The `mcpServers` key in
|
||||
`settings.json` is silently ignored by Claude Code's MCP loader. The correct file is `~/.claude.json`,
|
||||
which is managed by the `claude mcp` CLI.
|
||||
|
||||
```bash
|
||||
# Register a stdio MCP (user scope = all projects, persists across sessions)
|
||||
claude mcp add --scope user <name> -- npx -y <package>
|
||||
|
||||
# Register an HTTP MCP (e.g. OpenBrain)
|
||||
claude mcp add --scope user --transport http <name> <url> \
|
||||
--header "Authorization: Bearer <token>"
|
||||
|
||||
# List registered MCPs
|
||||
claude mcp list
|
||||
```
|
||||
|
||||
**Scope options:**
|
||||
|
||||
- `--scope user` — writes to `~/.claude.json`, available in all projects (recommended for shared tools)
|
||||
- `--scope project` — writes to `.claude/settings.json` in the project root, committed to the repo
|
||||
- `--scope local` — default, machine-local only, not committed
|
||||
|
||||
**Transport for HTTP MCPs must be `http`** — not `sse`. `type: "sse"` is a deprecated protocol
|
||||
that silently fails to connect against FastMCP streamable HTTP servers.
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
### OpenBrain Semantic Memory (Recommended)
|
||||
|
||||
OpenBrain is the shared cross-agent memory layer. Register once per machine:
|
||||
|
||||
```bash
|
||||
claude mcp add --scope user --transport http openbrain https://your-openbrain-host/mcp \
|
||||
--header "Authorization: Bearer YOUR_TOKEN"
|
||||
```
|
||||
|
||||
See [mosaic/openbrain](https://git.mosaicstack.dev/mosaic/openbrain) for setup and API docs.
|
||||
|
||||
## Bootstrap Any Repo
|
||||
|
||||
Attach any repository to the Mosaic standards layer:
|
||||
|
||||
```bash
|
||||
mosaic bootstrap /path/to/repo
|
||||
```
|
||||
|
||||
This creates `.mosaic/`, `scripts/agent/`, and an `AGENTS.md` if missing.
|
||||
|
||||
## Quality Rails
|
||||
|
||||
Apply and verify quality templates:
|
||||
|
||||
```bash
|
||||
~/.config/mosaic/bin/mosaic-quality-apply --template typescript-node --target /path/to/repo
|
||||
~/.config/mosaic/bin/mosaic-quality-verify --target /path/to/repo
|
||||
```
|
||||
|
||||
Templates: `typescript-node`, `typescript-nextjs`, `monorepo`
|
||||
|
||||
## Health Audit
|
||||
|
||||
```bash
|
||||
mosaic doctor # Standard audit
|
||||
~/.config/mosaic/bin/mosaic-doctor --fail-on-warn # Strict mode
|
||||
```
|
||||
|
||||
## Wizard Development
|
||||
|
||||
The installation wizard is a TypeScript project in the root of this repo.
|
||||
|
||||
```bash
|
||||
pnpm install # Install dependencies
|
||||
pnpm dev # Run wizard from source (tsx)
|
||||
pnpm build # Bundle to dist/mosaic-wizard.mjs
|
||||
pnpm test # Run tests (30 tests, vitest)
|
||||
pnpm typecheck # TypeScript type checking
|
||||
```
|
||||
|
||||
The wizard uses `@clack/prompts` for the interactive TUI and supports `--non-interactive` mode via `HeadlessPrompter` for CI and scripted installs. The bundled output (`dist/mosaic-wizard.mjs`) is committed to the repo so installs work without `node_modules`.
|
||||
|
||||
## Re-installing / Updating
|
||||
|
||||
Pull the latest and re-run the installer:
|
||||
|
||||
```bash
|
||||
cd ~/src/mosaic-bootstrap && git pull && bash install.sh
|
||||
```
|
||||
|
||||
If an existing install is detected, the installer prompts for:
|
||||
|
||||
- `keep` (recommended): preserve local `SOUL.md`, `USER.md`, `TOOLS.md`, and `memory/`
|
||||
- `overwrite`: replace everything in `~/.config/mosaic`
|
||||
|
||||
Or use the one-liner again — it always pulls the latest:
|
||||
|
||||
```bash
|
||||
curl -sL https://git.mosaicstack.dev/mosaic/bootstrap/raw/branch/main/remote-install.sh | sh
|
||||
```
|
||||
Reference in New Issue
Block a user