5c083763c8
Pi workers launched via `mosaic [yolo] pi` never loaded any skill because buildPiSkillArgs emitted `--no-skills` whenever MOSAIC_PI_SKILL_MODE was unset (the default everywhere), so maintained `~/.config/mosaic/tools/` wrappers stayed invisible and workers improvised raw `tmux send-keys` / `tea` / `gh`. An explicit `--skill` overrides `--no-skills` for that path, so we now force-load a small fleet-critical set (default: `mosaic-tools`) on every Pi launch regardless of mode — no full-catalog context bloat. - launch.ts: add DEFAULT_PI_FORCE_SKILLS + forcedPiSkillArgs(); merge into every buildPiSkillArgs() return path (existsSync-guarded → no-op until the skill is synced). Override via MOSAIC_PI_FORCE_SKILLS (colon-separated; empty string disables). - launch.spec.ts: deterministic 4th-param injection + force-load coverage. - runtime/pi/RUNTIME.md: reconcile the "skills load natively" drift with the real default-off + force-load + MOSAIC_PI_SKILL_MODE behavior. - templates/agent/**: fix stale `~/.config/mosaic/rails/` → `tools/` (60 occurrences across 12 scaffold templates; `rails/` no longer exists). Companion skill `mosaic-tools` ships in mosaic/agent-skills. Follow-up (NOT auto-applied): live fleet needs `mosaic-sync-skills` + launcher upgrade to pick up the new skill on running sessions. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QoYiBeKNh3BiYtAJS5Z587
76 lines
3.7 KiB
Markdown
76 lines
3.7 KiB
Markdown
# Pi Runtime Reference
|
|
|
|
## Runtime Scope
|
|
|
|
This file applies only to Pi runtime behavior.
|
|
|
|
## Required Actions
|
|
|
|
1. Follow global load order in `~/.config/mosaic/AGENTS.md`.
|
|
2. Use `~/.pi/agent/settings.json` as runtime config source.
|
|
3. If runtime config conflicts with global rules, global rules win.
|
|
4. Documentation rules are inherited from `~/.config/mosaic/AGENTS.md` and `~/.config/mosaic/guides/DOCUMENTATION.md`.
|
|
5. For issue/PR/milestone actions, run Mosaic git wrappers first (`~/.config/mosaic/tools/git/*.sh`) and do not call raw `gh`/`tea`/`glab` first.
|
|
6. For orchestration-oriented missions, load `~/.config/mosaic/guides/ORCHESTRATOR.md` before acting.
|
|
7. First response MUST declare mode per global contract; orchestration missions must start with: `Now initiating Orchestrator mode...`
|
|
8. 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
|
|
|
|
By default the launcher starts Pi with `--no-skills` to keep startup context small, then
|
|
force-loads a small set of fleet-critical skills via explicit `--skill` flags (an explicit
|
|
`--skill` overrides `--no-skills` for that path). The default forced set is `mosaic-tools`
|
|
(the must-use `~/.config/mosaic/tools/` cheatsheet: inter-agent messaging + git wrappers).
|
|
|
|
Tune skill loading with environment variables:
|
|
|
|
- `MOSAIC_PI_FORCE_SKILLS` — colon-separated skill dir names to force-load (default: `mosaic-tools`;
|
|
set to an empty string to disable force-loading). Missing skills are skipped silently.
|
|
- `MOSAIC_PI_SKILL_MODE=all` — link every skill found in `~/.config/mosaic/{skills,skills-local}/`
|
|
(full catalog; larger context).
|
|
- `MOSAIC_PI_SKILL_MODE=discover` — let Pi discover skills natively (no `--no-skills`), still
|
|
force-loading the fleet set on top.
|
|
|
|
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.
|