Remove AGENTS.md and associated references. (#8)

Author: pidster

.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
 

.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.
 
 <!--
 ==============================================================================

.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

.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**

AGENTS.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
 - See `CONTRIBUTING.md` for guidelines on contributing to this repository
 
@@ -160,7 +159,6 @@ flowchart LR
     %% Core Configuration Hub (Left)
     subgraph CONFIG ["🏠 Core Configuration"]
         CI["copilot-instructions.md"]
-        AGENTS["AGENTS.md"]
         README["README.md"]
     end
 
@@ -261,7 +259,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
 

README.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        |

plans/TODO.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      |