yala-agentic-toolkit AGENTS.md

AGENTS.md — using yala-toolkit from a coding-harness agent

529 standalone Python/Go/Bash/TS utilities for system, network, security, AI, infra, and dev work. This file is the routing table; everything else is discoverable at runtime.

Setup (once per checkout)

python -m venv .venv && source .venv/bin/activate
pip install -e .            # slim base; extras: .[browser], .[crawl], .[voice], .[db], .[crypto], .[all]

Discovery — do NOT read category READMEs (they cost thousands of tokens)

yala find <task words>            # top ~10 matching tools, one-liners (cheapest, start here)
yala find <query> --json          # same, machine-readable
yala info <tool>                  # tool's docstring + exact run command
yala list <category>              # tools in one category
cat tools/data/manifest.json      # full manifest: every tool + mutates/json_output/flags

Invocation

yala <category> <tool> [args...]   # preferred; tool names are hyphenated
yala <tool> [args...]              # works when the name is unique
python src/<category>/<tool>.py …  # direct invocation always works too

Conventions contract (rely on these)

• Every tool supports --help; yala <cat> <tool> --help forwards to it.
• Mutating tools support --dry-run ("mutates": true in the manifest). Always dry-run first when changing files/state.
• Data-producing tools generally support --json ("json_output": true in the manifest) — prefer it for parsing.
• Secrets come from environment variables only, never CLI args.
• Exit codes: 0 success, 1 finding/failure (scanners exit 1 when they find something — that is not a crash), 2 usage error.
• Dual-use tools (network-recon, network-tunneling, api-tools hardening, sqli-defense probes, load testing) are authorized-use only — targets must be owned or explicitly authorized.

Category routing table

Category	Use it for
system-process	CPU/mem/disk diagnostics, process + service management
file-data	organize, dedupe, rename, sync, back up, convert files
compression	codec benchmarks, archives, lossless recompress
security	secret scanning, CVE checks, file integrity, permissions
sqli-defense	SQL-injection source/log scanning + prevention
ai-detection	C2PA/provenance + heuristics for AI-made content
antivirus	static triage, signature scan, quarantine, ClamAV
crypto	AEAD file encryption, TRNG keys, PGP
vault	Vault AppRole, unseal, backup/restore, rotation
config-secrets	layered config render/validate/diff, .env hygiene, rotation
network	DNS, TLS expiry, ports, bandwidth (authorized hosts)
network-recon	port scan, host discovery (owned networks ONLY)
network-tunneling	SSH tunnels, proxies, WireGuard configs
ssh	config lint, known_hosts/authorized_keys hygiene, exec
development	git helpers, TODO extraction, license/dep checks
github / gitlab	PR/MR triage, pipelines, releases, security alerts
cicd	lint/generate/run pipelines, semver, changelog, deploy gates
nextjs / react-dev / component-libs	JS stack bootstrap, audits, codegen
code-intelligence	gitnexus/codegraph reports: hotspots, impact, arch
coding-loops	iterate-until-goal loops (coverage, CVEs, flaky tests)
agent-loops	ReAct/plan-execute/reflexion/RAG agent patterns (LLM API)
llm-tuning	prompt A/B, param sweeps, eval harnesses (Ollama)
deep-research	multi-source cited research report agent
web-search	SearXNG search/crawl
crawlee	resilient crawlers, SEO audits, sitemaps
browser-automation	Playwright: screenshots, link checks, form smoke tests
libretto	Libretto TS workflows: sessions, harvest, network capture
nl2sql	plain-English → safe read-only PostgreSQL
database / db-migrations	PG/SQLite DBA dashboards, schema diff, migration runner
redis / message-queue / messaging-streams	Redis/RabbitMQ/Streams/Kafka ops
api-tools / api-docs / api-versioning / api-gateway	probe/lint/harden APIs, OpenAPI gen, versioning, gateway
rate-limiting	limiter algorithms, Redis limiter, enforcing proxy
webhooks	HMAC sign/verify, receiver, delivery, replay, relay
feature-flags	flag engine, A/B stats, rollouts, hygiene audit
observability / dashboards-alerting	traces, Prometheus, SLO monitors, dashboards
logging	JSON logs, parse/query/aggregate, redact, ship, alert
load-testing	HTTP load gen, benchmarks, soak tests, regression gates
chaos-engineering	fault injection, resilience experiments
iac-provisioning / kubernetes	Terraform/Ansible, k8s manifests/ops
cloud-cost	cost/billing analysis and optimization
backup-dr	backup, restore, disaster recovery drills
data-pipeline	ETL/orchestration helpers
progressive-delivery	canary/blue-green release automation
local-environment	dev-service dashboards, repo health, Obsidian, nginx
gpu-stack	NVIDIA GPU/CUDA, Ollama/LiteLLM health
go-tools	Go hardware (I2C/GPIO/serial) + Go toolchain wrappers
jq	advanced jq JSON wrangling recipes
bash	certs, disk/mem alerts, service waits, backups
document-conversion	any document → Markdown
streaming	capture/transcribe .m3u8 streams
audio-voice	Whisper transcription, diarization, voice ID
localization	i18n string extract/translate/validate/merge
market-data	stocks/crypto prices, alerts (read-only)
news-trends	news digests, trend snapshots
messaging	email via SMTP, SMS/calls via Twilio-compatible API
vector-pageindex	vector DB + page-index tools (local embeddings)