Solution Scaffolder

Solution Scaffolder

Overview

This skill automates the creation of new .NET solutions that follow Vertical Slice Architecture along with the conventions and best practices of the ArticlesSite repository. Vertical Slice Architecture organizes code by business features rather than technical layers, resulting in simpler, more maintainable, and feature-focused projects. This skill provides an interactive guided experience that ensures consistency across projects while respecting custom requirements and project-specific needs.

When to Use

Use this skill when:

• Creating a new .NET 10 solution from scratch
• Starting a new project that should follow ArticlesSite conventions
• Onboarding team members to consistent project structure
• Establishing standardized folder layouts, configurations, and dependencies
• User asks to "create a new solution", "scaffold a project", or "set up a new .NET application"

Core Principles

1. Vertical Slice Architecture: Organize code by business features, not technical layers
2. Convention Over Configuration: Use ArticlesSite patterns as defaults, allowing overrides when needed
3. Interactive Guidance: Ask targeted questions to understand project requirements before generating scaffolds
4. Completeness: Create a production-ready structure with all necessary files and configurations
5. Standards Compliance: Enforce C# 14, .NET 10, and established coding guidelines
6. Minimal Bloat: Generate only necessary files; avoid boilerplate that's not used

Operational Workflow

Phase 1: Discovery (Interactive Interview)

Before generating any files, conduct a guided discovery to understand the project. Ask these questions in order:

Question 1: Solution Name

• Prompt: "What is the name of your new solution? (e.g., MyWebApp, DataProcessor, ApiService)"
• Validation: Must be PascalCase, starting with a letter and containing only letters and digits (no spaces, hyphens, or other special characters)
• Impact: Used for folder structure, project names, namespace roots, and solution file

Question 2: Destination Folder

• Prompt: "Where should the solution folder be created? (provide absolute or relative path, default: current directory)"
• Validation: Path must be valid and writable; create parent directories if needed
• Impact: Solution will be created at {path}/{SolutionName}/
• Example Responses:
  • . or empty (current directory)
  • ./projects
  • ~/Development
  • C:\Projects (Windows)
  • /home/user/repos (Linux/Mac)

Question 3: Solution Type

• Prompt: "What type of solution are you building?"
• Choices:
  • "Web Application (Blazor Server + API)" - Default. Includes Web, API, Domain, Persistence projects
  • "API-Only (.NET API)" - REST API without UI. Includes API, Domain, Persistence projects
  • "Console Application" - CLI tool or background service. Minimal structure
  • "Class Library" - Reusable library for other projects
  • "Microservice (Aspire-based)" - Distributed system with AppHost, ServiceDefaults
  • "Custom (Manual selection)" - Pick individual components

Question 4: Additional Features (Multi-Select)

• Prompt: "Which features should be included? (Select all that apply)"
• Options:
  • "Authentication & Authorization (Auth0)" - Default if Web Application
  • "Entity Framework Core with MongoDB" - Default if Web/API/Microservice
  • "MediatR for CQRS" - Default if Web/API/Microservice
  • "FluentValidation" - Default if Web/API/Microservice
  • "OpenTelemetry & Application Insights" - Default if API/Microservice
  • "Background Jobs (Hangfire or Quartz)" - Optional
  • "Caching (Redis)" - Optional
  • "API Versioning" - Default if API
  • "Unit & Integration Testing (xUnit)" - Recommended
  • "bUnit Component Testing" - Only if Blazor UI included
  • "Architecture Testing" - Recommended
  • "GitHub Actions CI/CD" - Optional

Question 5: Database Selection (If applicable)

• Prompt: "Which database will you use?"
• Choices:
  • "MongoDB" - Default. Enterprise-ready document store
  • "SQL Server" - Traditional relational database
  • "PostgreSQL" - Open-source relational
  • "None/In-Memory" - For libraries or simple apps
  • "Multiple (add later)" - Defer database selection

Question 6: Target Environment

• Prompt: "Where will this solution primarily run?"
• Choices:
  • "Local Development Only" - Minimal cloud configuration
  • "Cloud (Docker/Kubernetes)" - Include containerization and orchestration
  • "Azure" - Azure-specific settings and integrations
  • "Multiple Environments (Dev/Staging/Prod)" - Full environment configuration

Question 7: Team & Compliance

