From 605221d42f7bbded25b94e0a0abb1c0138fc97ae Mon Sep 17 00:00:00 2001 From: "jason.woltje" Date: Fri, 19 Jun 2026 18:03:03 +0000 Subject: [PATCH] docs(framework/tools): lead TOOLS.md with high-salience fleet-tools cheatsheet (#554) --- packages/mosaic/framework/defaults/TOOLS.md | 29 +++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/packages/mosaic/framework/defaults/TOOLS.md b/packages/mosaic/framework/defaults/TOOLS.md index ac0f79b..6ef3808 100644 --- 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//`. 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 -m "message" # or -f 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) |