Added agents.md

[alexeyzimarev]

PR Type

Documentation

---

Description

• Added comprehensive AI agent context document for Eventuous

• Covers repository structure, core concepts, and architecture patterns

• Includes development practices, common workflows, and key packages

• Provides important notes and resources for AI agents working with codebase

---

Diagram Walkthrough

flowchart LR
  A["agents.md<br/>Documentation"] --> B["Repository<br/>Overview"]
  A --> C["Project<br/>Structure"]
  A --> D["Core<br/>Concepts"]
  A --> E["Development<br/>Practices"]
  D --> F["Aggregates"]
  D --> G["Command<br/>Services"]
  D --> H["Event Store<br/>Abstractions"]
  E --> I["Testing &<br/>Building"]
  E --> J["Contributing<br/>Guidelines"]

Loading

File Walkthrough

Relevant files

Documentation

agents.md Comprehensive AI agent context documentation                          agents.md Created new comprehensive documentation file for AI agents working with Eventuous Documented repository structure with detailed component organization Explained core concepts including Aggregates, State, Command Services (both aggregate-based and functional), Event Store abstractions, Subscriptions, Producers, and Gateway Listed all key NuGet packages with their purposes Outlined development practices, code style, testing approaches, and contribution guidelines Provided architecture patterns overview covering Event Sourcing, CQRS, and Domain-Driven Design Included common workflows for creating aggregates, command services, event handlers, and subscriptions Added important notes for AI agents regarding breaking changes, deprecated APIs, stream naming, type mapping, and testing frameworks Provided file naming conventions and related resources +346/-0

---

[qodo-free-for-open-source-projects]

PR Compliance Guide 🔍

(Compliance updated until commit 73d356a)

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
🟢	No codebase code duplication found No new components were introduced in the PR code
Custom Compliance
🟢	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Passed Learn more about managing compliance generic rules or creating your own custom rules

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

---

Previous compliance checks

Compliance check up to commit da632cf

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
🟢	No codebase code duplication found No new components were introduced in the PR code
Custom Compliance
🟢	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Passed Learn more about managing compliance generic rules or creating your own custom rules

[qodo-free-for-open-source-projects]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Automate context file generation The manually created agents.md file will quickly become outdated. It is recommended to create a script that automatically generates this file by introspecting the source code to ensure the context provided to AI agents remains accurate. Examples: agents.md [1-346] # Eventuous - AI Agent Context ## Repository Overview **Eventuous** is a production-grade Event Sourcing library for .NET that provides abstractions and implementations for building event-sourced systems following Domain-Driven Design (DDD) tactical patterns. - **Primary Language:** C# - **Target Frameworks:** .NET 10, 9, and 8 - **License:** Apache 2.0 - **Copyright:** Eventuous HQ OÜ ... (clipped 336 lines) Solution Walkthrough: Before: # agents.md (Manual creation) # Eventuous - AI Agent Context ## Project Structure eventuous/ ├── src/ │ ├── Core/ │ │ ├── src/ │ │ │ ├── Eventuous.Domain/ ... (content is manually written and maintained) ## Core Concepts ### 1. Aggregates **Location:** `src/Core/src/Eventuous.Domain/Aggregate.cs` ```csharp public abstract class Aggregate<T> where T : State<T>, new() #### After: ```markdown # build_context_script.py (Conceptual) def get_project_structure(): # Use `tree` or `os.walk` to generate directory listing return ... def get_core_concepts(): # Use AST parsing or regex on source files # to find key classes like 'Aggregate' and get their signatures. return ... def generate_markdown_file(): structure = get_project_structure() concepts = get_core_concepts() # ... gather other info automatically # Render a template with the collected data render_template("agents.md.jinja", structure, concepts) generate_markdown_file() Suggestion importance[1-10]: 9 __ Why: The suggestion correctly identifies the critical long-term maintenance burden of a manual agents.md file and proposes a robust automated solution, which is essential for keeping the AI context accurate and reliable.	High
General	Correct the PostgreSQL package name Correct the PostgreSQL package name from Eventuous.Postgresql to Eventuous.Postgres in the "Key Packages" table for consistency with the project structure. agents.md [201-202] -| `Eventuous.Postgresql` | PostgreSQL support | +| `Eventuous.Postgres` | PostgreSQL support | | `Eventuous.SqlServer` | SQL Server support | Apply / Chat Suggestion importance[1-10]: 5 __ Why: The suggestion correctly identifies and fixes an inconsistency between the project structure diagram (line 32) and the package list regarding the PostgreSQL package name, improving the document's accuracy.	Low
Update