swe-copilot-agents 0.1.0

GitHub Copilot custom agents for orchestrating the complete software development lifecycle

Awesome Skills - GitHub Copilot Agents

A collection of specialized GitHub Copilot custom agents for orchestrating the complete software development lifecycle, from requirements gathering through implementation, testing, and review.

Overview

This repository contains AI agents that follow the "coordinator and worker" pattern—where specialist agents perform focused work under the guidance of an orchestrator. Each agent has a strong persona, clear boundaries, and specific expertise.

---

Agents

@dev-orchestrator

Role: Meticulous technical lead who conducts specialist agents like an orchestra conductor

Persona:

• Philosophy: "Right agent, right time, right order"
• Traits: Meticulous, patient, organized, clear
• Metaphor: Orchestra conductor who doesn't play instruments but brings out the best performance from each soloist

Responsibilities:

• Coordinates the complete development lifecycle across 4 movements
• Tracks state obsessively (which movement, which soloist, which outputs)
• Manages review cycles with automatic fix loops (max 2 reviews)
• Seeks human approval at each intermission

Orchestrated Agents:

• @brainstormer (Movement I - Planning)
• @plan-executor (Movement II - Implementation)
• @plan-reviewer (Movement III - Review)
• @pytest-agent (Movement IV - Testing, optional)

Best Practices: ✅ EXCELLENT

• Strong, distinctive persona with musical terminology throughout
• Clear YAML configuration with agents restriction
• Visual workflow diagram (ASCII art)
• Comprehensive error handling and human intervention pathways
• Review cycle feedback loop with automatic fixes
• Memorable tagline: "A great conductor doesn't play every instrument—they know exactly when each section should perform."

---

@brainstormer

Role: Curious planning agent who asks clarifying questions to crystallize requirements

Persona:

• Philosophy: Uncertainty triggers questions, not assumptions
• Traits: Insatiably curious, thorough, multi-round questioner (1-10 rounds)
• Metaphor: Exploratory researcher who never assumes

Responsibilities:

• Asks 1-10 rounds of clarifying questions before writing plans
• Queries knowledge graph for impact analysis (downstream, cycles, bottlenecks, test seams)
• Creates detailed markdown plan documents in docs/plan/YYYY-MM-DD-*.md
• Integrates knowledge graph findings into every plan

Best Practices: ✅ EXCELLENT

• Strong persona ("insatiably curious")
• Knowledge graph integration for impact analysis
• Multi-round questioning framework with defined stages
• Clear completion criteria (user confirmation before writing plan)
• Comprehensive plan output template with KG analysis sections
• Workflow summary diagram

---

@plan-executor

Role: Senior Python engineer who executes plans by blending seamlessly with existing codebases

Persona:

• Philosophy: "Consistency > Clean Code"
• Traits: Chameleon-like, adaptive, pattern-matching
• Metaphor: Code chameleon who becomes indistinguishable from existing code

Responsibilities:

• Reads 3-5 existing files to understand patterns before writing
• Matches existing style exactly (naming, imports, error handling, formatting)
• Implements requirements from plan documents
• Never "fixes" existing code because it's ugly

Best Practices: ✅ EXCELLENT

• Strong persona with clear philosophy ("Consistency > Clean Code")
• Concrete code examples showing good vs. bad matching
• Specific matching table (naming, imports, errors, strings, formatting)
• Clear boundaries (never "revamp" existing code)
• Executable commands for studying patterns

---

@plan-reviewer

Role: Senior code reviewer and quality assurance engineer who rigorously audits implementation against plans

Persona:

• Philosophy: "Evidence over assumptions"
• Traits: Ruthlessly thorough, evidence-driven, uncompromising
• Metaphor: Auditor who proves everything through code inspection

Responsibilities:

• Extracts all requirements from plan documents
• Searches codebase for concrete evidence of each requirement
• Categorizes execution status (Fully/Partially/Not Executed)
• Performs brittleness analysis via knowledge graph (high centrality, excessive dependencies, deep chains)
• Provides prioritized remediation recommendations

Best Practices: ✅ EXCELLENT

• Strong persona ("ruthlessly thorough")
• Clear execution status definitions with evidence gathering checklist
• Knowledge graph brittleness analysis with risk levels
• Comprehensive report output format
• Priority assignment criteria (P0-P3)
• Status determination rules with specific conditions

---

@pytest-agent

Role: Senior Python QA engineer specializing in pytest with expert-level mocking and patching

Persona:

• Philosophy: "Depth over breadth"
• Traits: Exhaustive, comprehensive, edge-case obsessed
• Metaphor: Test surgeon who operates at every code path

Responsibilities:

• Writes exhaustive test suites (happy path, edge cases, errors, state, integration)
• Expert-level mocking and patching (Mock, MagicMock, patch, PropertyMock)
• Targets >80% coverage for new code
• Tests only newly implemented code (respects scope boundaries)

Best Practices: ✅ EXCELLENT

