docs: create comprehensive AGENTS.md and enhance AI agent guidance

[Copilot]

Overview

This PR improves AI agent guidance by creating a comprehensive AGENTS.md file and enhancing existing documentation. After thorough exploration of the repository (including running the CLI and tests), I've created documentation that will help AI coding agents (GitHub Copilot, Claude Code, Cursor, etc.) better understand the codebase and generate code that follows project patterns.

What's New

AGENTS.md (713 lines)

A comprehensive guide specifically designed for AI coding agents, covering:

• Repository Overview: Complete project structure with descriptions of all modules
• Development Environment Setup: Step-by-step instructions using uv, nox, and pytest
• Architecture & Design Patterns: In-depth coverage of the modulith architecture, service discovery pattern, and dependency injection
• Common Agent Tasks: 5 detailed examples including:
  • Adding a new module
  • Fixing bugs
  • Adding CLI commands
  • Writing tests
  • Updating documentation
• Testing Guidelines: Test organization, markers (sequential, long_running, scheduled, docker), coverage requirements, and fixture patterns
• Code Standards & Style: Quick reference for naming conventions, type hints, docstrings, and imports
• CI/CD & Workflows: Workflow structure, triggers, and local execution with act
• Documentation Standards: How to maintain CLAUDE.md files and generate CLI references
• Troubleshooting: 5 common issues with solutions
• AI Agent Best Practices: Clear DO/DON'T lists
• Quick Command Reference: All essential commands in one place

Enhanced Existing Documentation

CODE_STYLE.md

Expanded the "Guidance for AI Pair Programming" section from 5 to 8 points:

• Added requirement to read AGENTS.md first
• Emphasized following existing patterns
• Added verification of correct tool usage (uv not pip)
• Clarified coverage expectations (85% minimum, 100% target)

CONTRIBUTING.md

Added prominent note at the top directing AI agents to read AGENTS.md before contributing.

.github/copilot-instructions.md

Added reference to AGENTS.md as the primary resource for AI agents working with this repository.

CLAUDE.md

Added note explaining that AGENTS.md provides concise, task-oriented guidance for all AI agents, while CLAUDE.md provides detailed architectural guidance specifically for Claude Code.

Validation

All documentation has been validated by:

• ✅ Running CLI commands (uv run aignostics system health)
• ✅ Testing pytest with specific test files and markers
• ✅ Verifying service discovery pattern with actual code execution
• ✅ Checking all file paths and cross-references exist
• ✅ Confirming all command examples work correctly

Key Benefits

1. Faster Onboarding: AI agents can quickly understand repository structure and patterns
2. Better Code Quality: Agents will follow established patterns and standards
3. Reduced Errors: Clear guidance on common pitfalls and troubleshooting
4. Consistent Style: All agents will follow the same guidelines in CODE_STYLE.md
5. Comprehensive Coverage: From architecture to testing to deployment workflows

Example Usage

AI agents can now:

• Quickly understand the modulith architecture with service discovery
• Know to use locate_subclasses(BaseService) for finding services
• Follow the three-layer module pattern (Service, CLI, GUI)
• Use uv instead of pip for package management
• Run tests with appropriate markers
• Generate code that passes all linting and type checking

Files Changed

• New: AGENTS.md (713 lines)
• Modified: CODE_STYLE.md (+17 lines)
• Modified: CONTRIBUTING.md (+2 lines)
• Modified: .github/copilot-instructions.md (+5 lines)
• Modified: CLAUDE.md (+2 lines)

Total: +739 lines, -7 lines across 5 files

---

This comprehensive documentation ensures AI agents have all the context needed to generate high-quality code that follows project standards and patterns.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>PR AI Guidance</issue_title>
<issue_description>Improve Agent guidance.

Perform a thorough, deep and full exploration of this repository including running the CLI and tests, with the goal to improve guidance for AI agents, by improving existing markdown files for coding agents, and creating an AGENTS.md</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #154

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.