ADR-0004 — Paperclip skill gateway as the runtime for all automations

Status: Accepted Date: 2026-04-15 Decision-maker: João Brazão

Context

JB systems need recurring automation: monitor social channels, ingest knowledge, run quality gates on the brain, send Telegram alerts, generate weekly reports, etc.

Without a unified runtime, every project ends up with its own cron jobs, its own retry logic, its own log location. That is a recipe for invisible failures.

Decision

All automation runs as Paperclip skills inside jb-skills-gateway (a FastAPI container at port 8095).

A skill is: - A self-contained module with a manifest (skill.yaml) declaring inputs, outputs, schedule - Invokable via the gateway HTTP API - Logged centrally in the command_runs table, viewable at joaoluisbrazao.cloud/admin/runs - Versioned in Forgejo alongside the gateway code

Current count: 43 skills. Categories: ingest.*, enrich.*, discover.*, brain-*, document.*, triage.*, etc.

Consequences

Positive - One log surface (/admin/runs) for every automation in the system - One retry/backoff implementation - One auth model (gateway-level API key) - LiteLLM cost caps apply uniformly because every skill goes through the proxy

Negative - Single point of failure for automations (mitigated by 3 uvicorn workers + healthcheck) - New skills must follow the manifest format — slight onboarding friction - Gateway restarts hit all skills simultaneously

What this enables

• The document.infra-scanner skill from adr/0002-docs-as-code-mkdocs.md will live here
• Cross-skill orchestration (one skill calling another via the gateway)
• A consistent "skill catalog" UI in the dashboard