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
docs(framework/tools): lead TOOLS.md with high-salience fleet-tools cheatsheet (#554 )
2026-06-19 13:20:11 -05:00 · 2026-06-19 18:03:03 +00:00
16 changed files with 223 additions and 73 deletions
--- a/packages/mosaic/framework/defaults/TOOLS.md
+++ b/packages/mosaic/framework/defaults/TOOLS.md
@@ -5,10 +5,39 @@ Tool suites live at `~/.config/mosaic/tools/<suite>/`. This is the index only.
 read it (or the relevant service guide) when your task actually touches that service.
 Project-specific tooling belongs in the project's `AGENTS.md`, not here.
 ## ⚡ Most-used fleet tools (reach for these FIRST — don't hand-roll)
 You are a Mosaic fleet agent. These cover the highest-frequency cross-agent and git-provider
 tasks — use them before improvising with raw `tmux send-keys`, raw `tea`/`gh`/`glab`, or `curl`.
 **1. Message another agent** → `tools/tmux/agent-send.sh` (NOT raw `tmux send-keys`):
 ```bash
 tools/tmux/agent-send.sh -s <target-session> -m "message"   # or -f <file> to send a file's contents
 ```
 The coordinator session is `mos-claude` — send status, findings, and questions there.
 **2. Issues / PRs / milestones** → `tools/git/*.sh` wrappers (before raw `tea`/`gh`/`glab`):
 ```bash
 tools/git/pr-create.sh ...   tools/git/issue-create.sh ...   tools/git/pr-merge.sh ...
 tools/git/ci-queue-wait.sh --purpose push|merge   # REQUIRED before any push/merge
 ```
 **GITEA_LOGIN gotcha** — the wrappers default to login `mosaicstack`; on a USC repo that fails with
 `gitea / Error: GetUserByName ... not found`. Pick the login from the repo's `origin` host first:
 | origin host           | login                                    |
 | --------------------- | ---------------------------------------- |
 | `git.uscllc.com`      | `export GITEA_LOGIN=usc`                 |
 | `git.mosaicstack.dev` | default `mosaicstack` (no export needed) |
 ## Suites (use wrappers first)
 | Suite      | Path                                             | Purpose                                                                  |
 | ---------- | ------------------------------------------------ | ------------------------------------------------------------------------ |
 | tmux       | `tools/tmux/agent-send.sh`                       | inter-agent messaging (see "Most-used" above)                            |
 | git        | `tools/git/*.sh`                                 | issues, PRs, milestones, CI queue guard (platform-auto-detected)         |
 | woodpecker | `tools/woodpecker/*.sh`                          | CI pipelines (`-a mosaic`\|`usc`; match git remote host)                 |
 | portainer  | `tools/portainer/*.sh`                           | Docker Swarm stacks (status/redeploy/list)                               |
--- a/packages/mosaic/framework/runtime/pi/RUNTIME.md
+++ b/packages/mosaic/framework/runtime/pi/RUNTIME.md
@@ -29,7 +29,21 @@ Pi supports `--models` for Ctrl+P model cycling during a session. Use cheaper mo
 ### Skills
-Mosaic skills are loaded natively via Pi's `--skill` flag. Skills are discovered from:
+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)
--- a/packages/mosaic/framework/templates/agent/AGENTS.md.template
+++ b/packages/mosaic/framework/templates/agent/AGENTS.md.template
@@ -9,8 +9,8 @@
 2. Do NOT ask for routine confirmation before required push/merge/issue-close/release/tag actions.
 3. Completion is forbidden at PR-open stage.
 4. Completion requires merged PR to `main` + terminal green CI + linked issue/internal task closed.
