Agentic Infrastructure Bootstrap 🚀

A foundational Reference Architecture to bootstrap your AI Agent infrastructure.

This repository provides a concrete implementation of Agent Platform Engineering. It is designed to bridge the gap between AI Agents (like Claude, Pi, Cursor) and your actual engineering infrastructure (Code, GitOps, Terraform, Cloud).

Read the foundational theory in my article on Dev.to: Agentic Platform Engineering: How to build an agent infrastructure that scales from your laptop to 11np

🏗️ Architecture & Topology (The Triad)

graph TD
    %% Core Nodes
    Agent[🤖 AI Agent\nClaude, Cursor, Pi]
    
    subgraph The Triad
        Setup[3. agent-setup/\nBridge & Config]
        Library[2. agent-library/\nSkills & Prompts]
        Catalog[1. resource-catalog/\nBackstage Yaml]
    end

    %% Connections
    Agent -- Reads Config --> Setup
    Setup -- Binds/Symlinks --> Library
    Library -- Context Rules --> Agent
    Library -- Executes --> Skills[Bash/Python Skills]
    Agent -- Discovers Topo --> Catalog
    Catalog -- Points to --> Repos[(Local Repositories\n~/codebase/)]
    Skills -. Acts on .-> Repos

    style Agent fill:#f9f,stroke:#333,stroke-width:2px
    style The Triad fill:#e1f5fe,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5

Loading

This bootstrap provides three interdependent foundational pieces to run agents effectively:

1. resource-catalog/: A Backstage-style service catalog. It acts as the "Service Registry" so agents can discover what systems, domains, and repositories exist across your organization.
2. agent-library/: The core intelligence. Contains context layers (global rules, domain rules) and executable skills (Bash/Go/Python tools) that agents can invoke. In a monorepo, this is managed via a single source of truth (library.yaml). In a distributed setup, each domain maintains its own library.
3. agent-setup/: The bridge/integration layer. Contains the specific configurations to bind the agent-library to your local agent runner (e.g., Pi-coding-agent, Cursor).

⚠️ Monorepo vs. Polyrepo Strategy

🧪 For Learning and Local Development (This Repository): This project is structured as a Monorepo to provide a frictionless onboarding experience. By cloning this single repository, you get the entire triad working seamlessly on your local machine using symlinks. This is perfect for single developers, testing, and understanding the core concepts with zero latency.

🏢 For Production and Enterprise (Cross-Org): In a real-world, scalable Platform Engineering environment, this architecture is designed to be completely decoupled into a Polyrepo strategy:

• resource-catalog/ lives in a central repository managed by the Platform Team.
• agent-library/ is split into multiple repositories owned by different domains.
• Instead of local symlinks, cross-team agents discover capabilities through network endpoints using standard web protocols like /.well-known/agent-capabilities.json (acting as a DNS for agents).

🚀 Getting Started

1. Clone this repository to your local workspace.
2. Explore the resource-catalog/ to understand how domains are mapped.
3. Review agent-library/library.yaml to see how agent context and skills are structured.
4. Check docs/cross-org-agent-discovery.md to learn how to scale this beyond your local machine.

Disclaimer: The skills, rules, and prompts provided in this repository are illustrative examples meant to demonstrate the architecture. They are not production-ready tools. Please review and modify them to fit your specific needs before using them in real workflows.

🤝 Contributing

Contributions, issues, and feature requests are welcome! If you have ideas on how to improve the /.well-known/ network discovery pattern or new base skills, feel free to open a PR.