mosaicstack/stack
1
0
Fork 1
Code Issues 170 Pull Requests 9 Actions Packages Projects Releases 15 Wiki Activity

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

Merged
jason.woltje merged 1 commits from feat/tools-cheatsheet-salience into main 2026-06-19 18:03:04 +00:00
Conversation 0 Commits 1 Files Changed 1
+29
jason.woltje commented 2026-06-19 18:00:59 +00:00
Owner
Copy Link
Copy Source

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 <[email protected]>
Claude-Session: https://claude.ai/code/session_01QoYiBeKNh3BiYtAJS5Z587
jason.woltje merged commit 605221d42f into main 2026-06-19 18:03:04 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
bug
Defect in framework tooling or delivered code
 fleet-enhancement
Fleet-wide reliability/speed/cost improvements surfaced by the nightly enhance pass
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
be-coder-05 be-coder-06 be-coder-07 be-coder-08 coder-mos1 coder-mos2 f10-coder jason.woltje (Jason Woltje) merge-gate mos-dt-0 pepper rev-974 (Rev-974 (Mosaic reviewer seat, web1)) rev-security-02
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaicstack/stack#554