agentregistry: Instructions file for Codex

AGENTS.md - Development Guidelines

This document provides guidelines for both AI coding assistants (Claude, Copilot, Cursor, etc.) and human developers working on the AgentRegistry codebase.

Project Overview

AgentRegistry is a centralized registry for securely curating, discovering, deploying, and managing agentic infrastructure including MCP (Model Context Protocol) servers, agents, and skills.

Tech Stack:

• Backend/CLI: Go 1.26+
• Database: PostgreSQL (accessed via pgx)
• Frontend: Next.js 14 (App Router) with Tailwind CSS
• CLI Framework: Cobra
• API Framework: Huma (OpenAPI)

---

Architecture

Directory Structure

agentregistry/
├── cmd/           # Entry points only - minimal code
│   ├── cli/       # CLI entry point
│   └── server/    # Server entry point
├── pkg/           # Public, reusable packages
├── internal/      # Private implementation
│   ├── registry/  # Core registry implementation
│   │   ├── api/       # HTTP handlers
│   │   ├── database/  # Database layer (pgx)
│   │   ├── service/   # Business logic
│   │   └── ...
│   ├── cli/       # CLI command implementations
│   └── mcp/       # MCP protocol handling
├── ui/            # Next.js frontend
└── docker/        # Container images and local Compose configuration

Layer Responsibilities

1. cmd/ - Entry points only. Delegate immediately to pkg/ or internal/
2. pkg/ - Public APIs for external consumption and reusability
3. internal/ - Implementation details, not importable by external packages
4. internal/registry/database/ - ONLY place that accesses the database directly
5. internal/registry/service/ - Business logic, receives database interface via constructor

Runtime Ownership

Deployment/runtime code should be organized by clear ownership, not by vague helper layers:

1. internal/registry/runtimes/<runtime>/ owns runtime behavior - concrete packages such as kubernetes should contain their adapter plus the runtime-specific materialization/apply/discovery logic they need
2. internal/registry/runtimes/utils/ is for narrowly shared deployment utilities only - use it for adapter-shared materialization helpers, validation, name generation, and request parsing that are truly cross-runtime
3. internal/registry/runtimes/types/ is for shared contracts only - keep shared schemas and DTO-style runtime types here, not behavior-heavy logic
4. internal/registry/api/handlers/ is transport only - HTTP handlers should parse requests, call services/adapters, and map errors; they should not own deployment/runtime behavior
5. internal/registry/registry_app.go is the composition root - wire concrete runtime adapters here explicitly instead of hiding registration/factory behavior in handler packages