From 6211f265bcaa677783310c104b96db0fff55c06e Mon Sep 17 00:00:00 2001
From: Stuart Williams <pidster@users.noreply.github.com>
Date: Fri, 24 Oct 2025 12:27:50 +0100
Subject: [PATCH] Remove AGENTS.md and associated references.

---
 .github/README.github.md                      |  1 -
 .github/copilot-instructions.md               | 13 +++++++-
 .github/instructions/README.md                |  2 +-
 .github/prompts/copilot-setup-check.prompt.md | 19 ++++++++---
 AGENTS.md                                     | 32 -------------------
 README.md                                     |  3 --
 plans/TODO.md                                 |  2 +-
 recommendations.md                            |  2 --
 8 files changed, 28 insertions(+), 46 deletions(-)
 delete mode 100644 AGENTS.md

diff --git a/.github/README.github.md b/.github/README.github.md
index f502e58..4c2f5fe 100644
--- a/.github/README.github.md
+++ b/.github/README.github.md
@@ -29,7 +29,6 @@ Key SSOT anchors:
 
 See also:
 - Project overview in [README.md](../README.md)
-- Agent context in [AGENTS.md](../AGENTS.md)
 
 ### Custom Chat Modes
 
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 2992306..6332f83 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -42,6 +42,18 @@ This creates a self-documenting system for understanding how AI instructions wor
 ==============================================================================
 -->
 
+**CRITICAL REQUIREMENTS**
+- AI assistants must _never_ remove HTML comments explaining the purpose and design of each section.
+- HTML comments provide essential context for understanding the instructional design and MUST remain intact.
+
+<CRIITICAL_REQUIREMENT type="MANDATORY">
+  <HTML_COMMENT presence="REQUIRED">
+    AUDIENCE: Primarily humans, but applicable to all AI coding assistants
+    DESIGN PHILOSOPHY: Maximum clarity and comprehensiveness through clear explanations
+    PURPOSE: Explain the instructional design, reinforcement techniques, and compliance mechanisms used in this section
+   </HTML_COMMENT>
+</CRITICAL_REQUIREMENT>
+
 **Audience:** Primarily GitHub Copilot. This file provides Copilot-specific instructions and configuration for this repository.
 
 **Repository Context:**
@@ -50,7 +62,6 @@ This repository is a GitHub Template created by Capgemini's AI & Software Engine
 **Copilot Guidance:**
 - Follow the configuration and best practices outlined here when assisting in this repository.
 - Reference `README.md` for general orientation and project goals.
-- Reference `AGENTS.md` for broader AI agent instructions and context.
 
 <!--
 ==============================================================================
diff --git a/.github/instructions/README.md b/.github/instructions/README.md
index ebb8ac1..b7d71c1 100644
--- a/.github/instructions/README.md
+++ b/.github/instructions/README.md
@@ -80,7 +80,7 @@ Bad:  # Architecture
 ## Best practices
 
 - Keep instruction files focused (single responsibility). Prefer multiple small files over one large file.
-- Cross-reference `AGENTS.md` and `.github/copilot-instructions.md` for repository-wide policies.
+- Cross-reference `.github/copilot-instructions.md` for repository-wide policies.
 - Use examples liberally — AI systems map rules to examples well.
 
 ## Official docs
diff --git a/.github/prompts/copilot-setup-check.prompt.md b/.github/prompts/copilot-setup-check.prompt.md
index 38fc7cf..4070443 100644
--- a/.github/prompts/copilot-setup-check.prompt.md
+++ b/.github/prompts/copilot-setup-check.prompt.md
@@ -13,7 +13,6 @@ Perform a comprehensive evaluation of the repository's GitHub Copilot and AI age
 ## Evaluation Scope
 
 This evaluation will assess:
