mosaicstack/stack

Fork 0

Files

Hermes Agent 5c083763c8

ci/woodpecker/pr/ci Pipeline was successful

Details

ci/woodpecker/push/ci Pipeline was successful

Details

feat(launch): force-load fleet-critical Pi skills + reconcile skill docs

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

2026-06-19 13:20:11 -05:00

3.7 KiB

Raw Blame History

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.json as runtime config source.
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.

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.

3.7 KiB Raw Blame History