Skip to content

AGENTS.md

Latest commit

 

History

History
289 lines (211 loc) · 12.7 KB

AGENTS.md

File metadata and controls

289 lines (211 loc) · 12.7 KB
Raw

Agent Quick Reference

Project-specific guidance for agents working on BuildMark - a .NET CLI tool for generating markdown build notes.

Standards Application (ALL Agents Must Follow)

Before performing any work, agents must read and apply the relevant standards from .github/standards/:

  • csharp-language.md - For C# code development (literate programming, XML docs, dependency injection)
  • csharp-testing.md - For C# test development (AAA pattern, naming, MSTest anti-patterns)
  • reqstream-usage.md - For requirements management (traceability, semantic IDs, source filters)
  • reviewmark-usage.md - For file review management (review-sets, file patterns, enforcement)
  • software-items.md - For software categorization (system/subsystem/unit/OTS classification)
  • technical-documentation.md - For documentation creation and maintenance (structure, Pandoc, README best practices)

Load only the standards relevant to your specific task scope and apply their quality checks and guidelines throughout your work.

Agent Delegation Guidelines

The default agent should handle simple, straightforward tasks directly. Delegate to specialized agents only for specific scenarios:

  • Light development work (small fixes, simple features) → Call @developer agent
  • Light quality checking (linting, basic validation) → Call @quality agent
  • Formal feature implementation (complex, multi-step) → Call the @implementation agent
  • Formal bug resolution (complex debugging, systematic fixes) → Call the @implementation agent
  • Formal reviews (compliance verification, detailed analysis) → Call @code-review agent
  • Template consistency (downstream repository alignment) → Call @repo-consistency agent
  • Production code and self-validation tests → Call software-developer agent
  • Requirements management → Call Requirements Agent
  • Documentation updates → Call Technical Writer
  • Unit/integration tests → Call Test Developer

Available Specialized Agents

  • code-review - Agent for performing formal reviews using standardized review processes
  • developer - General-purpose software development agent that applies appropriate standards based on the work being performed
  • implementation - Orchestrator agent that manages quality implementations through a formal state machine workflow
  • quality - Quality assurance agent that grades developer work against DEMA Consulting standards and Continuous Compliance practices
  • repo-consistency - Ensures BuildMark remains consistent with the TemplateDotNetTool template patterns and best practices
  • software-developer - Writes production code and self-validation tests - targets design-for-testability and literate programming style
  • Requirements Agent - Develops requirements and ensures test coverage linkage
  • Technical Writer - Creates accurate documentation following regulatory best practices
  • Test Developer - Creates unit and integration tests following AAA pattern

Quality Gate Enforcement (ALL Agents Must Verify)

Configuration files and scripts are self-documenting with their design intent and modification policies in header comments.

  1. Linting Standards: ./lint.sh (Unix) or lint.bat (Windows) - comprehensive linting suite
  2. Build Quality: Zero warnings (TreatWarningsAsErrors=true)
  3. Static Analysis: SonarQube/CodeQL passing with no blockers
  4. Requirements Traceability: dotnet reqstream --enforce passing
  5. Test Coverage: All requirements linked to passing tests
  6. Documentation Currency: All docs current and generated
  7. File Review Status: All reviewable files have current reviews

Continuous Compliance Overview

This repository follows the DEMA Consulting Continuous Compliance https://github.com/demaconsulting/ContinuousCompliance approach, which enforces quality and compliance gates on every CI/CD run instead of as a last-mile activity.

Core Principles

  • Requirements Traceability: Every requirement MUST link to passing tests
  • Quality Gates: All quality checks must pass before merge
  • Documentation Currency: All docs auto-generated and kept current
  • Automated Evidence: Full audit trail generated with every build

Required Compliance Tools

Linting Tools (ALL Must Pass)

  • markdownlint-cli2: Markdown style and formatting enforcement
  • cspell: Spell-checking across all text files (use .cspell.yaml for technical terms)
  • yamllint: YAML structure and formatting validation
  • Language-specific linters: Based on repository technology stack

