Skip to content

github-copilot-setup.md

Latest commit

 

History

History
250 lines (199 loc) · 12.4 KB

github-copilot-setup.md

File metadata and controls

250 lines (199 loc) · 12.4 KB

GitHub Copilot Collaborative Engineering Teams

Transform GitHub Copilot into a collaborative engineering team that works together to ensure reliable, maintainable, and business-aligned code.

⭐ Full Enterprise Support

Support Level: Fully tested and actively maintained

  • Native Integration: Uses GitHub Copilot chatmodes for seamless team workflows
  • GitHub Actions: Automated PR reviews with secure access controls
  • Comprehensive Testing: All chatmodes tested across multiple project configurations
  • Enterprise Features: Team handoffs, persistent documentation, GitHub issue creation
  • Active Development: Regular updates aligned with GitHub Copilot feature releases

🎯 What You Get: A Team That Collaborates

Instead of isolated AI responses, you get agents that:

  • Ask each other questions and delegate to specialists
  • Create persistent documentation that lives with your code
  • Follow enterprise workflows from requirements to deployment
  • Escalate to humans when business decisions are needed

🚀 Quick Setup

  1. Copy collaborative agents to your repository:

    cp -r engineering-team-agents/.github ./

  2. Initialize your project-specific agent team:

    ⚠️ Important: Use @workspace or agent/chat mode for file modifications

    Open GitHub Copilot Chat and run this team initialization:

    🤝 INITIALIZE COLLABORATIVE ENGINEERING TEAM

I've installed collaborative engineering agents that work as a team. Please help me set them up to work with my specific project context through documentation reference, not agent file modification.

**Team Mission**: Ensure every feature is user-focused, well-architected, secure, accessible, and reliably deployed.

**Setup Approach:**
1. **Discover**: Scan .github/chatmodes/ and .github/instructions/ directories
2. **Analyze Repository**: Read my README.md, package.json, docs/, and existing documentation to understand:
   - Project domain and business context
   - Technology stack and architecture
   - User types and business goals
   - Existing documentation structure
3. **Use Repository Links**: When chatmodes need domain knowledge, provide **file paths and repository links** instead of copying content:
   - "Project overview: README.md"
   - "Business goals: docs/product/business-context.md"
   - "Tech decisions: docs/architecture/"
   - "User journeys: docs/ux/user-personas.md"
4. **Fill Documentation Gaps**: If business context is missing, use /product-manager to help create:
   - docs/product/business-context.md
   - docs/architecture/system-overview.md
   - User personas and success metrics documentation
5. **Test Collaboration**: Demonstrate agents working together using discovered/created documentation

**My Project Context**: [Brief description: domain, users, tech stack, business goals]
Example: "Healthcare scheduling platform with React frontend, Node.js backend, serves small medical practices, focus on patient privacy and accessibility"

**🎯 Token Optimization Goal**: Agents understand my domain through **repository file references and links**, creating a lean knowledge system that scales without token bloat.

  3. Experience collaborative engineering in action:

    After initialization, watch your agents work as a team with chatmode commands:

    # Product-first approach
/pm-requirements "Add user authentication to our app"
→ Product Manager creates requirements, then asks UX Designer for user journey
→ UX Designer maps accessibility needs, asks Responsible AI for compliance review
→ Creates persistent docs/ files for team reference

# Architecture collaboration  
/architecture-review "Planning to add Redis caching layer"
→ Architecture reviewer analyzes system impact, creates ADR
→ Asks Code Reviewer about security implications  
→ Hands off to GitOps for deployment considerations

# Quality-focused development
/code-quality "Review this payment processing function"
→ Code Reviewer checks security, asks Architecture about scalability
→ Creates detailed review report with specific fixes
→ Escalates compliance questions to Responsible AI agent

# User experience validation
/ui-validation "Users are confused by our checkout flow"
→ UX Designer analyzes current journey, collaborates with Product Manager
→ Creates user journey maps and wireframes
→ Validates accessibility with Responsible AI agent

    Result: Every interaction creates persistent documentation and cross-agent collaboration that builds team knowledge over time.

🤝 Collaborative Chatmode Commands

Each command triggers team collaboration and document creation:

/pm-requirements 📊

Collaborative Role: Product Manager + UX Designer + Responsible AI

  • Creates: Requirements documents, GitHub issues, user stories
  • Collaborates with: UX Designer for user journeys, Responsible AI for accessibility
  • Documents: docs/product/[feature]-requirements.md, GitHub issues
  • Example: /pm-requirements "Add two-factor authentication for enterprise users"

/ui-validation 🎨

Collaborative Role: UX Designer + Product Manager + Responsible AI

  • Creates: User journey maps, wireframes, accessibility compliance reports
  • Collaborates with: Product Manager for business alignment, Responsible AI for WCAG compliance
  • Documents: docs/ux/[feature]-user-journey.md, docs/ux/[date]-[component]-ux-review.md
  • Example: /ui-validation "Our mobile checkout flow has 60% abandonment rate"

/architecture-review 🏛️

Collaborative Role: Architecture + Code Reviewer + GitOps

  • Creates: Architecture Decision Records (ADRs), system design documentation
  • Collaborates with: Code Reviewer for security, GitOps for deployment complexity
  • Documents: docs/architecture/ADR-[number]-[title].md
  • Example: /architecture-review "Migrating from monolith to microservices architecture"

/code-quality 🔍

