Skip to content

AGENTS.md

Latest commit

 

History

History
134 lines (99 loc) · 5.83 KB

AGENTS.md

File metadata and controls

134 lines (99 loc) · 5.83 KB
Raw

AI Agent Development Guide

Guidance for agents working in the 508.dev integrations monorepo.

Project Context

This repo contains multiple services:

  • Discord bot (apps/discord_bot)
  • Backend API (apps/api)
  • Worker consumer (apps/worker)
  • Shared package (packages/shared)

Architecture Principles

  1. Feature modularity in bot cogs
  • Bot features live in apps/discord_bot/src/five08/discord_bot/cogs/*.py.
  • Cogs auto-load from the five08.discord_bot.cogs package.
  1. Shared runtime code
  • Cross-service settings/queue/job logic lives in packages/shared/src/five08/.
  • Keep service-specific behavior in each app package.
  1. Service separation
  • apps/discord_bot: Discord gateway and bot commands/cogs
  • apps/api: webhook ingest API and dashboard auth routes
  • apps/worker: queue consumer and processing jobs
  • compose.yaml: canonical Coolify/base container stack with the external infra network; compose.local.yaml adds local host port publishing for ./scripts/docker-compose.sh; docker-compose.yml is a compatibility wrapper; day-to-day dev should prefer host-run app services with Docker-managed infra
  1. Human audit logging
  • Human-triggered CRM actions from Discord should write to the worker audit ingest endpoint.
  • Audit logging must be best effort: command flows should never fail if audit writes fail.
  • Keep reusable audit-write logic outside individual cogs.

Common Paths

  • Bot core: apps/discord_bot/src/five08/discord_bot/bot.py
  • Bot config: apps/discord_bot/src/five08/discord_bot/config.py
  • Bot audit helper: apps/discord_bot/src/five08/discord_bot/utils/audit.py
  • Backend API: apps/api/src/five08/backend/api.py
  • Worker consumer: apps/worker/src/five08/worker/consumer.py
  • Shared settings: packages/shared/src/five08/settings.py
  • Shared queue helpers: packages/shared/src/five08/queue.py

Development Commands

uv sync
./scripts/test.sh
./scripts/lint.sh
./scripts/format.sh
./scripts/pyrefly.sh

Run services directly:

uv run --package discord_bot discord-bot
uv run --package api backend-api
uv run --package worker worker-consumer

Run the local dev stack:

./scripts/dev.sh infra
./scripts/dev.sh discord-bot
./scripts/dev.sh api
./scripts/dev.sh worker
./scripts/dev.sh all

./scripts/dev.sh is the primary local-dev entrypoint. Full container parity remains available with:

./scripts/docker-compose.sh up --build

Bot Feature Pattern

from discord.ext import commands

class MyCog(commands.Cog):
    def __init__(self, bot: commands.Bot) -> None:
        self.bot = bot

async def setup(bot: commands.Bot) -> None:
    await bot.add_cog(MyCog(bot))

Worker Pattern

  • Keep ingest endpoints fast: validate input, persist jobs, enqueue, return 202.
  • Run long processing in worker consumer jobs (Dramatiq actors), with Postgres as source-of-truth job state and Redis as delivery transport.
  • Internal file movement is routed through MinIO (internal-transfers) inside the stack; this is explicitly the internal transfer path, with external object store adapters kept separate for future needs.
  • Worker schema is managed with Alembic migrations in apps/worker/src/five08/worker/migrations and applied at backend-api startup.

Current Operational Notes (temporary)

  • Protected API auth uses API_SHARED_SECRET for all protected API routes, including webhooks.
  • Worker queue configuration is now resolved to a single effective worker_queue_name; startup fails when WORKER_QUEUE_NAMES contains multiple queue names.
  • Job handler lookup for rerun and worker execution is now centralized in five08.worker.jobs.JOB_FUNCTIONS.

Data Model Note

  • Shared job state is persisted in Postgres table jobs with job type, status (queued, running, succeeded, failed, dead, canceled), payload, idempotency key, attempt counters, scheduling, and lock metadata.

Configuration Rules

  • Add shared env/config in packages/shared/src/five08/settings.py.
  • Add service-specific settings in local service config.py by subclassing shared settings.
  • Keep secrets in env vars, not code.
  • For Discord CRM audit writes, use AUDIT_API_BASE_URL and shared API_SHARED_SECRET.

Agent Guidelines

  • Prefer adding new bot features as isolated cogs.
  • Prefer adding reusable helpers/clients to packages/shared/src/five08/.
  • Update docs and .env.example when introducing new config.
  • Keep changes incremental and testable.

Agent Operating Rules

  • State material assumptions before acting. If a request has multiple reasonable interpretations and the difference changes the outcome, ask first.
  • Read before writing: inspect the target file, immediate callers, exports, and obvious shared utilities before adding new code.
  • Keep changes surgical and minimal. Do not refactor adjacent code, reformat unrelated files, or introduce abstractions for single-use code.
  • Match existing conventions for naming, error handling, async patterns, configuration, and tests. If local patterns conflict, choose the more established or better-tested pattern and flag the inconsistency instead of blending them.
  • Use code for deterministic decisions. Do not use LLM calls for routing, retries, status-code handling, validation that code can perform, or deterministic transforms.
  • For non-trivial changes, reason through state ownership, observability, blast radius, timing/order of operations, security, and rollback before implementation.
  • Tests should verify intent, not just surface behavior. Avoid tests that would still pass if the business logic were replaced with a constant or no-op.
  • Fail loud and report uncertainty. Do not call work complete if records, tests, migrations, jobs, or checks were skipped silently.
  • Checkpoint multi-step work: keep track of what changed, what was verified, and what remains. If the state of the work becomes unclear, stop and restate before continuing.