Standardize on AGENTS.md

[cmungall]

See
anthropics/claude-code#6235

Until the above is closed, we should switch the copier template

1. switch to AGENTS.md being SoT
2. symlink from CLAUDE.md to AGENTS.md (as we do for .goosehints etc)

The symlink is a bit annoying, it has to be done via justfile target because the md file is made from jinja

[github-actions]

Issue Summary: Standardize on AGENTS.md

Overview

This issue proposes transitioning the copier template from using CLAUDE.md as the source of truth to AGENTS.md, with a symlink fallback from CLAUDE.md to maintain compatibility. This change aligns with the broader AI tooling ecosystem's movement toward standardizing on AGENTS.md for project instructions.

Context and Background

Upstream Issue: The referenced Claude Code issue #6235 discusses adding support for AGENTS.md as a fallback to CLAUDE.md. The community is actively working toward a dual-file approach where:

1. CLAUDE.md remains the priority for Claude-specific instructions
2. AGENTS.md serves as a fallback for general AI agent instructions
3. This enables interoperability across different AI coding tools

Current Repository Structure:

• template/CLAUDE.md.jinja exists as a Jinja template for generating CLAUDE.md files
• No AGENTS.md template currently exists
• The repository uses copier for templating

Proposed Changes

1. Switch to AGENTS.md as Source of Truth

   • Create template/AGENTS.md.jinja
   • Migrate content from template/CLAUDE.md.jinja
   • Update the template to generate AGENTS.md files

2. Create Symlink from CLAUDE.md to AGENTS.md

   • Implement via justfile target (due to Jinja template complexity)
   • Similar to existing symlink patterns mentioned (.goosehints etc.)

Technical Considerations

Challenge: The symlink creation is "annoying" because the markdown file is generated from Jinja templates, requiring post-processing through justfile targets.

Implementation Strategy:

• Modify the copier template generation process
• Add justfile target to create CLAUDE.md → AGENTS.md symlink after template instantiation
• Ensure backward compatibility for existing Claude Code workflows

Benefits

1. Ecosystem Alignment: Follows emerging standards in AI tooling community
2. Future-Proofing: Prepares for when Claude Code officially supports AGENTS.md
3. Interoperability: Enables use with other AI coding tools that expect AGENTS.md
4. Backward Compatibility: Maintains existing Claude Code functionality via symlink

Related Issues

• Issue Add more background to README #1: Documentation improvements (may need updating after this change)
• Issue Explain what this repo is for #2: Repository explanation (closed, but provides context on repo purpose)

Status

• Priority: Enhancement
• Complexity: Medium (due to template generation and symlink automation)
• Dependencies: Waiting for Claude Code #6235 resolution (though can proceed independently)

This change represents a strategic alignment with the broader AI tooling ecosystem while maintaining compatibility with current Claude Code usage patterns.