diff --git a/skills/mosaic-tools/SKILL.md b/skills/mosaic-tools/SKILL.md new file mode 100644 index 0000000..d4b194a --- /dev/null +++ b/skills/mosaic-tools/SKILL.md @@ -0,0 +1,66 @@ +--- +name: mosaic-tools +description: Fast path to the Mosaic fleet toolkit at ~/.config/mosaic/tools/. Use FIRST when you need to message another agent's tmux session, open/merge a Gitea/GitHub PR or issue, run a CI queue wait, or operate Portainer/Woodpecker/Authentik/Cloudflare. Reach for these wrappers before hand-rolling raw tmux send-keys, raw tea/gh/glab, or curl. +--- + +# mosaic-tools + +You are a Mosaic fleet agent on web1. A maintained toolkit lives at `~/.config/mosaic/tools/`. +Use it FIRST for the tasks below — improvising with raw CLIs causes the recurring failures this +skill exists to prevent. This is the high-frequency fast path; the full reference is the +`# Machine Tools` section already in your system prompt. + +## 1. Message another agent (highest priority) + +To send a message or briefing to another agent's tmux session, use the wrapper — **never** raw +`tmux send-keys` / `paste-buffer` (interactive REPLs swallow a trailing Enter or leave the text as +an unsubmitted draft; the wrapper handles bracketed paste, Enter flushing, and the `[src -> dst]` +preamble): + +```bash +~/.config/mosaic/tools/tmux/agent-send.sh -s -m "your message" +~/.config/mosaic/tools/tmux/agent-send.sh -s mos-claude -f path/to/brief.md # send a file's contents +``` + +The coordinator session is `mos-claude`. Status reports, findings, and questions go there. + +## 2. Git provider operations (issues / PRs / milestones) + +Use the wrappers — they auto-detect the platform (Gitea or GitHub) and handle auth. Prefer them +over raw `tea` / `gh` / `glab`: + +```bash +~/.config/mosaic/tools/git/issue-create.sh ... +~/.config/mosaic/tools/git/issue-close.sh ... +~/.config/mosaic/tools/git/pr-create.sh ... +~/.config/mosaic/tools/git/pr-merge.sh ... +~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge # REQUIRED before any push or merge +``` + +### GITEA_LOGIN gotcha (do not skip) + +The wrappers default to `--login ${GITEA_LOGIN:-mosaicstack}`. On **USC** repos hosted at +`git.uscllc.com`, that default fails with `gitea / Error: GetUserByName ... not found`. Pick the +login from the repo's `origin` host **before** running a wrapper: + +```bash +git remote get-url origin # inspect the host, then: +``` + +| origin host | login | +| --------------------- | -------------------------------------------- | +| `git.uscllc.com` | `export GITEA_LOGIN=usc` | +| `git.mosaicstack.dev` | default `mosaicstack` (no export needed) | + +## 3. Other tool suites under `~/.config/mosaic/tools/` + +- `woodpecker/` — CI pipeline status/trigger (`pipeline-status.sh`, `pipeline-list.sh`; `-a usc` for USC repos) +- `portainer/` — Docker Swarm stack status/redeploy +- `authentik/` — identity: users, groups, apps, flows +- `cloudflare/` — DNS records (`-a ` for multi-account) +- `health/` — `stack-health.sh` service checks +- `openbrain/` — semantic agent memory (meta-observations only) + +For the complete reference, consult the `# Machine Tools` section in your system prompt before +improvising. Related skills: `mosaic-gitea` (full git-wrapper flag reference), +`mosaic-tmux-comms` (inter-agent messaging detail).