• Prompt: "Are there any special requirements?"
• Options:
  • "Code Coverage Requirements (minimum %)" - Input number if selected
  • "HIPAA/SOC2 Compliance" - Add security headers and audit logging
  • "Multi-tenant Architecture" - Add tenant isolation patterns
  • "None" - Standard requirements only

Phase 2: Analysis & Planning

Process user input:

1. Validate solution name and format
2. Determine which projects need to be created based on solution type and features
3. Map NuGet package requirements from Directory.Packages.props standards
4. Calculate .gitignore rules needed
5. Identify configuration files needed (appsettings.json, .editorconfig, etc.)
6. Review with user before proceeding: "I'm ready to create X projects with Y features. Ready to proceed?"

Phase 3: Scaffolding & Generation

Create the Vertical Slice Architecture structure with complete .github folder based on selections:

1. Create root directories: src/, tests/, docs/, scripts/, .github/
2. Generate .github structure (see ".github Folder Structure & Contents" section):
   • Workflow files (CI/CD, code quality, security scanning)
   • Issue and PR templates
   • Dependabot configuration
   • CODEOWNERS file
   • Instructions folder with solution-specific coding standards
   • Testing and debugging documentation (SETUP_SUMMARY.md, test-debugging-*.md)
   • Copy agents/, prompts/, and skills/ folders from source repository if they exist
3. Generate projects based on solution type and features
4. Generate configuration files (.editorconfig, Directory.Build.props, Directory.Packages.props, global.json)
5. Generate feature folder templates (sample feature structure for reference)
6. Generate solution file (.sln)
7. Generate root documentation (README.md, CONTRIBUTING.md, LICENSE.txt)

The .github folder ensures all workflows, standards, procedures, agents, prompts, and skills are included from the start, enabling consistent AI-assisted development immediately.

