🤖 Copilot Agent Starter

Multi-agent orchestration templates, delegation patterns, and agent definitions for AI coding agents.

Build sophisticated agent systems using GitHub Copilot CLI. This template repository provides battle-tested patterns for creating domain agents, orchestrators, and multi-agent teams drawn from real production systems.

📘 Part of The Agentic Development Blueprint by Hector Flores

---

⚡ Quick Start

1. Clone this template:

   gh repo create my-agent-system --template htekdev/copilot-agent-starter --private
   cd my-agent-system

2. Create your first agent:

   cp .github/agents/templates/domain-agent-template.agent.md .github/agents/my-agent.agent.md
   # Edit the file to define your agent's identity, domain, and behavior

3. Launch your agent:

   gh copilot task my-agent "Check the status of X"

---

📦 What's Included

🎭 Agent Patterns (patterns/)

• Orchestrator Prompt Template — How to coordinate multiple sub-agents
• Sub-Agent Task Schema — Structured format for delegating work
• Delegation Decision Flowchart — When to delegate vs do it yourself
• Parallel Agent Coordination — Running multiple agents safely
• Agent Steering vs Launch — When to steer vs launch fresh
• Team Agent Pattern — Goal-oriented multi-agent teams

📝 Agent Definition Templates (.github/agents/templates/)

• Domain Agent Template — Stateful agents that own a domain
• Task Agent Template — Stateless agents that run procedures
• Orchestrator Template — Agents that coordinate other agents
• Team Agent Template — Goal-oriented agent teams

🧠 Memory System (memory/)

• 4-Tier Memory Architecture — Core, Working, Long-term, Events
• Memory Management Guide — Loading, saving, pruning patterns

🎨 Example Agents (.github/agents/)

• Orchestrator Example — Dispatches multiple agents in parallel
• Code Reviewer Example — Specialized code review agent
• Researcher Example — Deep research and fact-gathering agent

📚 Examples (examples/)

• Multi-Agent System Walkthrough — End-to-end example
• Agent Communication Patterns — How agents share context

---

🎯 Agent Pattern Comparison

Pattern	Memory?	Orchestrates?	Owns a Goal?	Lifecycle	Example Use Case
Domain Agent	✅ 4-tier	❌	❌ (owns a domain)	Permanent	Finance manager, content editor, CI/CD monitor
Task Agent	❌ Stateless	❌	❌ (runs a procedure)	Permanent	Daily briefing, weekly report, one-time migration
Orchestrator	❌ Stateless	✅ All agents	❌ (generic coordination)	Permanent	System check-in, multi-domain audit
Team Agent	✅ 4-tier + manifest + progress	✅ Defined team	✅	Created → Active → Completed	Home-buying team, product launch team, debt payoff team

---

🔀 Delegation Decision Flowchart

New task arrives
  │
  ├─ Can I complete in ≤5 tool calls?
  │   → DO IT YOURSELF
  │
  ├─ Is it independent research across many files/modules?
  │   → LAUNCH EXPLORE AGENT
  │
  ├─ Does it need the full toolset + multi-step reasoning?
  │   → LAUNCH GENERAL-PURPOSE AGENT
  │
  ├─ Is this a follow-up to a running agent in the same domain?
  │   → STEER (write_agent)
  │
  └─ Is it a cron/scheduled job?
      → ALWAYS LAUNCH FRESH (never steer)

---

🧠 Memory Architecture (4-Tier System)

All stateful agents use this memory pattern:

Tier	File	Purpose	Load	Size Limit
1	core.md	Identity, mission, heuristics	ALWAYS	3-5KB
2	working.md	Current state, active context	ALWAYS	5KB max
3	long-term.md	Historical patterns, validated lessons	On-demand	10KB max
4	events.log	Append-only audit trail	Write-only	Unlimited (prune >30d)

Pattern: Load 1+2 → Work → Save 2+4 → Promote to 3 only when validated

---

🎭 How to Create Each Agent Type

Domain Agent

Use when: You need an agent that owns a specific area of responsibility with persistent memory.

---
name: finance-manager
description: "Owns budget tracking, bill payments, and expense categorization"
---

# Finance Manager — Budget & Bills

## Memory
**Load first:** core.md + working.md

## Identity
You own all financial tracking for the household...

## Domain Ownership
- Budget tracking
- Bill payment reminders
- Expense categorization

## Decision Framework
### Act Immediately
- Log expenses when receipts arrive
- Create tasks for due bills

### Ask First
- Purchases >$500

See: .github/agents/templates/domain-agent-template.agent.md

Task Agent

Use when: You need a stateless procedure that runs on-demand or on a schedule.

---
name: daily-briefing
description: "Morning briefing: weather, calendar, tasks, emails"
---

# Daily Briefing — Morning Summary

You compile the morning briefing: weather, calendar, top tasks, emails.

