AI-Augmented Project Template

A comprehensive project template that seamlessly integrates GitHub Copilot and AI coding agents into your software development workflow. This template provides structured documentation, specialized AI agent profiles, and professional development standards to enable effective human-AI collaboration.

🎯 Vision

Transform software development by providing AI assistants with rich project context, enabling them to understand your system architecture, coding standards, and business goals from the start. Create a development environment where both human developers and AI agents work together following the same professional standards.

✨ Key Features

🤖 AI-First Design

• Repository-Wide AI Instructions: Custom .github/copilot-instructions.md provides project context to GitHub Copilot
• Path-Specific Guidance: Specialized instructions for backend code, tests, and documentation
• AI Context Documentation: Dedicated AGENTS.md file with technical details for AI assistants

👥 Enterprise AI Agent Ecosystem

10 Specialized AI Agents covering the complete enterprise development lifecycle:

Core Business & Architecture

1. Stakeholder Agent: Business requirements, ROI analysis, user stories
2. Architect Agent: System design, ADRs, technology decisions, scalability

Development & Quality

3. Developer Agent: Feature implementation, bug fixing, clean code practices
4. Tester/QA Agent: Test strategy, automation, coverage analysis, quality assurance
5. Documentation Agent: Technical writing, ADRs, API docs, developer guides

Operations & Deployment

6. DevOps/Release Agent: CI/CD pipelines, Docker/K8s, IaC, release management

Security & Compliance

7. Security/Audit Agent: Security review, vulnerability scanning, OWASP compliance
8. Performance Agent: Performance monitoring, optimization, load testing
9. Compliance/Regulator Agent: GDPR, licensing, regulatory compliance

Change Management

10. Change-Management Agent: Feature flags, versioning, impact analysis

Plus Additional Specialists:

• Bug Fix Teammate: Systematic debugging and regression prevention
• Code Reviewer: Automated code quality and security review
• Refactoring Specialist: Code cleanup and quality improvement
• Docs Web Agent: Documentation website management (Docusaurus)

📋 Professional Workflow Templates

• Pull Request Template: Comprehensive checklist for code reviews
• YAML Issue Templates: Structured bug reports, feature requests, and free writing
• Issue Template Config: Flexible issue creation with both structured templates and blank issues
• Contribution Guidelines: Clear standards for all contributors
• Code Owners: Automatic review request routing

🏗️ Clean Architecture Foundation

• Complete Working Implementation: Full CRUD API with sample User entity
• Domain-driven design principles
• Clear layer separation (Domain, Application, Infrastructure, Presentation)
• SOLID principles throughout
• Dependency injection pattern
• Comprehensive testing structure (29 passing tests)
• Entity Framework Core with in-memory database
• FluentValidation for input validation

🚀 DevOps & CI/CD

• GitHub Actions Workflows: Automated build, test, and code coverage
• CodeQL Security Scanning: Automated vulnerability detection
• Dependency Review: Automatic checks for vulnerable dependencies
• Docker Support: Multi-stage Dockerfile and docker-compose
• Health Checks: Built-in health endpoint for monitoring

📦 .NET Template System

• Installable Template: Use dotnet new install to install
• Customizable Options: Choose framework version (net8.0/net9.0), Docker, Swagger, tests
• Production Ready: Professional structure ready for real-world projects

🚀 Quick Start

Use as a Template

This repository serves as both a working example and an installable .NET template.

Option 1: Install as .NET Template (Recommended)

# Install the template
dotnet new install /path/to/ai-augmented-project-template

# Create a new project using the template
dotnet new ai-dotnet-template -n MyAwesomeProject

# Navigate to your new project
cd MyAwesomeProject

# Build and run
dotnet build
dotnet run --project src/WebApi

Visit https://localhost:5001 to see your API with Swagger UI!

Option 2: Clone and Customize

# Clone this repository
git clone https://github.com/tlejmi/ai-augmented-project-template.git
cd ai-augmented-project-template

