This directory contains agent specifications for GitHub Copilot coding agents working in the Actions Runner Controller repository. These specifications enable AI-powered assistance for various development tasks through specialized agents.
The agent system uses a hierarchical structure with a main coding agent that delegates to specialized sub-agents based on the task at hand. This approach ensures that domain-specific expertise is applied to each problem.
coding-agent (Main Coordinator)
├── agent-manager (Lifecycle Management)
│ └── agent-recruiter (Specification Creator)
├── go-expert-agent (Go Development)
├── kubernetes-expert-agent (K8s/Helm)
├── documentation-agent (Documentation)
└── test-specialist-agent (Testing)
Main coordinating agent for general coding tasks. Delegates to specialized agents based on the task domain.
When to Use: General development tasks, coordinating multi-domain changes, overall project guidance.
Manages the agent lifecycle - identifies when agents need to be created, updated, or retired.
When to Use: Analyzing agent effectiveness, identifying gaps in coverage, deciding on agent updates.
Creates new agent specifications when new domains or patterns emerge.
When to Use: Need for a new specialized agent, creating agent documentation.
Go language specialist for all Go code changes, refactoring, and Go-specific tooling.
When to Use:
- Modifying Go source code
- Adding new features in Go
- Refactoring Go code
- Fixing Go-related bugs
- Managing Go dependencies
Expertise: Go 1.25+, controller-runtime, Ginkgo/Gomega, error handling, concurrency.
Kubernetes and Helm specialist for CRDs, manifests, charts, and K8s configurations.
When to Use:
- Modifying CRDs or API types
- Updating Helm charts
- Changing RBAC policies
- Kubernetes resource configurations
- Webhook configurations
Expertise: CRDs, Helm charts, RBAC, Kubebuilder, K8s resources, admission webhooks.
Documentation specialist for markdown files, README updates, and user guides.
When to Use:
- Updating documentation
- Creating new guides
- Maintaining README files
- Writing release notes
- Helm chart documentation
Expertise: Technical writing, markdown, API docs, user guides, troubleshooting docs.
Testing expert for unit tests, integration tests, E2E tests, and test infrastructure.
When to Use:
- Writing new tests
- Fixing broken tests
- Improving test coverage
- Creating test fixtures
- Test infrastructure changes
Expertise: Ginkgo/Gomega, Go testing, envtest, E2E testing, mocking, test patterns.
When working on a task:
- Identify the Domain: Determine which domain(s) the task touches
- Select Specialist: Choose the most appropriate specialized agent
- Delegate: Pass the task to the specialist with full context
- Coordinate: If multiple domains are involved, coordinate between specialists
- Validate: Ensure all changes work together correctly
These agent specifications also serve as:
- Onboarding Material: Understanding project conventions and structure
- Quick Reference: Finding commands, patterns, and best practices
- Decision Guide: Knowing which approach to use for common tasks
- Quality Standards: Understanding expectations for different types of work
Main Agent → "I need to modify CRD validation rules"
→ Delegates to kubernetes-expert-agent with full context
→ Kubernetes agent updates CRDs and manifests
→ Returns to main agent for integration
Main Agent → "Add new autoscaling feature"
→ go-expert-agent: Implement controller logic
→ kubernetes-expert-agent: Update CRDs and Helm chart
→ test-specialist-agent: Add unit and integration tests
→ documentation-agent: Document the feature
→ Main agent validates integration
When a new specialized domain emerges:
- agent-manager identifies the need
- agent-recruiter creates the specification
- Specification is reviewed and approved
- Agent is added to the
.github/agentsdirectory - This README is updated
- Other agents are updated to reference the new agent
When agent specifications need changes:
- agent-manager identifies outdated content
- Specification is updated with new information
- Version and update date are recorded
- Dependent agents are updated if needed
- Changes are documented
When agents are no longer needed:
- agent-manager confirms obsolescence
- Agent is moved to
.github/agents/archived/ - Retirement reason is documented
- References are removed from other agents
- This README is updated
- Always read the full agent specification before starting work
- Pass complete context when delegating
- Respect agent boundaries (don't ask them to work outside their domain)
- Coordinate between agents for cross-cutting concerns
- Validate that delegated work integrates correctly
- Keep specifications current with project evolution
- Document changes with dates and reasons
- Avoid overlap between agent domains
- Include concrete examples
- Reference actual code patterns from the project
- Update related agents when making changes
| Task | Primary Agent | Supporting Agents |
|---|---|---|
| Add Go controller logic | go-expert-agent | test-specialist-agent |
| Update CRD schema | kubernetes-expert-agent | go-expert-agent |
| Modify Helm chart | kubernetes-expert-agent | documentation-agent |
| Write new tests | test-specialist-agent | go-expert-agent |
| Update documentation | documentation-agent | - |
| Add new feature | coding-agent | All specialists as needed |
| Fix bug | coding-agent | Relevant specialist |
| Create new agent | agent-recruiter | agent-manager |
| Update agent spec | agent-manager | agent-recruiter |
.github/agents/
├── README.md # This file
├── coding-agent.md # Main coordinator
├── agent-manager.md # Lifecycle management
├── agent-recruiter.md # Specification creator
├── go-expert-agent.md # Go specialist
├── kubernetes-expert-agent.md # K8s/Helm specialist
├── documentation-agent.md # Documentation specialist
├── test-specialist-agent.md # Testing specialist
└── archived/ # Retired agents (when needed)
- Read
coding-agent.mdfor project overview - Review specialist agent that matches your interest area
- Follow the guidelines and conventions in the agent specifications
- Use agent specifications as quick reference
- Suggest updates when you find outdated information
- Propose new agents when new patterns emerge
Agent specifications are living documents that should evolve with the project:
- Found outdated info? Update the agent spec or file an issue
- Missing important context? Add it to the appropriate agent
- Need a new agent? Discuss with maintainers
- Agent overlap? Suggest consolidation or boundary clarification
- v1.0 (2025-12-02): Initial agent system with 7 agents
- Core: coding-agent
- Management: agent-manager, agent-recruiter
- Specialists: go-expert, kubernetes-expert, documentation, test-specialist
- GitHub Copilot Agent Best Practices
- Kubebuilder Documentation
- Ginkgo Testing Framework
- Helm Documentation
These agent specifications are part of the Actions Runner Controller project and follow the same Apache 2.0 license.