Knowledge Base

The common/ directory contains the architectural knowledge — the rules and patterns that agents reference when making decisions.

Structure

common/
├── rules/                 # Coding conventions
│   ├── architecture.md    # File structure, naming, async patterns, warnings
│   ├── ci-cd.md           # GitHub Actions, .NET CI, secrets
│   └── commit-conventions.md
├── architecture/          # Architectural patterns
│   ├── modular-monolith-principles.md   # P1-P8 non-negotiable principles
│   ├── layer-dependency-rules.md        # Allowed/forbidden reference matrix
│   ├── cross-module-communication.md    # Commands, queries, events via Wolverine
│   ├── anti-patterns.md                 # Patterns to reject
│   ├── cross-cutting-concerns.md        # Multi-tenancy, GDPR, audit, idempotency
│   ├── validation-patterns.md           # Three-tier validation composition
│   └── read-model-patterns.md           # Marten projections, PG views, reporting
├── technology/            # Technology-specific rules
│   ├── efcore.md          # EF Core configuration, explicit IEntityTypeConfig
│   ├── marten.md          # Document store, event store, projections
│   ├── wolverine.md       # Handler isolation, cascading messages, outbox
│   ├── fluentresults.md   # Result pattern for expected failures
│   ├── fluentvalidation.md # Three-tier validators
│   ├── vogen-ids.md       # Vogen-wrapped ULID entity IDs
│   ├── testcontainers.md  # Real infrastructure in tests
│   ├── smartenum.md       # Localizable enums with behavior
│   ├── ardalis-specification.md  # Query/repository encapsulation
│   ├── localization.md    # Source-generated C# localization
│   └── host-infrastructure.md   # Aspire, TickerQ, Serilog, Sentry, Scalar, Redis
└── layers/                # Layer-specific rules
    ├── shared-layer.md    # Public surface, constraints, validators
    ├── domain-layer.md    # Business logic, aggregates, specifications
    ├── application-layer.md  # Handlers, handler isolation, cascading messages
    └── infrastructure-layer.md  # Isolated infra, multi-instance schemas

How Agents Use the Knowledge Base

Each agent’s system prompt includes ## Reference Documents listing which files to read for context. For example:

The Software Architect reads modular-monolith-principles.md and layer-dependency-rules.md when designing modules
The Backend Developer reads common/layers/ files when implementing code
The Reviewer reads anti-patterns.md when checking for violations