# Restore dependencies
dotnet restore

# Build the solution
dotnet build

# Run tests
dotnet test

# Run the API
dotnet run --project src/WebApi

Development Setup

Set up pre-commit hooks (recommended):

# Install the pre-commit hook to run format/build/test automatically
cp .githooks/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

Before each commit, always run:

# 1. Format code
dotnet format

# 2. Build
dotnet build --configuration Release

# 3. Run tests
dotnet test --configuration Release

See CONTRIBUTING.md for detailed development guidelines.

Option 3: Docker

# Build and run with Docker Compose
docker-compose up

# API will be available at http://localhost:5000

Prerequisites

• .NET 8 SDK or later
• Git
• Docker (optional, for containerized development)
• Visual Studio 2022, VS Code, or JetBrains Rider
• GitHub Copilot (optional but recommended)

📚 Documentation Structure

This template uses a layered documentation approach:

For Human Developers

• README.md (this file): Project overview and quick start
• CONTRIBUTING.md: Contribution guidelines and workflow
• docs/: Additional guides and documentation

For AI Assistants

• AGENTS.md: Technical context, build instructions, and conventions
• .github/copilot-instructions.md: Repository-wide AI instructions
• .github/instructions/: Path-specific instructions (backend, tests, docs)
• .github/agents/: Specialized AI agent profiles
• .mcp.json: Model Context Protocol configuration (for external CLI tools, not VS Code)
• .github/MCP_CONFIGURATION.md: MCP configuration reference

🎭 Using Enterprise AI Agents

This template includes 10 specialized AI agent profiles for enterprise-scale development:

Business & Requirements

# Define business requirements and user stories
@copilot /agent stakeholder-agent
"Create user stories for a password reset feature"

Architecture & Design

# Design system architecture and make technical decisions
@copilot /agent architect-agent
"Design a microservices architecture for the order management system"

Development

# Implement features with clean code practices
@copilot /agent developer-agent
"Implement the user authentication feature following SOLID principles"

Testing & QA

# Create comprehensive test strategies
@copilot /agent tester-qa-agent
"Create unit and integration tests for the payment service"

Documentation

# Write technical documentation and ADRs
@copilot /agent documentation-agent
"Create an ADR for choosing PostgreSQL over MongoDB"

DevOps & Release

# Set up CI/CD pipelines and deployments
@copilot /agent devops-release-agent
"Create a GitHub Actions workflow for deploying to Azure"

Security & Audit

# Review code for security vulnerabilities
@copilot /agent security-audit-agent
"Review this authentication code for security vulnerabilities"

Performance Optimization

# Optimize application performance
@copilot /agent performance-agent
"Optimize these database queries and implement caching"

Compliance & Regulatory

# Ensure GDPR and regulatory compliance
@copilot /agent compliance-regulator-agent
"Implement GDPR data subject rights (access, erasure, portability)"

Change Management

# Manage feature flags and releases
@copilot /agent change-management-agent
"Create a feature flag strategy for gradual rollout"

See AI Agent Documentation for detailed agent capabilities.

Quick Agent Reference

Use Case	Agent	Example
Requirements	stakeholder-agent	Define user stories and acceptance criteria
Architecture	architect-agent	Design system components and ADRs
Coding	developer-agent	Implement features with clean code
Testing	tester-qa-agent	Create comprehensive test suites
Documentation	documentation-agent	Write ADRs and technical docs
CI/CD	devops-release-agent	Set up deployment pipelines
Security	security-audit-agent	Security review and vulnerability scanning
Performance	performance-agent	Optimize queries and implement caching
Compliance	compliance-regulator-agent	GDPR compliance and licensing
Changes	change-management-agent	Feature flags and version management

Model Context Protocol (MCP) Integration

Important: GitHub Copilot in VS Code has built-in MCP capabilities. No .mcp.json configuration is needed for GitHub Copilot.

This repository includes MCP server configuration for external CLI tools (like Copilot CLI) and documents how GitHub Copilot's built-in MCP features work.