• Strong persona ("depth over breadth")
• Comprehensive test coverage requirements table
• Expert mocking examples with all patterns
• Clarification protocol for ambiguous behavior
• Clear scope boundaries (only test new code)
• Code style examples (good vs. bad)

---

@knowledge-graph-agent

Role: Expert code analysis specialist who builds knowledge-base graphs from codebases

Persona:

• Philosophy: Static analysis reveals code architecture
• Traits: Multi-lingual, systematic, incremental
• Metaphor: Code cartographer who maps relationships

Responsibilities:

• Scans codebases and generates knowledge-graph.yaml in project root
• Tracks relationships: files, functions, classes, imports, call chains, concerns
• Supports incremental updates (only changed files)
• Version tracking via git commit hashes
• Multi-language support (Python, JS/TS, Go, Java, Rust)

Best Practices: ✅ EXCELLENT

• Clear startup behavior with git hash comparison
• Incremental update mode to avoid full rescans
• Comprehensive YAML output format specification
• Complete analysis standards with good/bad examples
• Web framework pattern recognition (Flask, FastAPI, Express, Gin)
• Validation checklist before completion

---

Best Practices Summary

Agent	Persona	Boundaries	Commands	Examples	Workflow Diagram	Overall
@dev-orchestrator	✅ Strong	✅ Clear	✅ Complete	✅ Musical	✅ ASCII	EXCELLENT
@brainstormer	✅ Strong	✅ Clear	✅ Complete	✅ Plan format	✅ Flowchart	EXCELLENT
@plan-executor	✅ Strong	✅ Clear	✅ Complete	✅ Code style	❌ None	EXCELLENT
@plan-reviewer	✅ Strong	✅ Clear	✅ Complete	✅ Report format	❌ None	EXCELLENT
@pytest-agent	✅ Strong	✅ Clear	✅ Complete	✅ Test style	❌ None	EXCELLENT
@knowledge-graph-agent	✅ Strong	✅ Clear	✅ Complete	✅ YAML format	❌ None	EXCELLENT

Overall Repository Quality: ✅ EXCELLENT - All agents follow GitHub Copilot custom agent best practices with strong personas, clear boundaries, executable commands, and comprehensive examples.

---

Workflow Orchestration

Complete Development Cycle

User Request
      ↓
┌─────────────────────────────────────────────────────────────────┐
│                    @dev-orchestrator (Conductor)                 │
└─────────────────────────────────────────────────────────────────┘
      │
      ├─ Movement I: @brainstormer → Plan document
      │     (1-10 rounds of questions)
      │     ↓ Human Approval
      │
      ├─ Movement II: @plan-executor → Implementation
      │     (Match existing code patterns)
      │     ↓ Human Approval
      │
      ├─ Movement III: @plan-reviewer → Review #1
      │     ↓ Major issues found?
      │     ├─ YES → Movement IIb: @plan-executor (Fix)
      │     │           ↓ Movement IIIb: @plan-reviewer (Re-review FINAL)
      │     │                  ↓ Issues persist?
      │     │                  └─ YES → Human Intervention
      │     └─ NO → Continue
      │     ↓ Human Approval
      │
      └─ Movement IV: @pytest-agent → Tests (Optional)
            ↓
         Finale

Review Cycle Logic

1. Review #1 identifies issues → If major issues found, trigger fix cycle
2. Fix Cycle (@plan-executor) implements recommendations
3. Review #2 (FINAL) re-audits → If issues persist, human intervention required
4. Maximum 2 reviews enforced

---

Usage

Basic Agent Invocation

# In VS Code with GitHub Copilot Chat
@dev-orchestrator
I want to add a user authentication system with JWT tokens

# Or invoke a specific agent directly
@brainstormer
I need to add a search feature to my application

@plan-reviewer
Review the implementation against docs/plan/2025-03-02-auth.md

File Locations

• Agents: agents/*.agent.md
• Plans: docs/plan/YYYY-MM-DD-*.md
• Knowledge Graph: knowledge-graph.yaml (project root)

---

Agent File Structure

All agents follow this structure:

---
name: agent-name
description: Brief description of purpose
tools: ["tool1", "tool2"]
agents: ["agent1", "agent2"]  # For orchestrators only
target: vscode | github-copilot
---

# Persona description
## Core Philosophy
## Your Role
## [Specific sections per agent]
## Boundaries (Always Do / Ask First / Never Do)
## Commands

---

Contributing

When adding new agents:

1. Follow the persona pattern - Give each agent a distinctive personality
2. Define clear boundaries - What they always do, ask first, never do
3. Include executable commands - Concrete bash commands they can run
4. Provide examples - Good vs. bad outputs
5. Add visual workflow - ASCII diagrams for complex agents
6. Document best practices - Mark if agent follows Copilot best practices

---

License

[Your License Here]

---

Inspiration

Based on patterns from:

• GitHub Custom Agents Documentation
• awesome-copilot community collection
• Subagent orchestration patterns in VS Code