Collaborative Role: Code Reviewer + Architecture + Responsible AI

  • Creates: Detailed review reports with specific code fixes
  • Collaborates with: Architecture for system impact, Responsible AI for bias/accessibility
  • Documents: docs/code-review/[date]-[component]-review.md
  • Example: /code-quality "Review this ML recommendation algorithm for bias"

/technical-writer ✍️

Collaborative Role: Technical Writer + Product Manager + Architecture

  • Creates: Documentation, blogs, tutorials, API docs, technical guides
  • Collaborates with: Product Manager for requirements clarity, Architecture for technical accuracy
  • Documents: docs/technical-writing/[topic]-documentation.md
  • Example: /technical-writer "Create user guide for our API authentication system"

/responsible-ai 🌍

Collaborative Role: Responsible AI + UX Designer + Product Manager

  • Creates: Responsible AI ADRs, bias testing reports, compliance documentation
  • Collaborates with: UX for accessibility, Product Manager for user impact assessment
  • Documents: docs/responsible-ai/RAI-ADR-[number]-[title].md, evolution logs
  • Example: /responsible-ai "Implement content moderation for user-generated content"

/cicd-optimization 🚀

Collaborative Role: GitOps + Code Reviewer + Architecture

  • Creates: Deployment guides, CI/CD optimization reports, operational runbooks
  • Collaborates with: Code Reviewer for security gates, Architecture for system dependencies
  • Documents: docs/gitops/[pipeline]-optimization.md
  • Example: /cicd-optimization "Our deployment pipeline takes 45 minutes, need to optimize"

📁 Project Structure After Setup

Your repository becomes a collaborative knowledge hub:

.github/
├── chatmodes/                    # Collaborative agent commands
│   ├── pm-requirements.chatmode.md
│   ├── ui-validation.chatmode.md
│   ├── architecture-review.chatmode.md
│   ├── code-quality.chatmode.md
│   ├── technical-writer.chatmode.md
│   ├── responsible-ai.chatmode.md
│   └── cicd-optimization.chatmode.md
├── instructions/
│   └── copilot-instructions.md   # Team collaboration patterns
└── docs/                         # Persistent knowledge base
    ├── product/                  # Requirements & user stories
    ├── ux/                       # User journeys & design reports
    ├── architecture/             # ADRs & system decisions
    ├── code-review/              # Review reports & fixes
    ├── technical-writing/        # Documentation, blogs, tutorials
    ├── responsible-ai/           # RAI-ADRs & compliance tracking
    ├── gitops/                   # Deployment guides & runbooks
    └── templates/                # Documentation templates

Key Difference: Every agent interaction creates lasting documentation that builds institutional knowledge over time.

🎯 Collaborative Development Best Practices

Question-First Development

  1. Start with /pm-requirements: Never write code without understanding user needs and business value
  2. Design before building: Use /ui-validation and /architecture-review to validate approach
  3. Review everything: Use /code-quality and /responsible-ai for comprehensive validation
  4. Deploy confidently: Use /cicd-optimization for reliable, observable deployments

Team Collaboration Patterns

  • Let agents talk to each other: Watch them delegate and ask questions of specialists
  • Provide business context: The more domain context you provide, the better the collaboration
  • Escalate when needed: Agents will tell you when human decisions are required
  • Trust the process: Each agent builds on previous team member insights

Documentation as Code

  • Persistent knowledge: Every interaction creates documentation that lives with your code
  • Version controlled: All agent-generated docs are committed and versioned
  • Template driven: Consistent formats make knowledge easy to find and update
  • Evolution tracking: See how practices and decisions evolve over time

🔄 Enterprise Development Workflow

🔍 Always Start Here (Question-First Approach)

/pm-requirements "Feature request: [describe what users want]"
→ Creates requirements → Asks UX for journey mapping → Validates accessibility

🏗️ Design Phase (Collaborative Architecture & UX)

/architecture-review "Technical approach: [system design]"
→ Creates ADR → Asks Code Reviewer about security → Consults GitOps on deployment

/ui-validation "User workflow: [current vs desired experience]"
→ Maps journey → Validates accessibility → Partners with Product Manager

💻 Implementation Phase (Quality-First Development)

/code-quality "Code review: [implementation details]"  
→ Reviews security/performance → Asks Architecture about system impact
→ Creates review report with specific fixes

/responsible-ai "Bias check: [AI/user-facing feature]"
→ Tests diverse inputs → Validates accessibility → Documents compliance

🚀 Deployment Phase (Operational Excellence)

/cicd-optimization "Pipeline improvement: [current deployment challenges]"
→ Optimizes workflow → Validates monitoring → Documents operational procedures

🔧 Troubleshooting & Customization

Common Issues

  • Chatmodes not loading: Verify .github/chatmodes/ files are properly copied and formatted
  • Generic responses: Re-run team initialization with more specific project context
  • Missing collaboration: Ensure agents have been customized with your project's domain knowledge

Customizing Your Team

  • Different document locations: Edit docs/ paths in agent files to match your preferences
  • Additional agents: Create new .chatmode.md files following existing patterns
  • Custom workflows: Modify agent collaboration patterns in .github/instructions/copilot-instructions.md

Success Indicators

✅ Agents reference each other in responses
✅ Documentation appears in your docs/ folders after interactions
✅ Business context is preserved and referenced across conversations
✅ Human escalation happens for strategic decisions
✅ Quality gates are systematically addressed before deployment