GitHub Copilot Configuration Guide

This directory contains comprehensive configuration for GitHub Copilot to provide optimal assistance when working on this repository.

📁 Directory Structure

.github/
├── copilot-instructions.md       # Repository-wide instructions
├── instructions/                  # Path-specific instructions (18 files)
├── agents/                        # Custom agent definitions (25 agents)
├── prompts/                       # Prompt templates (20+ prompts)
├── skills/                        # Skills and expertise modules
├── workflows/                     # GitHub Actions workflows
└── README.md                      # This file

📖 Instruction System

Repository-Wide Instructions

File: .github/copilot-instructions.md

Comprehensive instructions that apply to all work in this repository, including:

• Repository overview and architecture
• Tech stack (Next.js 16, React 19, TypeScript, Prisma, NextAuth, shadcn/ui)
• Build and validation workflows
• Development workflows
• Common pitfalls and workarounds
• MCP usage patterns (next-devtools, shadcn, playwright)

Path-Specific Instructions

Location: .github/instructions/*.instructions.md

Specialized instructions that apply when working with specific file types:

Frontend & Framework

• nextjs.instructions.md - Next.js 16 best practices (App Router, Server/Client Components, caching)
  • Applies to: **/*.tsx, **/*.ts, **/*.jsx, **/*.js, **/*.css
• nextjs-tailwind.instructions.md - Next.js + Tailwind CSS patterns
  • Applies to: **/*.tsx, **/*.ts, **/*.jsx, **/*.js, **/*.css
• reactjs.instructions.md - React 19 development standards
  • Applies to: **/*.jsx, **/*.tsx, **/*.js, **/*.ts, **/*.css, **/*.scss
• tanstack-start-shadcn-tailwind.instructions.md - TanStack + shadcn/ui patterns
  • Applies to: **/*.ts, **/*.tsx, **/*.js, **/*.jsx, **/*.css, **/*.scss, **/*.json

TypeScript & Node.js

• typescript-mcp-server.instructions.md - MCP server development with TypeScript
  • Applies to: **/*.ts, **/*.js, **/package.json
• nodejs-javascript-vitest.instructions.md - Node.js with Vitest testing
  • Applies to: **/*.js, **/*.mjs, **/*.cjs
• copilot-sdk-nodejs.instructions.md - GitHub Copilot SDK usage
  • Applies to: **/*.ts, **/*.js, **/package.json

Testing & Quality

• playwright-typescript.instructions.md - Playwright browser automation testing
  • Applies to: **/*.ts, **/*.tsx, **/*.js, **/*.jsx, **/*.css
• a11y.instructions.md - Accessibility best practices (WCAG 2.2 Level AA)
  • Applies to: **
• self-explanatory-code-commenting.instructions.md - Code commenting standards
  • Applies to: **

Security & Performance

• security-and-owasp.instructions.md - OWASP Top 10 security practices
  • Applies to: *
• performance-optimization.instructions.md - Comprehensive performance optimization
  • Applies to: *
• devops-core-principles.instructions.md - DevOps CALMS framework and DORA metrics
  • Applies to: *
• containerization-docker-best-practices.instructions.md - Docker and containerization
  • Applies to: **/Dockerfile, **/Dockerfile.*, **/*.dockerfile, **/docker-compose*.yml, **/compose*.yml

Database & Backend

• sql-sp-generation.instructions.md - SQL stored procedure development
  • Applies to: **/*.sql

Code Quality & Architecture

• object-calisthenics.instructions.md - Object-oriented design principles
  • Applies to: **/*.{cs,ts,java}
• spec-driven-workflow-v1.instructions.md - Specification-driven development workflow
  • Applies to: **

Task Management

