Skip to content

AGENTS.md

Latest commit

 

History

History
160 lines (118 loc) · 6.69 KB

AGENTS.md

File metadata and controls

160 lines (118 loc) · 6.69 KB

Agent Quick Reference

Project-specific guidance for agents working on VersionMark - a tool for capturing and publishing tool version information across CI/CD environments.

Available Specialized Agents

  • Requirements Agent - Develops requirements and ensures test coverage linkage
  • Technical Writer - Creates accurate documentation following regulatory best practices
  • Software Developer - Writes production code and self-validation tests in literate style
  • Test Developer - Creates unit and integration tests following AAA pattern
  • Code Quality Agent - Enforces linting, static analysis, and security standards
  • Repo Consistency Agent - Ensures downstream repositories remain consistent with template patterns

Agent Selection Guide

  • Fix a bug → Software Developer
  • Add a new feature → Requirements Agent → Software Developer → Test Developer
  • Write a test → Test Developer
  • Fix linting or static analysis issues → Code Quality Agent
  • Update documentation → Technical Writer
  • Add or update requirements → Requirements Agent
  • Ensure test coverage linkage in requirements.yaml → Requirements Agent
  • Run security scanning or address CodeQL alerts → Code Quality Agent
  • Propagate template changes → Repo Consistency Agent

Tech Stack

  • C# (latest), .NET 8.0/9.0/10.0, dotnet CLI, NuGet
  • YAML configuration files (.versionmark.yaml)
  • JSON for version capture data
  • Markdown for published documentation

VersionMark Overview

VersionMark is a tool that:

  • Captures tool versions from CI/CD environments (with --job-id)
  • Publishes consolidated version information to markdown
  • Uses .versionmark.yaml config to define tools and capture methods
  • Supports OS-specific command overrides (windows, linux, macos)
  • Consolidates common versions; reports conflicting versions by job-id

Key Files

  • .versionmark.yaml - Configuration defining tools to capture and how to extract versions
  • requirements.yaml - All requirements with test linkage (enforced via dotnet reqstream --enforce)
  • .editorconfig - Code style (file-scoped namespaces, 4-space indent, UTF-8, LF endings)
  • .cspell.json, .markdownlint-cli2.jsonc, .yamllint.yaml - Linting configs

Requirements

  • All requirements MUST be linked to tests (prefer VersionMark_* self-validation tests)
  • 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

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: VersionMark_MethodUnderTest_Scenario 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

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

Project Structure

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

Build and Test

# Build the project
dotnet build --configuration Release

# Run unit tests
dotnet test --configuration Release

# Run self-validation
dotnet run --project src/DemaConsulting.VersionMark \
  --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 -> auto-generated docs
  • Build Notes: Auto-generated via BuildMark
  • Code Quality: Auto-generated via CodeQL and SonarMark
  • Trace Matrix: Auto-generated via ReqStream
  • CHANGELOG.md: Not present - changes are captured in the auto-generated build notes

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

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

When agents need to write report files to communicate with each other or the user, follow these guidelines:

  • Naming Convention: Use the pattern AGENT_REPORT_xxxx.md (e.g., AGENT_REPORT_analysis.md, AGENT_REPORT_results.md)
  • Purpose: These files are for temporary inter-agent communication and should not be committed
  • Exclusions: Files matching AGENT_REPORT_*.md are automatically:
    • Excluded from git (via .gitignore)
    • Excluded from markdown linting
    • Excluded from spell checking