Skip to content

AGENTS.md

Latest commit

 

History

History
228 lines (194 loc) · 11.4 KB

AGENTS.md

File metadata and controls

228 lines (194 loc) · 11.4 KB

Agent System — Three Horizons Accelerator

Overview

The Three Horizons Accelerator uses GitHub Copilot Chat Agents — a role-based AI assistant system that operates directly within VS Code / GitHub Copilot Chat. The platform includes 19 specialized agents for interactive development assistance.

Architecture

.github/
├── agents/          # 17 role-based chat agents (.agent.md)
├── chatmodes/       # 3 chat modes (.chatmode.md)
├── instructions/    # 3 code-generation instructions (.instructions.md)
├── prompts/         # 7 reusable prompts (.prompt.md)
├── skills/          # 15 operational skill sets
└── ISSUE_TEMPLATE/  # 27 issue templates

Chat Agents

Agent File Role
Architect architect.agent.md System architecture, Microsoft Foundry, multi-agent design
DevOps devops.agent.md CI/CD, GitOps, MLOps, Golden Paths, pipelines
Docs docs.agent.md Documentation generation and maintenance
Onboarding onboarding.agent.md New team member onboarding and guidance
Platform platform.agent.md RHDH portal, platform services, developer experience
Reviewer reviewer.agent.md Code review, PR analysis, quality checks
Security security.agent.md Security policies, scanning, compliance
SRE sre.agent.md Reliability engineering, incident response, monitoring
Terraform terraform.agent.md Infrastructure as Code, Terraform modules
Test test.agent.md Test generation, validation, quality assurance
Deploy deploy.agent.md Deployment orchestration, end-to-end platform deployment
Azure Portal Deploy azure-portal-deploy.agent.md Azure AKS provisioning, Key Vault, PostgreSQL, ACR, Helm
GitHub Integration github-integration.agent.md GitHub App, org discovery, GHAS, Actions, Packages, supply chain
ADO Integration ado-integration.agent.md Azure DevOps PAT, repos, pipelines, boards, Copilot Standalone
Hybrid Scenarios hybrid-scenarios.agent.md GitHub + ADO coexistence scenarios A/B/C, dual auth, hybrid templates
Template Engineer template-engineer.agent.md Software Template expert for RHDH, Golden Path creation, devcontainer configs
Context Architect context-architect.agent.md Multi-file change planning/execution, dependency tracing, codebase context mapping
Engineering Intelligence engineering-intelligence.agent.md DORA metrics, Copilot analytics, GHAS security posture, developer productivity
RHDH Architect rhdh-architect.agent.md RHDH/Backstage plugin architecture, frontend wiring, component specs, ADRs

How to Use

In VS Code with GitHub Copilot Chat, mention an agent by name:

@deploy Deploy the platform to dev environment
@architect Design a microservice architecture for order processing
@devops Set up GitOps deployment with ArgoCD
@terraform Create a new AKS module with private networking
@security Review security posture for the platform
@sre Create an incident response runbook

Chat Modes

Mode File Purpose
Architect architect.chatmode.md Architecture design sessions
Reviewer reviewer.chatmode.md Code review sessions
SRE sre.chatmode.md Operations and incident response

Prompts

Prompt File Purpose
Deploy Platform deploy-platform.prompt.md Deploy the Three Horizons platform
Create Service create-service.prompt.md Scaffold a new microservice
Deploy Service deploy-service.prompt.md Deploy a service to AKS
Generate Docs generate-docs.prompt.md Generate documentation
Generate Tests generate-tests.prompt.md Generate test suites
Review Code review-code.prompt.md Perform code review
Troubleshoot troubleshoot-incident.prompt.md Troubleshoot incidents

Instructions

