refactor(framework): thin-core prompt diet — cut injected contract ~53%
Thin defaults/AGENTS.md + defaults/TOOLS.md + runtime/claude/RUNTIME.md to a core that references guides on demand; preserve the full tool catalog in new guides/TOOLS-REFERENCE.md. All 12 hard gates verbatim; validated via a deterministic gate-checklist + a 9-probe headless A/B (thin 7/9 vs monolith 5/9). Composed AGENTS+TOOLS+RUNTIME 8,827->4,122 tok. Diet-only against repo content; no behavioral change, nothing imported from drifted deployments. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jason Woltje
@@ -1,257 +1,58 @@
|
||||
# Machine-Level Tool Reference
|
||||
# Machine Tools — Index
|
||||
|
||||
Centralized reference for tools, credentials, and CLI patterns available across all projects.
|
||||
Tool suites live at `~/.config/mosaic/tools/<suite>/`. This is the index only.
|
||||
**Full CLI signatures, flags, and examples: `~/.config/mosaic/guides/TOOLS-REFERENCE.md`** —
|
||||
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.
|
||||
|
||||
All tool suites are located at `~/.config/mosaic/tools/`.
|
||||
|
||||
## Tool Suites
|
||||
|
||||
### Git Wrappers (Use First)
|
||||
|
||||
Mosaic wrappers at `~/.config/mosaic/tools/git/*.sh` handle platform detection and edge cases. Always use these before raw CLI commands.
|
||||
|
||||
```bash
|
||||
# Issues
|
||||
~/.config/mosaic/tools/git/issue-create.sh
|
||||
~/.config/mosaic/tools/git/issue-close.sh
|
||||
|
||||
# PRs
|
||||
~/.config/mosaic/tools/git/pr-create.sh
|
||||
~/.config/mosaic/tools/git/pr-merge.sh
|
||||
|
||||
# Milestones
|
||||
~/.config/mosaic/tools/git/milestone-create.sh
|
||||
|
||||
# CI queue guard (required before push/merge)
|
||||
~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge
|
||||
```
|
||||
|
||||
### Code Review (Codex)
|
||||
|
||||
```bash
|
||||
~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted
|
||||
~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted
|
||||
```
|
||||
|
||||
### Infrastructure — Portainer
|
||||
|
||||
```bash
|
||||
~/.config/mosaic/tools/portainer/stack-status.sh -n <stack-name>
|
||||
~/.config/mosaic/tools/portainer/stack-redeploy.sh -n <stack-name>
|
||||
~/.config/mosaic/tools/portainer/stack-list.sh
|
||||
~/.config/mosaic/tools/portainer/endpoint-list.sh
|
||||
```
|
||||
|
||||
### Infrastructure — Coolify (DEPRECATED)
|
||||
|
||||
> Coolify has been superseded by Portainer Docker Swarm in this stack.
|
||||
> Tools remain for reference but should not be used for new deployments.
|
||||
|
||||
```bash
|
||||
# DEPRECATED — do not use for new deployments
|
||||
~/.config/mosaic/tools/coolify/project-list.sh
|
||||
~/.config/mosaic/tools/coolify/service-list.sh
|
||||
~/.config/mosaic/tools/coolify/service-status.sh -u <uuid>
|
||||
~/.config/mosaic/tools/coolify/deploy.sh -u <uuid>
|
||||
~/.config/mosaic/tools/coolify/env-set.sh -u <uuid> -k KEY -v VALUE
|
||||
```
|
||||
|
||||
### Identity — Authentik
|
||||
|
||||
```bash
|
||||
~/.config/mosaic/tools/authentik/user-list.sh
|
||||
~/.config/mosaic/tools/authentik/user-create.sh -u <username> -n <name> -e <email>
|
||||
~/.config/mosaic/tools/authentik/group-list.sh
|
||||
~/.config/mosaic/tools/authentik/app-list.sh
|
||||
~/.config/mosaic/tools/authentik/flow-list.sh
|
||||
~/.config/mosaic/tools/authentik/admin-status.sh
|
||||
```
|
||||
|
||||
### CI/CD — Woodpecker
|
||||
|
||||
Multi-instance support: `-a <instance>` selects a named instance. Omit `-a` to use the default from `woodpecker.default` in credentials.json.
|
||||
|
||||
| Instance | URL | Serves |
|
||||
| ------------------ | ------------------ | ---------------------------------- |
|
||||
| `mosaic` (default) | ci.mosaicstack.dev | Mosaic repos (git.mosaicstack.dev) |
|
||||
| `usc` | ci.uscllc.com | USC repos (git.uscllc.com) |
|
||||
|
||||
```bash
|
||||
# List recent pipelines
|
||||
~/.config/mosaic/tools/woodpecker/pipeline-list.sh [-r owner/repo] [-a instance]
|
||||
|
||||
# Check latest or specific pipeline status
|
||||
~/.config/mosaic/tools/woodpecker/pipeline-status.sh [-r owner/repo] [-n number] [-a instance]
|
||||
|
||||
# Trigger a build
|
||||
~/.config/mosaic/tools/woodpecker/pipeline-trigger.sh [-r owner/repo] [-b branch] [-a instance]
|
||||
```
|
||||
|
||||
Instance selection rule: match `-a` to the git remote host of the target repo. If the repo is on `git.uscllc.com`, use `-a usc`. If on `git.mosaicstack.dev`, use `-a mosaic` (or omit, since it's the default).
|
||||
|
||||
### DNS — Cloudflare
|
||||
|
||||
Multi-instance support: `-a <instance>` selects a named instance (e.g. `personal`, `work`). Omit `-a` to use the default from `cloudflare.default` in credentials.json.
|
||||
|
||||
```bash
|
||||
# List zones (domains)
|
||||
~/.config/mosaic/tools/cloudflare/zone-list.sh [-a instance]
|
||||
|
||||
# List DNS records (zone by name or ID)
|
||||
~/.config/mosaic/tools/cloudflare/record-list.sh -z <zone> [-a instance] [-t type] [-n name]
|
||||
|
||||
# Create DNS record
|
||||
~/.config/mosaic/tools/cloudflare/record-create.sh -z <zone> -t <type> -n <name> -c <content> [-a instance] [-p] [-l ttl] [-P priority]
|
||||
|
||||
# Update DNS record
|
||||
~/.config/mosaic/tools/cloudflare/record-update.sh -z <zone> -r <record-id> -t <type> -n <name> -c <content> [-a instance] [-p] [-l ttl]
|
||||
|
||||
# Delete DNS record
|
||||
~/.config/mosaic/tools/cloudflare/record-delete.sh -z <zone> -r <record-id> [-a instance]
|
||||
```
|
||||
|
||||
### IT Service — GLPI
|
||||
|
||||
```bash
|
||||
~/.config/mosaic/tools/glpi/ticket-list.sh
|
||||
~/.config/mosaic/tools/glpi/ticket-create.sh -t <title> -c <content>
|
||||
~/.config/mosaic/tools/glpi/computer-list.sh
|
||||
~/.config/mosaic/tools/glpi/user-list.sh
|
||||
```
|
||||
|
||||
### Health Check
|
||||
|
||||
```bash
|
||||
# Check all configured services
|
||||
~/.config/mosaic/tools/health/stack-health.sh
|
||||
|
||||
# Check a specific service
|
||||
~/.config/mosaic/tools/health/stack-health.sh -s portainer
|
||||
|
||||
# JSON output for automation
|
||||
~/.config/mosaic/tools/health/stack-health.sh -f json
|
||||
```
|
||||
|
||||
### Shared Credential Loader
|
||||
|
||||
```bash
|
||||
# Source in any script to load service credentials
|
||||
source ~/.config/mosaic/tools/_lib/credentials.sh
|
||||
load_credentials <service-name>
|
||||
# Supported: portainer, coolify, authentik, glpi, github, gitea-mosaicstack, gitea-usc, woodpecker, cloudflare, turbo-cache, openbrain
|
||||
```
|
||||
|
||||
### OpenBrain — Semantic Memory (PRIMARY)
|
||||
|
||||
Self-hosted semantic brain backed by pgvector. Primary shared memory layer for all agents across all sessions and harnesses. Stores and retrieves decisions, context, and observations via semantic search.
|
||||
|
||||
**MANDATORY jarvis-brain rule:** When working in `~/src/jarvis-brain`, NEVER capture project data, meeting notes, status updates, timeline decisions, or task completions to OpenBrain. The flat files (`data/projects/*.json`, `data/tasks/*.json`) are the SSOT — use `tools/brain.py` and direct JSON edits. OpenBrain is for agent meta-observations ONLY (tooling gotchas, framework learnings, cross-project patterns). Violating this creates duplicate, divergent data.
|
||||
|
||||
**Credentials:** `load_credentials openbrain` → exports `OPENBRAIN_URL`, `OPENBRAIN_TOKEN`
|
||||
|
||||
Configure in your credentials.json:
|
||||
|
||||
```json
|
||||
"openbrain": {
|
||||
"url": "https://<your-openbrain-host>",
|
||||
"api_key": "<your-api-key>"
|
||||
}
|
||||
```
|
||||
|
||||
**REST API** (any language, any harness):
|
||||
|
||||
```bash
|
||||
source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials openbrain
|
||||
|
||||
# Search by meaning
|
||||
curl -s -X POST -H "Authorization: Bearer $OPENBRAIN_TOKEN" -H "Content-Type: application/json" \
|
||||
-d '{"query": "your search", "limit": 5}' "$OPENBRAIN_URL/v1/search"
|
||||
|
||||
# Capture a thought
|
||||
curl -s -X POST -H "Authorization: Bearer $OPENBRAIN_TOKEN" -H "Content-Type: application/json" \
|
||||
-d '{"content": "...", "source": "agent-name", "metadata": {}}' "$OPENBRAIN_URL/v1/thoughts"
|
||||
|
||||
# Recent activity
|
||||
curl -s -H "Authorization: Bearer $OPENBRAIN_TOKEN" "$OPENBRAIN_URL/v1/thoughts/recent?limit=5"
|
||||
|
||||
# Stats
|
||||
curl -s -H "Authorization: Bearer $OPENBRAIN_TOKEN" "$OPENBRAIN_URL/v1/stats"
|
||||
```
|
||||
|
||||
**Python client** (if jarvis-brain is available on PYTHONPATH):
|
||||
|
||||
```bash
|
||||
python tools/openbrain_client.py search "topic"
|
||||
python tools/openbrain_client.py capture "decision or observation" --source agent-name
|
||||
python tools/openbrain_client.py recent --limit 5
|
||||
python tools/openbrain_client.py stats
|
||||
```
|
||||
|
||||
**MCP (Claude Code sessions):** When connected, `mcp__openbrain__capture/search/recent/stats` tools are available natively — prefer those over CLI when in a Claude session.
|
||||
|
||||
**Rule: capture when you LEARN something. Never when you DO something.**
|
||||
|
||||
| Trigger | Action | Retention |
|
||||
| ----------------------------------------- | ----------------------------------------- | --------------------- |
|
||||
| Session start | `search` + `recent` to load prior context | — |
|
||||
| Architectural or tooling decision made | Capture with rationale | `long` or `permanent` |
|
||||
| Gotcha or non-obvious behavior discovered | Capture immediately | `medium` |
|
||||
| User preference stated or confirmed | Capture | `permanent` |
|
||||
| Cross-project pattern identified | Capture | `permanent` |
|
||||
| Prior decision superseded | UPDATE existing thought | (keep tier) |
|
||||
|
||||
**Never capture:** task started, commit pushed, PR opened, test results, file edits, CI status.
|
||||
|
||||
Full protocol and cleanup tools: `~/.config/mosaic/guides/MEMORY.md`
|
||||
Smart capture wrapper (enforces schema + dedup): `~/.config/mosaic/tools/openbrain/capture.sh`
|
||||
|
||||
### Excalidraw — Diagram Export (MCP)
|
||||
|
||||
Headless `.excalidraw` → SVG export via `@excalidraw/excalidraw`. Available as MCP tools in Claude Code sessions.
|
||||
|
||||
**MCP tools (when connected):**
|
||||
|
||||
| Tool | Input | Output |
|
||||
| ----------------------------------------- | --------------------------------------------- | ---------------------------------------------------- |
|
||||
| `mcp__excalidraw__excalidraw_to_svg` | `elements` JSON string + optional `app_state` | SVG string |
|
||||
| `mcp__excalidraw__excalidraw_file_to_svg` | `file_path` to `.excalidraw` | SVG string + writes `.svg` alongside |
|
||||
| `mcp__excalidraw__list_diagrams` | (none) | Available templates (requires `EXCALIDRAW_GEN_PATH`) |
|
||||
| `mcp__excalidraw__generate_diagram` | `name`, optional `output_path` | Path to generated `.excalidraw` |
|
||||
| `mcp__excalidraw__generate_and_export` | `name`, optional `output_path` | Paths to `.excalidraw` and `.svg` |
|
||||
|
||||
**Diagram generation** (`list_diagrams`, `generate_diagram`, `generate_and_export`) requires `EXCALIDRAW_GEN_PATH` env var pointing to `excalidraw_gen.py`. Set in environment or shell profile:
|
||||
|
||||
```bash
|
||||
export EXCALIDRAW_GEN_PATH="$HOME/src/jarvis-brain/tools/excalidraw_export/excalidraw_gen.py"
|
||||
```
|
||||
|
||||
**Manual registration:**
|
||||
|
||||
```bash
|
||||
mosaic-ensure-excalidraw # install deps + register with Claude
|
||||
mosaic-ensure-excalidraw --check # verify registration
|
||||
```
|
||||
|
||||
## Git Providers
|
||||
|
||||
| Instance | URL | CLI | Purpose |
|
||||
| ----------------------------- | --- | --- | ------- |
|
||||
| (add your git providers here) | | | |
|
||||
## Suites (use wrappers first)
|
||||
|
||||
| Suite | Path | Purpose |
|
||||
|---|---|---|
|
||||
| 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) |
|
||||
| coolify | `tools/coolify/*.sh` | **DEPRECATED** — superseded by Portainer; do not use for new deployments |
|
||||
| authentik | `tools/authentik/*.sh` | identity (users/groups/apps/flows) |
|
||||
| cloudflare | `tools/cloudflare/*.sh` | DNS (zones/records; `-a` instance) |
|
||||
| glpi | `tools/glpi/*.sh` | IT tickets/computers/users |
|
||||
| health | `tools/health/stack-health.sh` | service health checks |
|
||||
| codex | `tools/codex/*.sh` | code/security review (`--uncommitted`) |
|
||||
| openbrain | `tools/openbrain/*`, `tools/openbrain_client.py` | semantic memory (see below) |
|
||||
| excalidraw | MCP `mcp__excalidraw__*` | diagram export/generation |
|
||||
|
||||
Git wrappers are MANDATORY-first for issue/PR/milestone ops (see AGENTS.md hard gates 6–8).
|
||||
Queue guard before push/merge: `tools/git/ci-queue-wait.sh --purpose push|merge`.
|
||||
|
||||
## Credentials
|
||||
|
||||
**Location:** (configure your credential file path)
|
||||
**Loader:** `source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials <service>`
|
||||
`source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials <service>`
|
||||
Supported: portainer, coolify (deprecated), authentik, glpi, github, gitea-mosaicstack,
|
||||
gitea-usc, woodpecker, cloudflare, turbo-cache, openbrain. Never expose or commit values.
|
||||
|
||||
**Never expose actual values. Never commit credential files.**
|
||||
## OpenBrain — Semantic Memory (PRIMARY) — capture when you LEARN, never when you DO
|
||||
|
||||
## CLI Gotchas
|
||||
Primary cross-agent memory (pgvector). Capture decisions/gotchas/preferences/patterns; never task
|
||||
starts, commits, PRs, test results, or file edits. At session start, `search` + `recent` to load
|
||||
prior context. MCP (`mcp__openbrain__capture/search/recent/stats`) preferred when connected; else
|
||||
REST/`tools/openbrain_client.py`. Full protocol: `guides/MEMORY.md`.
|
||||
|
||||
(Add platform-specific CLI gotchas as you discover them.)
|
||||
**MANDATORY jarvis-brain rule:** when working in `~/src/jarvis-brain`, NEVER capture project data,
|
||||
meeting notes, status, timelines, or task completions to OpenBrain — the flat files
|
||||
(`data/projects/*.json`, `data/tasks/*.json`) are the SSOT (use `tools/brain.py` + direct JSON
|
||||
edits). OpenBrain there is for agent meta-observations ONLY (tooling gotchas, framework learnings,
|
||||
cross-project patterns). Violating this creates duplicate, divergent data.
|
||||
|
||||
## Git Providers
|
||||
|
||||
| Host | Instance | CI |
|
||||
|---|---|---|
|
||||
| git.mosaicstack.dev | mosaic (default) | ci.mosaicstack.dev (`-a mosaic`) |
|
||||
| git.uscllc.com | usc | ci.uscllc.com (`-a usc`) |
|
||||
|
||||
Match Woodpecker `-a` and credential instance to the target repo's git remote host.
|
||||
|
||||
## Safety Defaults
|
||||
|
||||
- Prefer `trash` over `rm` when available — recoverable beats gone forever
|
||||
- Never run destructive commands without explicit instruction
|
||||
- Write it down — "mental notes" don't survive session restarts; files do
|
||||
- Prefer `trash` over `rm` when available — recoverable beats gone forever.
|
||||
- Never run destructive commands without explicit instruction.
|
||||
|
||||
Reference in New Issue
Block a user