mosaicstack/stack
1
0
Fork 0
Code Issues 25 Pull Requests 4 Actions Packages Projects Releases 14 Wiki Activity

docs(framework/tools): lead TOOLS.md with high-salience fleet-tools cheatsheet
All checks were successful
ci/woodpecker/push/ci Pipeline was successful
Details
ci/woodpecker/pr/ci Pipeline was successful
Details

Browse Source 
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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QoYiBeKNh3BiYtAJS5Z587
This commit is contained in:
Hermes Agent
2026-06-19 13:00:25 -05:00
parent ee584ab48c
commit 6318167e5a
1 changed files with 29 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
packages/mosaic/framework/defaults/TOOLS.md
View File

@@ -5,10 +5,39 @@ Tool suites live at `~/.config/mosaic/tools/<suite>/`. 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 <target-session> -m "message" # or -f <file> 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) |