copilot-agent-patterns

name	copilot-agent-patterns
description	GitHub Copilot custom agent design patterns, best practices, collaboration workflows, and agent orchestration
license	Apache-2.0

Copilot Agent Patterns Skill

Purpose

Provides proven patterns for designing, implementing, and orchestrating GitHub Copilot custom agents that work effectively individually and collaboratively.

Rules

Agent Design Patterns

Specialist Agent Pattern:

---
name: ui-enhancement-specialist
description: Expert in HTML/CSS, accessibility, responsive design
tools: ["view", "edit", "create", "shell", "search_code"]
---

# UI Enhancement Specialist

## Core Expertise
- HTML5 semantic markup
- CSS best practices
- WCAG 2.1 AA accessibility
- Responsive design

## Scope
- MUST focus on UI/UX improvements
- MUST NOT handle backend logic
- MUST delegate security to security-specialist

## Skills Integration
- `.github/skills/quality/html-css-best-practices/`
- `.github/skills/quality/accessibility-wcag/`

Orchestrator Agent Pattern:

---
name: task-agent
description: Orchestration and task delegation specialist
tools: ["*"]
---

# Task Agent

## Core Responsibilities
1. Analyze repository comprehensively
2. Create GitHub issues for improvements
3. Assign issues to appropriate specialists
4. Track progress and quality

## Delegation Strategy
- UI/UX issues → ui-enhancement-specialist
- Security issues → security-architect
- Documentation → documentation-specialist

Discordian Trinity Pattern:

Visionary (Product Owner):
- Challenges assumptions
- Defines "what" and "why"
- Creates product vision

Architect (System Designer):
- Analyzes patterns
- Defines "how" architecturally
- Creates system designs

Developer (Implementer):
- Writes code
- Implements designs
- Tests and debugs

Agent Configuration Standards

YAML Frontmatter:

---
name: agent-name               # Lowercase, hyphen-separated
description: Brief expertise   # Max 200 characters
tools: ["tool1", "tool2"]     # Minimal set (or "*" for meta agents)
---

Required Sections:

## 📋 Required Configuration Files
[Instructions to read setup files]

## 🎯 Skills Integration
[List of relevant skills from .github/skills/]

## 🔐 ISMS Framework Compliance
[Security and compliance requirements]

## ⚖️ Rules and Enforcement
[MUST/MUST NOT rules]

## Examples
[Concrete examples of agent work]

## Related Policies
[Links to ISMS and skills]

Collaboration Patterns

Sequential Workflow:

1. task-agent analyzes repository
2. task-agent creates issues
3. task-agent assigns to specialists:
   - Issue #1 → ui-enhancement-specialist
   - Issue #2 → security-architect
   - Issue #3 → documentation-specialist
4. Specialists complete work independently
5. task-agent reviews and validates

Parallel Workflow:

Multiple specialists work simultaneously on different issues:
- ui-enhancement-specialist: Accessibility improvements
- security-architect: Security hardening
- documentation-specialist: API documentation

No coordination needed (different scopes)

Stacked PR Workflow:

