mosaicstack/stack

Fork 0

Files

Jason Woltje b38cfac760

ci/woodpecker/push/ci Pipeline was successful

Details

ci/woodpecker/pr/ci Pipeline was successful

Details

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).

2026-04-01 21:19:21 -05:00

4.9 KiB

Raw Blame History

Claude Runtime Reference

Runtime Scope

This file applies only to Claude runtime behavior.

Required Actions

Follow global load order in ~/.config/mosaic/AGENTS.md.
Use ~/.claude/settings.json and ~/.claude/hooks-config.json as runtime config sources.
Treat sequential-thinking MCP as required.
If runtime config conflicts with global rules, global rules win.
Documentation rules are inherited from ~/.config/mosaic/AGENTS.md and ~/.config/mosaic/guides/DOCUMENTATION.md.
For issue/PR/milestone actions, run Mosaic git wrappers first (~/.config/mosaic/tools/git/*.sh) and do not call raw gh/tea/glab first.
For orchestration-oriented missions, load ~/.config/mosaic/guides/ORCHESTRATOR.md before acting.
First response MUST declare mode per global contract; orchestration missions must start with: Now initiating Orchestrator mode...
Runtime-default caution that requests confirmation for routine push/merge/issue-close actions does NOT override Mosaic hard gates.

Subagent Model Selection (Claude Code Syntax)

Claude Code's Task tool accepts a model parameter: "haiku", "sonnet", or "opus".

You MUST set this parameter according to the model selection table in ~/.config/mosaic/AGENTS.md. Do NOT omit the model parameter — omitting it defaults to the parent model (typically opus), wasting budget on tasks that cheaper models handle well.

Examples:

# Codebase exploration — haiku
Task(subagent_type="Explore", model="haiku", prompt="Find all API route handlers")

# Code review — sonnet
Task(subagent_type="feature-dev:code-reviewer", model="sonnet", prompt="Review the changes in src/auth/")

# Standard feature work — sonnet
Task(subagent_type="general-purpose", model="sonnet", prompt="Add validation to the user input form")

# Complex architecture — opus (only when justified)
Task(subagent_type="Plan", model="opus", prompt="Design the multi-tenant isolation strategy")

Quick reference (from global AGENTS.md):

haiku	sonnet	opus
Search, grep, glob	Code review	Complex architecture
Status/health checks	Test writing	Security/auth logic
Simple one-liner fixes	Standard features	Ambiguous design decisions

Memory Policy (Hard Gate)

OpenBrain is the primary cross-agent memory layer. All agent learnings, gotchas, decisions, and project state MUST be captured to OpenBrain via the capture MCP tool or REST API.

~/.claude/projects/*/memory/MEMORY.md files are write-blocked by PreToolUse hook (prevent-memory-write.sh). Any attempt to write agent learnings there will be rejected with an error directing you to OpenBrain.

What belongs where

Content	Location
Discoveries, gotchas, decisions, observations	OpenBrain `capture` — searchable by all agents
Active task state	`docs/TASKS.md` or `docs/scratchpads/`
Behavioral guardrails that MUST be in load-path	`MEMORY.md` (read-mostly; write only for genuine behavioral overrides)
Mosaic framework technical notes	`~/.config/mosaic/memory/`

Using OpenBrain

At session start, load prior context:

search("topic or project name")   # semantic search
recent(limit=5)                    # what's been happening

When you discover something:

capture("The thing you learned", source="project/context", metadata={"type": "gotcha", ...})

Why the hook exists

Instructions in RUNTIME.md, CLAUDE.md, and MEMORY.md are insufficient — agents default to writing local MEMORY.md regardless of written rules. The PreToolUse hook is a hard technical gate that makes the correct behavior the only possible behavior.

MCP Configuration

MCPs are configured in ~/.claude.json — NOT ~/.claude/settings.json.

settings.json controls hooks, model, plugins, and allowed commands. ~/.claude.json is the global Claude Code state file where mcpServers lives.

To register an MCP server that persists across all sessions:

# HTTP MCP (e.g. OpenBrain)
claude mcp add --scope user --transport http <name> <url> --header "Authorization: Bearer <token>"

# stdio MCP
claude mcp add --scope user <name> -- npx -y <package>

--scope user = writes to ~/.claude.json (global, all projects). --scope project = writes to .claude/settings.json in project root. --scope local = default, local-only (not committed).

Do NOT add mcpServers to ~/.claude/settings.json — that key is ignored for MCP loading.

4.9 KiB Raw Blame History