[docs] Refactor AI agent documentation following best practices

[mattpodwysocki]

Summary

Refactors all AI agent documentation (CLAUDE.md, AGENTS.md, Copilot instructions) to follow industry best practices from https://www.humanlayer.dev/blog/writing-a-good-claude-md.

Changes

1. CLAUDE.md (140 → 81 lines)

Improvements:

• ✅ Added missing "WHY" section explaining geospatial intelligence purpose
• ✅ Removed stale code examples, replaced with file:line references
• ✅ Removed linter-appropriate rules (ESLint/Prettier handle these)
• ✅ Removed non-universal content (OTEL details, collaboration workflows)
• ✅ Added progressive disclosure via docs/ references
• ✅ Now under recommended 100-line limit

2. AGENTS.md (192 → 89 lines)

Improvements:

• ✅ Clarified distinct purpose from CLAUDE.md (for general AI assistants)
• ✅ Fixed factual errors: PolicyPipeline → HttpPipeline, fetchRequest.ts → httpPipeline.ts
• ✅ Removed massive duplication with CLAUDE.md
• ✅ Removed stale code examples, replaced with file references
• ✅ Added "Factual Errors to Watch For" section
• ✅ 54% size reduction

3. .github/copilot-instructions.md (58 → 51 lines)

Improvements:

• ✅ More focused on Copilot-specific concerns
• ✅ Removed redundancy with other documentation
• ✅ Added "Learning from the Codebase" section
• ✅ Clearer security and review guidance

4. docs/engineering_standards.md (NEW)

New file:

• Single source of truth for detailed engineering standards
• Contains all detailed rules removed from AI agent docs
• Allows AI agent docs to stay concise via progressive disclosure

5. README.md Contributing Section

Updates:

• Fixed outdated documentation descriptions
• Added reference to new docs/engineering_standards.md
• Clarified purpose of each documentation file
• Updated Quick Start steps

Best Practices Alignment

✅ Concise - All AI docs under 100 lines (CLAUDE.md: 81, AGENTS.md: 89)
✅ Complete - Has WHAT, WHY, and HOW (previously missing WHY)
✅ Current - Uses file:line references instead of stale code snippets
✅ Focused - Removed non-universally-applicable content
✅ Structured - Progressive disclosure via docs/ directory
✅ Appropriate - No "LLM as linter" anti-pattern
✅ Accurate - Fixed factual errors in AGENTS.md

Verification

Manual Testing Performed:

• ✅ All file:line references point to correct locations
• ✅ All internal links work correctly
• ✅ No duplication between documentation files
• ✅ Line counts under recommended limits
• ✅ CLAUDE.md loaded successfully in this Claude Code session
• ✅ All markdown renders correctly

Files to Review:

• CLAUDE.md - Claude Code specific guidance (81 lines)
• AGENTS.md - General AI assistant guidance (89 lines)
• .github/copilot-instructions.md - Copilot guidelines (51 lines)
• docs/engineering_standards.md - Detailed standards reference (85 lines)
• README.md - Updated Contributing section

Impact

• Better onboarding for AI coding assistants across all platforms
• Reduced confusion from redundant/contradictory guidance
• Faster comprehension due to conciseness
• More maintainable documentation structure
• Fixed misleading information that could cause AI agents to make errors

---

Note: This is documentation-only changes with no code modifications.