Skip to content

Remove AGENTS.md and associated references. #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pidster merged 1 commit into from
Oct 24, 2025
Merged

Remove AGENTS.md and associated references. #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion .github/README.github.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
13 changes: 12 additions & 1 deletion .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:**
Expand All @@ -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.

<!--
==============================================================================
Expand Down
2 changes: 1 addition & 1 deletion .github/instructions/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
19 changes: 14 additions & 5 deletions .github/prompts/copilot-setup-check.prompt.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand All @@ -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**
Expand Down
32 changes: 0 additions & 32 deletions AGENTS.md
View file
Open in desktop

This file was deleted.

3 changes: 0 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

Expand Down Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion plans/TODO.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
2 changes: 0 additions & 2 deletions recommendations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. |

Expand Down Expand Up @@ -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 |
Expand Down