-5. Before push or merge, run queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
+5. Before push or merge, run queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
-6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/rails/git/*.sh`).
+6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/tools/git/*.sh`).
 7. If any required wrapper command fails: report `blocked` with the exact failed wrapper command and stop.
 8. Do NOT stop at "PR created" and do NOT ask "should I merge?" for routine flow.
@@ -58,7 +58,7 @@ ${QUALITY_GATES}
 2. If external git provider is available (Gitea/GitHub/GitLab), create/update issue(s) before coding and map them in `docs/TASKS.md`.
 3. If no external provider is available, use internal refs in `docs/TASKS.md` (example: `TASKS:T1`).
 4. Keep `docs/TASKS.md` status in sync with actual progress until completion.
-5. For issue/PR/milestone actions, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first (no raw `gh`/`tea`/`glab` as first choice).
+5. For issue/PR/milestone actions, detect platform and use `~/.config/mosaic/tools/git/*.sh` wrappers first (no raw `gh`/`tea`/`glab` as first choice).
 6. If wrapper-driven merge/CI/issue-closure fails, report blocker with the exact failed wrapper command and stop (do not claim completion).
 ## Documentation Contract
@@ -88,7 +88,7 @@ Reference:
 5. Do not mark implementation complete until PR is merged.
 6. Do not mark implementation complete until CI/pipeline status is terminal green.
 7. Close linked issues/tasks only after merge + green CI.
-8. Before push or merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
+8. Before push or merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
 ## Container Release Strategy (When Applicable)
@@ -138,8 +138,8 @@ When completing an orchestrated task:
 ### Post-Coding Review
 After implementing changes, code review is REQUIRED for any source-code modification.
 For orchestrated tasks, the orchestrator will run:
-1. **Codex code review** — `~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted`
+1. **Codex code review** — `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted`
-2. **Codex security review** — `~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted`
+2. **Codex security review** — `~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted`
 3. If blockers/critical findings: remediation task created
 4. If clean: task marked done
--- a/packages/mosaic/framework/templates/agent/CLAUDE.md.template
+++ b/packages/mosaic/framework/templates/agent/CLAUDE.md.template
@@ -135,7 +135,7 @@ ${QUALITY_GATES}
 ## Issue Tracking
 Use external git provider issues when available. If no external provider exists, `docs/TASKS.md` is the canonical tracker for tasks, milestones, and issue-equivalent work.
-For issue/PR/milestone operations, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first; do not use raw `gh`/`tea`/`glab` as first choice.
+For issue/PR/milestone operations, detect platform and use `~/.config/mosaic/tools/git/*.sh` wrappers first; do not use raw `gh`/`tea`/`glab` as first choice.
 If wrapper-driven merge/CI/issue-closure fails, report blocker with exact failed wrapper command and stop.
 Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close the issue?" for routine delivery flow.
@@ -147,9 +147,9 @@ Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close
 5. Ensure `docs/PRD.md` or `docs/PRD.json` exists and is current before coding.
 6. Create scratchpad: `docs/scratchpads/{task-id}-{short-name}.md` and include issue/internal ref.
 7. Update `docs/TASKS.md` status + issue/internal ref before coding.
-8. Before push, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push -B main`.
+8. Before push, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push -B main`.
 9. Open PR to `main` for delivery changes (no direct push to `main`).
-10. Before merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose merge -B main`.
+10. Before merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B main`.
 11. Merge PRs that pass required checks and review gates with squash strategy only.
 12. Reference issues/internal refs in commits (`Fixes #123`, `Refs #123`, or `Refs TASKS:T1`).
 13. Close issue/internal task only after testing and documentation gates pass, PR merge is complete, and CI/pipeline status is terminal green.
@@ -176,10 +176,10 @@ Run independent reviews:
 ```bash
 # Code quality review (Codex)
-~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
+~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted
 # Security review (Codex)
-~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
+~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted
 ```
 **Fallback:** If Codex is unavailable, use Claude's built-in review skills.
--- a/packages/mosaic/framework/templates/agent/projects/django/AGENTS.md.template
+++ b/packages/mosaic/framework/templates/agent/projects/django/AGENTS.md.template
@@ -9,8 +9,8 @@
 2. Do NOT ask for routine confirmation before required push/merge/issue-close/release/tag actions.
 3. Completion is forbidden at PR-open stage.
 4. Completion requires merged PR to `main` + terminal green CI + linked issue/internal task closed.
-5. Before push or merge, run queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
+5. Before push or merge, run queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
-6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/rails/git/*.sh`).
+6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/tools/git/*.sh`).
 7. If any required wrapper command fails: report `blocked` with the exact failed wrapper command and stop.
 8. Do NOT stop at "PR created" and do NOT ask "should I merge?" for routine flow.
@@ -68,7 +68,7 @@ ruff check . && mypy . && pytest tests/
 2. If external git provider is available (Gitea/GitHub/GitLab), create/update issue(s) before coding and map them in `docs/TASKS.md`.
 3. If no external provider is available, use internal refs in `docs/TASKS.md` (example: `TASKS:T1`).
 4. Keep `docs/TASKS.md` status in sync with actual progress until completion.
-5. For issue/PR/milestone actions, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first (no raw `gh`/`tea`/`glab` as first choice).
+5. For issue/PR/milestone actions, detect platform and use `~/.config/mosaic/tools/git/*.sh` wrappers first (no raw `gh`/`tea`/`glab` as first choice).
 6. If wrapper-driven merge/CI/issue-closure fails, report blocker with the exact failed wrapper command and stop (do not claim completion).
 ## Documentation Contract
@@ -97,7 +97,7 @@ Reference:
 5. Do not mark implementation complete until PR is merged.
 6. Do not mark implementation complete until CI/pipeline status is terminal green.
 7. Close linked issues/tasks only after merge + green CI.
-8. Before push or merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
+8. Before push or merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
 ## Container Release Strategy (When Applicable)
@@ -139,8 +139,8 @@ Use `${TASK_PREFIX}` for orchestrated tasks (e.g., `${TASK_PREFIX}-SEC-001`).
 ### Post-Coding Review
 After implementing changes, code review is REQUIRED for any source-code modification.
 For orchestrated tasks, the orchestrator will run:
-1. **Codex code review** — `~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted`
+1. **Codex code review** — `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted`
-2. **Codex security review** — `~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted`
+2. **Codex security review** — `~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted`
 3. If blockers/critical findings: remediation task created
 4. If clean: task marked done
--- a/packages/mosaic/framework/templates/agent/projects/django/CLAUDE.md.template
+++ b/packages/mosaic/framework/templates/agent/projects/django/CLAUDE.md.template
@@ -159,10 +159,10 @@ Run independent reviews:
 ```bash
 # Code quality review (Codex)
-~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
+~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted
 # Security review (Codex)
-~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
+~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted
 ```
 See `~/.config/mosaic/guides/CODE-REVIEW.md` for the full review checklist.
@@ -186,7 +186,7 @@ See `~/.config/mosaic/guides/DOCUMENTATION.md` for required documentation delive
 ## Issue Tracking
 Use external git provider issues when available. If no external provider exists, `docs/TASKS.md` is the canonical tracker for tasks, milestones, and issue-equivalent work.
-For issue/PR/milestone operations, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first; do not use raw `gh`/`tea`/`glab` as first choice.
+For issue/PR/milestone operations, detect platform and use `~/.config/mosaic/tools/git/*.sh` wrappers first; do not use raw `gh`/`tea`/`glab` as first choice.
 If wrapper-driven merge/CI/issue-closure fails, report blocker with exact failed wrapper command and stop.
 Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close the issue?" for routine delivery flow.
@@ -198,9 +198,9 @@ Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close
 5. Ensure `docs/PRD.md` or `docs/PRD.json` exists and is current before coding.
 6. Create scratchpad: `docs/scratchpads/{task-id}-{short-name}.md` and include issue/internal ref.
 7. Update `docs/TASKS.md` status + issue/internal ref before coding.
-8. Before push, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push -B main`.
+8. Before push, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push -B main`.
 9. Open PR to `main` for delivery changes (no direct push to `main`).
-10. Before merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose merge -B main`.
+10. Before merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B main`.
 11. Merge PRs that pass required checks and review gates with squash strategy only.
 12. Reference issues/internal refs in commits (`Fixes #123`, `Refs #123`, or `Refs TASKS:T1`).
 13. Close issue/internal task only after testing and documentation gates pass, PR merge is complete, and CI/pipeline status is terminal green.
--- a/packages/mosaic/framework/templates/agent/projects/nestjs-nextjs/AGENTS.md.template
+++ b/packages/mosaic/framework/templates/agent/projects/nestjs-nextjs/AGENTS.md.template
@@ -9,8 +9,8 @@
 2. Do NOT ask for routine confirmation before required push/merge/issue-close/release/tag actions.
 3. Completion is forbidden at PR-open stage.
 4. Completion requires merged PR to `main` + terminal green CI + linked issue/internal task closed.
-5. Before push or merge, run queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
+5. Before push or merge, run queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
-6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/rails/git/*.sh`).
+6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/tools/git/*.sh`).
 7. If any required wrapper command fails: report `blocked` with the exact failed wrapper command and stop.
 8. Do NOT stop at "PR created" and do NOT ask "should I merge?" for routine flow.
@@ -72,7 +72,7 @@ pnpm typecheck && pnpm lint && pnpm test
 2. If external git provider is available (Gitea/GitHub/GitLab), create/update issue(s) before coding and map them in `docs/TASKS.md`.
 3. If no external provider is available, use internal refs in `docs/TASKS.md` (example: `TASKS:T1`).
 4. Keep `docs/TASKS.md` status in sync with actual progress until completion.
-5. For issue/PR/milestone actions, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first (no raw `gh`/`tea`/`glab` as first choice).
+5. For issue/PR/milestone actions, detect platform and use `~/.config/mosaic/tools/git/*.sh` wrappers first (no raw `gh`/`tea`/`glab` as first choice).
 6. If wrapper-driven merge/CI/issue-closure fails, report blocker with the exact failed wrapper command and stop (do not claim completion).
 ## Documentation Contract
@@ -101,7 +101,7 @@ Reference:
 5. Do not mark implementation complete until PR is merged.
 6. Do not mark implementation complete until CI/pipeline status is terminal green.
 7. Close linked issues/tasks only after merge + green CI.
-8. Before push or merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
+8. Before push or merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
 ## Container Release Strategy (When Applicable)
@@ -143,8 +143,8 @@ Use `${TASK_PREFIX}` for orchestrated tasks (e.g., `${TASK_PREFIX}-SEC-001`).
 ### Post-Coding Review
 After implementing changes, code review is REQUIRED for any source-code modification.
 For orchestrated tasks, the orchestrator will run:
-1. **Codex code review** — `~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted`
+1. **Codex code review** — `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted`
-2. **Codex security review** — `~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted`
+2. **Codex security review** — `~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted`
 3. If blockers/critical findings: remediation task created
 4. If clean: task marked done
--- a/packages/mosaic/framework/templates/agent/projects/nestjs-nextjs/CLAUDE.md.template
+++ b/packages/mosaic/framework/templates/agent/projects/nestjs-nextjs/CLAUDE.md.template
@@ -191,10 +191,10 @@ Run independent reviews:
 ```bash
 # Code quality review (Codex)
-~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
+~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted
 # Security review (Codex)
-~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
+~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted
 ```
 See `~/.config/mosaic/guides/CODE-REVIEW.md` for the full review checklist.
@@ -218,7 +218,7 @@ See `~/.config/mosaic/guides/DOCUMENTATION.md` for required documentation delive
 ## Issue Tracking
 Use external git provider issues when available. If no external provider exists, `docs/TASKS.md` is the canonical tracker for tasks, milestones, and issue-equivalent work.
-For issue/PR/milestone operations, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first; do not use raw `gh`/`tea`/`glab` as first choice.
+For issue/PR/milestone operations, detect platform and use `~/.config/mosaic/tools/git/*.sh` wrappers first; do not use raw `gh`/`tea`/`glab` as first choice.
 If wrapper-driven merge/CI/issue-closure fails, report blocker with exact failed wrapper command and stop.
 Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close the issue?" for routine delivery flow.
@@ -230,9 +230,9 @@ Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close
 5. Ensure `docs/PRD.md` or `docs/PRD.json` exists and is current before coding.
 6. Create scratchpad: `docs/scratchpads/{task-id}-{short-name}.md` and include issue/internal ref.
 7. Update `docs/TASKS.md` status + issue/internal ref before coding.
-8. Before push, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push -B main`.
+8. Before push, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push -B main`.
 9. Open PR to `main` for delivery changes (no direct push to `main`).
-10. Before merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose merge -B main`.
+10. Before merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B main`.
 11. Merge PRs that pass required checks and review gates with squash strategy only.
 12. Reference issues/internal refs in commits (`Fixes #123`, `Refs #123`, or `Refs TASKS:T1`).
 13. Close issue/internal task only after testing and documentation gates pass, PR merge is complete, and CI/pipeline status is terminal green.
--- a/packages/mosaic/framework/templates/agent/projects/python-fastapi/AGENTS.md.template
+++ b/packages/mosaic/framework/templates/agent/projects/python-fastapi/AGENTS.md.template
@@ -9,8 +9,8 @@
 2. Do NOT ask for routine confirmation before required push/merge/issue-close/release/tag actions.
 3. Completion is forbidden at PR-open stage.
 4. Completion requires merged PR to `main` + terminal green CI + linked issue/internal task closed.
-5. Before push or merge, run queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
+5. Before push or merge, run queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
-6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/rails/git/*.sh`).
+6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/tools/git/*.sh`).
 7. If any required wrapper command fails: report `blocked` with the exact failed wrapper command and stop.
 8. Do NOT stop at "PR created" and do NOT ask "should I merge?" for routine flow.
@@ -58,7 +58,7 @@ uv run ruff check src/ tests/ && uv run ruff format --check src/ && uv run mypy
 2. If external git provider is available (Gitea/GitHub/GitLab), create/update issue(s) before coding and map them in `docs/TASKS.md`.
 3. If no external provider is available, use internal refs in `docs/TASKS.md` (example: `TASKS:T1`).
 4. Keep `docs/TASKS.md` status in sync with actual progress until completion.
-5. For issue/PR/milestone actions, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first (no raw `gh`/`tea`/`glab` as first choice).
+5. For issue/PR/milestone actions, detect platform and use `~/.config/mosaic/tools/git/*.sh` wrappers first (no raw `gh`/`tea`/`glab` as first choice).
 6. If wrapper-driven merge/CI/issue-closure fails, report blocker with the exact failed wrapper command and stop (do not claim completion).
 ## Documentation Contract
@@ -87,7 +87,7 @@ Reference:
 5. Do not mark implementation complete until PR is merged.
 6. Do not mark implementation complete until CI/pipeline status is terminal green.
 7. Close linked issues/tasks only after merge + green CI.
-8. Before push or merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
+8. Before push or merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
 ## Container Release Strategy (When Applicable)
--- a/packages/mosaic/framework/templates/agent/projects/python-fastapi/CLAUDE.md.template
+++ b/packages/mosaic/framework/templates/agent/projects/python-fastapi/CLAUDE.md.template
@@ -135,7 +135,7 @@ uv run ruff check src/ tests/ && uv run ruff format --check src/ && uv run mypy
 ## Issue Tracking
 Use external git provider issues when available. If no external provider exists, `docs/TASKS.md` is the canonical tracker for tasks, milestones, and issue-equivalent work.
-For issue/PR/milestone operations, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first; do not use raw `gh`/`tea`/`glab` as first choice.
+For issue/PR/milestone operations, detect platform and use `~/.config/mosaic/tools/git/*.sh` wrappers first; do not use raw `gh`/`tea`/`glab` as first choice.
 If wrapper-driven merge/CI/issue-closure fails, report blocker with exact failed wrapper command and stop.
 Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close the issue?" for routine delivery flow.
@@ -146,9 +146,9 @@ Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close
 5. Ensure `docs/PRD.md` or `docs/PRD.json` exists and is current before coding.
 6. Create scratchpad: `docs/scratchpads/{task-id}-{short-name}.md` and include issue/internal ref.
 7. Update `docs/TASKS.md` status + issue/internal ref before coding.
-8. Before push, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push -B main`.
+8. Before push, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push -B main`.
 9. Open PR to `main` for delivery changes (no direct push to `main`).
-10. Before merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose merge -B main`.
+10. Before merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B main`.
 11. Merge PRs that pass required checks and review gates with squash strategy only.
 12. Reference issues/internal refs in commits (`Fixes #123`, `Refs #123`, or `Refs TASKS:T1`).
 13. Close issue/internal task only after testing and documentation gates pass, PR merge is complete, and CI/pipeline status is terminal green.
@@ -171,8 +171,8 @@ If you modify source code, independent code review is REQUIRED before completion
 Run independent reviews:
 ```bash
-~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
+~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted
-~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
+~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted
 ```
 See `~/.config/mosaic/guides/CODE-REVIEW.md` for the full review checklist.
--- a/packages/mosaic/framework/templates/agent/projects/python-library/AGENTS.md.template
+++ b/packages/mosaic/framework/templates/agent/projects/python-library/AGENTS.md.template
@@ -9,8 +9,8 @@
 2. Do NOT ask for routine confirmation before required push/merge/issue-close/release/tag actions.
 3. Completion is forbidden at PR-open stage.
 4. Completion requires merged PR to `main` + terminal green CI + linked issue/internal task closed.
-5. Before push or merge, run queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
+5. Before push or merge, run queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
-6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/rails/git/*.sh`).
+6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/tools/git/*.sh`).
 7. If any required wrapper command fails: report `blocked` with the exact failed wrapper command and stop.
 8. Do NOT stop at "PR created" and do NOT ask "should I merge?" for routine flow.
@@ -55,7 +55,7 @@ uv run ruff check src/ tests/ && uv run ruff format --check src/ && uv run mypy
 2. If external git provider is available (Gitea/GitHub/GitLab), create/update issue(s) before coding and map them in `docs/TASKS.md`.
 3. If no external provider is available, use internal refs in `docs/TASKS.md` (example: `TASKS:T1`).
 4. Keep `docs/TASKS.md` status in sync with actual progress until completion.
-5. For issue/PR/milestone actions, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first (no raw `gh`/`tea`/`glab` as first choice).
+5. For issue/PR/milestone actions, detect platform and use `~/.config/mosaic/tools/git/*.sh` wrappers first (no raw `gh`/`tea`/`glab` as first choice).
 6. If wrapper-driven merge/CI/issue-closure fails, report blocker with the exact failed wrapper command and stop (do not claim completion).
 ## Documentation Contract
@@ -84,7 +84,7 @@ Reference:
 5. Do not mark implementation complete until PR is merged.
 6. Do not mark implementation complete until CI/pipeline status is terminal green.
 7. Close linked issues/tasks only after merge + green CI.
-8. Before push or merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
+8. Before push or merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
 ## Container Release Strategy (When Applicable)
--- a/packages/mosaic/framework/templates/agent/projects/python-library/CLAUDE.md.template
+++ b/packages/mosaic/framework/templates/agent/projects/python-library/CLAUDE.md.template
@@ -125,7 +125,7 @@ uv run ruff check src/ tests/ && uv run ruff format --check src/ && uv run mypy
 ## Issue Tracking
 Use external git provider issues when available. If no external provider exists, `docs/TASKS.md` is the canonical tracker for tasks, milestones, and issue-equivalent work.
-For issue/PR/milestone operations, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first; do not use raw `gh`/`tea`/`glab` as first choice.
+For issue/PR/milestone operations, detect platform and use `~/.config/mosaic/tools/git/*.sh` wrappers first; do not use raw `gh`/`tea`/`glab` as first choice.
 If wrapper-driven merge/CI/issue-closure fails, report blocker with exact failed wrapper command and stop.
 Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close the issue?" for routine delivery flow.
@@ -136,9 +136,9 @@ Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close
 5. Ensure `docs/PRD.md` or `docs/PRD.json` exists and is current before coding.
 6. Create scratchpad: `docs/scratchpads/{task-id}-{short-name}.md` and include issue/internal ref.
 7. Update `docs/TASKS.md` status + issue/internal ref before coding.
-8. Before push, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push -B main`.
+8. Before push, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push -B main`.
 9. Open PR to `main` for delivery changes (no direct push to `main`).
-10. Before merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose merge -B main`.
+10. Before merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B main`.
 11. Merge PRs that pass required checks and review gates with squash strategy only.
 12. Reference issues/internal refs in commits (`Fixes #123`, `Refs #123`, or `Refs TASKS:T1`).
 13. Close issue/internal task only after testing and documentation gates pass, PR merge is complete, and CI/pipeline status is terminal green.
@@ -161,8 +161,8 @@ If you modify source code, independent code review is REQUIRED before completion
 Run independent reviews:
 ```bash
-~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
+~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted
-~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
+~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted
 ```
 See `~/.config/mosaic/guides/CODE-REVIEW.md` for the full review checklist.
--- a/packages/mosaic/framework/templates/agent/projects/typescript/AGENTS.md.template
+++ b/packages/mosaic/framework/templates/agent/projects/typescript/AGENTS.md.template
@@ -9,8 +9,8 @@
 2. Do NOT ask for routine confirmation before required push/merge/issue-close/release/tag actions.
 3. Completion is forbidden at PR-open stage.
 4. Completion requires merged PR to `main` + terminal green CI + linked issue/internal task closed.
-5. Before push or merge, run queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
+5. Before push or merge, run queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
-6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/rails/git/*.sh`).
+6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/tools/git/*.sh`).
 7. If any required wrapper command fails: report `blocked` with the exact failed wrapper command and stop.
 8. Do NOT stop at "PR created" and do NOT ask "should I merge?" for routine flow.
@@ -56,7 +56,7 @@ ${QUALITY_GATES}
 2. If external git provider is available (Gitea/GitHub/GitLab), create/update issue(s) before coding and map them in `docs/TASKS.md`.
 3. If no external provider is available, use internal refs in `docs/TASKS.md` (example: `TASKS:T1`).
 4. Keep `docs/TASKS.md` status in sync with actual progress until completion.
-5. For issue/PR/milestone actions, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first (no raw `gh`/`tea`/`glab` as first choice).
+5. For issue/PR/milestone actions, detect platform and use `~/.config/mosaic/tools/git/*.sh` wrappers first (no raw `gh`/`tea`/`glab` as first choice).
 6. If wrapper-driven merge/CI/issue-closure fails, report blocker with the exact failed wrapper command and stop (do not claim completion).
 ## Documentation Contract
@@ -85,7 +85,7 @@ Reference:
 5. Do not mark implementation complete until PR is merged.
 6. Do not mark implementation complete until CI/pipeline status is terminal green.
 7. Close linked issues/tasks only after merge + green CI.
-8. Before push or merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`.
+8. Before push or merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
 ## Container Release Strategy (When Applicable)
--- a/packages/mosaic/framework/templates/agent/projects/typescript/CLAUDE.md.template
+++ b/packages/mosaic/framework/templates/agent/projects/typescript/CLAUDE.md.template
@@ -122,7 +122,7 @@ ${QUALITY_GATES}
 ## Issue Tracking
 Use external git provider issues when available. If no external provider exists, `docs/TASKS.md` is the canonical tracker for tasks, milestones, and issue-equivalent work.
-For issue/PR/milestone operations, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first; do not use raw `gh`/`tea`/`glab` as first choice.
+For issue/PR/milestone operations, detect platform and use `~/.config/mosaic/tools/git/*.sh` wrappers first; do not use raw `gh`/`tea`/`glab` as first choice.
 If wrapper-driven merge/CI/issue-closure fails, report blocker with exact failed wrapper command and stop.
 Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close the issue?" for routine delivery flow.
@@ -133,9 +133,9 @@ Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close
 5. Ensure `docs/PRD.md` or `docs/PRD.json` exists and is current before coding.
 6. Create scratchpad: `docs/scratchpads/{task-id}-{short-name}.md` and include issue/internal ref.
 7. Update `docs/TASKS.md` status + issue/internal ref before coding.
-8. Before push, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push -B main`.
+8. Before push, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push -B main`.
 9. Open PR to `main` for delivery changes (no direct push to `main`).
-10. Before merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose merge -B main`.
+10. Before merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B main`.
 11. Merge PRs that pass required checks and review gates with squash strategy only.
 12. Reference issues/internal refs in commits (`Fixes #123`, `Refs #123`, or `Refs TASKS:T1`).
 13. Close issue/internal task only after testing and documentation gates pass, PR merge is complete, and CI/pipeline status is terminal green.
@@ -159,10 +159,10 @@ Run independent reviews:
 ```bash
 # Code quality review (Codex)
-~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
+~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted
 # Security review (Codex)
-~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
+~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted
 ```
 **Fallback:** If Codex is unavailable, use Claude's built-in review skills.
--- a/packages/mosaic/src/commands/launch.spec.ts
+++ b/packages/mosaic/src/commands/launch.spec.ts
@@ -1,6 +1,11 @@
 import { describe, it, expect, vi, beforeEach, afterEach, type MockInstance } from 'vitest';
 import { Command } from 'commander';
-import { buildPiSkillArgs, registerRuntimeLaunchers, type RuntimeLaunchHandler } from './launch.js';
+import {
  buildPiSkillArgs,
  piForceSkillNames,
  registerRuntimeLaunchers,
  type RuntimeLaunchHandler,
 } from './launch.js';
 /**
 * Tests for the commander wiring between `mosaic <runtime>` / `mosaic yolo <runtime>`
@@ -23,6 +28,7 @@ function buildProgram(handler: RuntimeLaunchHandler): Command {
 }
 const fakeSkills = ['--skill', '/skills/test-driven-development', '--skill', '/skills/pdf'];
 const fakeForced = ['--skill', '/skills/mosaic-tools'];
 // `process.exit` returns `never`, so vi.spyOn demands a replacement with the
 // same signature. We throw from the mock to short-circuit into test-land.
@@ -66,16 +72,42 @@ describe('registerRuntimeLaunchers — non-yolo subcommands', () => {
 });
 describe('buildPiSkillArgs', () => {
-  it('defaults to disabling Pi skill discovery to keep startup context small', () => {
+  it('disables auto-discovery but force-loads fleet-critical skills by default', () => {
-    expect(buildPiSkillArgs([], {}, fakeSkills)).toEqual(['--no-skills']);
+    expect(buildPiSkillArgs([], {}, fakeSkills, fakeForced)).toEqual([
      '--no-skills',
      '--skill',
      '/skills/mosaic-tools',
    ]);
  });
-  it('keeps explicit user skills while disabling automatic discovery', () => {
+  it('ignores _runtimeArgs (user --skill flags reach Pi via the launch handler, not here)', () => {
-    expect(buildPiSkillArgs(['--skill', '/tmp/custom'], {}, fakeSkills)).toEqual(['--no-skills']);
+    expect(buildPiSkillArgs(['--skill', '/tmp/custom'], {}, fakeSkills, fakeForced)).toEqual([
      '--no-skills',
      '--skill',
      '/skills/mosaic-tools',
    ]);
  });
-  it('supports legacy all-skills mode without double-loading settings skills', () => {
+  it('emits only --no-skills when no forced skills are present on disk', () => {
-    expect(buildPiSkillArgs([], { MOSAIC_PI_SKILL_MODE: 'all' }, fakeSkills)).toEqual([
+    expect(buildPiSkillArgs([], {}, fakeSkills, [])).toEqual(['--no-skills']);
  });
  it('all-skills mode merges the forced set in without duplicating discovered skills', () => {
    expect(buildPiSkillArgs([], { MOSAIC_PI_SKILL_MODE: 'all' }, fakeSkills, fakeForced)).toEqual([
      '--no-skills',
      '--skill',
      '/skills/test-driven-development',
      '--skill',
      '/skills/pdf',
      '--skill',
      '/skills/mosaic-tools',
    ]);
  });
  it('all-skills mode does not double-load a forced skill already discovered', () => {
    expect(
      buildPiSkillArgs([], { MOSAIC_PI_SKILL_MODE: 'all' }, fakeSkills, ['--skill', '/skills/pdf']),
    ).toEqual([
      '--no-skills',
      '--skill',
      '/skills/test-driven-development',
@@ -84,8 +116,27 @@ describe('buildPiSkillArgs', () => {
    ]);
  });
-  it('supports native Pi discovery when explicitly requested', () => {
+  it('force-loads fleet skills even under native Pi discovery', () => {
-    expect(buildPiSkillArgs([], { MOSAIC_PI_SKILL_MODE: 'discover' }, fakeSkills)).toEqual([]);
+    expect(
      buildPiSkillArgs([], { MOSAIC_PI_SKILL_MODE: 'discover' }, fakeSkills, fakeForced),
    ).toEqual(['--skill', '/skills/mosaic-tools']);
  });
 });
 describe('piForceSkillNames', () => {
  it('defaults to mosaic-tools when MOSAIC_PI_FORCE_SKILLS is unset', () => {
    expect(piForceSkillNames({})).toEqual(['mosaic-tools']);
  });
  it('treats an empty string as "disable force-loading" (distinct from unset)', () => {
    expect(piForceSkillNames({ MOSAIC_PI_FORCE_SKILLS: '' })).toEqual([]);
  });
  it('parses a colon list, trimming blanks and whitespace', () => {
    expect(piForceSkillNames({ MOSAIC_PI_FORCE_SKILLS: 'mosaic-tools: mosaic-gitea ::' })).toEqual([
      'mosaic-tools',
      'mosaic-gitea',
    ]);
  });
 });
--- a/packages/mosaic/src/commands/launch.ts
+++ b/packages/mosaic/src/commands/launch.ts
@@ -455,22 +455,78 @@ function normalizePiSkillMode(env: NodeJS.ProcessEnv): PiSkillMode {
  return 'none';
 }
 /**
 * Fleet-critical Pi skills that are force-loaded on every Pi launch regardless
 * of MOSAIC_PI_SKILL_MODE. They cover the highest-frequency cross-agent and
 * git-provider operations where Pi workers historically improvised raw CLIs
 * (raw `tmux send-keys`, raw `tea`/`gh`/`glab`) instead of the maintained
 * `~/.config/mosaic/tools/` wrappers.
 *
 * An explicit `--skill <dir>` overrides `--no-skills` for that path, so forcing
 * a single targeted skill surfaces the must-use toolkit without loading the full
 * ~100-skill catalog (context bloat). Missing skills are skipped silently, so
 * this is a no-op until the named skill is synced into ~/.config/mosaic/skills/.
 *
 * Override with MOSAIC_PI_FORCE_SKILLS (colon-separated skill dir names; set to
 * an empty string to disable force-loading entirely).
 */
 const DEFAULT_PI_FORCE_SKILLS = ['mosaic-tools'];
 export function piForceSkillNames(env: NodeJS.ProcessEnv): string[] {
  const override = env['MOSAIC_PI_FORCE_SKILLS'];
  if (override === undefined) return DEFAULT_PI_FORCE_SKILLS;
  return override
    .split(':')
    .map((name) => name.trim())
    .filter(Boolean);
 }
 function forcedPiSkillArgs(env: NodeJS.ProcessEnv = process.env): string[] {
  const args: string[] = [];
  for (const name of piForceSkillNames(env)) {
    const skillDir = join(MOSAIC_HOME, 'skills', name);
    if (existsSync(join(skillDir, 'SKILL.md'))) {
      args.push('--skill', skillDir);
    }
  }
  return args;
 }
 /** Concatenate `--skill <dir>` arg groups, dropping any directory already seen. */
 function mergeSkillArgs(...groups: string[][]): string[] {
  const seen = new Set<string>();
  const out: string[] = [];
  for (const group of groups) {
    for (let i = 0; i < group.length; i += 2) {
      const dir = group[i + 1];
      if (group[i] !== '--skill' || dir === undefined || seen.has(dir)) continue;
      seen.add(dir);
      out.push('--skill', dir);
    }
  }
  return out;
 }
 export function buildPiSkillArgs(
  _runtimeArgs: string[],
  env: NodeJS.ProcessEnv = process.env,
  discoveredSkillArgs: string[] = discoverPiSkills(),
  forcedSkillArgs: string[] = forcedPiSkillArgs(env),
 ): string[] {
  const mode = normalizePiSkillMode(env);
  if (mode === 'discover') {
-    return [];
+    // Native Pi discovery handles the rest; still force-load the fleet skills.
    return [...forcedSkillArgs];
  }
  if (mode === 'all') {
-    return ['--no-skills', ...discoveredSkillArgs];
+    // 'all' links the full catalog; merge in the forced set so fleet-critical
    // skills are guaranteed present even if they live only under skills-local/.
    return ['--no-skills', ...mergeSkillArgs(discoveredSkillArgs, forcedSkillArgs)];
  }
-  return ['--no-skills'];
+  return ['--no-skills', ...forcedSkillArgs];
 }
 function discoverPiExtension(): string[] {