Agent CLI hub

Router for lightweight CLI tooling skills in image-scoring-gallery. Prefer bounded, low-memory commands before broad reads or heavyweight indexers.

Purpose

Central entry point for agent-safe CLI workflows: which skill to use, how to install tools, how to bound output, and when to ask for confirmation.

When to use

• Starting work in an unfamiliar repo or shell environment
• Choosing between text search, structural search, git, config tools, or MCP layers
• Before running install commands or destructive shell operations

Skill router

Need	Skill
Find files / grep / browse tree	agent-search — rg vs grep vs ast-grep vs fd; optional fff-gallery project MCP
git status, diff, gh PR/issue	agent-git-workflows
jq/yq on JSON/YAML, API probes	agent-data-config
npm lint, tsc, vitest, docker	agent-dev-tooling
Windows vs WSL2 choice	agent-platform-tooling
MCP vs CLI code intelligence	mcp-code-intelligence
Gallery pipeline / DB triage	image-scoring-mcp
Fast indexed file search (MCP)	fff — project fff-gallery in .cursor/mcp.json; see AGENTS.md § fff
Architecture / cross-module graph	Graphify — skill graphify; soft rule .cursor/rules/graphify.mdc; see AGENTS.md § Graphify

Required tools (baseline)

git, rg, fd, jq, node (+ npm). Install full set via references/install-blocks.md.

Install tiers

Install in order — see references/install-tiers.md:

1. Tier 0: git, rg, fd, jq, node
2. Block A: canonical block in references/install-blocks.md
3. Block B: child-skill extensions (yq, just, mise, …)
4. Deferred: optional tools per skill (fzf, semgrep, …)

Agent environment

After installing CLI tools, restart Cursor and verify PATH — see references/agent-environment.md.

Install

See references/install-blocks.md — Windows winget, WSL2 apt, macOS Homebrew.

Agent-safe patterns

1. Inspect git status --short before editing.
2. Use bounded output — see references/bounded-output-patterns.md.
3. Prefer project scripts (npm run …) over ad hoc commands — see .agent/COMMANDS.md.
4. Do not assume repo language before inspecting package.json, pyproject.toml, etc.
5. Never auto-run destructive commands — see references/commands-requiring-confirmation.md.

Commands requiring confirmation

Full list: references/commands-requiring-confirmation.md.

Platform guidance

references/windows-wsl-split.md — when Windows native is enough vs WSL2 for sibling backend work.

Troubleshooting

• Tool not found: Re-run install block for your platform; restart shell.
• Slow search on WSL: Avoid /mnt/c for heavy repos; clone under ~/src.
• Gallery dev: npm run doctor for config and backend URL probes.

Verification checklist

git --version && rg --version && node --version && jq --version
npm run doctor   # gallery-specific