-- **AGENTS.md** - General AI agent instructions and repository context
 - **.github/copilot-instructions.md** - Copilot-specific configuration and guidelines
 - **.github/chatmodes/** - Custom conversational behaviors and specialized modes
 - **.github/prompts/** - Reusable prompt templates and slash commands
@@ -41,18 +40,23 @@ This evaluation will assess:
 
 ### Phase 1: Core Files Assessment
 
-1. **Check AGENTS.md existence and quality**
+1. **For each file type, check existence and quality**
    - Verify presence and structure
    - Assess clarity of repository context
    - Evaluate AI agent guidance completeness
    - Check for conflicting instructions warning mechanisms
+   - Verify effectiveness of XML semantic tags reinforcing critical requirements
+   - Suggest improvements for clarity and completeness
+   - Suggest enhancements for maintainability and organization
+   - Suggest additions for missing best practices
+   - Suggest removal of redundant or conflicting content
+   - Suggest reinforcements (e.g. XML, Mermaid) for critical policies
 
 2. **Evaluate .github/copilot-instructions.md**
    - Verify comprehensive project methodology coverage
    - Assess branching strategy and workflow definitions
    - Check commit message and naming conventions
-   - Evaluate coding standards and quality requirements
-   - Verify XML semantic tags for critical requirements
+   - Evaluate generic coding standards and quality requirements
 
 ### Phase 2: Advanced Configuration Review
 
@@ -61,18 +65,23 @@ This evaluation will assess:
    - Assess relevance to project needs
    - Check for mode-specific optimization
    - Evaluate documentation quality
+   - Evaluate conflicts with core instructions, custom instructions (per file type), or custom prompts
 
 4. **Review prompt templates**
    - Inventory available slash commands
    - Assess prompt structure and parameterization
    - Check tool integration and capability coverage
    - Evaluate reusability and maintenance
+   - Evaluate conflicts with core instructions, custom instructions (per file type), or custom chatmodes
 
 5. **Examine instruction files**
    - Catalog language/domain-specific instructions
-   - Assess coverage of technology stack
+   - Assess coverage of technology stack and frameworks
+   - Evaluate clarity and actionability of language/framework specific instructions
    - Check alignment with project requirements
    - Evaluate specificity and actionability
+   - Evaluate specific coding standards and quality requirements
+   - Evaluate conflicts with core instructions, custom chatmodes, or custom prompts
 
 ### Phase 3: Integration and Optimization
 6. **Repository structure alignment**
diff --git a/AGENTS.md b/AGENTS.md
deleted file mode 100644
index 464bbf5..0000000
--- a/AGENTS.md
+++ /dev/null
@@ -1,32 +0,0 @@
-# AGENTS
-
-This file provides general instructions and context for all AI agents working in this repository (not just Copilot).
-
-**Repository Overview:**
-
-- This is a GitHub Template created by Capgemini's AI & Software Engineering experts.
-- It contains practical examples of Copilot and agent configuration, plus educational resources.
-
-**For Humans:**
-
-- See [the main project README](./README.md) for a general project overview and orientation.
-
-**For AI Agents:**
-
-- Use this file to understand the project’s goals, structure, and best practices.
-- Reference configuration and documentation files for deeper context.
-- For Copilot-specific instructions, see `.github/copilot-instructions.md`.
-- Authoritative workflow rules (branching, commits, PRs, coverage policy) live in `.github/copilot-instructions.md` — link to it instead of duplicating.
-- Other AI Agents should consider `.github/copilot-instructions.md` as informative, but not supersede their own custom instruction files, if present.
-- It's critical to stop and alert the user if an AI finds conflicting instructions.
-- The assistant must never use emojis to decorate its responses to the user
-
-**Repository Structure for Docs and Plans:**
-
-- Documentation is stored in the `docs/` directory. This includes general documentation, architectural decision records (ADRs), and product requirements documents (PRDs).
-- Project plans and related planning materials are stored only in the `plans/` directory.
-- Strictly follow the instructions on plan creation and management that are found in the `plans/README.md`.
-- Agent todo items MUST be maintained as a Markdown checkbox list only in `plans/TODO.md`, not in any other agent-specific file.
-- Source code will be stored in the `src` directory.
-
-This file intentionally stays minimal; prefer linking to SSOT docs (see `README.md` Appendix: SSOT Source Map) over copying content.
diff --git a/README.md b/README.md
index 8f40a13..bae1c15 100644
--- a/README.md
+++ b/README.md
@@ -141,7 +141,6 @@ When adding new chat modes, prompts, or instructions:
 
 ## Where to find more information
 
-- See `AGENTS.md` for general AI agent instructions and project context
 - See `.github/copilot-instructions.md` for Copilot-specific rules and configuration
 
 ### Copilot Customisation
@@ -159,7 +158,6 @@ flowchart LR
     %% Core Configuration Hub (Left)
     subgraph CONFIG ["🏠 Core Configuration"]
         CI["copilot-instructions.md"]
-        AGENTS["AGENTS.md"]
         README["README.md"]
     end
 
@@ -260,7 +258,6 @@ flowchart LR
 ### Central Configuration Hub
 
 - `.github/copilot-instructions.md` serves as the primary configuration document, referencing most instruction files and core documentation
-- `AGENTS.md` provides repository-wide context and references key directories and processes
 
 ### Documentation Workflow
 
diff --git a/plans/TODO.md b/plans/TODO.md
index 7ed8817..8c49dec 100644
--- a/plans/TODO.md
+++ b/plans/TODO.md
@@ -26,7 +26,7 @@ How to use:
 | P1-09 | Small Plan Example          | Add lightweight “Small Feature Plan” example                             | `plans/examples/plan-small.md` (new)                                                                         | New example file added; linked from `plans/README.md`                                                                    | High     | AI    | Done        | Added example aligned to complexity-only; linked from plans README                                                     |
 | P1-10 | SSOT Source Map             | Add “Source Map” appendix to README linking SSOT designations            | `README.md`                                                                                                  | Appendix added with links mapping domains to SSOT files                                                                  | High     | AI    | Done        | Added Appendix: SSOT Source Map with links to core policies and anchors                                                |
 | P2-11 | GitHub README Consolidation | Fold `.github/README.github.md` into root `README.md` or leave stub      | `.github/README.github.md`; `README.md`                                                                      | Duplicated sections removed; unique GitHub-specific notes retained/merged; stub or removal justified                     | Medium   | AI    | Done        | Kept distinct .github README, pruned duplication, added SSOT links and pointers to root                                |
-| P2-12 | Agents Landing              | Keep `AGENTS.md` minimal; add explicit pointer to copilot-instructions   | `AGENTS.md`                                                                                                  | Line added: authoritative workflow rules in `.github/copilot-instructions.md`                                            | Medium   | AI    | Done        | Added explicit pointer to SSOT rules and note to keep file minimal                                                     |
+| P2-12 | Agents generic file              | Remove `AGENTS.md`   | `AGENTS.md`                                                                                                  | Line added: authoritative workflow rules in `.github/copilot-instructions.md`                                            | Medium   | AI    | Done        | Added explicit pointer to SSOT rules and note to keep file minimal                                                     |
 | P2-13 | Chat Modes SSOT             | Declare chat modes authoring SSOT and avoid meta duplication             | `.github/chatmodes/README.md`; all `*.chatmode.md`                                                           | README declares SSOT; each chat mode avoids restating meta-guidelines                                                    | Medium   | AI    | Done        | Added SSOT section to chatmodes README; inserted SSOT reference notes in all modes                                     |
 | P2-14 | Frontend Testing Reference  | Explicitly reference testing standards                                   | `.github/instructions/frontend.instructions.md`                                                              | Adds “Testing” subsection that links to Tester chat mode and BDD instructions                                            | Medium   | AI    | Done        | Added Testing section with links to Tester chat mode, BDD SSOT, and Quality Policy                                     |
 | P2-15 | ADR Save Validation         | Ensure ADR prompt enforces save path/versioning                          | `.github/prompts/write-adr.prompt.md`; `docs/ADRs/adr-template.md`                                           | Prompt validates save under `docs/ADRs/` with sequence/timestamp; ADR template includes Status field                     | Medium   | AI    | Done        | Prompt updated with sequence/timestamp rules, save validation, and commit guidance; template already has Status        |
diff --git a/recommendations.md b/recommendations.md
index e4afbc7..e2a6908 100644
--- a/recommendations.md
+++ b/recommendations.md
@@ -17,7 +17,6 @@ Status Legend:
 | File                                                               | Assessment                                                                                                | Issues / Risks                                                                                                                                                                                   | Recommendation                                                                                                                                                 |
 | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [.github/copilot-instructions.md](.github/copilot-instructions.md) | Comprehensive anchor (branching, commits, standards, repo overview). Strong reinforcement (XML, Mermaid). | Duplicates coverage & workflow rules already present in chat modes. Repository overview partially overlaps with [README.md](README.md) and [.github/README.github.md](.github/README.github.md). | Refine: Trim “Repository Overview” (point to README). Establish it as single source of truth (SSOT) for: branching, commit, PR workflow, global quality gates. |
-| [AGENTS.md](AGENTS.md)                                             | Lightweight cross‑entry overview for all AI agents.                                                       | Some repetition (structure, docs locations) already covered in [README.md](README.md).                                                                                                           | Keep: Leave as minimal orientation. Add explicit statement: “For authoritative workflow rules see .github/copilot-instructions.md”.                            |
 | [README.md](README.md)                                             | Broad narrative, feature catalog, diagrams, best practices.                                               | Overlaps with `.github/copilot-instructions.md` (methodology summaries) and `.github/chatmodes/README.md` (instruction philosophy).                                                              | Refine: Move “Best Practices” enforcement rules to a new “CONTRIBUTING.md” or keep here but reference as non-authoritative.                                    |
 | [.github/README.github.md](.github/README.github.md)               | GitHub config explainer; bridges discoverability.                                                         | Partial duplication of README sections (chat modes, instructions explanation).                                                                                                                   | Consolidate: Fold unique GitHub-specific notes into README; leave a short index stub or remove.                                                                |
 
@@ -175,7 +174,6 @@ Principles:
 | File                                            | Status      |
 | ----------------------------------------------- | ----------- |
 | .github/copilot-instructions.md                 | Refine      |
-| AGENTS.md                                       | Keep        |
 | README.md                                       | Refine      |
 | .github/README.github.md                        | Consolidate |
 | Developer.chatmode.md                           | Refine      |