🧠 Code Reviewer Agent Specification

🎯 Purpose

The Code Reviewer Agent is an autonomous validation persona designed to ensure that all code entering the ConnectSoft ecosystem adheres to:

• ✅ Business requirements
• 🧠 Engineering best practices
• 🧱 Architectural boundaries
• 🔒 Security constraints
• 🧪 Test and observability requirements
• 🧾 Platform conventions and traceability policies

It reviews code before or during pull request evaluation, acting as the final automated gate before code promotion, deployment, or human QA escalation.

---

🧭 Strategic Factory Role

The agent is positioned after the Pull Request Creator Agent and before final commit or CI/CD triggering. It performs:

• 🔍 Semantic, structural, and functional review
• 📊 Pattern enforcement for DDD, Clean Architecture, and framework usage
• 🔒 Security and compliance scanning
• 📡 Telemetry + observability coverage checks
• 🧾 Code traceability validation (e.g., trace_id, metadata)

---

🧩 Agent Mesh Integration

flowchart TD
    Dev[Backend/Frontend Developer Agents]
    Commit[Code Committer Agent]
    PR[Pull Request Creator Agent]
    CR[🧠 Code Reviewer Agent]
    Orchestrator[⚙️ Deployment Orchestrator]
    HumanQA[👤 HumanOps Agent]

    Dev --> Commit --> PR --> CR
    CR -->|Pass| Orchestrator
    CR -->|Fail| HumanQA

Hold "Alt" / "Option" to enable pan & zoom

---

🔗 Downstream Influence

Triggered System	Action
✅ CI/CD Pipelines	Allow auto-merge and deploy if review passes
❌ QA Review System	Escalate for manual validation if agent detects risk
🧪 Test Generator Agent	May trigger re-generation of missing test coverage
📢 Developer Notifications	Posts inline PR comments or summary review documents

---

🔐 Governance Alignment

This agent is responsible for ensuring that code:

• ❗ Does not violate Clean Architecture boundaries
• 🔌 Uses port/adapters correctly
• 📦 Is correctly structured (e.g., modular layout, proper test separation)
• 🔒 Complies with security baseline (e.g., secrets management, auth checks)
• 📄 Includes observability instrumentation where required (OpenTelemetry spans)

---

🧾 Agent Objective Summary

Area	Description
📘 Reviews	Full code review across all changed files
🔁 Context-Aware	Understands related requirements, tech stack, edition constraints
📡 Trace-Aware	Tracks trace_id, metadata references, blueprint lineage
❌ Blocks	Any code that fails standard, safety, or traceability rules
📬 Notifies	Developers, Committer Agent, HumanOps Agent as needed

---

🧠 Summary

The Code Reviewer Agent:

“Acts as the final automated quality guardian for every pull request in the ConnectSoft Software Factory — verifying architectural integrity, security, observability, and coding standards before integration and deployment.”

It guarantees that every line of code merged into the platform is review-validated, trace-labeled, and aligned with ConnectSoft’s multi-agent standards.

---

📌 Core Responsibilities

The Code Reviewer Agent performs a deep, autonomous review of submitted code to ensure all contributions are:

• ✅ Technically correct
• 🧠 Architecturally compliant
• 🔒 Security-hardened
• 🧾 Trace-aware and test-covered
• 🧩 Integrated cleanly into the multi-agent codebase

Its role is not just to "lint code" — it evaluates intent, structure, traceability, and maintainability in the context of ConnectSoft’s Clean Architecture and domain-driven design (DDD) principles.

---

🔧 Core Responsibilities

Category	Description
🧱 Architecture Enforcement	Ensure proper use of Clean Architecture (domain, application, port, adapter, UI boundaries). Detect violations like UI referencing infrastructure or direct access to persistence layers.
🧠 Requirement Alignment	Cross-check business logic and structure against requirement.md and blueprint context. Validate that expected use cases are covered.
🔌 Port/Adapter Validation	Confirm that services are accessed only through interfaces. Reject code with direct API, DB, or external access from presentation layers.
🧪 Test Coverage Checks	Validate presence and scope of unit and integration tests. Check test logic coverage for public methods and edge cases.
🔒 Security Rule Review	Identify secrets in code, missing auth guards, insecure serialization, or improper permission checks. Validate use of vaults and safe defaults.
📡 Observability Enforcement	Ensure telemetry spans (OpenTelemetry) are injected into services and user-interaction points. Detect missing ActivitySource, trace ID propagation.
🧾 Traceability & Metadata	Validate that all files/components are tagged with trace_id, execution_id, and agent_origin. Reject anonymous outputs.
🔄 Edition & Feature Flag Logic	Check that multi-tenant logic is encapsulated. Ensure edition switches do not leak across unrelated areas.
📄 Structural & Naming Consistency	Verify correct folder layout, naming conventions, file modularity, and file-level separation (e.g., one public class per file).
🔁 Suggest Improvements	Propose better abstractions, performance optimizations, or pattern corrections when code is functionally correct but suboptimal.
🧪 Code Style & Lint Review	Optionally run linters and formatters; enforce naming patterns and spacing unless auto_format: true is specified in input.
📬 Inline PR Comments (Optional)	If integrated into GitHub/GitLab, emit review comments inline for critical issues, warnings, or suggestions.

---

🔁 Temporal Responsibilities by Review Stage

Phase	Activity
🔍 Pre-Review	Parse file diffs, trace prompt context, load related design/architecture inputs
🧪 In-Review	Execute all review skills: structural, semantic, security, traceability
📘 Post-Review	Emit review summary, flag pass/fail status, publish comments or generate diagnostics artifact

---

🧠 Role Expansion (Optional)

• Feedback loop: Suggest structural refactors to Architect Agents
• Learning role: Observe patterns and build heuristics for future pattern validation (via vector memory)

---

✅ Summary

The Code Reviewer Agent is responsible for:

• 🔍 Deep review of code changes using architectural, security, and DDD principles
• ✅ Validating every PR before merging into the ConnectSoft platform
• 🔁 Suggesting improvements, corrections, or failing unsafe contributions
• 🧠 Acting as the AI equivalent of a senior staff engineer performing enterprise-level code reviews

This agent guarantees that every commit is safe, clean, structured, traceable, observable, and maintainable.

---

📥 Input Channels and Artifacts

The Code Reviewer Agent needs more than just code diffs. It must ingest technical context, blueprint lineage, traceability metadata, and requirements to understand what is being reviewed and how it fits within the platform’s architecture and standards.

---

📦 Core Inputs

Input	Source	Description
code-diff.json	Pull Request Creator Agent	Parsed file-level diff (additions, deletions, file metadata, line numbers)
trace-context.yaml	Orchestrator / Blueprint	Identifies trace_id, execution_id, component, and agent origin
requirement.md	Vision Agent / Business Context	Description of functional and non-functional requirements this code addresses
blueprint.md	Solution / Application Architect Agent	High-level design document, interfaces, business rules, and boundaries
architecture-context.yaml	Architect Agents	Lists layered structure, allowed dependencies, DDD rules (e.g., domain must not reference infrastructure)
test-report.json	Test Generator Agent	Summarized or raw test output results (optional during review pass)
security-policy.yaml	Security Engineer Agent	Defines vault usage, allowed packages, secret patterns, encryption/hashing rules
telemetry-rules.yaml	Observability Agent	Declares required telemetry injection points and span formatting
metadata.json	Any Developer Agent	Describes origin of component or service, expected usage, tags (trace_id, edition, agent_origin)
project-structure.snapshot	Repository Scanner	File/folder layout + namespace/class declarations for full picture validation

---

🧠 Semantic Kernel Context Injection

{
  "trace_id": "trace-pr-340",
  "execution_id": "exec-code-review-340",
  "component": "BillingService",
  "review_type": "pull_request",
  "code_changed": ["InvoiceHandler.cs", "InvoiceMapper.cs", "InvoiceHandler.test.cs"],
  "requirement_ref": "requirement-billing-21",
  "architecture_model": "CleanArchitecture",
  "framework": ".NET Core 8"
}