Quality Analysis

  • SonarQube/SonarCloud: Code quality and security analysis
  • CodeQL: Security vulnerability scanning (produces SARIF output)
  • Static analyzers: Microsoft.CodeAnalysis.NetAnalyzers, SonarAnalyzer.CSharp, etc.

Requirements & Compliance

  • ReqStream: Requirements traceability enforcement (dotnet reqstream --enforce)
  • ReviewMark: File review status enforcement
  • BuildMark: Tool version documentation
  • VersionMark: Version tracking across CI/CD jobs

Key Configuration Files

Essential Files (Repository-Specific)

  • lint.sh / lint.bat - Cross-platform comprehensive linting scripts
  • .editorconfig - Code formatting rules
  • .cspell.yaml - Spell-check configuration and technical term dictionary
  • .markdownlint-cli2.yaml - Markdown linting rules
  • .yamllint.yaml - YAML linting configuration
  • package.json - Node.js dependencies for linting tools

Compliance Files

  • requirements.yaml - Root requirements file with includes
  • .reviewmark.yaml - File review definitions and tracking
  • CI/CD pipeline files with quality gate enforcement

Continuous Compliance Workflow

CI/CD Pipeline Stages (Standard)

  1. Lint: ./lint.sh or lint.bat - comprehensive linting suite
  2. Build: Compile with warnings as errors
  3. Analyze: SonarQube/SonarCloud, CodeQL security scanning
  4. Test: Execute all tests, generate coverage reports
  5. Validate: Tool self-validation tests
  6. Document: Generate requirements reports, trace matrix, build notes
  7. Enforce: Requirements traceability, file review status
  8. Publish: Generate final documentation (Pandoc → PDF)

Quality Gate Enforcement

All stages must pass before merge. Pipeline fails immediately on:

  • Any linting errors
  • Build warnings or errors
  • Security vulnerabilities (CodeQL)
  • Requirements without test coverage
  • Outdated file reviews
  • Missing documentation

Continuous Compliance Requirements

This repository follows continuous compliance practices from DEMA Consulting Continuous Compliance https://github.com/demaconsulting/ContinuousCompliance.

Core Requirements Traceability Rules

  • ALL requirements MUST be linked to tests - Enforced in CI via dotnet reqstream --enforce
  • NOT all tests need requirement links - Tests may exist for corner cases, design validation, failure scenarios
  • Source filters are critical - Platform/framework requirements need specific test evidence

For detailed requirements format, test linkage patterns, and ReqStream integration, see the Requirements and Test Source Filters sections below.

Tech Stack

  • C# (latest), .NET 8.0/9.0/10.0, MSTest, dotnet CLI, NuGet

Key Files

  • requirements.yaml - Root requirements file using includes: to reference docs/reqstream/ files
  • docs/reqstream/ - Per-software-unit, platform, and OTS requirements YAML files
  • .editorconfig - Code style (file-scoped namespaces, 4-space indent, UTF-8, LF endings)
  • .cspell.yaml, .markdownlint-cli2.yaml, .yamllint.yaml - Linting configs

Requirements

  • All requirements MUST be linked to tests (prefer BuildMark_* self-validation tests for command-line behavior)
  • Not all tests need to be linked to requirements (tests may exist for corner cases, design testing, failure-testing, etc.)
  • Enforced in CI: dotnet reqstream --requirements requirements.yaml --tests "test-results/**/*.trx" --enforce
  • When adding features: add requirement + link to test
  • See Requirements Agent for detailed test coverage strategy

Test Source Filters

Test links in requirements.yaml can include a source filter prefix to restrict which test results count as evidence. This is critical for platform and framework requirements - do not remove these filters.

  • windows@TestName - proves the test passed on a Windows platform
  • ubuntu@TestName - proves the test passed on a Linux (Ubuntu) platform
  • macos@TestName - proves the test passed on a macOS platform
  • net8.0@TestName - proves the test passed under the .NET 8 target framework
  • net9.0@TestName - proves the test passed under the .NET 9 target framework
  • net10.0@TestName - proves the test passed under the .NET 10 target framework
  • dotnet8.x@TestName - proves the self-validation test ran on a machine with .NET 8.x runtime
  • dotnet9.x@TestName - proves the self-validation test ran on a machine with .NET 9.x runtime
  • dotnet10.x@TestName - proves the self-validation test ran on a machine with .NET 10.x runtime

