docs(framework/tools): lead TOOLS.md with high-salience fleet-tools cheatsheet #554

jason.woltje · 2026-06-19T18:00:59Z

jason.woltje commented

2026-06-19 18:00:59 +00:00

What

Lead packages/mosaic/framework/defaults/TOOLS.md with a ~25-line high-salience "Most-used fleet tools" cheatsheet, and add the missing tmux suite row.

Why

Investigation (Pi-harness tool-discovery, Jason-directed) found the tools index IS injected into every runtime system prompt via buildRuntimePrompt, but agents — especially Pi/Codex — under-use the buried reference and hand-roll raw tmux send-keys / raw tea/gh instead of the wrappers. Verdict: present-but-ignored (salience), not a launcher bug.

Live before/after test on throwaway Pi sessions: baseline used raw tmux send-keys; with this cheatsheet appended the agent correctly used tools/tmux/agent-send.sh. Fixes the recurring inter-agent-messaging failure class + the GITEA_LOGIN GetUserByName-on-USC trap.

Scope / risk

Content-only. No launcher/code changes. Helps Claude/Codex/Pi/OpenCode uniformly.
Priority in the block: #1 inter-agent messaging (agent-send.sh), #2 git wrappers + GITEA_LOGIN auto-pick-by-origin-host.
prettier --check passes.

Follow-up (separate PR, gated): mosaic-tools skill + --skill force-load launcher change + reconcile pi RUNTIME.md skills-default drift. Also noted: templates/TOOLS.md.template still references a stale rails/ path — separate fix.

🤖 Generated with Claude Code

## What Lead `packages/mosaic/framework/defaults/TOOLS.md` with a ~25-line high-salience "Most-used fleet tools" cheatsheet, and add the missing `tmux` suite row. ## Why Investigation (Pi-harness tool-discovery, Jason-directed) found the tools index IS injected into every runtime system prompt via `buildRuntimePrompt`, but agents — especially Pi/Codex — under-use the buried reference and hand-roll raw `tmux send-keys` / raw `tea`/`gh` instead of the wrappers. Verdict: **present-but-ignored (salience), not a launcher bug.** Live before/after test on throwaway Pi sessions: baseline used raw `tmux send-keys`; with this cheatsheet appended the agent correctly used `tools/tmux/agent-send.sh`. Fixes the recurring inter-agent-messaging failure class + the `GITEA_LOGIN` GetUserByName-on-USC trap. ## Scope / risk - **Content-only.** No launcher/code changes. Helps Claude/Codex/Pi/OpenCode uniformly. - Priority in the block: #1 inter-agent messaging (`agent-send.sh`), #2 git wrappers + `GITEA_LOGIN` auto-pick-by-origin-host. - `prettier --check` passes. Follow-up (separate PR, gated): `mosaic-tools` skill + `--skill` force-load launcher change + reconcile `pi RUNTIME.md` skills-default drift. Also noted: `templates/TOOLS.md.template` still references a stale `rails/` path — separate fix. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

jason.woltje added 1 commit 2026-06-19 18:01:00 +00:00

docs(framework/tools): lead TOOLS.md with high-salience fleet-tools cheatsheet

ci/woodpecker/push/ci Pipeline was successful

Details

ci/woodpecker/pr/ci Pipeline was successful

Details

6318167e5a

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

jason.woltje merged commit 605221d42f into main

2026-06-19 18:03:04 +00:00

jason.woltje referenced this issue from a commit

2026-06-19 18:03:05 +00:00

docs(framework/tools): lead TOOLS.md with high-salience fleet-tools cheatsheet (#554)

jason.woltje referenced this pull request

2026-06-19 18:21:55 +00:00

feat(launch): force-load fleet-critical Pi skills + reconcile skill docs #555

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: mosaicstack/stack#554