mosaicstack/stack
21
0
Fork 1
Code Issues 338 Pull Requests 13 Actions Packages Projects Releases 15 Wiki Activity

chore: consolidate new foundation and archive v1 (#1495)

Browse Source
This commit is contained in:
jason.woltje
2026-09-07 12:32:57 -05:00
parent 9a5fbdbda7 5d27700026
commit 127a54fdff
3511 changed files with 727899 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files
v1/packages/mosaic/framework/defaults/README.md
+244
View File
@@ -0,0 +1,244 @@
# 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 [email protected]: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.)
### Install lanes
| Lane | Command | Use when | Source |
| ------------------------ | ------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Stable | `bash tools/install.sh` | You want the released framework and CLI | npm `@mosaicstack/mosaic@latest` + `main` |
| Prerelease integration | `bash tools/install.sh --next` | You want the permanent `next` integration lane | Fast npm `@mosaicstack/mosaic@next` + `@mosaicstack/gateway@next`; source fallback at `next` |
| Contributor/source build | `bash tools/install.sh --dev --ref X` | You are validating a branch before release | Build-from-source at the requested git ref |
`--next` is fast-by-default from the Gitea npm `next` dist-tag and falls back to a source build at the permanent `next` branch if the dist-tag is missing or unreachable. Explicit `--ref` or `MOSAIC_REF` wins and uses the source path.
## 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 "Mosaic Agent" --style direct --user-name "Your Name" --timezone "UTC"
```
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. For Pi, loads the framework-owned core and persistent-goal extensions from
`~/.config/mosaic/runtime/pi/`
5. Forwards all arguments to the runtime CLI
Inside `mosaic pi`, `/goal set <statement>` starts a bounded persistent goal loop. Use `/goal status`,
`/goal pause`, `/goal resume`, or `/goal cancel` to control it. The extension remains part of Mosaic
under `~/.config/mosaic/runtime/pi/goal-extension.ts`; it is not installed in Pi's main extension
directory.
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.)
├── tools/ ← Tool suites: git, orchestrator, prdy, quality, etc.
│ └── _scripts/ ← Framework helper scripts (sync skills, doctor, runtime links)
├── 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, goal-extension.ts
│ └── mcp/ ← MCP server configs
├── skills/ ← Universal skills (shipped with the framework package)
├── 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 + Mosaic extensions |
| `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 --next # Prerelease lane: npm @next, source fallback
bash tools/install.sh --dev # Contributor lane: source build at --ref/main
bash tools/install.sh --ref v1.0 # Install from a specific git ref (--ref wins over --next)
```
The installer rejects unrecognized flags or positional arguments before making changes and prints the supported-option usage.
## Universal Skills
Canonical skills ship inside the framework package itself; the installer installs them into `~/.config/mosaic/skills/` together with the rest of the framework (there is no separate skills repository). Install, wizard finalization, and `mosaic update` automatically link every canonical skill into Claude Code's `~/.claude/skills/` directory.
```bash
mosaic sync # Relink the full canonical catalog
~/.config/mosaic/tools/_scripts/mosaic-sync-skills --link-only # Re-link only (same as default)
mosaic skill list # Show registered, missing, dangling, and foreign entries
mosaic skill register <name> # Register or repair one canonical Claude link
mosaic skill unregister <name> # Remove one Mosaic-owned Claude link
```
Skill names are direct children using `[A-Za-z0-9][A-Za-z0-9._-]*`, not paths. Registration rejects traversal/control characters and never replaces foreign files, directories, or symlinks; unregister removes only links that point inside the canonical Mosaic skill root. After registering during a running Claude Code session, use `/reload-skills` or start a new session.
M1 lifecycle management targets Claude Code. Pi can discover the canonical Mosaic root through its launcher configuration. Codex parity remains follow-up scope and continues to use the existing full skill-sync linker.
## Health Audit
```bash
mosaic doctor # Standard audit
~/.config/mosaic/tools/_scripts/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/tools/_scripts/mosaic-ensure-sequential-thinking
~/.config/mosaic/tools/_scripts/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
```