Repo Analyser

Discovery Process

The Repo Analyser agent contains detailed discovery instructions. In summary, explore these areas:

1. Solution Overview — find *.sln and *.csproj files, note .NET version(s) and project types
2. Architecture Pattern — identify folder structure signals (Vertical Slice, Clean Architecture, Hexagonal, N-Tier, or mixed)
3. External Dependencies — scan PackageReference entries and config files for databases, message brokers, cloud services
4. Testing Approach — examine test projects, naming conventions, assertion libraries, mocking frameworks (read 3-5 actual test files)
5. Code Patterns — identify request handling, validation, error handling, mapping, and DI approaches (read 3-5 representative files)
6. Code Style — nullable refs, namespace style, primary constructors, record types, naming conventions
7. Anything Else Notable — custom base classes, domain-specific patterns, unusual structures

Output Format

Create .planning/CONVENTIONS.md using this template:

# Repository Conventions

> Generated by repo-analyser on {date}
> Review and adjust if needed. Re-run if conventions change significantly.

## Overview

| Aspect | Value |
|--------|-------|
| Solution | {name} |
| .NET Version | {version} |
| Architecture | {pattern or "unclear"} |
| Test Framework | {framework} |
| Key Packages | {e.g., FluentValidation 11.x, MediatR 12.x} |

## Architecture

{Description of the architectural pattern observed, with folder structure examples}

## Project Structure

{Folder tree with purpose annotations}

## External Dependencies

| Type | Technology | Notes |
|------|------------|-------|
| Database | {e.g., SQL Server via EF Core} | {any notes} |
| Messaging | {e.g., Azure Service Bus} | {any notes} |

## Testing Conventions

| Aspect | Convention |
|--------|------------|
| Framework | {xUnit/NUnit/MSTest} |
| Assertions | {FluentAssertions/Shouldly/built-in} |
| Mocking | {Moq/NSubstitute/none} |
| Test naming | {pattern} |
| Organisation | {description} |

### Example Test

{Actual test method from codebase showing naming and structure}

## Code Patterns

| Aspect | Pattern |
|--------|---------|
| Request handling | {MediatR/custom handlers/direct/etc.} |
| Validation | {FluentValidation/DataAnnotations/manual} |
| Error handling | {Result type/exceptions/etc.} |
| Mapping | {AutoMapper/Mapster/manual/extensions} |
| API style | {Controllers / Minimal APIs / mixed} |
| Data access | {Dapper raw / Dapper.Contrib / EF Core / mixed} |

### Example Handler/Service

{Simplified example from codebase showing typical structure}

### Example Error Handling

{Actual example showing Result<T> vs exception usage}

## Code Style

| Aspect | Convention |
|--------|------------|
| Nullable refs | {enabled/disabled} |
| Namespaces | {file-scoped/block-scoped} |
| Records | {used for X/not used} |
| Field naming | {_camelCase/other} |

## Notes

{Anything unusual, unclear, or worth highlighting}

---

## For Agents

**Critical rules when writing code in this repository:**

1. **Architecture:** Place new features in `{path pattern}` following {pattern}
2. **Error handling:** Use `{Result<T> | exceptions}` — see Example Error Handling above
3. **Test naming:** `{pattern}` — see Example Test above
4. **Assertions:** Use `{assertion library}` syntax
5. **New files:** Follow the folder structure in Project Structure above
6. **API style:** Use `{Controllers | Minimal APIs}` — see existing endpoints for reference
7. **Data access:** Use `{Dapper pattern}` — see existing repositories/queries for reference

After Generation

1. Briefly summarise what was discovered
2. Highlight anything ambiguous that might need human clarification
3. The file is ready for agents to reference