This injection allows the agent to resolve framework-level rules, validate file modularity, and choose appropriate review strategies.

---

🧾 Optional Inputs (Based on Config)

Input	Purpose
visual-diff.html	Enables UI diff validation (frontend PRs)
coverage-report.xml	Validates test coverage targets
pr-description.md	Consumed to check that PR rationale aligns with requirements
feature-flags.json	Injected if reviewing multi-edition or toggleable logic
custom-ruleset.yaml	Enables tenant-specific coding policies, naming, annotations

---

📘 Example Input File Set for a Review

/review-inputs/
  ├── code-diff.json
  ├── trace-context.yaml
  ├── requirement.md
  ├── blueprint.md
  ├── security-policy.yaml
  ├── architecture-context.yaml
  ├── telemetry-rules.yaml
  ├── metadata/
  │   ├── InvoiceHandler.metadata.json
  │   └── InvoiceMapper.metadata.json
  ├── test-report.json
  └── pr-description.md

---

🧠 Inferred Context

The agent infers additional context based on:

• component and trace_id to locate domain boundaries
• Git diff patterns to identify possible architectural violations
• Metadata fields to determine which agent originally created a file or service

---

✅ Summary

The Code Reviewer Agent consumes:

• 📄 Code diffs + structural metadata
• 🧠 Requirement and architectural overlays
• 🔐 Security and observability rules
• 🧩 Cross-agent metadata including origin and traceability
• 🧪 Test results and file structure snapshots

This input scope enables the agent to perform deep, trace-aware, and standards-aligned code reviews in a fully autonomous but audit-capable fashion.

---

📤 Output Deliverables

The Code Reviewer Agent produces traceable, structured, and machine- or human-readable outputs for:

• Developers (inline and summary feedback)
• Other agents (commit approval, test re-trigger, orchestration coordination)
• Auditors (diagnostic logs, validation results)
• Orchestration layer (pass/fail gating)

---

📦 Core Outputs

Output	Format	Description
review-summary.json	JSON	Structured result of review: status, score, risk level, violations, recommendations
review-comments.yaml	YAML	Optional inline comments mapped to line number, file, severity, and suggestion
validation-report.json	JSON	Diagnostic checks against architecture, telemetry, test coverage, security rules
code-review-events.json	JSON	Events emitted to orchestration, e.g., CodeReviewPassed, CodeReviewFailed
suggested-refactor.patch	Git diff	Optional patch file with suggested improvements or fixes
trace-index.yaml	YAML	Per-file metadata including trace_id, author agent, execution ID, origin
review-log.md	Markdown	Human-readable, styled summary of the review (for audit trail or GitHub PR comment)

---

🧠 Output Breakdown

✅ Review Summary

{
  "trace_id": "trace-pr-340",
  "component": "BillingService",
  "review_status": "fail",
  "score": 72,
  "risk_level": "medium",
  "violations": 3,
  "recommendations": 2,
  "required_changes": [
    "Inject IInvoiceRepository via port interface",
    "Add test coverage for edge case: zero balance invoices"
  ]
}

---

🧩 Review Comments

- file: InvoiceHandler.cs
  line: 27
  severity: error
  issue: "Direct call to database context detected"
  suggestion: "Use injected IInvoiceRepository port"
- file: InvoiceMapper.cs
  line: 12
  severity: info
  issue: "Missing OTEL span on DTO transformation"
  suggestion: "Inject trace span: 'invoice.mapper.transform'"

Can be posted to GitHub/GitLab via orchestrator webhook or PR comment integration.

---

📄 Validation Report Example

{
  "architecture": "CleanArchitecture",
  "violations": [
    { "type": "layer_violation", "from": "UI", "to": "Infrastructure" },
    { "type": "missing_trace_metadata", "file": "InvoiceService.cs" }
  ],
  "security": {
    "secrets_found": false,
    "unsafe_package_used": false
  },
  "observability": {
    "spans_missing": ["InvoiceHandler.cs"],
    "span_compliance": "partial"
  }
}

---

📬 Emitted Events

Event	Payload
CodeReviewPassed	{ trace_id, component, reviewer, timestamp, commit_sha }
CodeReviewFailed	{ trace_id, reason, failed_checks, reviewer }
RefactorSuggested	{ diff_url, suggestion_count, trace_id }

---

🧠 Patch File (Optional)

- return _context.Invoices.ToList();
+ return _invoiceRepository.GetAll();

When a simple fix is inferable, the agent can generate a .patch file for developer approval.

---

📘 Human-Friendly Markdown Summary

## 🔍 Code Review Summary — BillingService

**Status:** ❌ Failed  
**Trace ID:** `trace-pr-340`  
**Score:** 72/100  
**Issues:**  
- Direct use of DbContext in handler  
- Missing telemetry in mapper  
- Undocumented route in API service

✅ Recommendations available in `suggested-refactor.patch`.

---

📁 Output Folder Example

/code-review/
  ├── review-summary.json
  ├── validation-report.json
  ├── review-comments.yaml
  ├── review-log.md
  ├── suggested-refactor.patch
  └── trace-index.yaml

---

✅ Summary

The Code Reviewer Agent emits:

• 🧠 Structured, traceable review artifacts
• 📢 Events for coordination and orchestration decisions
• 🧾 Logs, diagnostics, and refactors for audit and improvement
• 🧩 Inline guidance when configured with Git integration

These outputs enable the ConnectSoft factory to automate high-quality, architecture-aware code review gates while maintaining auditability and developer feedback loops.

---

📚 Knowledge Base

The Code Reviewer Agent must reason about much more than syntax and style. Its embedded knowledge base allows it to:

• Understand Clean Architecture and DDD constraints
• Validate semantic alignment with business requirements
• Detect violations in structure, layering, and contracts
• Enforce traceability, telemetry, and compliance standards
• Offer meaningful refactoring suggestions across .NET and frontend stacks

---

🧠 Core Knowledge Domains

Domain	Description
🧱 Clean Architecture Ruleset	Recognizes layers: Domain, Application, Ports, Adapters, Infrastructure, and enforces allowed dependencies (e.g., UI must not reference Infrastructure).
📐 ConnectSoft Engineering Standards	Familiar with naming conventions, folder structure rules, file boundaries, test separation, telemetry injection, Git commit structure, and metadata standards.
🧠 Domain-Driven Design Patterns	Understands aggregates, entities, value objects, domain services, application services, and event-driven patterns.
🔐 Security Best Practices	Applies static analysis rules: validate absence of plaintext secrets, validate vault-based secrets usage, check for insecure token/crypto practices.
📡 Observability Standards	Knows OpenTelemetry API usage (ActivitySource, trace propagation), required span injection for APIs, services, and user-visible actions.
🧪 Test Coverage Requirements	Internal matrix for test coverage per file type (e.g., service = 90%, controller = 100% if exposed), enforces test stub presence.
🔄 Pull Request Heuristics	Tracks known risk patterns: large unreviewed diffs, undocumented changes, missing tests in high-risk modules.
🔎 Cognitive Complexity Metrics	Uses internal heuristics to flag functions that are too large, deeply nested, or poorly modularized.

---

🧩 Reference Standards Used

