mosaicstack/stack
16
0
Fork 1
Code Issues 330 Pull Requests 12 Actions Packages Projects Releases 15 Wiki Activity

Skills system consolidation: monorepo package, ms- naming, style-gate promotion, sync hardening #1333

New Issue
Open
opened 2026-08-20 19:11:30 +00:00 by vision · 0 comments
vision commented 2026-08-20 19:11:30 +00:00
Member
Copy Link
Copy Source

Summary

Umbrella issue for the fleet skills system: consolidate skills into the stack monorepo as their own package, apply the confirmed ms- naming convention safely, promote the reviewed style-gate (unslop) into the framework, and harden the sync/launcher paths the rename touches. Design work, measurements, and review trail live in the brain repo (estate); this issue is the stack-side execution plan.

Decisions already made (context, not re-litigated here)

  • D2 (operator): fold mosaicstack/agent-skills into this monorepo; skills remain their own package for install/upgrade purposes. Monorepo containment, separate package boundary.
  • Naming (operator, confirmed 2026-08-20): ms- is the vendor namespace for every Mosaic-authored skill, one meaning. Provenance moves to the directory: skills/ = framework, skills-local/ = operator-authored. Rename map and hazards: brain docs/plans/2026-08-20_skill-naming-convention.md.
  • D12 (operator, confirmed 2026-08-20): skills-local/ is tracked in the brain repo (staging tree), with backup artifacts excluded.
  • Precedent for framework-side skills: mosaic-context-refresh shipped in packages/mosaic/framework/skills/ via #846.

