From 6318167e5a6f58609d37cb5c18fb2306c48002e7 Mon Sep 17 00:00:00 2001 From: Hermes Agent Date: Fri, 19 Jun 2026 13:00:25 -0500 Subject: [PATCH] docs(framework/tools): lead TOOLS.md with high-salience fleet-tools cheatsheet MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Agents (esp. Pi/Codex) under-use the buried tools index and hand-roll raw `tmux send-keys` / raw `tea`/`gh` instead of the wrappers. Lead the doc with a ~25-line actionable block — #1 inter-agent messaging via tools/tmux/agent-send.sh, #2 git wrappers + the GITEA_LOGIN auto-pick-by-origin-host rule (the GetUserByName-on-USC trap) — and add the missing tmux row to the suites table. Content-only; injected into every runtime prompt via buildRuntimePrompt. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01QoYiBeKNh3BiYtAJS5Z587 --- 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) |