Sync compliance docs and lint templates with TemplateDotNetLibrary PR #67

docs/agentic.md

@@ -34,32 +34,18 @@ is a compact quick-reference card covering everything an agent needs to know to
 ```markdown
 # Agent Quick Reference
 
-## Available Specialized Agents
+## Key Compliance Files
 
-- **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
-- **Test Developer** - Creates unit and integration tests
-- **Code Quality Agent** - Enforces linting, static analysis, and security standards
-- **Code Review Agent** - Assists in performing formal file reviews
-- **Repo Consistency Agent** - Ensures downstream repositories remain consistent with template patterns
+- `requirements.yaml` — all project requirements (ALL must be linked to passing tests)
+- `.reviewmark.yaml` — files requiring formal review and named review-set groupings
+- `.cspell.yaml`, `.markdownlint-cli2.yaml`, `.yamllint.yaml` — linting configuration
+- `.editorconfig` — code formatting rules
 
-## Agent Selection Guide
+## Requirements Rules
 
-- 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**
-- Run security scanning or address CodeQL alerts → **Code Quality Agent**
-- Perform a formal file review → **Code Review Agent**
-- Propagate template changes → **Repo Consistency Agent**
-
-## Requirements
-
-- All requirements MUST be linked to tests (enforced via `dotnet reqstream --enforce`)
-- When adding features: add requirement + link to test
+- ALL requirements MUST be linked to tests (enforced via `dotnet reqstream --enforce`)
+- When adding features: add a requirement entry and link to at least one test
+- When writing tests: name them so they can be linked in `requirements.yaml`
 
 ## Test Source Filters
 
@@ -76,6 +62,7 @@ is a compact quick-reference card covering everything an agent needs to know to
 
 dotnet build --configuration Release
 dotnet test --configuration Release
+./lint.sh   # or lint.bat on Windows
 ```
 
 ### .github/agents/ — Specialized Role Instructions
@@ -84,23 +71,10 @@ For projects that use specialized agent roles, each role has its own instruction
 `.github/agents/`. These files define the role's responsibilities, when to invoke it, what it owns,
 and which other agents it defers to.
 
-DEMA Consulting projects define the following specialized roles:
-
-| Agent | File | Responsibilities |
-| :---- | :--- | :--------------- |
-| Requirements Agent | `requirements-agent.md` | Creates and maintains `requirements.yaml`; determines test coverage strategy |
-| Technical Writer | `technical-writer.md` | Creates and maintains documentation following regulatory best practices |
-| Software Developer | `software-developer.md` | Writes production code and self-validation tests in literate style |
-| Test Developer | `test-developer.md` | Creates unit and integration tests following the AAA pattern |
-| Code Quality Agent | `code-quality-agent.md` | Enforces all quality gates (linting, static analysis, requirements traceability) |
-| Code Review Agent | `code-review-agent.md` | Performs formal ReviewMark file reviews; elaborates review-sets and produces structured findings reports |
-| Repo Consistency Agent | `repo-consistency-agent.md` | Ensures downstream repositories remain consistent with template patterns |
-
-The `AGENTS.md` file should also include an **Agent Selection Guide** — a short decision table that
-maps common tasks (fix a bug, add a feature, update documentation, perform a review) to the
-appropriate agent role. This guide helps both human developers and AI agents quickly identify which
-specialized role to invoke for a given task, reducing the risk of using the wrong agent or
-duplicating effort across roles.
+The exact set of agents varies by project, but common roles include development, quality assurance,
+code review, and repository consistency. The `AGENTS.md` file should also include a delegation
+guide — a short section mapping common tasks to the appropriate agent role, helping both human
+developers and AI agents quickly identify which role to invoke for a given task.
 
 Role files use the GitHub Copilot agent front-matter format:
 
@@ -115,6 +89,19 @@ description: Develops requirements and ensures appropriate test coverage linkage
 ...
 ```
 
+### Additional Guidance Files
+
+Beyond `AGENTS.md` and role files, projects may include additional guidance files with detailed
+standards and conventions agents can load when relevant to their task. Unlike the compact
+quick-reference in `AGENTS.md`, these files contain the full detail agents need to produce
+compliant output on the first attempt — covering areas such as requirements management, file
+review configuration, documentation structure, and code style.
+
+By placing these guidance files in the repository alongside the code they govern, projects make
+their standards self-documenting: an agent working on requirements can read the requirements
+guidance, an agent performing a review can read the review guidance, and so on — without any
+external configuration or pre-training.
+
 ## What Helps Agents Most
 
 The following information, when present in `AGENTS.md` or role files, has the highest impact on
@@ -168,17 +155,18 @@ without additional correction.
 ## Agent Report Files
 
 When agents need to communicate intermediate results or hand off work between roles, they write
-report files. DEMA Consulting projects use a naming convention that keeps these files out of the
-committed codebase:
+report files to a dedicated folder. DEMA Consulting projects use a `.agent-logs/` folder that is
+excluded from source control and linting:
 
-- **Pattern**: `AGENT_REPORT_<description>.md` (e.g., `AGENT_REPORT_analysis.md`)
-- **Purpose**: Temporary inter-agent communication; not intended for long-term storage
-- **Exclusions**: Files matching this pattern are excluded from:
+- **Location**: `.agent-logs/[agent-name]-[subject]-[unique-id].md`
+- **Purpose**: Records work performed, decisions made, and follow-up items; also used for temporary
+  inter-agent communication
+- **Exclusions**: The `.agent-logs/` folder is excluded from:
   - Git tracking (via `.gitignore`)
   - Markdown linting
   - Spell checking
 
-This prevents agent-generated scratch files from polluting the project history or triggering false
+This prevents agent-generated log files from polluting the project history or triggering false
 linting failures.
 
 ## Continuous Compliance as Agent Context
@@ -190,11 +178,13 @@ Compliance project provides an agent with:
 - **What to build** — `requirements.yaml` defines all requirements
 - **How to prove it** — test naming conventions and source filters define the evidence format
 - **What style to follow** — `.editorconfig`, `.cspell.yaml`, `.markdownlint-cli2.yaml`, `.yamllint.yaml`
-- **What gates to pass** — `AGENTS.md` and role files enumerate every CI enforcement step
+- **What standards to apply** — guidance files in the repository provide detailed domain-specific rules
+- **What gates to pass** — `AGENTS.md` enumerates every CI enforcement step
 - **Where to look** — the documentation map points to guides, requirements, and trace matrices
 
-An agent that reads `AGENTS.md` at the start of every session has all of this context available
-immediately, without needing to discover it through trial and error.
+An agent that reads `AGENTS.md` at the start of every session — and then loads any additional
+guidance files relevant to its task — has all of this context available immediately, without
+needing to discover it through trial and error.
 
 ## ReviewMark and AI-Assisted Reviews