b38cfac760
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).
2.9 KiB
Pi Runtime Reference
Runtime Scope
This file applies only to Pi runtime behavior.
Required Actions
- Follow global load order in
~/.config/mosaic/AGENTS.md. - Use
~/.pi/agent/settings.jsonas runtime config source. - If runtime config conflicts with global rules, global rules win.
- Documentation rules are inherited from
~/.config/mosaic/AGENTS.mdand~/.config/mosaic/guides/DOCUMENTATION.md. - For issue/PR/milestone actions, run Mosaic git wrappers first (
~/.config/mosaic/tools/git/*.sh) and do not call rawgh/tea/glabfirst. - For orchestration-oriented missions, load
~/.config/mosaic/guides/ORCHESTRATOR.mdbefore 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.
Pi-Specific Capabilities
Pi is the native Mosaic agent runtime. Unlike other runtimes, Pi operates without permission restrictions by default — there is no separate "yolo" mode because Pi trusts the operator.
Thinking Levels
Pi supports native thinking levels via --thinking <level>. For complex planning or architecture tasks, use high or xhigh. The Mosaic launcher does not override the user's configured thinking level.
Model Cycling
Pi supports --models for Ctrl+P model cycling during a session. Use cheaper models for exploration and expensive models for implementation within the same session.
Skills
Mosaic skills are loaded natively via Pi's --skill flag. Skills are discovered from:
~/.config/mosaic/skills/(Mosaic global skills)~/.pi/agent/skills/(Pi global skills).pi/skills/(project-local skills)
Extensions
The Mosaic Pi extension (~/.config/mosaic/runtime/pi/mosaic-extension.ts) handles:
- Session start/end lifecycle hooks
- Active mission detection and context injection
- Memory routing to
~/.config/mosaic/memory/ - MACP queue status reporting
Sessions
Pi persists sessions natively. Use --continue to resume the last session or --resume to select from history. Mosaic session locks integrate with Pi's session system.
Memory Policy
All durable memory MUST be written to ~/.config/mosaic/memory/ per ~/.config/mosaic/guides/MEMORY.md. Pi's native session storage (~/.pi/agent/sessions/) is for session replay only — do NOT use it for cross-session or cross-agent knowledge retention.
MCP Configuration
Pi reads MCP server configuration from ~/.pi/agent/settings.json under the mcpServers key. Mosaic bootstrap configures sequential-thinking MCP automatically.
Sequential-Thinking
Pi has native thinking levels (--thinking) which serve the same purpose as sequential-thinking MCP. Both may be active simultaneously without conflict. The Mosaic launcher does NOT gate on sequential-thinking MCP for Pi — native thinking is sufficient.