[codex] Add shared AI agent setup

[cmungall]

Summary

• add a repo-level AGENTS.md with practical guidance for AI coding agents
• add .goosehints and .github/copilot-instructions.md symlinks to the shared instructions
• update ai.just setup recipes to target AGENTS.md, skip unset secrets, and use the correctly spelled CLAUDE_CODE_OAUTH_TOKEN
• add a helper recipe for inviting the Dragon AI agent collaborator

Validation

• git diff --cached --check
• just --list -f ai.just in a clean worktree
• verified committed symlink targets in a clean worktree

[claude]

Claude finished @cmungall's task —— View job

---

Code Review for PR #75

Reviewing the shared AI agent setup implementation:

Todo List:

• Read and analyze all changed files
• Review AGENTS.md content for completeness and accuracy
• Review ai.just changes for correctness and best practices
• Check symlink implementation
• Assess security considerations
• Provide comprehensive review feedback

Review Summary

This PR implements a solid shared AI agent setup with well-structured configuration files. Overall, the implementation is clean and follows good practices.

✅ Strengths

1. Excellent consolidation approach: The AGENTS.md file provides a single source of truth that feeds multiple AI tools via symlinks
2. Comprehensive documentation: Clear project overview, repository structure, and practical guidance for AI agents
3. Secure secret handling: The ai.just script properly checks for environment variables before setting secrets
4. Proper symlink implementation: Both .goosehints and .github/copilot-instructions.md correctly point to AGENTS.md
5. Practical focus: Documentation emphasizes actionable content over theoretical discussion

🔍 Detailed Analysis

AGENTS.md (AGENTS.md:1-71)

• Content quality: Comprehensive coverage of project structure, repo management, and documentation standards
• Audience clarity: Well-defined primary (curators) and secondary (developers) audiences
• Standards: Clear guidelines for practical, immediately actionable content
• Tool guidance: Proper specification of uv for dependency management and MkDocs commands

ai.just (ai.just:1-50)

• Security: The set_secret_if_exists() function properly validates environment variables before setting secrets
• Error handling: Uses set -euo pipefail for robust bash error handling
• Flexibility: Supports both GH_* prefixed and plain environment variable names
• OAuth token: Correctly uses CLAUDE_CODE_OAUTH_TOKEN (fixed spelling from previous version)

Symlinks

• Correct targets: Both symlinks properly point to AGENTS.md
• Path accuracy: .github/copilot-instructions.md uses correct relative path ../AGENTS.md

🔒 Security Assessment

• No hardcoded secrets: All sensitive values are properly externalized to environment variables
• Safe secret handling: The bash script validates variables exist before attempting to use them
• Appropriate permissions: Dragon AI invitation uses write-level permissions (standard for AI collaborators)

⚡ Performance & Best Practices

• Efficient setup: Symlinks avoid content duplication while supporting multiple AI tools
• Build validation: Includes uv run mkdocs build --strict for documentation validation
• Tool-specific optimization: Uses established entry points (justfile targets) over generic commands

🎯 Test Coverage Considerations

While this PR doesn't include automated tests, the validation approach is appropriate:

• Manual verification of symlink targets ✅
• git diff --cached --check for whitespace issues ✅
• just --list -f ai.just for syntax validation ✅

For future enhancement, consider adding a simple CI check to validate symlink integrity.

📋 Minor Suggestions

1. Documentation consistency: The AGENTS.md structure differs slightly from CLAUDE.md (e.g., section naming). Consider aligning terminology where possible.

2. Recipe enhancement: Consider adding a validation recipe to ai.just that checks symlink integrity:

   validate-setup:
     test -L .goosehints && test "$(readlink .goosehints)" = "AGENTS.md"
     test -L .github/copilot-instructions.md && test "$(readlink .github/copilot-instructions.md)" = "../AGENTS.md"

🚀 Recommendation

Approve and merge. This PR successfully implements a clean, secure, and maintainable shared AI agent setup that follows repository conventions and security best practices.

---