MyWebApp/                                    (Solution Root)
├── .github/
│   ├── workflows/
│   │   ├── ci-cd.yml                       (If GitHub Actions selected)
│   │   ├── code-quality.yml                (If testing selected)
│   │   └── security-scan.yml               (If security scanning enabled)
│   ├── ISSUE_TEMPLATE/
│   │   ├── bug.md                          (Bug report template)
│   │   ├── feature.md                      (Feature request template)
│   │   └── config.yml
│   ├── pull_request_template.md            (PR description template)
│   ├── dependabot.yml                      (Automated dependency updates)
│   ├── CODEOWNERS                          (Code ownership rules)
│   └── instructions/
│       ├── copilot-instructions.md         (Solution-specific Copilot rules)
│       ├── blazor.instructions.md          (If Blazor UI selected)
│       ├── git-commit-instructions.md      (Commit message conventions)
│       └── markdown.instructions.md        (Documentation standards)
├── docs/                                   (README, architecture diagrams)
├── scripts/                                (Setup and utility scripts)
├── src/
│   ├── MyWebApp.AppHost/                  (If Aspire selected)
│   ├── MyWebApp.ServiceDefaults/          (If microservice)
│   ├── MyWebApp.Api/                      (API entry point, Program.cs, middleware)
│   ├── MyWebApp.Web/                      (Blazor UI entry point, layout, shared components)
│   ├── MyWebApp.Common/                   (Shared abstractions, interfaces, extensions)
│   ├── MyWebApp.Persistence/              (Data access context, repositories, configurations)
│   └── MyWebApp.Features/
│       ├── Articles/                      (Articles feature vertical slice)
│       │   ├── CreateArticle/
│       │   │   ├── CreateArticleCommand.cs
│       │   │   ├── CreateArticleHandler.cs
│       │   │   ├── CreateArticleValidator.cs
│       │   │   └── CreateArticlePage.razor  (If Blazor UI)
│       │   ├── GetArticles/
│       │   │   ├── GetArticlesQuery.cs
│       │   │   ├── GetArticlesHandler.cs
│       │   │   └── ArticlesListComponent.razor
│       │   ├── GetArticleById/
│       │   └── UpdateArticle/
│       ├── Users/                         (Users feature vertical slice)
│       │   ├── Register/
│       │   ├── Login/
│       │   └── GetProfile/
│       └── Comments/                      (Comments feature vertical slice)
│           ├── CreateComment/
│           ├── GetComments/
│           └── DeleteComment/
├── tests/
│   ├── MyWebApp.Tests.Unit/               (Unit tests organized by feature)
│   │   └── Features/
│   │       ├── Articles/
│   │       └── Users/
│   ├── MyWebApp.Tests.Integration/        (Integration tests)
│   │   └── Features/
│   │       └── Articles/
│   ├── MyWebApp.Tests.Architecture/       (Architecture tests, if selected)
│   ├── MyWebApp.Tests.Bunit/              (Blazor component tests, if selected)
│   │   └── Features/
│   │       └── Articles/
│   └── MyWebApp.Tests.E2E/                (End-to-end tests, if selected)
├── .editorconfig                          (Copy from ArticlesSite)
├── .gitignore                             (Customized for selections)
├── Directory.Build.props                  (C# 14, .NET 10 config)
├── Directory.Packages.props                (Centralized versions)
├── global.json                            (SDK version lock)
├── MyWebApp.sln                           (Solution file)
├── NuGet.config                           (Private feeds if needed)
├── README.md                              (Getting started guide)
├── LICENSE.txt                            (Default: MIT)
└── CONTRIBUTING.md                       (Development guidelines)

Vertical Slice Organization:

• Each feature lives in its own folder under Features/
• Each endpoint/operation (Command/Query) is self-contained within the feature
• Shared abstractions go in Common/
• Data access and persistence layer stays centralized in Persistence/
• Each feature folder can contain: handlers, validators, DTOs, models, and UI components (if Blazor)
• .github folder contains all workflow, template, and instruction files for the repository

Phase 4: Post-Scaffolding

After generation:

1. Verify all files created successfully
2. Run dotnet restore to validate project structure
3. Provide next steps:
   • Running tests: dotnet test
   • Building: dotnet build
   • Running development: dotnet run or dotnet watch (if applicable)
   • Adding first entity/API endpoint
4. Create a quick start guide tailored to the selected features

File Generation Standards

Project Files (.csproj)

All .csproj files must include:

• Target framework: <TargetFramework>net10.0</TargetFramework>
• Language version: <LangVersion>14.0</LangVersion>
• Nullable reference types: <Nullable>enable</Nullable>
• ImplicitUsings: <ImplicitUsings>enable</ImplicitUsings>
• XML documentation: <GenerateDocumentationFile>true</GenerateDocumentationFile>

Configuration Files

• .editorconfig: Copy from ArticlesSite (enforces style rules)
• Directory.Build.props: Centralized build configuration
• Directory.Packages.props: Pinned NuGet versions from ArticlesSite standards
• global.json: Lock .NET SDK to 10.x
• .gitignore: Extended with project-specific ignores
• appsettings.json: Environment-specific configs (Development, Staging, Production)

Documentation Files

• README.md: Quick start, tech stack, running instructions
• CONTRIBUTING.md: Development setup, code style, PR process
• LICENSE.txt: Default MIT (customizable)
• docs/ARCHITECTURE.md: High-level architecture overview
• .github/SETUP_SUMMARY.md: Comprehensive setup and debugging guide
• .github/test-debugging-unit.md: Unit testing best practices and debugging
• .github/test-debugging-integration.md: Integration testing with TestContainers
• .github/test-debugging-e2e.md: E2E testing with Playwright

Global Usings File

Each project should include GlobalUsings.cs:

global using System;
global using System.Collections.Generic;
global using System.Linq;
global using System.Text;
global using System.Threading.Tasks;
global using Microsoft.Extensions.DependencyInjection;
// ... project-specific usings

NuGet Package Defaults

Use ArticlesSite Directory.Packages.props as the baseline. Include only what's selected:

Core (Always)

• Microsoft.Extensions.Configuration.*
• Microsoft.Extensions.DependencyInjection
• Microsoft.Extensions.Logging

Web/API

• MediatR
• FluentValidation
• Scalar.AspNetCore (API docs)

Database

• MongoDB.Driver
• MongoDB.EntityFrameworkCore
• OR Microsoft.EntityFrameworkCore.SqlServer
• OR Npgsql.EntityFrameworkCore.PostgreSQL

Testing

• xUnit
• FluentAssertions
• NSubstitute
• Microsoft.NET.Test.Sdk

Blazor UI

• bunit
• bunit.web

Observability

• OpenTelemetry.Exporter.ApplicationInsights
• OpenTelemetry.Instrumentation.AspNetCore

Authentication

• Auth0.AspNetCore.Authentication

Customization & Overrides

While this skill follows ArticlesSite conventions, allow customization in:

1. Namespace Prefix: Default to solution name, but allow override (e.g., Company.Product)
2. Project Structure: Offer different folder layouts (flat vs. grouped)
3. Package Versions: Use ArticlesSite versions by default, but allow newer stable versions
4. CI/CD Strategy: GitHub Actions by default, but allow GitLab CI, Azure Pipelines, etc.
5. License Type: MIT by default, but allow Apache 2.0, GPL, custom, or none

Example: Creating "BlogEngine" Web Application

Interview Flow

Q1: Solution name? → "BlogEngine"
Q2: Destination folder? → "~/Projects"
Q3: Solution type? → "Web Application (Blazor Server + API)"
Q4: Features? → Authentication, EF Core + MongoDB, MediatR, FluentValidation, 
                  Testing, bUnit, Architecture Testing, GitHub Actions
Q5: Database? → "MongoDB"
Q6: Environment? → "Azure"
Q7: Special requirements? → "None"

Generated Structure (Vertical Slice Architecture)

BlogEngine/
├── .github/
│   ├── workflows/
│   │   ├── ci-cd.yml
│   │   ├── code-quality.yml
│   │   └── security-scan.yml
│   ├── ISSUE_TEMPLATE/
│   │   ├── bug.md
│   │   ├── feature.md
│   │   └── config.yml
│   ├── pull_request_template.md
│   ├── dependabot.yml
│   ├── CODEOWNERS
│   ├── instructions/
│   │   ├── copilot-instructions.md
│   │   ├── blazor.instructions.md
│   │   ├── git-commit-instructions.md
│   │   └── markdown.instructions.md
│   ├── test-debugging-unit.md           (Unit testing and debugging guide)
│   ├── test-debugging-integration.md    (Integration testing guide)
│   ├── test-debugging-e2e.md            (E2E testing with Playwright)
│   ├── SETUP_SUMMARY.md                 (Setup and debugging overview)
│   ├── agents/                          (Copied from source if available)
│   │   ├── solution-scaffolder.agent.md
│   │   ├── code-reviewer.agent.md
│   │   └── ...
│   ├── prompts/                         (Copied from source if available)
│   │   ├── code-review-checklist.md
│   │   ├── test-generation.md
│   │   └── ...
│   └── skills/                          (Copied from source if available)
│       ├── solution-scaffolder/
│       ├── nuget-manager/
│       ├── refactor/
│       └── ...
├── src/
│   ├── BlogEngine.Api/
│   ├── BlogEngine.Web/
│   ├── BlogEngine.Common/
│   ├── BlogEngine.Persistence/
│   └── BlogEngine.Features/
│       ├── Articles/
│       │   ├── CreateArticle/
│       │   │   ├── CreateArticleCommand.cs
│       │   │   ├── CreateArticleHandler.cs
│       │   │   ├── CreateArticleValidator.cs
│       │   │   └── CreateArticlePage.razor
│       │   ├── GetArticles/
│       │   │   ├── GetArticlesQuery.cs
│       │   │   ├── GetArticlesHandler.cs
│       │   │   └── ArticlesListComponent.razor
│       │   └── GetArticleById/
│       └── Comments/
│           ├── CreateComment/
│           └── GetComments/
├── tests/
│   ├── BlogEngine.Tests.Unit/
│   │   └── Features/Articles/
│   ├── BlogEngine.Tests.Integration/
│   │   └── Features/Articles/
│   ├── BlogEngine.Tests.Architecture/
│   ├── BlogEngine.Tests.Bunit/
│   │   └── Features/Articles/
│   └── BlogEngine.Tests.E2E/
├── docs/
│   ├── ARCHITECTURE.md
│   └── README.md
├── scripts/
│   └── setup.sh
├── .editorconfig
├── .gitignore
├── Directory.Build.props
├── Directory.Packages.props
├── global.json
├── BlogEngine.sln
├── NuGet.config
├── README.md
├── LICENSE.txt
└── CONTRIBUTING.md

Next Steps Provided

✅ Solution created successfully!

📦 Vertical Slice Architecture structure:
  - BlogEngine.Api: API entry point with minimal configuration
  - BlogEngine.Web: Blazor Server UI entry point
  - BlogEngine.Common: Shared abstractions, interfaces, extensions
  - BlogEngine.Persistence: Data access context, repositories, EF configuration
  - BlogEngine.Features: Business features organized in vertical slices
    - Each feature (Articles, Comments, Users) is self-contained
    - Includes Commands/Queries, Handlers, Validators, and Blazor components

🚀 Quick Start:
  1. cd BlogEngine
  2. dotnet restore
  3. dotnet build
  4. dotnet test
  5. dotnet run --project src/BlogEngine.Web

📚 Vertical Slice Architecture Guide:
  - Read docs/ARCHITECTURE.md for detailed structure overview
  - Each feature folder contains everything needed for that feature
  - Shared code goes in Common/ (interfaces, extensions, utilities)
  - Data layer stays in Persistence/ (DbContext, repositories)
  - New features: Create Features/{FeatureName}/{Operation}/ folders

🔐 Configure Auth0 in appsettings.json
🗄️  Set MongoDB connection string in appsettings.Production.json

Happy coding! 🎉

Copying From Source Repository

agents/, prompts/, and skills/ Folders

When scaffolding a new solution, the skill will automatically copy these folders from the source repository if they exist:

agents/ - Custom AI agents that extend Copilot's capabilities

• These agents automate complex workflows and analysis tasks
• Copied so new solutions inherit the same AI automation
• Examples: code reviewer, architecture analyzer, test generator

prompts/ - Pre-built prompt templates for consistent results

• Standardized prompts for common development tasks
• Ensures consistent AI-assisted workflows across projects
• Examples: code review checklists, test generation patterns, documentation templates

skills/ - Specialized Copilot skill modules

• Custom skills that solve project-specific problems
• Enable guided workflows for complex operations
• Examples: solution scaffolder (this skill), nuget manager, refactoring assistance

Copy Process

1. Detection: Skill checks if agents/, prompts/, and skills/ folders exist in source repository
2. Validation: Ensures folders contain valid .md or .agent.md files
3. Recursive Copy: Copies entire folder structures with all nested files
4. Preservation: Maintains original file structure and content exactly as-is
5. Reporting: Informs user what was copied (e.g., "Copied 3 agents, 5 prompts, 6 skills")

Benefits

✅ Immediate AI Assistance: New solutions start with all custom agents and skills
✅ Consistent Automation: All projects use the same AI-assisted workflows
✅ Knowledge Sharing: Team standards and practices built into every solution
✅ Easy Onboarding: New developers inherit proven patterns and tools
✅ Template Reuse: Prompt templates ensure consistent output quality

Example Copy Result

If the source repository has:

.github/agents/             (3 agents)
.github/prompts/            (5 prompts)
.github/skills/             (6 skills)

The new BlogEngine solution will have:

BlogEngine/.github/agents/   (Same 3 agents)
BlogEngine/.github/prompts/  (Same 5 prompts)
BlogEngine/.github/skills/   (Same 6 skills)

All ready to use immediately in the new solution.

Quality Checks

After scaffolding, verify:

1. ✅ All .csproj files compile without errors
2. ✅ All test projects reference correct test frameworks
3. ✅ No circular dependencies between projects
4. ✅ GlobalUsings.cs exists in each project
5. ✅ .editorconfig rules are consistent
6. ✅ README.md contains setup instructions
7. ✅ Package versions are consistent across projects

Limitations & Future Enhancements

Current Scope

• Creates .NET 10 solutions only
• Focuses on ArticlesSite patterns
• Interactive CLI-based generation only

Out of Scope (For Future)

• Visual Studio project template generation
• Web-based scaffolding UI
• Direct GitHub repository creation
• Automated CI/CD pipeline deployment

.github Folder Structure & Contents

Purpose

The .github folder contains all repository-level configuration, documentation, and automation. It ensures consistent workflows, clear contribution guidelines, and automated processes.

Folder Organization

.github/
├── workflows/              CI/CD pipelines and automated workflows
├── ISSUE_TEMPLATE/         Issue templates for bug reports and feature requests
├── pull_request_template.md PR submission guidelines
├── dependabot.yml          Automated dependency updates configuration
├── CODEOWNERS              Code ownership and review routing
├── instructions/           Coding standards and guidelines (solution-specific)
├── agents/                 Custom Copilot agents (if they exist)
├── prompts/                Copilot prompt templates (if they exist)
└── skills/                 Custom Copilot skills (if they exist)

Files & Their Purpose

workflows/ - Continuous Integration & Deployment

ci-cd.yml (If GitHub Actions selected)

• Builds the solution on push/PR
• Runs unit and integration tests
• Generates coverage reports
• Publishes to artifact registry or deployment environment

name: CI/CD
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-dotnet@v5
        with:
          global-json-file: global.json
      - run: dotnet restore
      - run: dotnet build
      - run: dotnet test --logger trx

code-quality.yml (If testing selected)

• Runs linters (.editorconfig validation)
• Performs static code analysis
• Checks code coverage thresholds
• Enforces style compliance

security-scan.yml (Optional)

• OWASP dependency scanning
• Secret detection
• Vulnerability scanning in NuGet packages

ISSUE_TEMPLATE/ - Issue & PR Templates

bug.md

---
name: Bug Report
about: Report a bug
---

## Description
Clear description of the bug.

## Steps to Reproduce
1. Step one
2. Step two

## Expected Behavior
What should happen.

## Actual Behavior
What actually happens.

## Environment
- OS: [e.g., Windows 11]
- .NET Version: 10.0

feature.md

---
name: Feature Request
about: Suggest a feature
---

## Feature Description
What should be added.

## Motivation
Why this is needed.

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

config.yml

blank_issues_enabled: false
contact_links:
  - name: Documentation
    url: https://github.com/yourorg/yourrepo/blob/main/README.md

pull_request_template.md - PR Description

Guides contributors on what to include in PRs:

## Description
Brief description of changes.

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Unit tests added
- [ ] Integration tests added
- [ ] Manual testing completed

## Checklist
- [ ] Code follows .editorconfig style
- [ ] Comments explain complex logic
- [ ] Documentation updated
- [ ] No new warnings introduced

dependabot.yml - Dependency Updates

Automated security and version updates:

version: 2
updates:
  - package-ecosystem: "nuget"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 5
    reviewers:
      - "devops-team"
    assignees:
      - "maintainer"

CODEOWNERS - Code Ownership Rules

Routes PRs to appropriate reviewers:

# Global
* @maintainer

# Feature teams
/src/MyWebApp.Features/Articles/ @articles-team
/src/MyWebApp.Features/Users/ @users-team
/src/MyWebApp.Persistence/ @data-team
/tests/ @qa-team

instructions/ - Coding Standards (Solution-Specific)

Customized versions of ArticlesSite guidelines:

copilot-instructions.md

• Technology stack requirements
• Architecture rules
• SOLID principles enforcement
• Naming conventions
• Security requirements
• Testing requirements

blazor.instructions.md (If Blazor UI selected)

• Blazor component structure
• State management patterns
• Performance optimization guidelines
• Event handling best practices

git-commit-instructions.md

• Commit message format
• Branch naming conventions
• Conventional commits (feat:, fix:, etc.)
• Squash/rebase policies

markdown.instructions.md

• Documentation formatting standards
• README structure
• Code example formatting
• Link validation rules

agents/ - Custom Copilot Agents

Contains custom AI agents for specialized tasks (copied from source repository if available):

Example agents:

• solution-scaffolder.agent.md - This agent for creating new solutions
• code-reviewer.agent.md - AI-powered code review assistant
• architecture-analyzer.agent.md - Architecture validation and analysis

Each agent file defines:

• Purpose and scope
• Available tools and capabilities
• Decision-making rules
• Interaction patterns

prompts/ - Copilot Prompt Templates

Pre-built prompt templates for common development tasks (copied from source repository if available):

Example prompts:

• code-review-checklist.md - Code review guidelines
• test-generation.md - Unit test generation patterns
• documentation-template.md - API documentation template
• refactoring-checklist.md - Refactoring best practices

Prompts can be invoked via Copilot CLI for consistent results.

skills/ - Custom Copilot Skills

Specialized skill modules extending Copilot capabilities (copied from source repository if available):

Example skills:

• solution-scaffolder/ - Create new solutions (this skill)
• nuget-manager/ - Manage NuGet packages
• test-migrator/ - Migrate tests to new frameworks
• refactor/ - Code refactoring assistance
• prd/ - Generate Product Requirements Documents

Each skill folder contains:

• SKILL.md - Skill definition, capabilities, and usage examples
• Optional supporting files or templates

Skills provide guided workflows for complex tasks.

What is Vertical Slice Architecture?

Instead of organizing code by technical layers (Controllers, Services, Repositories, Models), Vertical Slice Architecture organizes code by business features. Each feature is a "vertical slice" that contains everything needed to implement that feature—from the API endpoint down to the database query.

Key Benefits

• Feature Isolation: Changes to one feature don't affect others
• Easier Onboarding: New developers can understand an entire feature by looking at one folder
• Reduced Coupling: Features are loosely coupled; shared code is minimal and explicit
• Scalability: Easy to add new features without modifying existing ones
• Testing: Each feature can be tested independently
• Navigation: Developers spend less time jumping between folders

Project Organization

BlogEngine.Features/ Structure:

Features/
├── Articles/
│   ├── CreateArticle/              Command operation
│   │   ├── CreateArticleCommand.cs
│   │   ├── CreateArticleHandler.cs
│   │   ├── CreateArticleValidator.cs
│   │   └── CreateArticlePage.razor
│   ├── GetArticles/                Query operation (list)
│   ├── GetArticleById/             Query operation (single)
│   ├── UpdateArticle/              Command operation
│   └── DeleteArticle/              Command operation
├── Users/
│   ├── Register/
│   ├── Login/
│   └── GetProfile/
└── Comments/
    ├── CreateComment/
    ├── GetComments/
    └── DeleteComment/

BlogEngine.Common/ (Shared Code):

• Interfaces: IRepository<T>, IUnitOfWork, ICommand<T>, IQuery<T>
• Exceptions: Custom exceptions used across features
• Extensions: Utility methods, DI registration helpers
• Models: Shared enums, constants, validation rules

BlogEngine.Persistence/ (Data Layer):

• BlogEngineDbContext - Entity Framework DbContext
• Repository implementations
• Migration files
• MongoDB/SQL configurations

Naming Conventions for Features

Each operation folder follows this pattern:

• Commands (Write operations): CreateArticleCommand, UpdateArticleCommand, DeleteArticleCommand
• Queries (Read operations): GetArticlesQuery, GetArticleByIdQuery
• Handlers: CreateArticleHandler (implements ICommandHandler<CreateArticleCommand>)
• Validators: CreateArticleValidator (FluentValidation rules)
• Blazor Pages: CreateArticlePage.razor (Blazor page for the operation)
• Components: ArticlesListComponent.razor (Reusable component)

MediatR Integration

With MediatR, operations are dispatched as commands/queries:

// In API endpoint or Blazor component
var result = await mediator.Send(new CreateArticleCommand { Title = "...", Content = "..." });

// In the handler
public class CreateArticleHandler : ICommandHandler<CreateArticleCommand, ArticleDto>
{
    private readonly IRepository<Article> _repository;
    
    public async Task<ArticleDto> Handle(CreateArticleCommand request, CancellationToken cancellationToken)
    {
        var article = new Article { Title = request.Title, Content = request.Content };
        await _repository.AddAsync(article, cancellationToken);
        return article.ToDto();
    }
}

Test Organization

Tests mirror the feature structure:

tests/
├── BlogEngine.Tests.Unit/
│   └── Features/
│       ├── Articles/
│       │   ├── CreateArticleHandlerTests.cs
│       │   └── CreateArticleValidatorTests.cs
│       └── Users/
├── BlogEngine.Tests.Integration/
│   └── Features/Articles/ArticleRepositoryTests.cs
└── BlogEngine.Tests.Bunit/
    └── Features/Articles/CreateArticlePageTests.cs

This skill should:

1. Use interactive questions via the available agent tools (not plain text)
2. Validate all inputs before generating files
3. Create files using the repository's supported file-creation tools (for example, create_file) instead of shell commands
4. Run dotnet restore after scaffolding to verify
5. Provide clear, actionable next steps
6. Reference ArticlesSite instructions (copilot-instructions.md, blazor.instructions.md, etc.) as generation rules