Add AGENTS.md for AI agent guidance

[ralphbean]

User description

Summary

• Add AGENTS.md containing project-specific guidance for AI coding agents
• Symlink CLAUDE.md to AGENTS.md for compatibility with Claude Code
• Add .agentready to .gitignore

Details

The AGENTS.md file provides:

• Quick reference commands for testing (tox), linting (flake8, black, isort), and running the service
• High-level architecture overview explaining the data flow and core components
• Links to existing documentation (README.md, CONTRIBUTING.md) to avoid duplication

This helps AI agents quickly understand the codebase structure and common development tasks.

🤖 Generated with Claude Code

---

PR Type

Documentation

---

Description

• Add AGENTS.md with AI agent guidance and architecture overview

• Create CLAUDE.md symlink for Claude Code compatibility

• Add .agentready to .gitignore for agent-related files

---

Diagram Walkthrough

flowchart LR
  A["AGENTS.md<br/>AI Agent Guidance"] --> B["Quick Reference<br/>Commands"]
  A --> C["Architecture<br/>Overview"]
  A --> D["Component<br/>Documentation"]
  E["CLAUDE.md<br/>Symlink"] -.->|"points to"| A
  B --> F["Testing/Linting<br/>Commands"]
  C --> G["Data Flow<br/>Diagram"]
  D --> H["Core Components<br/>Description"]

Loading

File Walkthrough

	Relevant files
Documentation	AGENTS.md AI agent guidance with commands and architecture                  AGENTS.md Provides comprehensive guidance for AI coding agents working with the codebase Includes quick reference commands for testing with tox, linting with flake8/black/isort Documents the architecture with data flow and core component descriptions References existing documentation (README.md, CONTRIBUTING.md) to avoid duplication +102/-0  CLAUDE.md Symlink to AGENTS.md for Claude Code                                          CLAUDE.md Creates a symlink pointing to AGENTS.md for Claude Code compatibility Enables Claude Code to automatically discover agent guidance +1/-0
Configuration changes	.gitignore Add .agentready to gitignore                                                          .gitignore Adds .agentready to gitignore to exclude agent-related temporary files

---

[qodo-code-review]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
Update

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[ralphbean]

I'm using our repo here as a test for https://github.com/ambient-code/agentready

[qodo-code-review]

PR Code Suggestions ✨

Latest suggestions up to 817e896

Category	Suggestion	Impact
General	Fix incorrect configuration requirement Correct the description of required configuration keys for GitHub Projects integration to remove a repeated key and clarify the usage of issue_updates. AGENTS.md [103] -- **Configuration**: Requires `github_project_number`, `github_project_fields`, and `github_project_fields` in `issue_updates` +- **Configuration**: Requires `github_project_number` and `github_project_fields`, and `issue_updates` must include `github_project_fields` Apply / Chat Suggestion importance[1-10]: 5 __ Why: The suggestion correctly identifies a repetitive and confusing statement in the documentation and proposes a clearer, more accurate version that aligns with the provided example.	Low
	Correct a spelling mistake Correct the spelling of "spectactular" to "spectacular". AGENTS.md [84] -- Manages upstream rate limiting (and does a less than spectactular job at it) +- Manages upstream rate limiting (and does a less than spectacular job at it) Apply / Chat Suggestion importance[1-10]: 2 __ Why: The suggestion correctly identifies and fixes a spelling error, which is a minor but valid improvement to the documentation's quality.	Low
More

---

Previous suggestions

Suggestions up to commit d242b79

Category	Suggestion	Impact
General	Replace duplicate with reference To avoid maintenance overhead, replace the duplicated content in CLAUDE.md with a reference to AGENTS.md. CLAUDE.md [1-102] # CLAUDE.md -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. -... +See [AGENTS.md](AGENTS.md) for up-to-date AI agent guidance. Suggestion importance[1-10]: 7 __ Why: This is an excellent suggestion that significantly improves maintainability by eliminating duplicated content between AGENTS.md and CLAUDE.md, establishing a single source of truth.	Medium
	Correct document header Correct the header in AGENTS.md to match its filename for clarity and consistency. AGENTS.md [1] -# CLAUDE.md +# AGENTS.md Suggestion importance[1-10]: 4 __ Why: This is a valid and good suggestion. The file AGENTS.md has a title # CLAUDE.md, which is inconsistent with the filename and its purpose as a general guide.	Low

[ralphbean]

Ah, the duplicate things that qodo sees here are red herrings, b/c CLAUDE.md is a symlink to AGENTS.md. There's not really duplication there.

[webbnh]

Looks good. I just have a couple of additional comments.

[webbnh]

github_project_number is optional -- it's required only for disambiguation for issues which are referenced by more than one project; however, if specified, only project metadata from the specified project will be used, so if an issue is associated only with another project (e.g., because the configured project has been closed because the team has started using a new project) no project fields will be sync'd. (That is, if a team is going to use this feature, they need to keep it up to date.)

[webbnh]

github_project_fields, and github_project_fields in issue_updates

The repetition of "github_project_fields" is potentially confusing. Perhaps something like

the github_project_fields configuration key and the "github_project_fields" entry in the issue_updates key.

(Note the quotes around the entry, as distinguishing from the keys.)

[webbnh]

Qodo concurs (and has a more concise suggestion for fixing it). It also found a misspelling (in text which you should probably just delete 😄).

[webbnh]

@qodo-code-review, I don't know if you read these comments, but the duplication between AGENTS.md and CLAUDE.md is because the CLAUDE.md file is a symbolic link to AGENTS.md, so the contents appear to be the same, depending on how they are viewed.