Instruction File Applies To
Kubernetes kubernetes.instructions.md *.yaml, *.yml, kubernetes/**, helm/**
Python python.instructions.md *.py, python/**
Terraform terraform.instructions.md *.tf, terraform/**, *.tfvars

Skills

The 15 skills in .github/skills/ provide domain-specific knowledge that agents can reference:

Skill Description
ai-foundry-operations Microsoft Foundry and OpenAI operations
argocd-cli ArgoCD CLI for GitOps workflows
azure-cli Azure CLI resource management
azure-infrastructure Azure infrastructure patterns
codespaces-golden-paths GitHub Codespaces devcontainer configs per Golden Path
database-management Database ops and health monitoring
github-cli GitHub CLI for repos and workflows
helm-cli Helm CLI for Kubernetes packages
kubectl-cli Kubernetes CLI for AKS
mcp-cli Model Context Protocol server reference
observability-stack Prometheus, Grafana, observability
prerequisites CLI tool validation and setup
terraform-cli Terraform CLI for Azure infra
validation-scripts Validation scripts for deployments
deploy-orchestration End-to-end platform deployment orchestration

RHDH Official Documentation Skills

6 domain-specific skills sourced from 31 official Red Hat documentation PDFs (RHDH 1.8), converted to Markdown and stored in docs/official-docs/rhdh/markdown/. Agents MUST consult these before performing any RHDH-related action.

Skill Description Agents
rhdh-installation Installation, setup, AKS/OCP deployment, sizing @deploy, @onboarding, @platform, @sre
rhdh-configuration app-config.yaml, branding, theming, logging, telemetry, audit @platform, @rhdh-architect, @sre, @deploy
rhdh-plugins Dynamic plugins, wiring, MCP tools, AI connectors, Orchestrator @rhdh-architect, @platform, @template-engineer, @devops
rhdh-auth-rbac Authentication providers, RBAC policies, permissions @security, @platform, @rhdh-architect, @deploy
rhdh-catalog-templates Software Catalog, Templates, TechDocs, GitHub integration, Scorecards @template-engineer, @platform, @engineering-intelligence, @docs
rhdh-operations Release notes, GitOps patterns, DX best practices, upgrades @sre, @devops, @deploy, @docs
rhdh-plugin-design Custom plugin architecture, frontend wiring, Backstage APIs @rhdh-architect
aro-deployment ARO (Azure Red Hat OpenShift) provisioning, RHDH Operator install, ARO vs AKS @deploy, @azure-portal-deploy, @sre, @devops, @platform, @onboarding

Agent Orchestration & Handoffs

All 19 agents are interconnected via YAML handoffs: in their frontmatter. Key orchestration flows:

Deployment Flow (AKS + ARO)

@onboarding → @architect → @terraform → @deploy → @sre
                                           ↓
                         ┌─────────────────┴─────────────────┐
                         │                                   │
              @azure-portal-deploy              @github-integration
                    ↓                            @ado-integration
             ┌──────┴──────┐                     @hybrid-scenarios
             │             │
          AKS (Helm)   ARO (Operator)
             │             │
             ↓             ↓
          @platform → @sre (health check)
             ↓
      @engineering-intelligence (dashboards)

Post-Deploy Verification Flow

@deploy → @sre (health check)
            ↓
     @engineering-intelligence (DORA metrics)
            ↓
     @platform (catalog + templates)
            ↓
     @onboarding (user adoption)

Security Flow

@reviewer → @security → @devops (remediate) → @test
                ↓
           @terraform (IaC fixes)
           @sre (incident response)
           @context-architect (multi-file fixes)
           @deploy (redeploy with fixes)
           @platform (RBAC policies)

Template Flow

@platform → @template-engineer → @devops (CI/CD) → @security (review)
                    ↓
              @rhdh-architect (plugin design)
              @github-integration
              @ado-integration
              @hybrid-scenarios
              @test (template validation)
              @deploy (register templates)

Multi-File Change Flow

Any agent → @context-architect → @test → @docs
                    ↓
              @terraform (IaC)
              @devops (pipelines)
              @security (review)
              @deploy (deployment)

Hybrid Integration Flow

@github-integration + @ado-integration → @hybrid-scenarios → @deploy

RHDH Portal Customization Flow

@rhdh-architect → @platform → @deploy → @sre
       ↓
   @template-engineer (templates)
   @devops (CI/CD for plugins)
   @security (RBAC policies)
   @engineering-intelligence (dashboard plugins)
   @onboarding (adoption guides)

Engineering Intelligence Flow

@engineering-intelligence → @rhdh-architect (plugin design)
                          → @platform (register dashboards)
                          → @deploy (deploy pipeline)
                          → @sre (SLO correlation)
                          → @devops (scheduled workflows)

Entry Points (user-invoked)

Agent When to use
@onboarding First time setup, getting started
@deploy Full platform deployment (AKS or ARO)
@architect Design decisions, ADRs
@context-architect Multi-file codebase changes
@azure-portal-deploy Azure infrastructure provisioning (AKS/ARO)
@engineering-intelligence DORA metrics, Copilot analytics, security posture

Related Documentation