Switch to AGENTS.md as standard in copier template

[cmungall]

Fixes #8

[claude]

Claude finished @cmungall's task —— View job

---

PR Review: Switch to AGENTS.md as standard

Todo List:

• Read and understand the repository structure and CLAUDE.md
• Review justfile changes
• Review template/.github/workflows/claude.yml changes
• Review template/.github/workflows/dragon-ai.yml changes
• Review template/AGENTS.md.jinja (renamed file)
• Review template/ai.just changes
• Provide comprehensive feedback on code quality, bugs, performance, security, and test coverage

---

Code Review Results

Overall Assessment

This PR implements a sensible standardization by switching from CLAUDE.md to AGENTS.md as the primary configuration file for AI agents. The change maintains backward compatibility while establishing a more generic naming convention.

File-by-File Analysis

1. justfile (/justfile:9)

• Good: Simple addition of the setup-ai-instructions target to support the new structure
• Code Quality: ✅ Clean and follows existing patterns

2. template/.github/workflows/claude.yml (lines 84, 87-90)

• Enhancement: Added mcp__ols_mcp__search_all_ontologies and mcp__ols_mcp__get_terms_from_ontology to allowed tools
• Code Quality: ✅ These additions support ontology search capabilities which aligns well with the project's focus
• Security: ✅ Tool permissions are appropriately scoped

3. template/.github/workflows/dragon-ai.yml (lines 144-150)

• Enhancement: Added uv installation and Python virtual environment setup
• Code Quality: ✅ Follows modern Python dependency management practices
• Performance: ✅ Using uv instead of pip for faster dependency resolution
• Issue: ⚠️ Line 150 activates venv but subsequent steps may not inherit this activation

4. template/AGENTS.md.jinja (renamed from template/CLAUDE.md.jinja)

• Good: Comprehensive template covering multiple project types (LinkML, Python)
• Code Quality: ✅ Well-structured with clear sections and helpful guidance
• Content Quality: ✅ Includes best practices and specific tooling recommendations
• Minor Issue: ⚠️ Line 1 change from "CLAUDE.md" to "AGENTS.md" - title should match

5. template/ai.just (significant expansion)

• Excellent: Added comprehensive symlink management for multiple AI tools
• Code Quality: ✅ Implements the "AGENTS.md as standard" approach correctly
• Backward Compatibility: ✅ Creates symlinks to maintain compatibility with existing tools
• Security: ✅ Safe handling of environment variables with proper fallbacks
• Best Practice: ✅ Function-based approach for secret management is clean and maintainable

Specific Issues & Recommendations

1. Minor Bug in dragon-ai.yml: The virtual environment activation in line 150 may not persist to subsequent steps. Consider:

   - name: Install python tools
     run: |
       uv venv
       echo "$GITHUB_WORKSPACE/.venv/bin" >> $GITHUB_PATH

2. Template Title Consistency: In AGENTS.md.jinja line 1, update the title to reflect the new filename:

   # AGENTS.md for {{project_name}}

3. Documentation: Consider updating the repository's main documentation to reflect this standardization change.

Security Assessment

✅ No security concerns identified

• Environment variable handling follows secure practices
• GitHub Actions permissions are appropriately scoped
• No sensitive data exposure risks

Performance Assessment

✅ Performance improvements noted

• Migration to uv improves Python dependency installation speed
• Symlink approach is efficient for multi-tool compatibility

Test Coverage Assessment

⚠️ Limited test coverage visibility

• The justfile includes test targets for the copier functionality
• Consider adding tests to verify the new symlink creation behavior
• No obvious test coverage for the AI workflow configurations

Summary

This is a well-executed refactoring that standardizes on AGENTS.md while maintaining backward compatibility. The changes are logical, secure, and improve the project's tooling integration. The only issues are minor and easily addressed.

Recommendation: ✅ Approve with minor suggestions

---