A multi-agent workflow system for GitHub Copilot in VS Code that brings structure and quality gates to AI-assisted development.
This repository provides a set of custom agent definitions for GitHub Copilot in VS Code.
The agents are intentionally specialized to support a structured workflow (planning, review, security, testing, release) with clear handoffs and constraints.
AI coding assistants are powerful but chaotic:
- They forget context between sessions
- They try to do everything at once (plan, code, test, review)
- They skip quality gates and security reviews
- They lose track of decisions made earlier
This repository provides specialized AI agents that each own a specific part of your development workflow:
| Agent | Role |
|---|---|
| Roadmap | Product vision and epics |
| Planner | Implementation-ready plans (WHAT, not HOW) |
| Analyst | Deep technical research |
| Architect | System design and patterns |
| Critic | Plan quality review |
| Security | Comprehensive security assessment |
| Implementer | Code and tests |
| Code Reviewer | Code quality gate before QA |
| QA | Test strategy and verification |
| UAT | Business value validation |
| DevOps | Packaging and releases |
| Retrospective | Lessons learned |
| ProcessImprovement | Workflow evolution |
Each agent has clear constraints (Planner can't write code, Implementer can't redesign) and produces structured documents that create an audit trail.
Use as many or as few as you need, in any order. They are designed to know their own role and work together with other agents in this repo. They are designed to work together to create a structured and auditable development process. They are also designed to challenge each other to ensure the best possible outcome.
git clone https://github.com/groupzer0/agents.gitCopy agents to your workspace (per-repo, recommended):
your-project/
└── .github/
└── agents/
├── planner.agent.md
├── implementer.agent.md
└── ... (others you need)
Or install them at the user level so they are available across all VS Code workspaces. User-level agents are stored in your VS Code profile folder:
- Linux:
~/.config/Code/User/ - macOS:
~/Library/Application Support/Code/User/ - Windows:
%APPDATA%\Code\User\
Tip
The easiest way to create a user-level agent is via the Command Palette: Chat: New Custom Agent → select User profile. VS Code will place it in the correct location automatically.
In VS Code, select your agent from the agents dropdown at the top of the Chat panel, then type your prompt:
Create a plan for adding user authentication
Note
Unlike built-in participants (e.g., @workspace), custom agents are not invoked with the @ symbol. You must select them from the dropdown or use the Command Palette.
Note
Review the chat.tools.*.autoApprove entries below before enabling. These settings allow certain actions to proceed without per-action confirmation.
{
"accessibility.hideAccessibleView": true,
"chat.agent.maxRequests": 256,
"chat.checkpoints.showFileChanges": true,
"chat.customAgentInSubagent.enabled": true,
"chat.instructionsFilesLocations": {
".github/instructions": true
},
"chat.mcp.autostart": "newAndOutdated",
"chat.mcp.gallery.enabled": true,
"chat.tools.terminal.autoApprove": {
"cd": true,
"git": true,
"npm": true,
"python": true
},
"chat.tools.urls.autoApprove": {
"https://duckduckgo.com": {
"approveRequest": false,
"approveResponse": true
},
"https://github.com": {
"approveRequest": false,
"approveResponse": true
},
"https://vtk.org": true,
"https://www.google.com": {
"approveRequest": false,
"approveResponse": true
}
},
"chat.useAgentSkills": true,
"editor.accessibilitySupport": "off",
"github.copilot.nextEditSuggestions.enabled": true,
"terminal.integrated.accessibleViewFocusOnCommandExecution": false
}You can also use these agents with the GitHub Copilot CLI by placing your .agent.md files under .github/agents/ in each repository where you run the CLI, then invoking them with commands like:
copilot --agent planner --prompt "Create a plan for adding user authentication"Known limitation (user-level agents): The Copilot CLI currently has an upstream bug where user-level agents in ~/.copilot/agents/ are not loaded, even though they are documented (github/copilot-cli#452). This behavior and the recommended per-repository workaround were identified and documented by @rjmurillo. Until the bug is fixed, prefer .github/agents/ in each repo.
| Document | Purpose |
|---|---|
| USING-AGENTS.md | Quick start guide (5 min read) |
| AGENTS-DEEP-DIVE.md | Comprehensive documentation |
| CHANGELOG.md | Notable repository changes |
Roadmap → Planner → Analyst/Architect/Security/Critic → Implementer → Code Reviewer → QA → UAT → DevOps
- Roadmap defines what to build and why
- Planner creates a structured plan at the feature level or smaller
- Analyst researches unknowns
- Architect ensures design fit. Enforces best practices.
- Security audits for vulnerabilities. Recommends best practices.
- Critic reviews plan quality
- Implementer writes code
- Code Reviewer verifies code quality
- QA verifies tests. Ensures robust test coverage
- UAT confirms business value was delivered
- DevOps releases (with user approval)
Each agent has one job. Planner plans. Implementer implements. No scope creep.
Agents produce Markdown documents in agent-output/. Every decision is recorded.
Critic reviews plans. Security audits code. QA verifies tests. Nothing ships without checks.
Agents hand off to each other with context. No lost information between phases.
For larger changes, you can use the execution orchestration skills to coordinate subagent work with strict quality gates and a single authoritative execution-state file:
- Skills:
execution-orchestration,planner-execution-orchestration - State file location:
agent-output/planning/<ID>-execution-state.yaml
agents/
├── CHANGELOG.md # Notable changes
├── README.md # This file
├── USING-AGENTS.md # Quick start guide
├── AGENTS-DEEP-DIVE.md # Comprehensive documentation
├── LICENSE # MIT License
└── vs-code-agents/ # Agent definitions
├── analyst.agent.md
├── architect.agent.md
├── critic.agent.md
├── devops.agent.md
├── implementer.agent.md
├── pi.agent.md # ProcessImprovement
├── planner.agent.md
├── qa.agent.md
├── code-reviewer.agent.md
├── retrospective.agent.md
├── roadmap.agent.md
├── security.agent.md
├── uat.agent.md
└── reference/
├── uncertainty-review-template.md
└── security-language-vuln-reference.md
The Security Agent has been enhanced to provide truly comprehensive security reviews:
- Architectural Security: Trust boundaries, STRIDE threat modeling, attack surface mapping
- Code Security: OWASP Top 10, language-specific vulnerability patterns
- Dependency Security: CVE scanning, supply chain risk assessment
- Infrastructure Security: Headers, TLS, container security
- Compliance: OWASP ASVS, NIST, industry standards
Most developers don't know how to conduct thorough security reviews. They miss:
- Architectural weaknesses (implicit trust, flat networks)
- Language-specific vulnerabilities (prototype pollution, pickle deserialization)
- Supply chain risks (abandoned packages, dependency confusion)
- Compliance gaps (missing security headers, weak TLS)
The Security Agent systematically checks all of these, producing actionable findings with severity ratings and remediation guidance.You can then hand this off to the Planner agent and the Implementer to address.
See security.agent.md for the full specification.
Edit .agent.md files to adjust:
description: What shows in Copilottools: Which VS Code tools the agent can usehandoffs: Other agents it can hand off to- Responsibilities and constraints
- Create
your-agent.agent.mdfollowing the existing format - Define purpose, responsibilities, constraints
- Add to
.github/agents/in your workspace
Recent commits introduced significant improvements to agent workflow and capabilities:
Agents now explicitly avoid forced root-cause narratives when evidence is missing.
- Analyst: Uses an objective hard pivot trigger (timebox/evidence gate) to switch from RCA attempts to system hardening + telemetry requirements.
- Architect: Treats insufficient observability as an architectural risk; defines normal vs debug logging guidance and a minimum viable incident telemetry baseline.
- QA: Validates diagnosability improvements; prefers asserting structured telemetry fields/events over brittle log string matching.
- Template:
vs-code-agents/reference/uncertainty-review-template.mdprovides a repeatable output format.
Agents now use Claude Skills—modular, reusable instruction sets that load on-demand:
| Skill | Purpose |
|---|---|
analysis-methodology |
Confidence levels, gap tracking, investigation techniques |
architecture-patterns |
ADR templates, patterns, anti-pattern detection |
code-review-checklist |
Pre/post-implementation review criteria |
code-review-standards |
Code review checklist, severity definitions, document templates |
cross-repo-contract |
Multi-repo API type safety and contract coordination |
document-lifecycle |
Unified numbering, automated closure, orphan detection |
engineering-standards |
SOLID, DRY, YAGNI, KISS with detection patterns |
release-procedures |
Two-stage release workflow, semver, platform constraints |
security-patterns |
OWASP Top 10, language-specific vulnerabilities |
testing-patterns |
TDD workflow, test pyramid, coverage strategies |
Skill Placement:
- VS Code Stable (1.107.1): Place in
.claude/skills/ - VS Code Insiders: Place in
.github/skills/
Note
These locations are changing with upcoming VS Code releases. The .github/skills/ location is becoming the standard. See the VS Code Agent Skills documentation for the latest guidance.
- TDD mandatory: Implementer and QA now require Test-Driven Development for new feature code
- Two-stage release: DevOps commits locally first; pushes only on explicit release approval
- Document status tracking: All agents update Status fields in planning docs ("Draft", "In Progress", "Released")
- Open Question Gate: Implementer halts if plans have unresolved questions; requires explicit user acknowledgment to proceed
- Slimmed Security agent: Reduced by 46% using skill references instead of inline content
New cross-repo-contract skill for projects with runtime + backend repos that need to stay aligned:
- Contract discovery: Agents check
api-contract/or.contracts/for type definitions - Type safety enforcement: Implementer verifies contract definitions before coding API endpoints/clients
- Breaking change coordination: Plans must document contract changes and sync dependencies
- Quality gate: Critic verifies multi-repo plans address contract adherence
Integrated into Architect, Planner, Implementer, and Critic agents.
New document-lifecycle skill implementing:
- Unified numbering: All documents in a work chain share the same ID (analysis 080 → plan 080 → qa 080 → uat 080)
- Automated closure: Documents move to
closed/subfolders after commit - Orphan detection: Agents self-check + Roadmap periodic sweep
This keeps active plans visible while archiving completed work for traceability.
- Aligned agent tool names with VS Code APIs (2025-12-16): Agent
toolsdefinitions now use official VS Code agent tool identifiers. - Added subagent usage patterns (2025-12-15): Planner, Implementer, QA, Analyst, and Security document how to invoke each other as scoped subagents.
- Background Implementer mode (2025-12-15): Implementation can run as local chat or background agent in isolated Git worktree.
Contributions welcome! Areas of interest:
- Agent refinements: Better constraints, clearer responsibilities
- New agents: For specialized workflows (e.g., Documentation, Performance)
- Documentation: Examples, tutorials, troubleshooting
This repository also runs an automatic Markdown lint check in GitHub Actions on pushes and pull requests that touch .md files. The workflow uses markdownlint-cli2 with a shared configuration, and helps catch issues like missing fenced code block languages (MD040) early in review. This lint workflow was proposed based on feedback and review from @rjmurillo.
- VS Code with GitHub Copilot
MIT License - see LICENSE