docs: optimize AGENTS.md for AI agent efficiency

[HardlyDifficult]

Summary

• Remove PR Review Format section (reference canton/AGENTS.md instead)
• Condense LocalNet section to reference localnet skill
• Condense Linear API section to reference linear-api skill
• Reduces file from 392 to 232 lines (~40% reduction)

Context

Based on analysis of all Fairmint repos' agent docs. Skills are centralized in fairmint-workspace for cross-repo access.

Test plan

• AGENTS.md still readable and contains all essential info
• LocalNet quick start commands still work

---

Note

Low Risk
Docs-only change that primarily removes/condenses guidance; main risk is losing repo-specific troubleshooting details for contributors.

Overview
AGENTS.md is significantly condensed by removing the inlined Linear GraphQL curl example and most LocalNet setup/troubleshooting details, replacing them with brief pointers to the centralized linear-api and localnet skills.

It also drops the repository-specific PR Review Format section, relying on shared conventions in canton/AGENTS.md instead, while keeping a minimal LocalNet quick-start command sequence.

^{Written by Cursor Bugbot for commit 5b7cffe. This will update automatically on new commits. Configure here.}

[claude]

Claude finished @HardlyDifficult's task —— View job

---

PR Review Complete ✓

Reviewing the AGENTS.md optimization changes:

Todo List:

• Read current AGENTS.md file
• Review git diff to understand what was removed
• Analyze condensed content for completeness
• Check cross-references and skill references
• Provide comprehensive review feedback

Review Summary

Overall Assessment: ✅ Approved - This is a well-executed documentation optimization that achieves its goals without compromising essential information.

Code Quality and Best Practices ✅

• Excellent condensation strategy: The PR successfully reduces file size from 392 to 232 lines (~40% reduction) while maintaining all essential information
• Proper cross-referencing: Replaced verbose inline content with appropriate references to centralized skills and shared documentation
• Maintains consistency: The file structure and formatting remain consistent with project conventions

Content Analysis ✅

What was removed (appropriately):

• 11 lines of verbose Linear GraphQL API examples → replaced with skill reference AGENTS.md:13
• 34-line PR Review Format section → appropriately deferred to canton/AGENTS.md
• 114 lines of detailed LocalNet documentation → condensed to essential quick-start commands with skill reference

Essential information preserved:

• Quick start commands for LocalNet still present (AGENTS.md:166-174)
• All architectural guidance maintained
• Development patterns and conventions intact
• Cross-references to detailed documentation remain accessible

Potential Issues and Considerations

Minor Concerns:

• Assumption about skill availability: References to linear-api and localnet skills assume they exist and are accessible to users. Consider verifying these skills contain the referenced information.
• LocalNet troubleshooting gap: While detailed troubleshooting was moved to the localnet skill, some basic troubleshooting might be helpful inline for immediate issues.

Performance Considerations ✅

• Reduced file size: 40% reduction improves load times and readability
• Better information architecture: Centralized skills reduce duplication across repositories
• Improved maintenance: Less duplicate content to maintain

Security Concerns ✅

• No security-sensitive content was modified
• OAuth2 credentials references appropriately moved to skill
• No exposure of sensitive information

Test Coverage ✅

The test plan in the PR description is appropriate:

• AGENTS.md readability ✓ (confirmed through review)
• LocalNet quick start commands preserved ✓ (AGENTS.md:166-174)

Recommendations

1. Verify skill references: Ensure the linear-api and localnet skills exist and contain the referenced content
2. Consider minimal troubleshooting: Perhaps add 1-2 lines for the most common LocalNet issues (Docker daemon, port conflicts) with reference to skill for details

Final Verdict

This PR successfully optimizes the documentation while maintaining all essential information. The condensation strategy is well-thought-out and the cross-references are appropriate. The reduction in file size will improve maintainability and user experience.

✅ Recommended for merge

---