• task-implementation.instructions.md - Task plan implementation from .copilot-tracking/plans/**
  • Applies to: **/.copilot-tracking/changes/*.md

🤖 Custom Agents (25 agents)

Location: .github/agents/*.agent.md

Specialized agents for specific development tasks:

Planning & Architecture

• Planer.agent.md - Multi-step plan research and outlining
• implementation-plan.agent.md - Generate implementation plans from features
• task-planner.agent.md - Create actionable implementation plans
• task-researcher.agent.md - Comprehensive project analysis
• research-technical-spike.agent.md - Technical spike research and validation
• prd.agent.md - Generate Product Requirements Documents

Development Experts

• expert-nextjs-developer.agent.md - Next.js 16 specialist (App Router, Cache Components, Turbopack)
• expert-react-frontend-engineer.agent.md - React 19.2 specialist (hooks, Server Components, Actions)
• typescript-mcp-expert.agent.md - MCP server development expert
• ui-ux-saas-specialist-agent.md - UI/UX specialist for multi-tenant SaaS

Testing & Quality

• playwright-tester.agent.md - Playwright test generation and execution
• tdd-red.agent.md - Write failing tests first (TDD Red phase)
• tdd-green.agent.md - Implement code to pass tests (TDD Green phase)
• tdd-refactor.agent.md - Refactor while maintaining tests (TDD Refactor phase)
• web-design-guidelines-agent.agent.md - UI/UX audit against Web Interface Guidelines

DevOps & Infrastructure

• se-gitops-ci-specialist.agent.md - CI/CD pipeline and deployment debugging
• github-actions-expert.agent.md - GitHub Actions workflow security and optimization
• postgresql-dba.agent.md - PostgreSQL database operations

Code Review & Security

• se-security-reviewer.agent.md - OWASP Top 10 and security best practices
• se-responsible-ai-code.agent.md - Bias prevention and ethical AI development
• se-system-architecture-reviewer.agent.md - Architecture validation (Well-Architected frameworks)

Documentation & Collaboration

• se-technical-writer.agent.md - Technical documentation specialist
• se-product-manager-advisor.agent.md - Product management and GitHub issue creation

Automation & Tooling

• agentic-workflows.agent.md - GitHub Agentic Workflows (gh-aw) specialist
• custom-agent-foundry.agent.md - Create custom VS Code agents

📝 Prompt Templates

Location: .github/prompts/*.prompt.md

Pre-built prompts for common tasks:

Planning & Design

• create-implementation-plan.prompt.md - Generate implementation plans
• breakdown-feature-implementation.prompt.md - Break down features into tasks
• breakdown-epic-arch.prompt.md - Break down epics with architecture
• create-technical-spike.prompt.md - Create technical spike documents
• update-implementation-plan.prompt.md - Update existing plans
• create-github-issues-feature-from-implementation-plan.prompt.md - Generate GitHub issues

Code Quality & Review

• sql-code-review.prompt.md - SQL code review
• postgresql-code-review.prompt.md - PostgreSQL-specific review
• sql-optimization.prompt.md - SQL query optimization
• postgresql-optimization.prompt.md - PostgreSQL optimization
• ai-prompt-engineering-safety-review.prompt.md - AI prompt safety review

Testing

• playwright-generate-test.prompt.md - Generate Playwright tests
• playwright-explore-website.prompt.md - Explore websites with Playwright

Theme Editor (Project-Specific)

• plan-shopifyThemeEditorEnhancement.prompt.md
• plan-shopifyThemeEditorEnhancement-extended.prompt.md
• plan-shopifyInspiredEditorOverhaul.prompt.md
• plan-themeEditorReliability.prompt.md

Specialized

• typescript-mcp-server-generator.prompt.md - Generate TypeScript MCP servers
• suggest-awesome-github-copilot-agents.prompt.md - Discover Copilot agent patterns

🎓 Skills

Location: .github/skills/

Specialized knowledge modules:

• copilot-sdk/ - Build agentic applications with GitHub Copilot SDK
• vercel-composition-patterns/ - React composition patterns that scale
• vercel-react-best-practices/ - React and Next.js performance optimization from Vercel
• web-design-guidelines/ - Review UI code for Web Interface Guidelines compliance

🔌 MCP Servers

Configuration Files:

• .vscode/mcp.json - VS Code MCP configuration
• .mcp.json - Repository-wide MCP configuration

Available MCP Servers

1. playwright - Browser automation testing

   • Command: npx @playwright/mcp@latest
   • Capabilities: Navigate, click, fill forms, take screenshots, capture console

2. next-devtools - Next.js 16 development tools

   • Command: npx -y next-devtools-mcp@latest
   • Tools: init, nextjs_docs, nextjs_runtime, browser_eval, upgrade_nextjs_16, enable_cache_components
   • Documentation resources: Cache Components, Next.js 16 migration guides

3. shadcn - shadcn/ui component management

   • Command: npx shadcn@latest mcp
   • Capabilities: Search, view, install shadcn/ui components

4. github-mcp-server - GitHub API integration

   • URL: https://api.githubcopilot.com/mcp
   • Capabilities: GitHub Actions, workflows, issues, PRs, code scanning

MCP Usage Patterns

Next.js Development Workflow

# 1. Start dev server
npm run dev

# 2. Initialize Next DevTools MCP (once per session)
# Use init tool from next-devtools-mcp

# 3. Query documentation
# Use nextjs_docs tool for any Next.js questions

# 4. Inspect runtime state
# Use nextjs_runtime tools:
#   - discover_servers
#   - list_tools
#   - call_tool (get_errors, get_logs, get_page_metadata)

# 5. Browser verification
# Use browser_eval via next-devtools-mcp

shadcn/ui Component Installation

# DO NOT manually copy component files
# Use MCP tool:
#mcp_shadcn_get_add_command_for_items ["@shadcn/dialog", "@shadcn/form"]
# Then run returned command: npx shadcn@latest add dialog form

🚀 Quick Start for Copilot

When Copilot starts working on this repository:

1. Read repository-wide instructions (.github/copilot-instructions.md)
2. Check path-specific instructions for relevant file types
3. Use MCP servers for up-to-date documentation:
   • next-devtools for Next.js 16 patterns
   • shadcn for component usage
   • playwright for browser testing
4. Leverage custom agents for specialized tasks
5. Reference prompt templates for common workflows

📚 Key Resources

• Best Practices Guide: https://gh.io/copilot-coding-agent-tips
• GitHub Copilot Docs: https://docs.github.com/en/copilot
• Custom Instructions Guide: https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot
• VS Code Copilot: https://code.visualstudio.com/docs/copilot
• MCP Documentation: https://modelcontextprotocol.io

🔄 Maintenance

This instruction system should be updated when:

• New technologies or frameworks are adopted
• Build or validation workflows change
• New custom agents are created
• MCP servers are added or updated
• Best practices evolve

---

Last Updated: February 2026 Maintained By: StormCom Development Team