Work items

  • W1 — Package fold. Move mosaicstack/agent-skills content into the monorepo as its own package per D2. Active repo measured 2026-08-20: 101 skills = third-party catalog + 6 mosaic ops skills (deploy, gitea, woodpecker, portainer, orchestrator, tools; added 12545cf, 5d2371c, quote-fix a0dd77c). Sub-decision Q1: graft agent-skills git history into the package or start clean with a retirement notice on the old repo.
  • W2 — Stale repo disposition (Q33, operator's). mosaicstack/skills holds exactly one feature: the gantt skill (single branch feature/26-gantt-skill, also its default; no main; 11 files, ~1090 lines; issue #26, 2026-01-30). Preserve the skill into the package, or retire the repo with it. This routes Q3: preserve → family refactor lands in the monorepo package; keep-repo → the repo becomes the consolidation home and then needs its own trunk decision (absent-repo.json class).
  • W3 — Naming rename. Apply the 7-name map (mosaic-{deploy,gitea,orchestrator,portainer,tools,woodpecker} → ms-*; atomic-workstation-ops → ms-workstation-ops). Each rename changes directory, name: frontmatter, and H1 together in one commit (ms-orchestrator carried a mismatched H1 its whole life; a directory-only rename reproduces that defect six more times).
  • W4 — Launcher hazard H1 (same commit as W3). runtime/pi/RUNTIME.md:34,39: launcher forces skills over --no-skills, default MOSAIC_PI_FORCE_SKILLS=mosaic-tools, and missing skills are skipped silently. A bare rename degrades every pi seat with no error. Update the default in the same commit and make an unresolvable forced skill fail loud instead of launching degraded.
  • W5 — Sync hazard H2 (same commit as W3). mosaic-sync-skills migrates by directory name into skills-local/ with local precedence; renaming one tree yields two linked copies of one skill. Rename both trees in one operation. MOSAIC_INSTALL_SKILLS is a name whitelist: update every host/profile that sets it and document the rename in release notes (measured unset on sb-it-1-dt; other hosts unverified).
  • W6 — Style gate (G1). Promote the unslop hook framework-side. Prototype reviewed and closed (brain tools/unslop-hook/, review R-260819, suite 24/24 at 3da4c21): dependency-free checker + lists.json machine source (per-entry provenance, hard-fail-closed loader, CLI exit codes 0/1/2) + pi extension (message_end check, session-file notice injection, fail-closed on broken lists). Deployment shape: checker shared as the single source for a Claude Code Stop-hook script (same lists), extension into the framework runtime, lists versioned beside the communication contract they mechanize. Sub-decision Q2: who owns per-harness enablement (seat overlay vs profile.json).
  • W7 — ms-unslop split (G2, before first promotion). Split into the catalog skill (mechanical patterns, always safe) and a voice skill (the "adding soul" section, prose deliverables only). The two conflict if the voice rules are forced on operational comms.
  • W8 — Installer/doctor (A1). The skills-local on-ramp is a per-host directory symlink today (~/.config/mosaic/skills-local → brain tree). Make it installer behavior: detect brain home, offer/create the link. Doctor regression check: skills-local is a symlink → never overwritten, never replaced by a real dir (#791, install.sh:461 already scatters protection; make it explicit). Document that sync-script migration writes land in the brain tree by design so a future reader does not "fix" it.
  • W9 — Rename-drift fix (M1). mosaic-sync-skills default MOSAIC_SKILLS_REPO_URL still points at the pre-org-rename mosaic/agent-skills spelling; works via redirect today, breaks the day the redirect dies. Measured still live 2026-08-20 (sync clone remote).
  • W10 — Upgrade adoption note (H3). Hosts running pre-#1325 skill trees still ship the branch-protection bypass recipes (#1323, fixed by #1325, squash 420507d). Measured on sb-it-1-dt 2026-08-20: both mosaic-gitea and mosaic-deploy in ~/.config/mosaic/skills/ carry the literal recipe. The fold (W1) must take text from the merged fix, never from a stale host tree; release notes must call the update mandatory for any host that copied skills out.

Open decisions tracked in this issue

ID Question Owner Gates
Q33 gantt preserve-or-retire (W2) operator routes Q3 / W1+W3 destination
Q1 agent-skills history graft vs clean (W1) operator W1 mechanics
Q2 per-harness hook enablement owner (W6) operator W6 deployment

Q3 (promotion path: sync pipeline vs framework fileset) resolves from Q33 per the routing above; not a separate channel.

Acceptance criteria

  1. agent-skills content ships as its own package in this monorepo; install/upgrade boundary unchanged for existing hosts.
  2. Every Mosaic-authored skill's directory, name: frontmatter, and H1 agree and carry the ms- prefix; a mechanical check enforces it (CI or package test) so the convention cannot drift.
  3. Renames land with W4+W5 in one commit: launcher default updated, unresolvable forced skills fail loud, both trees renamed atomically, whitelist documented.
  4. The style gate ships framework-side with shared lists across pi and Claude Code surfaces; ms-unslop is split before its first promotion.
  5. Installer/doctor handle the skills-local symlink with a regression check; M1 default fixed.
  6. Q33/Q1/Q2 resolved in this thread; no parallel decision channels.

Evidence index

  • Brain repo (estate): fleet/agents/vision/notes/2026-08-19-ms-skills-system-design.md (decisions D1-D5, measurements M1-M6, A1 caveats C1-C3, G-track), docs/plans/2026-08-20_skill-naming-convention.md (rename map, hazards H1-H3, ordering), tools/unslop-hook/ (gate prototype + review trail), fleet/agents/rev-code-01/notes/unslop-review-20260819.md (independent review, approved).
  • Stack side: #846 (framework skills precedent), #791 (skills-local unprunable), #1323/#1325 (bypass recipes, fixed), #1311 (credential helper seat-awareness, related to W8 host story).
## Summary Umbrella issue for the fleet skills system: consolidate skills into the stack monorepo as their own package, apply the confirmed `ms-` naming convention safely, promote the reviewed style-gate (unslop) into the framework, and harden the sync/launcher paths the rename touches. Design work, measurements, and review trail live in the brain repo (estate); this issue is the stack-side execution plan. ## Decisions already made (context, not re-litigated here) - **D2 (operator):** fold `mosaicstack/agent-skills` into this monorepo; skills remain their own package for install/upgrade purposes. Monorepo containment, separate package boundary. - **Naming (operator, confirmed 2026-08-20):** `ms-` is the vendor namespace for every Mosaic-authored skill, one meaning. Provenance moves to the directory: `skills/` = framework, `skills-local/` = operator-authored. Rename map and hazards: brain `docs/plans/2026-08-20_skill-naming-convention.md`. - **D12 (operator, confirmed 2026-08-20):** `skills-local/` is tracked in the brain repo (staging tree), with backup artifacts excluded. - Precedent for framework-side skills: `mosaic-context-refresh` shipped in `packages/mosaic/framework/skills/` via #846. ## Work items - [ ] **W1 — Package fold.** Move `mosaicstack/agent-skills` content into the monorepo as its own package per D2. Active repo measured 2026-08-20: 101 skills = third-party catalog + 6 mosaic ops skills (deploy, gitea, woodpecker, portainer, orchestrator, tools; added 12545cf, 5d2371c, quote-fix a0dd77c). Sub-decision **Q1**: graft agent-skills git history into the package or start clean with a retirement notice on the old repo. - [ ] **W2 — Stale repo disposition (Q33, operator's).** `mosaicstack/skills` holds exactly one feature: the gantt skill (single branch `feature/26-gantt-skill`, also its default; no `main`; 11 files, ~1090 lines; issue #26, 2026-01-30). Preserve the skill into the package, or retire the repo with it. **This routes Q3:** preserve → family refactor lands in the monorepo package; keep-repo → the repo becomes the consolidation home and then needs its own trunk decision (absent-`repo.json` class). - [ ] **W3 — Naming rename.** Apply the 7-name map (mosaic-{deploy,gitea,orchestrator,portainer,tools,woodpecker} → ms-*; atomic-workstation-ops → ms-workstation-ops). Each rename changes directory, `name:` frontmatter, and H1 together in one commit (`ms-orchestrator` carried a mismatched H1 its whole life; a directory-only rename reproduces that defect six more times). - [ ] **W4 — Launcher hazard H1 (same commit as W3).** `runtime/pi/RUNTIME.md:34,39`: launcher forces skills over `--no-skills`, default `MOSAIC_PI_FORCE_SKILLS=mosaic-tools`, and missing skills are skipped silently. A bare rename degrades every pi seat with no error. Update the default in the same commit and make an unresolvable forced skill fail loud instead of launching degraded. - [ ] **W5 — Sync hazard H2 (same commit as W3).** `mosaic-sync-skills` migrates by directory name into `skills-local/` with local precedence; renaming one tree yields two linked copies of one skill. Rename both trees in one operation. `MOSAIC_INSTALL_SKILLS` is a name whitelist: update every host/profile that sets it and document the rename in release notes (measured unset on sb-it-1-dt; other hosts unverified). - [ ] **W6 — Style gate (G1).** Promote the unslop hook framework-side. Prototype reviewed and closed (brain `tools/unslop-hook/`, review R-260819, suite 24/24 at 3da4c21): dependency-free checker + `lists.json` machine source (per-entry provenance, hard-fail-closed loader, CLI exit codes 0/1/2) + pi extension (message_end check, session-file notice injection, fail-closed on broken lists). Deployment shape: checker shared as the single source for a Claude Code Stop-hook script (same lists), extension into the framework runtime, lists versioned beside the communication contract they mechanize. Sub-decision **Q2**: who owns per-harness enablement (seat overlay vs profile.json). - [ ] **W7 — ms-unslop split (G2, before first promotion).** Split into the catalog skill (mechanical patterns, always safe) and a voice skill (the "adding soul" section, prose deliverables only). The two conflict if the voice rules are forced on operational comms. - [ ] **W8 — Installer/doctor (A1).** The `skills-local` on-ramp is a per-host directory symlink today (`~/.config/mosaic/skills-local` → brain tree). Make it installer behavior: detect brain home, offer/create the link. Doctor regression check: `skills-local` is a symlink → never overwritten, never replaced by a real dir (`#791`, `install.sh:461` already scatters protection; make it explicit). Document that sync-script migration writes land in the brain tree by design so a future reader does not "fix" it. - [ ] **W9 — Rename-drift fix (M1).** `mosaic-sync-skills` default `MOSAIC_SKILLS_REPO_URL` still points at the pre-org-rename `mosaic/agent-skills` spelling; works via redirect today, breaks the day the redirect dies. Measured still live 2026-08-20 (sync clone remote). - [ ] **W10 — Upgrade adoption note (H3).** Hosts running pre-#1325 skill trees still ship the branch-protection bypass recipes (#1323, fixed by #1325, squash 420507d). Measured on sb-it-1-dt 2026-08-20: both `mosaic-gitea` and `mosaic-deploy` in `~/.config/mosaic/skills/` carry the literal recipe. The fold (W1) must take text from the merged fix, never from a stale host tree; release notes must call the update mandatory for any host that copied skills out. ## Open decisions tracked in this issue | ID | Question | Owner | Gates | |---|---|---|---| | Q33 | gantt preserve-or-retire (W2) | operator | routes Q3 / W1+W3 destination | | Q1 | agent-skills history graft vs clean (W1) | operator | W1 mechanics | | Q2 | per-harness hook enablement owner (W6) | operator | W6 deployment | Q3 (promotion path: sync pipeline vs framework fileset) resolves from Q33 per the routing above; not a separate channel. ## Acceptance criteria 1. agent-skills content ships as its own package in this monorepo; install/upgrade boundary unchanged for existing hosts. 2. Every Mosaic-authored skill's directory, `name:` frontmatter, and H1 agree and carry the `ms-` prefix; a mechanical check enforces it (CI or package test) so the convention cannot drift. 3. Renames land with W4+W5 in one commit: launcher default updated, unresolvable forced skills fail loud, both trees renamed atomically, whitelist documented. 4. The style gate ships framework-side with shared lists across pi and Claude Code surfaces; `ms-unslop` is split before its first promotion. 5. Installer/doctor handle the skills-local symlink with a regression check; M1 default fixed. 6. Q33/Q1/Q2 resolved in this thread; no parallel decision channels. ## Evidence index - Brain repo (estate): `fleet/agents/vision/notes/2026-08-19-ms-skills-system-design.md` (decisions D1-D5, measurements M1-M6, A1 caveats C1-C3, G-track), `docs/plans/2026-08-20_skill-naming-convention.md` (rename map, hazards H1-H3, ordering), `tools/unslop-hook/` (gate prototype + review trail), `fleet/agents/rev-code-01/notes/unslop-review-20260819.md` (independent review, approved). - Stack side: #846 (framework skills precedent), #791 (skills-local unprunable), #1323/#1325 (bypass recipes, fixed), #1311 (credential helper seat-awareness, related to W8 host story).
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
Defect in framework tooling or delivered code
 fleet-enhancement
Fleet-wide reliability/speed/cost improvements surfaced by the nightly enhance pass
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
code-be-01 (Mosaic fleet seat code-be-01) code-be-02 (Mosaic fleet seat code-be-02) code-infra-01 (Mosaic fleet seat code-infra-01) fargo fred gate-merge-01 (Mosaic fleet seat gate-merge-01) happy jason.woltje (Jason Woltje) merge-gate ops-01 (Mosaic fleet seat ops-01) ops-02 (Mosaic fleet seat ops-02) ops-03 (Mosaic fleet seat ops-03) ops-ci-01 (Mosaic fleet seat ops-ci-01) ops-deploy-01 (Mosaic fleet seat ops-deploy-01) pepper rev-code-01 rev-code-02 rev-security-01 rev-security-02 rev-security-03 (Mosaic fleet seat rev-security-03) sanity scooby (Scooby) scrappy shaggy tiny velma veronica (Mosaic fleet seat veronica) vision woodpecker
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaicstack/stack#1333