MCP Capabilities Available to GitHub Copilot Agents

All GitHub Copilot agents in this repository automatically have access to:

1. GitHub MCP Server (built-in) - Repository operations, code search, issue/PR management
2. Web Fetch (built-in) - HTTP/HTTPS requests and external APIs
3. Memory (built-in) - Session context and state management
4. Time (built-in) - Timestamps, durations, and date utilities
5. Sequential Thinking (built-in) - Step-by-step reasoning and complex problem solving

External MCP Client Configuration

For external CLI tools (not GitHub Copilot in VS Code), the repository includes:

• .mcp.json: MCP server definitions for CLI tools like Copilot CLI
• .github/MCP_CONFIGURATION.md: Reference guide explaining VS Code vs CLI usage

GitHub Copilot in VS Code does NOT use .mcp.json - MCP capabilities are built-in and configured via agent profiles in .github/agents/*.agent.md.

For detailed information:

• MCP Integration Guide - Comprehensive guide
• MCP Configuration Reference - Quick reference
• Official MCP Documentation - Protocol specification

📦 What's Included

This template includes a fully functional sample application demonstrating all architectural patterns:

Sample Implementation

• User Entity: Complete domain entity with business logic
  • Email validation and normalization
  • Active/inactive status management
  • Audit fields (CreatedAt, UpdatedAt)
• CRUD API: Full REST API with 5 endpoints
  • GET /api/users - List all users
  • GET /api/users/{id} - Get user by ID
  • POST /api/users - Create new user
  • PUT /api/users/{id} - Update user
  • DELETE /api/users/{id} - Delete user
  • POST /api/users/{id}/deactivate - Deactivate user
• Validation: FluentValidation rules for all inputs
• Service Layer: Business logic separation
• Repository Pattern: Data access abstraction
• DTOs: Proper request/response models

Testing

• 16 Core Tests: User entity unit tests
• 7 Application Tests: UserService unit tests with Moq
• 6 Integration Tests: Full API endpoint tests
• AAA Pattern: Arrange-Act-Assert structure throughout
• FluentAssertions: Readable test assertions

Configuration

• In-Memory Database: Easy to run without external dependencies
• Swagger UI: Interactive API documentation at root path
• Structured Logging: Serilog configuration with console and file outputs
• Health Endpoint: /health for monitoring

🏛️ Architecture Overview

This template follows Clean Architecture principles:

┌─────────────────────────────────────────┐
│          Presentation Layer             │
│         (WebApi/Controllers)            │
├─────────────────────────────────────────┤
│         Application Layer               │
│    (Use Cases, Commands, Queries)       │
├─────────────────────────────────────────┤
│        Infrastructure Layer             │
│  (Database, External Services, Repos)   │
├─────────────────────────────────────────┤
│           Domain Layer                  │
│    (Entities, Value Objects, Logic)     │
└─────────────────────────────────────────┘

Key Principles:

• Dependencies point inward (outer layers depend on inner layers)
• Business logic isolated in the Core/Domain layer
• Infrastructure concerns abstracted by interfaces
• Testable at every layer

🛠️ Technology Stack

Backend

• .NET 8 (C#): Modern, cross-platform framework (LTS)
• ASP.NET Core: Web API with minimal APIs and controllers
• Entity Framework Core: ORM with in-memory database (easily swappable to SQL Server, PostgreSQL, etc.)
• Serilog: Structured logging to console and file
• Swashbuckle: OpenAPI/Swagger documentation with XML comments

Testing

• xUnit: Modern testing framework
• FluentAssertions: Readable and expressive assertions
• Moq: Mocking framework for unit tests
• Microsoft.AspNetCore.Mvc.Testing: Integration testing support

Validation & Quality

• FluentValidation: Fluent API for validation rules
• CodeQL: Security vulnerability scanning
• Code Coverage: Automated test coverage reporting

DevOps

• GitHub Actions: CI/CD workflows
• Docker: Multi-stage containerization
• Health Checks: Built-in health monitoring endpoints

Package Management

• Directory.Packages.props: Centralized NuGet package version management
• global.json: .NET SDK version pinning

📖 Key Concepts

Using as a .NET Template

Once installed, you can create new projects with various options:

# Basic usage with defaults (.NET 8, Docker, Swagger, Tests)
dotnet new ai-dotnet-template -n MyProject

# Use .NET 9
dotnet new ai-dotnet-template -n MyProject --Framework net9.0

# Without Docker
dotnet new ai-dotnet-template -n MyProject --UseDocker false

# Without tests
dotnet new ai-dotnet-template -n MyProject --IncludeTests false

# Minimal setup (no Docker, no GitHub Actions, no tests)
dotnet new ai-dotnet-template -n MyProject --UseDocker false --IncludeGitHubActions false --IncludeTests false

Available Template Options:

Option	Type	Default	Description
--Framework	choice	net8.0	Target framework (net8.0 or net9.0)
--UseDocker	bool	true	Include Docker support
--UseSwagger	bool	true	Include Swagger/OpenAPI
--UseSerilog	bool	true	Use Serilog logging
--IncludeTests	bool	true	Include test projects
--IncludeGitHubActions	bool	true	Include CI/CD workflows

Conventional Commits

All commits follow the Conventional Commits specification:

<type>(<scope>): <description>

[optional body]

[optional footer]

Examples:

feat(auth): add password reset functionality
fix(api): handle null reference in user controller
docs(readme): update installation instructions
test(users): add integration tests for user service

AI-Augmented Development

This template is designed for human-AI collaboration:

1. AI agents have full project context through structured documentation
2. Specialized agents excel at specific tasks (testing, planning, reviewing)
3. Consistent standards apply to both human and AI contributions
4. Human oversight ensures quality and alignment with business goals

🤝 Contributing

We welcome contributions from both humans and AI agents! Please read our Contributing Guidelines for details on:

• Code of conduct
• Development workflow
• Coding standards
• Testing requirements
• Pull request process
• Working with AI agents

📋 Roadmap

Current Features ✅

• Complete .NET 8 solution with Clean Architecture
• Sample CRUD API with User entity
• Comprehensive test suite (29 tests)
• GitHub Copilot integration with custom instructions
• 10 Enterprise AI Agent Profiles (Stakeholder, Architect, Developer, Tester/QA, Documentation, DevOps/Release, Security/Audit, Performance, Compliance/Regulator, Change-Management)
• Additional specialized agents (Bug Fix, Code Reviewer, Refactoring, Docs Web)
• GitHub Actions CI/CD workflows
• CodeQL security scanning
• Docker containerization
• Swagger/OpenAPI documentation
• .NET template system
• YAML issue templates
• Centralized package management

Future Enhancements 🚀

• Additional database providers (SQL Server, PostgreSQL)
• Authentication & authorization (JWT, OAuth)
• Rate limiting and API versioning
• Redis caching support
• Message queue integration (RabbitMQ, Azure Service Bus)
• Kubernetes deployment manifests
• Multi-language support (TypeScript, Python, Java variants)
• Advanced monitoring and observability (OpenTelemetry)
• GraphQL support option
• AI Agent orchestration and workflow automation

🔒 Security

Security is a top priority. This template includes:

• Input validation guidelines
• Security-focused code review checklist
• No secrets in code (use environment variables)
• SQL injection prevention
• Authentication and authorization patterns

Report security vulnerabilities privately through GitHub Security Advisories.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by Clean Architecture by Robert C. Martin
• Built with GitHub Copilot
• Based on .NET architectural patterns from Microsoft

📞 Support

• Documentation: Check AGENTS.md for detailed technical information
• Issues: Report bugs or request features via GitHub Issues
• Discussions: Ask questions or share ideas in GitHub Discussions

---

Built with ❤️ for human-AI collaboration in software development