diff --git a/packages/mosaic/framework/runtime/pi/RUNTIME.md b/packages/mosaic/framework/runtime/pi/RUNTIME.md index e79ecf6..d8247a7 100644 --- 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) diff --git a/packages/mosaic/framework/templates/agent/AGENTS.md.template b/packages/mosaic/framework/templates/agent/AGENTS.md.template index d9b0c9f..14dfc1c 100755 --- 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`. -6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/rails/git/*.sh`). +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/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` -2. **Codex security review** — `~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted` +1. **Codex code review** — `~/.config/mosaic/tools/codex/codex-code-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 diff --git a/packages/mosaic/framework/templates/agent/CLAUDE.md.template b/packages/mosaic/framework/templates/agent/CLAUDE.md.template index c88cb0a..937de77 100755 --- 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. diff --git a/packages/mosaic/framework/templates/agent/projects/django/AGENTS.md.template b/packages/mosaic/framework/templates/agent/projects/django/AGENTS.md.template index 5525e9e..b566acc 100755 --- 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`. -6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/rails/git/*.sh`). +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/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` -2. **Codex security review** — `~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted` +1. **Codex code review** — `~/.config/mosaic/tools/codex/codex-code-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 diff --git a/packages/mosaic/framework/templates/agent/projects/django/CLAUDE.md.template b/packages/mosaic/framework/templates/agent/projects/django/CLAUDE.md.template index 0488d78..306b3e1 100755 --- 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. diff --git a/packages/mosaic/framework/templates/agent/projects/nestjs-nextjs/AGENTS.md.template b/packages/mosaic/framework/templates/agent/projects/nestjs-nextjs/AGENTS.md.template index c182a09..85aad51 100755 --- 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`. -6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/rails/git/*.sh`). +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/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` -2. **Codex security review** — `~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted` +1. **Codex code review** — `~/.config/mosaic/tools/codex/codex-code-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 diff --git a/packages/mosaic/framework/templates/agent/projects/nestjs-nextjs/CLAUDE.md.template b/packages/mosaic/framework/templates/agent/projects/nestjs-nextjs/CLAUDE.md.template index 09d376f..b2cbb75 100755 --- 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. diff --git a/packages/mosaic/framework/templates/agent/projects/python-fastapi/AGENTS.md.template b/packages/mosaic/framework/templates/agent/projects/python-fastapi/AGENTS.md.template index 1249f94..2205eb5 100755 --- 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`. -6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/rails/git/*.sh`). +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/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) diff --git a/packages/mosaic/framework/templates/agent/projects/python-fastapi/CLAUDE.md.template b/packages/mosaic/framework/templates/agent/projects/python-fastapi/CLAUDE.md.template index 7949c55..036651d 100755 --- 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/rails/codex/codex-security-review.sh --uncommitted +~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted +~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted ``` See `~/.config/mosaic/guides/CODE-REVIEW.md` for the full review checklist. diff --git a/packages/mosaic/framework/templates/agent/projects/python-library/AGENTS.md.template b/packages/mosaic/framework/templates/agent/projects/python-library/AGENTS.md.template index 50662e4..2557b6e 100755 --- 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`. -6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/rails/git/*.sh`). +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/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) diff --git a/packages/mosaic/framework/templates/agent/projects/python-library/CLAUDE.md.template b/packages/mosaic/framework/templates/agent/projects/python-library/CLAUDE.md.template index 4fe66f4..f671359 100755 --- 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/rails/codex/codex-security-review.sh --uncommitted +~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted +~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted ``` See `~/.config/mosaic/guides/CODE-REVIEW.md` for the full review checklist. diff --git a/packages/mosaic/framework/templates/agent/projects/typescript/AGENTS.md.template b/packages/mosaic/framework/templates/agent/projects/typescript/AGENTS.md.template index f08b7d6..0deed88 100755 --- 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`. -6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/rails/git/*.sh`). +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/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) diff --git a/packages/mosaic/framework/templates/agent/projects/typescript/CLAUDE.md.template b/packages/mosaic/framework/templates/agent/projects/typescript/CLAUDE.md.template index abb6c17..9843d67 100755 --- 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. diff --git a/packages/mosaic/src/commands/launch.spec.ts b/packages/mosaic/src/commands/launch.spec.ts index 5c7d1e9..560c269 100644 --- 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 ` / `mosaic yolo ` @@ -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', () => { - expect(buildPiSkillArgs([], {}, fakeSkills)).toEqual(['--no-skills']); + it('disables auto-discovery but force-loads fleet-critical skills by default', () => { + expect(buildPiSkillArgs([], {}, fakeSkills, fakeForced)).toEqual([ + '--no-skills', + '--skill', + '/skills/mosaic-tools', + ]); }); - it('keeps explicit user skills while disabling automatic discovery', () => { - expect(buildPiSkillArgs(['--skill', '/tmp/custom'], {}, fakeSkills)).toEqual(['--no-skills']); + it('ignores _runtimeArgs (user --skill flags reach Pi via the launch handler, not here)', () => { + 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', () => { - expect(buildPiSkillArgs([], { MOSAIC_PI_SKILL_MODE: 'all' }, fakeSkills)).toEqual([ + it('emits only --no-skills when no forced skills are present on disk', () => { + 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', () => { - expect(buildPiSkillArgs([], { MOSAIC_PI_SKILL_MODE: 'discover' }, fakeSkills)).toEqual([]); + it('force-loads fleet skills even under native Pi discovery', () => { + 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', + ]); }); }); diff --git a/packages/mosaic/src/commands/launch.ts b/packages/mosaic/src/commands/launch.ts index de8179f..b7f7bdf 100644 --- 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 ` 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 ` arg groups, dropping any directory already seen. */ +function mergeSkillArgs(...groups: string[][]): string[] { + const seen = new Set(); + 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[] {