Source	Coverage
✅ connectsoft-architecture-rules.yaml	Layer dependencies, naming rules
✅ connectsoft-security-guide.md	Secrets, crypto, auth, OIDC integration
✅ connectsoft-observability.yaml	Required span types, injection points, severity
✅ clean-architecture-reference.md	DTO boundaries, mapping rules, allowed circular dependencies
✅ agent-templates/*	Code generated by Developer Agents used as baselines for expected layout and patterns
✅ traceability-schema.json	Metadata requirements, naming consistency, trace_id propagation
✅ feature-flag-handling-guide.md	How to implement edition/tenant switches securely and modularly

---

🧠 LLM-Embedded Heuristics (Semantic Memory)

The agent has internal prompt-trained heuristics for:

• Detecting violations in hexagonal, clean, or onion architectures
• Inferring whether a service is overstepping its domain (e.g., logic in controller)
• Recognizing anti-patterns like “anemic models”, static utility bloat, duplicate code
• Offering micro-refactor advice for repositories, command handlers, test fixtures

These are not rule-based — they are reasoned via LLM tokens augmented with architectural constraints.

---

🔁 Continual Knowledge Expansion

• Every validated refactor, reviewer override, or human correction is logged
• Vector memory stores prior examples (e.g., "PRs that failed due to missing telemetry")
• Over time, the agent improves alignment to real-world review exceptions and tolerances

---

🧠 Skills That Leverage This Knowledge

• ArchitectureViolationDetectorSkill
• SecurityMisuseScannerSkill
• ObservabilityCoverageSkill
• TraceabilityValidatorSkill
• DomainEncapsulationLinterSkill
• CrossLayerUsageHeuristicSkill

These Semantic Kernel functions allow the agent to use knowledge like an experienced human architect.

---

✅ Summary

The Code Reviewer Agent has an embedded knowledge base that includes:

• 🧠 Clean Architecture rules
• 🔐 Security practices
• 📡 Observability requirements
• 🧱 DDD and structural correctness
• 🧪 Test coverage expectations
• 📘 ConnectSoft-specific policies

This knowledge allows it to perform reviews at the same depth and discipline as a principal engineer or architect — but at full automation scale.

---

🔁 Process Flow

The Code Reviewer Agent transforms pull request input bundles and architectural context into structured review reports, inline diagnostics, and event triggers.

The agent’s flow is strictly orchestrated to ensure:

• 🧠 Context is resolved before inspection
• ✅ Architectural, semantic, security, and trace rules are applied
• 📘 Feedback is generated in structured and human-readable formats
• 📡 Resulting events are emitted to orchestrator and commit agents

---

🧭 Process Flow Diagram

flowchart TD
    A[Receive Pull Request Input Bundle]
    B[Resolve Architecture + Requirement Context]
    C[Parse Code Diff + Metadata]
    D[Run Layered Review Passes]
    E[Validate Traceability + Test Coverage]
    F[Assess Observability + Telemetry Spans]
    G[Aggregate Issues and Suggestions]
    H[Emit Review Summary + Diagnostics]
    I[Trigger Events or Escalation]

    A --> B --> C --> D --> E --> F --> G --> H --> I

Hold "Alt" / "Option" to enable pan & zoom

---

🔬 Step-by-Step Breakdown

1️⃣ Input Initialization

• Ingest:
  • code-diff.json
  • architecture-context.yaml
  • requirement.md
  • security-policy.yaml
• Extract:
  • trace_id, component, framework, origin agent
  • Changed files and commit metadata

---

2️⃣ Architectural Context Resolution

• Load Clean Architecture or Hexagonal model
• Map layers of all modified files (UI, Application, Domain, Adapter, Infrastructure)
• Initialize allowed dependencies graph

---

3️⃣ Semantic & Structural Review Pass

• Run:
  • ArchitectureViolationDetectorSkill
  • DomainEncapsulationSkill
  • LayerInteractionHeuristicSkill
• Check file/folder boundaries, DTO flow, method size, dependency injection usage

---

4️⃣ Traceability Validation

• Ensure every file contains:
  • trace_id, execution_id, agent_origin
• Check that outputs are metadata-linked (e.g., metadata.json)
• Detect accidental anonymous contributions

---

5️⃣ Test Coverage Review

• Cross-check test coverage for changed services/components
• Validate:
  • Unit test presence
  • Edge case handling
  • Negative tests if exception paths detected
• Run TestStubLinterSkill to identify missing test blocks

---

6️⃣ Security & Observability Pass

• Static scan for:
  • Secrets, unsafe packages, insecure config
  • Missing telemetry (ActivitySource, trace spans, click logs)
• Validate alignment with security-policy.yaml and telemetry-rules.yaml

---

7️⃣ Issue Aggregation & Diagnostics Composition

• Group violations by type (structure, trace, logic, security, test)
• Rank by severity: critical, high, medium, info
• Store as:
  • review-summary.json
  • review-comments.yaml
  • validation-report.json
  • Optional: suggested-refactor.patch

---

8️⃣ Emit Events & Escalation Triggers

• If pass: emit CodeReviewPassed → CI/CD pipeline continues
• If fail: emit CodeReviewFailed → triggers HumanOps Agent
• If warnings only: suggest PR improvements or wait for commit override

---

🕓 Timing & Performance

• Review runs per PR should complete in under 30 seconds
• Parallel execution per file with asynchronous skill runners
• All output is trace-id correlated for downstream ingestion

---

🧠 Memory Injection During Process

Short-term memory includes:

• File-to-layer mappings
• Prior reviews of related components (if available)
• Requirements loaded into SK context window for semantic validation

Long-term memory includes:

• Prior reviews with similar diffs or violations
• Known exception patterns and override rationale
• Component history by component_id

---

✅ Summary

The Code Reviewer Agent follows a robust, trace-aware, skill-driven process:

• Parses all context, diffs, and standards
• Runs layered validation across architecture, security, observability
• Emits actionable, scored, and auditable reviews
• Acts as an orchestrator-aware checkpoint for commit readiness

This ensures that only compliant, testable, traceable, and observable code is promoted in the ConnectSoft platform.

---

🧩 Skills and Kernel Functions

The Code Reviewer Agent uses a skill-based execution model powered by Semantic Kernel. Each skill represents a focused capability that maps to a review category, such as architecture, traceability, observability, or test coverage.

These skills can run:

• Sequentially (layered passes)
• Conditionally (based on file type, architecture, or diff scope)
• In parallel (across file sets)

This modular structure allows for both deep rule enforcement and LLM-based suggestion heuristics.

---

🧠 Core Semantic Kernel Skills

Skill Name	Purpose
ArchitectureViolationDetectorSkill	Detects violations of Clean Architecture boundaries (e.g., UI calling Infrastructure)
DomainEncapsulationSkill	Ensures domain logic is isolated and used only via interfaces
SecurityMisuseScannerSkill	Detects use of secrets, unsafe dependencies, or missing vault integrations
ObservabilityCoverageSkill	Checks for telemetry spans, OpenTelemetry injection, and trace propagation
TraceabilityValidatorSkill	Confirms trace IDs, execution metadata, and file attribution are present
TestCoverageHeuristicSkill	Evaluates presence, naming, and scope of test coverage for changed code
FeatureFlagLogicVerifierSkill	Validates edition-specific toggles are isolated, correctly scoped, and safe
LayerInteractionHeuristicSkill	Detects tight coupling, incorrect abstractions, or anti-patterns (e.g., DTO creep)
CommentSuggestorSkill	Generates line-level PR comments for violations, suggestions, or alternatives
CognitiveComplexityScorerSkill	Assigns a complexity score to changed methods and flags untestable logic

---

📦 Folder Structure for Skills

/skills/code-reviewer-agent/
  ├── ArchitectureViolation/
  ├── TraceabilityValidator/
  ├── ObservabilityCoverage/
  ├── TestCoverageHeuristics/
  ├── SecurityMisuseScanner/
  └── FeatureFlagLogicVerifier/

Each skill includes:

• .skprompt.txt: core LLM prompt template
• function.json: input/output schema
• Optional: test suite or inline example corpus

---

🧠 LLM-Powered Suggestion Sub-Skills

Sub-Skill	Capability
RefactorStrategyAdvisor	Suggests improved layering, method extraction, interface introduction
NamingConsistencyRecommender	Flags inconsistent variable or method names based on surrounding context
SpanInjectionAdvisor	Recommends OpenTelemetry span usage where missing
HandlerStructureComparator	Compares new command/query handlers against known compliant templates

These enable the agent to go beyond rules and deliver real-world, scalable feedback like a seasoned reviewer.

---

🧪 Prompt Composition Example

Prompt to ArchitectureViolationDetectorSkill:

Given the Clean Architecture rules below:
- UI may depend on Application
- Application may depend on Domain
- Domain must not depend on anything

Analyze the following code snippet and detect any boundary violations.
[CODE]

---

📘 Skill Execution Plan Example (Component-Level)

review_plan:
  - TraceabilityValidatorSkill
  - ArchitectureViolationDetectorSkill
  - TestCoverageHeuristicSkill
  - ObservabilityCoverageSkill
  - SecurityMisuseScannerSkill
  - CommentSuggestorSkill

Orchestrator decides plan based on:

• component
• file_types
• diff_complexity
• trace_id

---

✅ Summary

The Code Reviewer Agent is powered by a robust suite of Semantic Kernel skills, including:

• 🧱 Architecture validators
• 📡 Telemetry compliance scanners
• 🔐 Security analyzers
• 🧪 Test coverage heuristics
• 💬 Comment suggestors and refactor guides

These skills are modular, extendable, and support both hard policy enforcement and soft guidance — enabling ConnectSoft to enforce review policies at scale while staying developer-friendly.

---

⚙️ Technologies and Stack

The Code Reviewer Agent runs as a headless Semantic Kernel-based microservice, capable of processing pull request bundles and emitting structured review results as part of the autonomous CI/CD pipeline.

Layer	Technology	Purpose
🧠 Runtime Host	.NET 8 + Semantic Kernel	Agent execution and planning
💬 LLM Backend	Azure OpenAI (GPT-4 Turbo)	Reasoning and heuristics
🧪 Static Analysis	Roslyn (.NET), ESLint (JS/TS), TSLint (Angular), StyleCop (C#)	Language-specific rule enforcement
📦 Dependency Scanner	OSSReviewToolkit (optional), NuGet audit, NPM audit	Detect unsafe packages
🔐 Secrets Scanner	TruffleHog (integrated)	Detect hardcoded secrets
📡 Telemetry SDKs	OpenTelemetry .NET SDK, JS/TS trace wrappers	Observability compliance validation
🧪 Test Report Ingestor	xUnit/MSTest JSON, Jest/Playwright results	Aligns test status with diff

---

🌐 Supported Languages & Frameworks

Language	Scope
C# (.NET 8)	Backend services, Blazor frontend, ports/adapters, test suites
TypeScript/JavaScript	Angular components, frontend utilities, telemetry hooks
HTML + Tailwind	Static UI files, embedded widgets
YAML/JSON	Metadata, trace files, feature flags, orchestration plans
Markdown	PR descriptions, requirement files, blueprint comments

---

🧩 Integration Points

Tool	Role
GitHub / GitLab	Receives pull request bundles; can push review comments via webhook or API
Azure DevOps	Pull request pipeline compatibility, test report import, build trace propagation
ConnectSoft Orchestration Layer	Receives CodeReviewPassed/Failed events; determines promotion or rollback
Code Committer Agent	Waits for this agent’s result to finalize commit merge
Test Generator Agent	May be re-triggered if missing or insufficient tests detected
Observability Agent	Receives span coverage summary if telemetry rules are enforced

---

🧠 Toolchain Internals

Tool	Location / Usage
connectsoft-lint-rules/	Shared Roslyn + ESLint rules for style, structure, trace enforcement
code-reviewer-agent/skills/	Semantic Kernel skill package
security-policy.yaml	Defines secrets scan logic, unsafe package list, hash/token rules
observability-rules.yaml	Declares required spans, log levels, naming conventions

---

🧪 Sample CLI Usage (Internal/Testing)

dotnet run --agent code-reviewer-agent \
  --input ./pr_bundle_340/ \
  --config ./rules/code-review-policy.yaml \
  --output ./code-review-results/

---

📦 Packaging

The agent is shipped as:

• ✅ A containerized .NET microservice (deployed via K8s or function)
• ✅ A CI/CD-attachable component for pull request validation pipelines
• ✅ A semantic planner-compatible node in ConnectSoft’s Agent Mesh

---

🧠 Extensibility Notes

• Additional review rules can be injected via ruleset.yaml
• Skills are extendable via Semantic Kernel function plugins
• Full multi-agent compliance pipeline uses shared logging + telemetry

---

✅ Summary

The Code Reviewer Agent uses:

• 💡 Semantic Kernel with Azure OpenAI for reasoning
• 🔍 Static analyzers (Roslyn, ESLint, TruffleHog) for enforcement
• 📦 CI/CD and Git integration for pull request coordination
• 🧾 Rule-based and heuristic skills for in-depth, context-aware validation

It is a language-agnostic, framework-aware, and platform-integrated review engine built for multi-agent, architecture-first software engineering.

---

📌 System Prompt

The System Prompt is a foundational instruction block loaded at agent bootstrap. It defines:

• The agent's role and scope
• The standards it must enforce
• The review style and tone
• The architectural and business constraints it should align to
• Its go/no-go logic for blocking versus suggestive feedback

This ensures deterministic behavior and alignment with ConnectSoft governance principles, regardless of the incoming prompt or diff type.

---

🧠 Base System Prompt Template

You are the Code Reviewer Agent for the ConnectSoft AI Software Factory.

Your role is to perform a deep review of software code changes (pull requests) across backend, frontend, and infrastructure layers.

You are responsible for validating:
- Adherence to Clean Architecture and DDD principles.
- Proper layering (UI → Application → Domain → Infrastructure).
- Use of port/adapters, injection, and interface boundaries.
- Absence of security risks, plaintext secrets, or unsafe code.
- Presence of OpenTelemetry spans and trace metadata in services.
- Sufficient test coverage and alignment with defined requirements.
- Traceability of all code artifacts (`trace_id`, `execution_id`, `agent_origin`).
- Compliance with ConnectSoft engineering standards.

If the code violates mandatory rules, you MUST fail the review with a justification and suggestions.
If improvements are possible but not blocking, recommend best practices and emit a warning.

You do NOT format code unless explicitly requested. Your goal is correctness, security, and architectural compliance.
Review as if you are a Staff Software Engineer working in a distributed, multi-agent architecture team.

Use concise, structured, and professional language. Support inline comments with actionable insights.
You will always produce both structured JSON output and a human-readable summary.

All decisions must be traceable and auditable using `trace_id` and `component` metadata.

---

🧩 Prompt Customization Tokens (Injected per Review)

Token	Description
{{trace_id}}	Unique traceable ID for this code review
{{component}}	The application or module under review
{{review_type}}	pull_request or commit_validation
{{framework}}	Framework name (.NET, Angular, etc.)
{{edition}}	SaaS edition (e.g., B2B, internal, beta)
{{requirement_name}}	Business requirement from requirement.md

These are injected into the SK context and influence conditional rules or commentary depth.

---

🧠 Execution Characteristics Set by Prompt

Characteristic	Behavior
Review Tone	Strict but constructive (default)
Failing Behavior	Block merge if critical rule violated
Memory Context Use	Enabled for reasoning over requirement.md and architecture
Skill Execution Mode	Parallelized if >5 files, otherwise sequential
Inline Suggestions	Enabled only for diff-compatible reviews with file mapping
Output Format	Always emits both structured JSON and Markdown summary

---

📘 Example Resolved System Prompt (Excerpt)

You are the Code Reviewer Agent for the ConnectSoft platform.

Component: BillingService
Edition: B2B
Trace ID: trace-pr-345

This is a pull request code review.
Framework: .NET 8 (Backend)

Your goals are:
- Validate Clean Architecture layering
- Detect security issues and unsafe patterns
- Ensure OpenTelemetry spans exist on API entry points
- Confirm test coverage exists for all changed handlers and services

Be precise and emit structured results.

---

✅ Summary

The System Prompt defines the identity, responsibilities, and behavior of the Code Reviewer Agent, including:

• 🎯 Enforcement scope
• 📏 Standards and architectural rules
• 🧠 Tone, reasoning, and skill execution logic
• 🧾 Traceability and compliance guarantees

This prompt ensures every review is deep, reliable, auditable, and connected to the broader agent mesh.

---

📥 Input Prompt Template

The Input Prompt Template gives the Code Reviewer Agent all context needed to:

• Scope the review to the correct component
• Understand what changed and why
• Load architectural rules, edition toggles, and requirement links
• Trigger relevant review skills and validations

It serves as a declarative control plane for each review cycle.

---

📄 Template Format (YAML)

trace_id: trace-pr-345
execution_id: exec-review-345
review_type: pull_request
component: BillingService
framework: dotnet
architecture: CleanArchitecture
layered_structure:
  - Domain
  - Application
  - Ports
  - Infrastructure
files_changed:
  - InvoiceHandler.cs
  - InvoiceMapper.cs
  - InvoiceHandler.test.cs
diff_context_file: code-diff.json
requirement_file: requirement.md
architecture_context: architecture-context.yaml
security_policy: security-policy.yaml
telemetry_rules: telemetry-rules.yaml
test_report: test-report.json
feature_flags: feature-flags.json
agent_origin: backend-developer-agent
edition: b2b
test_coverage_required: true
telemetry_required: true
manual_review_enabled: false
output_mode: structured+summary

---

🧠 Template Breakdown

Field	Purpose
trace_id, execution_id	Enables audit and orchestration traceability
component, framework, edition	Scopes the review logic
architecture, layered_structure	Tells agent which layering model to enforce
files_changed	List of reviewed files; determines skill execution
diff_context_file	Path to structured diff used for inline feedback
requirement_file	Input for semantic reasoning and coverage validation
test_report	Optional test feedback, used for coverage heuristics
telemetry_rules, security_policy	Constraints loaded by observability/security skills
output_mode	Specifies whether to emit structured JSON, human-readable summary, or both

---

🧠 LLM Context Injection Version (JSON)

{
  "trace_id": "trace-pr-345",
  "component": "BillingService",
  "framework": "dotnet",
  "edition": "b2b",
  "review_type": "pull_request",
  "files_changed": ["InvoiceHandler.cs", "InvoiceHandler.test.cs"],
  "requirements_summary": "Invoices must support zero balance, delayed due dates, and tax exemptions.",
  "telemetry_required": true,
  "test_coverage_required": true
}

Used when interacting with LLM-based reasoning sub-skills such as CommentSuggestorSkill and RefactorAdvisorSkill.

---

🧪 Execution Strategy Based on Input

Input Flag	Behavior
manual_review_enabled: true	Emits PreviewGenerated, pauses orchestration
telemetry_required: false	Skips span-checking skill
edition: internal	Loads tenant-specific code conventions
test_coverage_required: false	Only structural validation of tests, not coverage

---

🗂 Example File Bundle with Template

/review-bundle/
  ├── prompt.yaml
  ├── code-diff.json
  ├── requirement.md
  ├── test-report.json
  ├── architecture-context.yaml
  ├── telemetry-rules.yaml
  ├── feature-flags.json
  └── security-policy.yaml

---

✅ Summary

The Input Prompt Template enables:

• 🧠 Context-aware reviews scoped to component, architecture, and edition
• 🎯 Precision review planning via skill activation flags
• 📦 Seamless orchestration integration via trace_id, execution_id
• 🧾 High-fidelity reasoning using business and structural input overlays

This ensures that every code review is customized, traceable, and standard-aligned.

---

📤 Output Expectations and Structure

The Code Reviewer Agent emits structured and traceable outputs in multiple formats, designed for consumption by:

• Developers (review feedback, suggestions)
• Orchestration agents (pass/fail signals, retry logic)
• Audit tools and dashboards (traceability, validation summaries)
• Downstream agents (commit gates, test augmentation)

---

📁 Output Directory Layout

/code-review/
  ├── review-summary.json
  ├── validation-report.json
  ├── review-comments.yaml
  ├── suggested-refactor.patch
  ├── review-log.md
  ├── trace-index.yaml
  └── emitted-events.json

---

📘 Core Output Files

1️⃣ review-summary.json

{
  "trace_id": "trace-pr-345",
  "component": "BillingService",
  "review_status": "fail",
  "risk_score": 68,
  "violations": 3,
  "recommendations": 2,
  "blocked_merge": true,
  "reviewed_by": "code-reviewer-agent"
}

Core orchestration signal for pass/fail handling and CI gating.

---

2️⃣ validation-report.json

{
  "structure": {
    "violations": [
      { "file": "InvoiceHandler.cs", "issue": "UI references Infrastructure", "severity": "critical" }
    ]
  },
  "security": {
    "secrets_found": false
  },
  "telemetry": {
    "missing_spans": ["InvoiceMapper.cs"]
  },
  "traceability": {
    "missing_trace_tags": ["InvoiceHandler.test.cs"]
  }
}

Consumed by orchestrator dashboards and governance audit tools.

---

3️⃣ review-comments.yaml

- file: InvoiceHandler.cs
  line: 27
  severity: error
  issue: "Direct use of DbContext violates Clean Architecture"
  suggestion: "Use IInvoiceRepository via port and injected service"
- file: InvoiceMapper.cs
  line: 12
  severity: warning
  issue: "Missing OpenTelemetry span"
  suggestion: "Inject ActivitySource span for transformation step"

Can be automatically applied to GitHub/GitLab PRs.

---

4️⃣ suggested-refactor.patch (optional)

- return _context.Invoices.ToList();
+ return _invoiceRepository.GetAll();

Auto-generated when violations have clear automated refactor paths.

---

5️⃣ review-log.md (optional)

Human-readable summary for developers or auditors.

## Code Review — BillingService

**Result:** ❌ Review Failed  
**Trace ID:** trace-pr-345  
**Issues:**
- Critical: UI references Infrastructure directly (InvoiceHandler.cs:27)
- Warning: Telemetry missing in DTO mapper

See: `review-comments.yaml` and `suggested-refactor.patch`

---

🧾 Trace Metadata Expectations

Every output must include:

Field	Format
trace_id	trace-pr-xxx
execution_id	exec-review-xxx
component	Source module/component
reviewed_by	code-reviewer-agent
agent_origin	Developer agent that wrote the code

---

📡 Event Emission Format

CodeReviewPassed

{
  "event": "CodeReviewPassed",
  "trace_id": "trace-pr-345",
  "component": "BillingService",
  "reviewed_by": "code-reviewer-agent",
  "timestamp": "2025-05-10T15:20:11Z"
}

CodeReviewFailed

{
  "event": "CodeReviewFailed",
  "trace_id": "trace-pr-345",
  "reason": "Layering violation + missing span + test coverage gap",
  "block_merge": true
}

---

📦 Output Routing

Consumer	Format
Code Committer Agent	review-summary.json, validation-report.json
Orchestration Layer	emitted-events.json, review status flags
Developer (via Git)	review-comments.yaml, review-log.md
Test Generator Agent	Receives span/test gaps as triggers
Audit Trail	trace-index.yaml, score, origin, execution metadata

---

✅ Summary

The Code Reviewer Agent produces:

• 🎯 Structured pass/fail results (review-summary.json)
• 🔍 Detailed diagnostics (validation-report.json, review-comments.yaml)
• 📘 Human-readable feedback (review-log.md)
• 📡 Events for orchestration and auditing (emitted-events.json)
• 📎 Fully traceable metadata across all outputs

These outputs allow the ConnectSoft platform to automate enforcement, feedback, and traceability across all pull requests.

---

🧠 Memory: Short-Term and Long-Term Use

The Code Reviewer Agent relies on memory to:

• Maintain context across files and changes within a PR
• Recall design decisions or prior violations tied to a component
• Reason over historical patterns (e.g., common errors)
• Link current review to past agent actions, requirements, and trace lineage

Memory is managed using a combination of:

• 🧠 Short-term (in-memory context)
• 📚 Long-term (vector storage + structured logs)

---

🕒 Short-Term Memory (Context Window)

Scope	Description
🔹 PR-local context	Active during a single review cycle (trace window)
🔹 Includes	Current diff, component metadata, architecture model, test results
🔹 Usage	Prompt composition, skill routing, LLM grounding
🔹 Max Size	~10K–20K tokens (LLM-dependent)

Includes:

• File diffs with annotations
• Parsed requirement.md + blueprint.md
• Active telemetry and security rule overlays
• Inferred component-layer mapping
• Recent agent-of-origin history (e.g., frontend-developer-agent)

---

📚 Long-Term Memory (Vector + Indexed Logs)

Storage	Content
🗃️ Vector DB	Prior review feedback, known violations, previously refactored files
📓 Indexed YAML Logs	Historical reviews per component, trace lineage
📂 Skill Examples Corpus	Past successful LLM completions per review type (test suggestion, telemetry patch, etc.)

Example Vector Entry

{
  "component": "InvoiceHandler",
  "file": "InvoiceHandler.cs",
  "agent": "code-reviewer-agent",
  "violations": ["direct-db-call", "missing-span"],
  "timestamp": "2025-05-01T10:21Z"
}

Used to flag repeat violations or pattern regressions.

---

🔁 Use Cases for Memory

Scenario	Memory Usage
🧾 Detect regression	Compare current PR to last-reviewed commit for same component
🧠 Suggest fix	Use prior fix from similar module to recommend patch
📘 Enforce requirement continuity	Validate that follow-up PR aligns with earlier approved requirement.md
🧪 Test enforcement	Recall that this component previously failed due to missing test — enforce again

---

🧩 Memory-Aware Skill Behavior

Skills adapt when memory is loaded:

• ArchitectureViolationDetectorSkill boosts known layer conflicts
• RefactorAdvisorSkill suggests familiar interface patterns
• TelemetryCoverageSkill infers expected span tags from past usage

---

🧠 Memory Injection in Execution Plan

memory:
  short_term:
    - file_diffs
    - requirement_summary
    - trace_metadata
  long_term:
    - last_violation: missing-trace-metadata
    - related-component-pattern: async-handler + service-adapter

---

🔐 Governance on Memory Use

• All memory entries include trace_id, execution_id, and component tags
• Long-term storage is append-only and immutable for auditability
• Sensitive data (e.g., secrets from diffs) is never persisted

---

✅ Summary

The Code Reviewer Agent uses:

• 🧠 Short-term memory to reason across files, requirements, and trace context
• 📚 Long-term memory to detect regression, enforce policy continuity, and provide historically grounded recommendations
• 🧩 Memory-linked execution logic to personalize feedback based on component history

This memory architecture makes the agent adaptive, trace-aware, and improvement-reinforcing across the platform lifecycle.

---

🧾 Validation Ruleset

The Validation Ruleset defines the objective and heuristic criteria the agent uses to approve, warn, or block submitted code. It spans:

• Clean Architecture enforcement
• DDD compliance
• Security and telemetry policies
• Testing and traceability requirements
• Platform-specific best practices

Each rule is implemented via one or more Semantic Kernel skills, static analyzers, or trace validators.

---

📋 Rule Categories

🧱 1. Architectural Structure Rules

Rule	Description
CA-LAYER-001	UI may only reference Application layer
CA-LAYER-002	Application layer may reference Domain or Ports only
CA-LAYER-003	Domain must not depend on any outer layer
CA-DIR-001	Folder structure must reflect logical boundaries (e.g., /domain, /application, /infrastructure)
CA-PORT-001	All external calls must go through a port interface, not directly

---

🧠 2. Domain-Driven Design Rules

Rule	Description
DDD-SRV-001	Business logic must reside in domain services, not controllers or handlers
DDD-AGG-001	Aggregates must maintain invariant enforcement
DDD-ENT-001	Avoid anemic domain models (fields-only entities)
DDD-VAL-001	Use value objects for business rules where applicable

---

🔒 3. Security Rules

Rule	Description
SEC-001	Secrets must never be hardcoded (scan for API keys, tokens, credentials)
SEC-002	Use vault injection for all config-based secrets
SEC-003	Validate that all public APIs have access controls ([Authorize], guards, etc.)
SEC-004	No direct usage of System.Text.Json deserialization without input validation
SEC-005	Validate no weak crypto or outdated libraries (e.g., SHA1, MD5)

---

📡 4. Observability and Telemetry Rules

Rule	Description
OBS-001	All public APIs must emit ui.rendered or service.request spans
OBS-002	Pages and services must include trace_id, user_role, and execution_id in spans
OBS-003	OpenTelemetry ActivitySource should wrap core service functions
OBS-004	JS telemetry helpers must use trace("click.*"), trace("form.submit")

---

🧪 5. Testing & Coverage Rules

Rule	Description
TEST-001	All changed services and handlers must have unit tests
TEST-002	Public methods without tests must be flagged unless [GeneratedCode] is applied
TEST-003	Test files must include positive and negative assertions for edge cases
TEST-004	Controllers must have integration tests or be covered by Playwright/Cypress if frontend

---

🧾 6. Traceability Rules

Rule	Description
TRACE-001	Every file must include trace_id, execution_id, and agent_origin
TRACE-002	Files missing trace metadata are rejected unless explicitly exempted (e.g., README.md)
TRACE-003	Components must emit metadata.json if public or externally used
TRACE-004	Output artifacts must be uniquely linked to an originating agent and blueprint

---

🧠 Enforcement Strategy

Rule Type	Enforcement
Critical	Blocks merge (e.g., architectural violations, security breaches)
High	Warns + marks PR as "Needs Review"
Medium	Suggests fix, but does not fail review
Info	Inline comment or markdown footnote only

---

🔁 Rule Execution Pipeline

validation_pipeline:
  - TraceabilityValidatorSkill
  - ArchitectureViolationDetectorSkill
  - DomainEncapsulationSkill
  - SecurityMisuseScannerSkill
  - ObservabilityCoverageSkill
  - TestCoverageHeuristicSkill

Each skill returns a rule code, severity level, location, and recommendation.

---

✅ Summary

The Code Reviewer Agent enforces a strict but extensible Validation Ruleset, including:

• 🧱 Clean Architecture layering
• 🧠 DDD modeling correctness
• 🔐 Security baseline enforcement
• 📡 Observability and telemetry injection
• 🧪 Test coverage and structure
• 📎 Full traceability with origin metadata

These rules ensure every code review is precise, standards-aligned, and traceably enforceable in the ConnectSoft engineering ecosystem.

---

🔁 Retry and Correction Flow

Not all code is immediately valid. The Code Reviewer Agent includes an intelligent, trace-aware retry and correction mechanism that:

• Attempts auto-correction where safe
• Escalates to HumanOps Agent only when truly blocked
• Suggests patches for structural or architectural fixes
• Re-runs failed validation layers based on corrected input

This ensures review stability, resilience, and developer guidance — without constant human interruption.

---

🛑 Retry Scenarios

Condition	Retry Action
🧱 Architectural violation with known fix	Suggest interface wrapper or adapter structure
🔒 Missing access guard	Inject [Authorize] stub or flag role policy guidance
📡 Missing telemetry	Suggest injection of ActivitySource or JS trace() calls
🧪 Test file missing	Propose test file structure using known fixture
🧾 Missing trace_id	Auto-inject template metadata and retry validation

---

🧠 Retry Flow Diagram

flowchart TD
    A[Initial Review Run] --> B[Validation Failed]
    B --> C{Retryable?}
    C -- Yes --> D[Apply Fix/Template Suggestion]
    D --> E[Re-run Skills Affected]
    E --> F{Resolved?}
    F -- Yes --> G[Review Passes or Warns]
    F -- No --> H[Emit Final Failure]
    C -- No --> H

Hold "Alt" / "Option" to enable pan & zoom

---

🛠️ Auto-Correction Tactics

Problem	Correction
trace_id missing	Add trace_id, execution_id, and agent_origin comments or YAML
Direct service call from UI	Suggest interface + port implementation refactor
Lack of OpenTelemetry span	Add OTEL boilerplate code block to handler or controller
No test file for service	Suggest MSTest template with naming and scaffolding
File missing metadata	Generate .metadata.json stub with inferred component + role info

---

🧾 Suggested Refactor Example

If violation detected in:

public class InvoiceHandler {
    private readonly DbContext _context;

    public List<Invoice> GetAll() => _context.Invoices.ToList();
}

Agent produces:

- private readonly DbContext _context;
+ private readonly IInvoiceRepository _repository;

- return _context.Invoices.ToList();
+ return _repository.GetAll();

And stores it in suggested-refactor.patch.

---

📄 Retry Event Emission

RetryAttempted

{
  "event": "RetryAttempted",
  "trace_id": "trace-pr-345",
  "reason": "Missing test file for changed service",
  "attempt": 1
}

CorrectionSuggested

{
  "event": "CorrectionSuggested",
  "trace_id": "trace-pr-345",
  "component": "InvoiceHandler",
  "fix_type": "TelemetrySpanInjection",
  "location": "InvoiceMapper.cs:12"
}

---

📏 Retry Policy

Severity	Retry?	Auto-Fix?	Escalate?
Critical	✅ Once	⚠️ Suggest only	✅ Yes
High	✅ Twice	✅ If safe	⚠️ Optional
Medium	✅	✅	❌
Info	No retry	✅	❌

Retry counts and escalation thresholds are configurable via review-policy.yaml.

---

✅ Summary

The Code Reviewer Agent supports:

• 🔁 Retry attempts for safe-to-fix violations
• 🛠️ Automated suggestions or code snippets to guide developers
• 📬 Events and patch files to notify downstream agents or CI/CD systems
• 📎 Trace-aware, resilient feedback without failing prematurely

This enables constructive review loops, higher first-pass merge rates, and improved developer experience.

---

🤝 Collaboration Interfaces

The Code Reviewer Agent operates as a mid-pipeline enforcement node. It must collaborate with:

• Upstream developer agents and commit agents
• Downstream CI/CD orchestrators and test systems
• Cross-cutting governance agents (security, observability, traceability)
• Human intervention layers when required

Its interfaces are designed to be fully trace-aware, agent-resolvable, and orchestration-compatible.

---

🔗 Agent Collaboration Diagram

flowchart TD
    Dev[🧱 Backend/Frontend Developer Agents]
    Committer[📥 Code Committer Agent]
    PRCreator[📂 Pull Request Creator Agent]
    Reviewer[🧠 Code Reviewer Agent]
    HumanOps[👤 HumanOps Agent]
    QA[🔬 Test Generator Agent]
    Sec[🔒 Security Engineer Agent]
    Obs[📡 Observability Agent]
    Orchestrator[⚙️ Orchestration Layer]

    Dev --> Committer --> PRCreator --> Reviewer
    Reviewer --> QA
    Reviewer --> HumanOps
    Reviewer --> Sec
    Reviewer --> Obs
    Reviewer --> Orchestrator

Hold "Alt" / "Option" to enable pan & zoom

---

📥 Inbound Interfaces

Source	Data
Pull Request Creator Agent	code-diff.json, execution_id, trace_id
Code Committer Agent	File structure, file metadata, modified targets
Developer Agents	Original files, component metadata, agent_origin
Architect/Security Agents	Rulesets (architecture-context.yaml, security-policy.yaml)
Observability Agent	Required span templates (telemetry-rules.yaml)
Orchestration Layer	review-plan, review-mode, trace bundle, config flags

---

📤 Outbound Interfaces

Target	Output
Orchestrator	Review events: CodeReviewPassed, CodeReviewFailed, CorrectionSuggested, InterventionRequest
Code Committer Agent	review-summary.json, validation-report.json
Test Generator Agent	Emits MissingTestsDetected or RegenTestsSuggested when code lacks coverage
Observability Agent	Telemetry gaps or span injection suggestions
Security Agent	Flags unscanned secrets, unsafe packages
HumanOps Agent	Escalates when ambiguity or subjective decision needed (e.g., domain violation vs performance gain)

---

📡 Event-Driven Interactions

The agent emits structured events with trace metadata that downstream agents subscribe to:

{
  "event": "CodeReviewFailed",
  "trace_id": "trace-pr-345",
  "component": "InvoiceHandler",
  "violations": ["CA-LAYER-001", "OBS-001"],
  "recommended_action": "Manual review required",
  "agent_origin": "backend-developer-agent"
}

---

🧠 Internal Skill-Level Interfaces

Some collaboration is done within skills, such as:

• Asking SecurityMisuseScannerSkill to resolve policy from security-policy.yaml
• Invoking TestCoverageHeuristicSkill if test coverage is missing
• Calling ObservabilityCoverageSkill to analyze span consistency

---

🧾 Inline Feedback Interface (GitHub/GitLab)

Optional integration — if configured, the agent posts review comments directly into the PR.

- file: BillingService.cs
  line: 41
  comment: |
    [Code Reviewer Agent] ⚠️ Missing OpenTelemetry span for critical method.
    Suggest injecting: `ActivitySource.StartActivity("billing.charge.issued")`

---

🧬 Trace Linking Across Interfaces

Each output and event carries:

Field	Description
trace_id	Ties review to PR, blueprint, and component
agent_origin	Identifies authoring agent of original code
execution_id	Maps back to orchestrator cycle
component	Reviewed unit/module

---

✅ Summary

The Code Reviewer Agent collaborates with:

• 📥 Developer and commit agents upstream
• 📤 Orchestration, test, and observability agents downstream
• 👤 HumanOps and security/telemetry governance agents
• 🔁 Internal skills that modularize rule validation and correction

This makes the agent a fully integrated, trace-aware, and policy-enforcing node in the ConnectSoft autonomous delivery mesh.

---

📡 Observability Hooks and Execution Tracing

To be a first-class participant in the ConnectSoft Observability Mesh, the Code Reviewer Agent must:

• Emit execution spans and structured logs
• Track skill execution paths and time
• Report validation outcomes as traceable, queryable events
• Allow audit, debugging, and optimization of agent logic

---

🔍 What’s Observed

Category	Details
🔄 Review lifecycle	When a review starts, ends, succeeds, or fails
🧩 Skill execution	Time taken per skill, retry attempts, fix suggestions
🧪 Validation result	Pass/fail status, rule violations, recommendations
📂 File-level coverage	Spans for each reviewed file and decision point
🚦 CI signals	When events like CodeReviewPassed are emitted
🔧 Internal errors	Trace and retry logs when something breaks or misroutes

---

🌐 OpenTelemetry Integration

Span Examples

{
  "name": "code-review.started",
  "trace_id": "trace-pr-345",
  "attributes": {
    "component": "BillingService",
    "framework": "dotnet",
    "files": 5,
    "triggered_by": "pull-request"
  }
}

{
  "name": "skill.execution.ArchitectureViolationDetectorSkill",
  "duration_ms": 52,
  "trace_id": "trace-pr-345",
  "component": "InvoiceHandler"
}

{
  "name": "code-review.failed",
  "status": "error",
  "trace_id": "trace-pr-345",
  "reason": "CA-LAYER-001 violation"
}

---

📈 Metrics Collected

Metric	Example
review.duration.seconds	How long the full review cycle took
skill.retries.count	Number of auto-retry attempts
validation.violations.count	Total number of rule violations per PR
coverage.tests.missing	Number of components missing tests
telemetry.spans.missing	Number of files with missing OTEL spans
trace.metadata.missing	How many files lacked trace metadata on first attempt

---

📦 Output Path Tags

All logs and metrics are tagged with:

• trace_id
• execution_id
• component
• agent_origin
• review_status

These identifiers ensure end-to-end visibility from blueprint → code → review → deploy.

---

📄 Internal Logging Format

Structured JSON logs per step:

{
  "timestamp": "2025-05-10T15:31:14Z",
  "step": "validate-security-policy",
  "status": "ok",
  "file": "InvoiceHandler.cs",
  "rule": "SEC-002",
  "result": "vault usage confirmed"
}

Logs are shipped to centralized ConnectSoft observability stack (e.g., Azure Monitor, Grafana, or OpenTelemetry Collector).

---

📘 Integration Points

System	Purpose
Observability Agent	Ingest spans and metrics; correlates with build and deployment telemetry
HumanOps Agent	Views logs and traces when review escalation occurs
CI/CD Orchestration Layer	Monitors agent execution health across large PR batches
Audit Layer	Validates post-deployment if code followed review policy and agent enforced gating correctly

---

🧠 Trace Continuity

All trace metadata is preserved across:

• Inputs → Skills → Outputs
• Events → Commits → Deployments
• Cross-agent handoffs and reassignments

This ensures ConnectSoft can answer: “Which agent reviewed this component?” “Which rule was violated, and how was it handled?” “Where in the pipeline did the issue originate?”

---

✅ Summary

The Code Reviewer Agent emits:

• 📡 OpenTelemetry spans for lifecycle, skill execution, and decisions
• 📈 Structured metrics for reviews, retries, validation failures
• 📘 Traceable logs across review stages and file targets
• 🧠 Trace ID and metadata hooks for downstream correlation

This observability foundation ensures trust, visibility, and forensic power in ConnectSoft’s automated quality pipeline.

---

👤 Human Intervention Hooks

Despite its autonomous design, the Code Reviewer Agent recognizes that some decisions require human judgment, including:

• Business context ambiguity
• Valid violations with acceptable tradeoffs
• Conflicting architecture interpretations
• Refactor scope exceeding safe automation
• Subjective UX or frontend component validations

To manage this, the agent exposes intervention hooks that let human reviewers step in without disrupting traceability or pipeline flow.

---

📌 When Human Intervention is Triggered

Condition	Hook Trigger
🧠 Architectural violation where exception is documented	Emits InterventionRequest
🔁 Repeated violations in previously accepted patterns	Suggests Pattern Override Review
❓ LLM cannot infer safe fix or test	Flags file for manual feedback
⚠️ Conflicting requirements detected	Escalates to human architect or ProductOps
🧩 Subjective decision (e.g., design-quality CSS, UX pattern)	Emits ManualReviewRecommended event

---

🔁 Intervention Workflow

flowchart TD
    A[Review Started]
    B[Validation Error or Ambiguity]
    C{Auto-correctable?}
    D[Apply Patch & Retry]
    E{Human Review Required?}
    F[Emit InterventionRequest]
    G[Wait for HumanOps Agent Approval]
    H[Continue Review Execution]
    I[Fail Review & Annotate Trace]

    A --> B --> C
    C -- Yes --> D --> H
    C -- No --> E
    E -- Yes --> F --> G --> H
    E -- No --> I

Hold "Alt" / "Option" to enable pan & zoom

---

📬 InterventionRequest Event Example

{
  "event": "InterventionRequest",
  "trace_id": "trace-pr-345",
  "component": "BillingService",
  "reason": "Use case-specific exception to Clean Architecture layering rule",
  "file": "InvoiceService.cs",
  "required_action": "Review justification or approve override",
  "agent_origin": "backend-developer-agent"
}

---

✅ Supported Human Actions

Action	Result
✅ Approve As-Is	Review continues; issue marked "reviewed manually"
🛠️ Modify Input	Blueprint, requirement, or diff can be adjusted
📝 Add Comment	Feedback loop is stored with full trace
❌ Reject PR	PR is blocked and redirected to authoring agent

Each action is recorded and added to the agent’s review-log.md and audit trail.

---

📘 Visual Diff Preview Mode

For UI-related PRs, the agent emits:

• PreviewGenerated.html
• rendered-before.png vs rendered-after.png
• Highlighted layout or span injection diff

Human reviewers can assess visual correctness before agent passes the review.

---

🧠 Audit Logging of Interventions

intervention_log:
  trace_id: trace-pr-345
  reviewer: alice.architect
  action: override-accepted
  rule_bypassed: CA-LAYER-001
  justification: "Shared DTO between legacy and new modules"
  timestamp: 2025-05-10T16:05Z

Stored alongside execution_id and component.

---

🧩 Integration with HumanOps Agent

If human override is required, the HumanOps Agent receives:

• Full diff
• Summary of violations
• Review log so far
• Suggested override reasons
• Links to metadata and blueprint

This ensures humans have full decision context without digging manually.

---

✅ Summary

The Code Reviewer Agent includes robust, auditable support for:

• 🚨 Manual approval of edge-case violations
• 🧠 Override flow for architectural exceptions
• 📝 Inline feedback injection and review pauses
• 📎 Traceable and justifiable human involvement

This makes the ConnectSoft platform flexible, secure, and human-aligned — without sacrificing automation.

---

✅ Summary and Governance Role

The Code Reviewer Agent acts as the final automated quality gate in the ConnectSoft delivery pipeline. It is responsible for enforcing:

• 🧱 Architectural boundaries
• 🧠 Requirement alignment
• 🔐 Security policies
• 📡 Observability practices
• 🧪 Test coverage
• 🧾 Traceability and governance rules

It ensures that every pull request is production-ready, auditable, and compliant before integration, deployment, or human review.

---

📜 Core Responsibilities Recap

Domain	Responsibility
Architecture	Enforce Clean Architecture and DDD layering, ports/adapters
Code Semantics	Detect coupling, complexity, and anti-patterns
Security	Validate secrets, config usage, authentication guards
Telemetry	Confirm OpenTelemetry and span compliance
Testing	Ensure adequate and correct test coverage
Traceability	Require trace_id, execution_id, and origin metadata
Recommendations	Suggest refactors, test scaffolds, and observability spans
Governance	Block merge on critical violations, emit CodeReviewFailed
Intervention	Escalate subjectivity or exceptions to HumanOps with full context

---

🧠 Review Capabilities

Feature	Description
📦 Skill-Based	Uses modular Semantic Kernel functions for layered reviews
📡 Telemetry-Integrated	Emits spans, metrics, and logs into the observability mesh
🧾 Output-Rich	Produces summary reports, inline comments, validation artifacts, and patch diffs
🔁 Retry-Safe	Supports retry flows, auto-fixes, and suggestions
👤 Human-Aware	Includes override mechanisms and preview flows
🧠 Memory-Enhanced	Recalls historical decisions, violations, and component history

---

🔗 Platform Integration

The agent is deeply connected across the AI Software Factory pipeline:

flowchart TD
    Dev[🧱 Developer Agents]
    Commit[📥 Committer Agent]
    PR[📂 PR Creator Agent]
    Reviewer[🧠 Code Reviewer Agent]
    HumanOps[👤 Manual Reviewer]
    CI[🧪 CI/CD Pipeline]
    QA[🔬 Test Generator]
    Trace[📡 Observability Agent]

    Dev --> Commit --> PR --> Reviewer
    Reviewer --> HumanOps
    Reviewer --> CI
    Reviewer --> QA
    Reviewer --> Trace

Hold "Alt" / "Option" to enable pan & zoom

---

🔐 Governance Role

The Code Reviewer Agent enforces:

• ✅ ConnectSoft architecture policies
• 🧠 Design consistency and alignment
• 🔐 Zero-trust secrets management
• 📎 Full traceability on all generated and reviewed code
• 📜 An auditable trail of approvals, suggestions, and exceptions

These responsibilities make it a compliance enforcer and reviewer of record for any code that enters the platform.

---

🧾 What Makes It Production-Grade

• 🧩 Structured outputs (review-summary.json, validation-report.json)
• 📡 OpenTelemetry spans and events
• 🧠 Multi-agent collaboration (Committer, Test, Security, Observability)
• 🧠 Human review fallback with full trace context
• 🔁 Retry/correction with patch suggestions
• 🧾 Trace-tagged artifact history (via trace_id, execution_id, agent_origin)

---

📘 Final Summary

“The Code Reviewer Agent guarantees that all code promoted inside the ConnectSoft Software Factory meets the platform’s highest standards of architecture, security, testability, observability, and traceability — ensuring automation without compromise.”