Add ARCHITECTURE.md documenting internal design and processing flows

.github/agents/documentation-writer.md

@@ -48,12 +48,15 @@ update, and maintain high-quality documentation that is clear, accurate, and hel
 ### Documentation Content
 
 - **README.md**: Keep concise and focused on getting started quickly
+- **ARCHITECTURE.md**: Comprehensive guide to the tool's architecture and internal workings (reference this when
+  explaining how the tool works)
 - **Code Examples**: Use proper YAML formatting for requirement examples
 - **CLI Usage**: Document all command-line options and arguments
 - **API Documentation**: Use clear descriptions and examples
 
 ### Technical Accuracy
 
+- Review ARCHITECTURE.md for understanding the tool's behavior and internal design
 - Verify all code examples work correctly
 - Test CLI commands before documenting them
 - Keep documentation synchronized with code changes

.github/agents/project-maintainer.md

@@ -67,6 +67,7 @@ Located in `.github/workflows/`:
 - **`.yamllint.yaml`**: YAML linting rules
 - **`.config/dotnet-tools.json`**: Dotnet tools manifest
 - **`DemaConsulting.ReqStream.sln`**: Solution file
+- **`ARCHITECTURE.md`**: Comprehensive architecture documentation (reference for understanding tool behavior)
 
 ### Quality Standards
 

.github/agents/software-quality-enforcer.md

@@ -85,6 +85,13 @@ Based on `.editorconfig` and project preferences:
   - EnforceCodeStyleInBuild enabled
   - AnalysisLevel set to latest
 
+### Architecture Understanding
+
+- **ARCHITECTURE.md**: Contains comprehensive guide to the tool's architecture and internal workings
+  - Review this document to understand the data model, processing flows, and design decisions
+  - Reference when reviewing changes to ensure they align with the architectural patterns
+  - Use when providing feedback about implementation choices
+
 ### Test Requirements
 
 - **Test Framework**: MSTest (Microsoft.VisualStudio.TestTools.UnitTesting)

AGENTS.md

@@ -12,6 +12,10 @@ updated as agents are configured for this repository.
 ReqStream is a .NET command-line tool for managing requirements written in YAML files. It provides functionality to
 create, validate, and manage requirement documents in a structured and maintainable way.
 
+For detailed information about the architecture and internal workings of ReqStream, see [ARCHITECTURE.md][architecture].
+This document provides comprehensive coverage of the data model, requirements processing flow, trace matrix
+construction, and test coverage enforcement mechanisms.
+
 ### Technology Stack
 
 - **Language**: C# 12
@@ -40,6 +44,7 @@ ReqStream/
 ├── .markdownlint.json            # Markdown linting rules
 ├── .yamllint.yaml                # YAML linting rules
 ├── AGENTS.md                     # This file
+├── ARCHITECTURE.md               # Architecture documentation
 ├── LICENSE                       # MIT License
 └── README.md                     # Project documentation
 ```
@@ -51,6 +56,7 @@ ReqStream/
 - **`.markdownlint.json`**: Markdown linting rules
 - **`.yamllint.yaml`**: YAML linting rules
 - **`DemaConsulting.ReqStream.sln`**: Solution file containing all projects
+- **`ARCHITECTURE.md`**: Comprehensive guide to the tool's architecture and internal design
 
 ## Testing Guidelines
 
@@ -209,3 +215,5 @@ As the project grows, we may add additional custom agents for:
 
 If you have suggestions for custom agents that would benefit this project, please open an issue or submit a pull
 request.
+
+[architecture]: ARCHITECTURE.md