Without the source filter, a test result from any platform/framework satisfies the requirement. Adding the filter ensures the CI evidence comes specifically from the required environment.

Testing

  • Test Naming: BuildMark_FeatureBeingValidated for self-validation tests
  • Self-Validation: All tests run via --validate flag and can output TRX/JUnit format
  • Test Framework: Uses DemaConsulting.TestResults library for test result generation
  • MSTest v4: Use Assert.HasCount(), Assert.IsEmpty(), Assert.DoesNotContain() (not old APIs)
  • Console Tests: Always save/restore Console.Out in try/finally

Code Style

  • XML Docs: On ALL members (public/internal/private) with spaces after /// in summaries
  • Errors: ArgumentException for parsing, InvalidOperationException for runtime issues
  • Namespace: File-scoped namespaces only
  • Using Statements: Top of file only (no nested using declarations except for IDisposable)
  • String Formatting: Use interpolated strings ($"") for clarity
  • No code duplication: Extract to properties/methods

Project Structure

  • docs/ - Documentation and compliance artifacts
    • reqstream/ - Per-software-unit, platform, and OTS requirements YAML files (included by root requirements.yaml)
    • Auto-generated reports (requirements, justifications, trace matrix)
  • src/ - Source code files
  • test/ - Test files
  • .github/workflows/ - CI/CD pipeline definitions (build.yaml, build_on_push.yaml, release.yaml)
  • Configuration files: .editorconfig, .reviewmark.yaml, .cspell.yaml, .yamllint.yaml, etc.

Key Source Files

  • Context.cs: Handles command-line argument parsing, logging, and output
  • Program.cs: Main entry point with version/help/validation routing
  • Validation.cs: Self-validation tests with TRX/JUnit output support

Build and Test

# Build the project
dotnet build --configuration Release

# Run self-validation
dotnet run --project src/DemaConsulting.BuildMark \
  --configuration Release --framework net10.0 --no-build -- --validate

# Use convenience scripts
./build.sh    # Linux/macOS
build.bat     # Windows

Documentation

  • User Guide: docs/guide/guide.md
  • Requirements: requirements.yaml includes docs/reqstream/ files → auto-generated docs
  • Build Notes: Auto-generated via BuildMark
  • Code Quality: Auto-generated via CodeQL and SonarMark
  • Trace Matrix: Auto-generated via ReqStream

CI/CD

  • Quality Checks: Markdown lint, spell check, YAML lint
  • Build: Multi-platform (Windows/Linux/macOS)
  • CodeQL: Security scanning
  • Integration Tests: .NET 8/9/10 on Windows/Linux/macOS
  • Documentation: Auto-generated via Pandoc + Weasyprint

Common Tasks

# Format code
dotnet format

# Run all linters
./lint.sh     # Linux/macOS
lint.bat      # Windows

# Pack as NuGet tool
dotnet pack --configuration Release

Agent Report Files

Upon completion, create a report file at .agent-logs/[agent-name]-[subject]-[unique-id].md that includes:

  • A concise summary of the work performed
  • Any important decisions made and their rationale
  • Follow-up items, open questions, or TODOs

Store agent logs in the .agent-logs/ folder so they are ignored via .gitignore and excluded from linting and commits.

Markdown Link Style

  • AI agent markdown files (.github/agents/*.md): Use inline links [text](url) so URLs are visible in agent context
  • README.md: Use absolute URLs (shipped in NuGet package)
  • All other markdown files: Use reference-style links [text][ref] with [ref]: url at document end

Notable Absent Files

  • CHANGELOG.md: Not present - changes are captured in the auto-generated build notes