1. Foundation PR (simon-moon creates architecture)
2. Implementation PR (george-dorn builds on #1)
3. UI Polish PR (ui-enhancement-specialist builds on #2)
4. Documentation PR (hagbard-celine documents all)

Each PR uses base_ref to stack on previous work

Agent Communication

Issue Assignment:

## Task for @ui-enhancement-specialist

**Context**: Homepage accessibility audit failed

**Requirements**:
- Fix WCAG 2.1 AA violations
- Improve keyboard navigation
- Add ARIA labels to forms
- Test with screen readers

**Skills to Use**:
- `.github/skills/quality/accessibility-wcag/`
- `.github/skills/quality/html-css-best-practices/`

**Acceptance Criteria**:
- [ ] Lighthouse accessibility score = 100
- [ ] All ARIA labels present
- [ ] Keyboard navigation functional
- [ ] Screen reader tested

PR Review Comments:

@george-dorn Great implementation! A couple of security concerns:

1. **Authentication**: Line 45 needs rate limiting. See 
   `.github/skills/security/access-control/` for pattern.

2. **Input Validation**: Line 78 should sanitize user input.
   Reference `.github/skills/security/secure-development/`.

Otherwise LGTM! 🚀

Agent Boundaries

MUST Respect Boundaries:

UI Specialist:
✅ Can: HTML, CSS, accessibility, responsive design
❌ Cannot: Backend logic, database, API design

Security Architect:
✅ Can: Security design, threat modeling, controls
❌ Cannot: Implement all code (delegates to developers)

Business Development:
✅ Can: Strategy, positioning, sales enablement
❌ Cannot: Technical implementation, code changes

Task Agent:
✅ Can: Orchestrate, delegate, create issues
❌ Cannot: Implement all specialized work itself

Autonomy Guidance ("Ask Less, Complete More")

Agents SHOULD:

1. Default to Best Practices
   - Use skills library guidelines
   - Follow ISMS policies automatically
   - Apply established patterns

2. Make Informed Decisions
   - Review relevant skills first
   - Check existing codebase patterns
   - Only ask when genuinely ambiguous

3. Fix Issues Proactively
   - Security issues: fix without asking
   - Accessibility problems: correct immediately
   - Broken links: update automatically

4. Complete Tasks Fully
   - Update related files
   - Verify across all language versions
   - Test edge cases
   - Document changes

5. Validate Before Submitting
   - Run tests
   - Check quality metrics
   - Verify compliance

Only Ask When:

- Requirements genuinely ambiguous
- Major architectural decision required
- Breaking change affects multiple systems
- Policy interpretation unclear
- Business/product decision needed

Agent Metrics

Quality Metrics:

- Issues created (quality over quantity)
- Issues successfully completed
- Code quality improvements
- Security vulnerabilities found/fixed
- Accessibility improvements
- Documentation completeness

Efficiency Metrics:

- Time to first response
- Time to issue resolution
- Number of review iterations
- Test coverage improvements
- CI/CD success rate

Best Practices

DO:

✅ Focus on your expertise area
✅ Reference skills library constantly
✅ Delegate outside your scope
✅ Provide concrete examples
✅ Document your decisions
✅ Test your changes thoroughly
✅ Follow ISMS policies
✅ Complete work autonomously when possible

DON'T:

❌ Work outside your expertise
❌ Duplicate work of other agents
❌ Skip testing or validation
❌ Ignore security policies
❌ Create unnecessary documentation files
❌ Ask for confirmation on standard patterns
❌ Make changes without verification

Examples

Agent Delegation Decision Tree

Issue Type: "Improve accessibility"
↓
Is this UI/UX? → YES
↓
Assign to: ui-enhancement-specialist
Skills: accessibility-wcag, html-css-best-practices

Issue Type: "Add authentication"
↓
Is this security? → YES
↓
Assign to: security-architect
Skills: access-control, secure-development, cryptography

Issue Type: "Optimize database queries"
↓
Is this performance? → YES
↓
Is there a specialist? → NO
↓
Assign to: george-dorn (developer)
Skills: testing-strategy, code-review-practices

Multi-Agent Collaboration Example

# Project: Add User Dashboard

## Phase 1: Architecture (simon-moon)
- Create DATA_MODEL.md
- Create ARCHITECTURE.md
- Design API contracts
- Skills: c4-modeling, security-architecture

## Phase 2: Backend (george-dorn)
- Implement API endpoints
- Add authentication
- Write unit tests
- Skills: secure-development, testing-strategy

## Phase 3: Frontend (ui-enhancement-specialist)
- Build responsive UI
- Ensure accessibility
- Add animations
- Skills: html-css-best-practices, accessibility-wcag

## Phase 4: Documentation (hagbard-celine)
- User guide
- API documentation
- Release notes
- Skills: product-documentation, api-documentation

## Phase 5: Business Enablement (marketing-specialist)
- Feature announcement
- SEO optimization
- Social media content
- Skills: content-marketing, seo-optimization

Related Policies

• Hack23 ISMS-PUBLIC
• MCP Server Integration SKILL

Related Documentation

• .github/agents/README.md
• .github/agents/INDEX.md
• .github/skills/INDEX.md

Resources

• GitHub Copilot Custom Agents Documentation
• Hack23 Agent Ecosystem Summary