|
| 1 | +# Agent Instructions for Codebelt.Extensions.Swashbuckle.AspNetCore |
| 2 | + |
| 3 | +This document provides guidance for AI agents working in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +Codebelt.Extensions.Swashbuckle.AspNetCore is a suite of .NET libraries providing uniform, opinionated, and extensible APIs for Swagger and OpenAPI documentation with ASP.NET Core. The solution targets .NET 10.0 and .NET 9.0. It includes: |
| 8 | + |
| 9 | +- **Codebelt.Extensions.Swashbuckle.AspNetCore** — Core extensions for Swagger/OpenAPI generation, customization, and configuration with ASP.NET Core. |
| 10 | +- **Codebelt.Extensions.Swashbuckle.AspNetCore.ModelContextProtocol** — Model Context Protocol (MCP) integration for Swagger/OpenAPI documentation discovery and tooling. |
| 11 | + |
| 12 | +## Coding Standards |
| 13 | + |
| 14 | +- **Text encoding:** UTF-8 for text files (enforced via `.editorconfig`) |
| 15 | +- **Template rewrites:** Preserve UTF-8 explicitly when scripts or tools rewrite text files; avoid locale-dependent encoding defaults |
| 16 | +- **Namespaces:** File-scoped namespaces are required (enforced via `.editorconfig`) |
| 17 | +- **Top-level statements:** Not allowed (enforced via `.editorconfig`) |
| 18 | +- **Language version:** Always use the latest C# features (`LangVersion=latest`) |
| 19 | +- **Nullable:** Enable nullable reference types in all new code |
| 20 | +- **XML documentation:** All public APIs must have XML documentation comments |
| 21 | +- **Testing:** Use xUnit v3 with Codebelt.Extensions.Xunit.App base classes |
| 22 | + |
| 23 | +## Project Structure |
| 24 | + |
| 25 | +- `src/` — Production source code |
| 26 | + - `Codebelt.Extensions.Swashbuckle.AspNetCore/` — Core Swagger/OpenAPI extensions and ASP.NET Core integration |
| 27 | + - `Codebelt.Extensions.Swashbuckle.AspNetCore.ModelContextProtocol/` — Model Context Protocol (MCP) integration |
| 28 | +- `test/` — Unit and functional tests (project names end with `Tests` or `FunctionalTests`) |
| 29 | +- `tooling/` — Development tools and example applications |
| 30 | +- `.nuget/` — Per-package NuGet metadata (icon, README, release notes) |
| 31 | +- `.docfx/` — DocFX documentation configuration |
| 32 | +- `.github/` — CI/CD workflows, contributing guidelines, Copilot instructions |
| 33 | + |
| 34 | +## Test Conventions |
| 35 | + |
| 36 | +- Test project names must end with `Tests` (unit tests) or `FunctionalTests` (integration/functional tests) |
| 37 | +- Test classes should inherit from the `Test` base class in `Codebelt.Extensions.Xunit` |
| 38 | +- Use `Microsoft.Testing.Platform` as the test runner (`UseMicrosoftTestingPlatformRunner=true`) |
| 39 | +- All tests are executable (`OutputType=Exe`) |
| 40 | +- Test namespaces must match the SUT namespace (System Under Test), without `.Tests` or `.FunctionalTests` suffix |
| 41 | +- See `.github/copilot-instructions.md` for detailed test writing guidelines |
| 42 | + |
| 43 | +## Build & CI |
| 44 | + |
| 45 | +- Centralized package versions via `Directory.Packages.props` |
| 46 | +- Resolve new or updated `Directory.Packages.props` versions from NuGet.org and keep them on the latest stable listed releases |
| 47 | +- Centralized build configuration via `Directory.Build.props` |
| 48 | +- MinVer for semantic versioning from Git tags |
| 49 | +- Strong-name signing is enabled in CI environments (`CI=true`) |
| 50 | +- Keep `.github/dependabot.yml` enabled at the repo root so central NuGet package management stays current |
| 51 | + |
| 52 | +## .bot/ Folder |
| 53 | + |
| 54 | +If a `.bot/` folder exists at the root, it contains **confidential, local-only** working material for AI agents — product requirement documents (PRDs), design proposals, agentic loop state, and brainstorming outputs. This folder is gitignored and never committed. |
| 55 | + |
| 56 | +When starting creative or design work (new features, architecture decisions, PRD drafts), use the [brainstorming skill](https://skills.sh/obra/superpowers/brainstorming) and save outputs to `.bot/`. Only move finalized, non-confidential instructions into `AGENTS.md` or `.github/copilot-instructions.md`. |
| 57 | + |
| 58 | +## Git Operations Safeguards |
| 59 | + |
| 60 | +Agents must never automatically commit code changes or push to remote repositories. Both actions require explicit user approval: |
| 61 | + |
| 62 | +- **Commits**: Always request confirmation from the user before staging and committing code. Present a clear summary of the changes and wait for approval before executing the commit. |
| 63 | +- **Remote Operations**: Do not push, pull, fetch, or interact with `origin` or any remote repository without explicit user instruction. These operations modify repository history and can cause data loss if performed unexpectedly. |
| 64 | + |
| 65 | +**Rationale:** Automatic commits can clutter history with incomplete work, temporary debugging code, or unintended changes. Unexpected remote operations risk overwriting or losing commits on shared branches. Always require explicit user approval before performing these actions. |
| 66 | + |
| 67 | +## Official Documentation |
| 68 | + |
| 69 | +- Public API conventions belong in `.docfx/api/namespaces/` and should be treated as the official documentation source for library behavior and naming vocabulary. |
| 70 | +- When adding or renaming public APIs, update the relevant namespace page in `.docfx/api/namespaces/` if the change introduces or clarifies a convention. |
| 71 | +- Keep internal reasoning, exploratory notes, and agent discussion out of DocFX pages; summarize only stable public guidance. |
![codebelt-aicia[bot]](https://avatars.githubusercontent.com/in/2887840?v=4&size=40){kind=avatar}
0 commit comments