**No memory** — fresh state every run.

## Procedure
1. Get weather forecast
2. Load today's calendar events
3. Find top 3 priority tasks
4. Scan unread emails for urgency
5. Send one consolidated message

See: patterns/task-agent-pattern.md

Orchestrator

Use when: You need to dispatch multiple agents and compile their results.

---
name: system-checkin
description: "Dispatches all domain agents, collects reports, compiles one summary"
---

# System Check-In Orchestrator

## Orchestration Workflow
1. Discover all domain agents (glob `.github/agents/*.agent.md`)
2. Filter out orchestrators, task agents, team agents
3. Launch all remaining agents in parallel via `task` tool
4. Collect results with `read_agent`
5. Compile consolidated report
6. Send ONE notification (silence if all clear)

See: .github/agents/orchestrator.agent.md and patterns/orchestrator-prompt.md

Team Agent

Use when: You have a goal-oriented initiative requiring multiple specialized agents over weeks/months.

---
name: product-launch-team
description: "Coordinates product launch from planning through post-launch review"
---

# Product Launch Team

## Goal
Successfully launch Product X by Q2 2026.

## Team Roster
- **marketing-lead** (dedicated) — Owns campaign, messaging, launch timeline
- **engineering-lead** (shared) — Feature delivery, deployment
- **sales-enablement** (dedicated) — Collateral, training, demo prep

## Phases
1. **Planning** (Weeks 1-2) — Roadmap, messaging, timeline
2. **Build** (Weeks 3-8) — Feature dev, content creation
3. **Launch** (Week 9) — Go-live, monitoring
4. **Post-Launch** (Weeks 10-12) — Metrics, retrospective

See: patterns/team-agent-pattern.md

---

🚦 Agent Steering vs Launch Decision

Steer (write_agent) — When ALL are true:

• ✅ An IDLE agent exists in the same domain
• ✅ Message is a follow-up (correcting, clarifying, continuing)
• ✅ Agent has context that would be lost by launching fresh
• ✅ NOT a cron dispatch

Launch Fresh (task tool) — When ANY is true:

• ✅ New topic unrelated to any running agent
• ✅ No idle agents exist with relevant context
• ✅ High-quality results needed with clean slate
• ✅ Unsure? (default to launch — cleaner)
• ✅ ALL cron-dispatched jobs (absolute rule)

See: patterns/agent-steering-vs-launch.md

---

📐 Orchestrator Pattern

The canonical pattern for coordinating multiple agents:

Step 1: Discover Agents

glob(pattern: ".github/agents/*.agent.md")

Extract agent names, filter out orchestrators and team agents.

Step 2: Dispatch in Parallel

task(agent_type: "agent1", mode: "background", ...)
task(agent_type: "agent2", mode: "background", ...)
task(agent_type: "agent3", mode: "background", ...)

Step 3: Collect Results

read_agent(agent_id: "agent1", wait: true)
read_agent(agent_id: "agent2", wait: true)
read_agent(agent_id: "agent3", wait: true)

Step 4: Compile Report

Aggregate only agents with updates. Omit "all clear" sections.

Step 5: Send ONE Notification

Single consolidated message. Stay silent if nothing actionable.

See: patterns/parallel-coordination.md and .github/agents/orchestrator.agent.md

---

📚 Documentation

Document	What It Covers
patterns/README.md	Overview of all delegation patterns
patterns/orchestrator-prompt.md	How to write orchestrator prompts
patterns/sub-agent-task-schema.md	Structured task delegation format
patterns/delegation-decision.md	Flowchart: delegate vs do it yourself
patterns/parallel-coordination.md	Running agents safely in parallel
patterns/agent-steering-vs-launch.md	When to steer vs launch fresh
patterns/team-agent-pattern.md	Goal-oriented agent teams
memory/4-tier-system.md	Complete memory architecture
examples/multi-agent-system.md	Full system walkthrough
examples/agent-communication.md	How agents share context

---

🎓 Learn More

This template is part of The Agentic Development Blueprint — a comprehensive guide to building production-grade agentic systems with GitHub Copilot CLI.

The blueprint covers:

• ✅ Agent architecture (this repo)
• ✅ Custom instructions — htekdev/copilot-instructions-starter
• ✅ Git hookflows — htekdev/copilot-hookflow-starter
• ✅ Quality gates — htekdev/copilot-quality-starter

👉 Get the full blueprint on htek.dev

---

🤝 Contributing

Found a pattern that works well? Submit a PR! This is a living template that evolves with the community.

---

📄 License

MIT License — See LICENSE file.

---

👨‍💻 About

Created by Hector Flores (@htekdev)

• 🌐 htek.dev
• 📺 YouTube
• 💼 LinkedIn

These patterns are drawn from production agentic systems managing complex multi-domain workflows. They're battle-tested, not theoretical.