Migrate to tool-agnostic agent structure and optimize documentation

[amccall-mindera]

Migrate to Tool-Agnostic AI Agent Structure

Overview

This PR restructures our AI agent system to be tool-agnostic, eliminating dependencies on specific AI coding assistants and dramatically reducing context overhead for AI agents.

Problem Statement

Previously, our AI agent documentation was:

• Tool-specific - .github/agents/ directory only worked with GitHub Copilot
• Massive - Single 966-line AGENTS.md file loaded for every operation
• Inefficient - Agents consumed full context even for simple tasks
• Duplicated - Tool-specific configs (.cursorrules, .clinerules) created maintenance burden

Solution

1. Tool-Agnostic Agent Structure

Moved agents from .github/agents/ to .ai/agents/

• Standard markdown format with YAML frontmatter
• Compatible with any AI coding assistant
• No proprietary formats or tool-specific configurations

Removed tool-specific files:

• .github/agents/ directory (7 files)
• .cursorrules (Cursor-specific)
• .clinerules (Cline-specific)

Simplified .github/copilot-instructions.md:

• Now just points to AGENTS.md (5 lines)
• Maintains GitHub Copilot compatibility

2. Documentation Restructure (89% Context Reduction)

Before:

• Single AGENTS.md: 966 lines
• All context loaded for every operation

After:

• AGENTS.md: 103 lines (core essentials only)
• Focused guides in Docs/ directory:
  • Architecture.md (359 lines) - MVVM, navigation, modules
  • GraphQL.md (54 lines) - GraphQL integration
  • Localization.md (36 lines) - L10n string catalog
  • Testing.md (53 lines) - Testing patterns
  • Development.md (144 lines) - Feature development process
  • CodeStyle.md (95 lines) - SwiftLint, conventions
  • QuickReference.md (131 lines) - Directories, commands, security

Result: Agents load minimal context by default, read detailed guides only when needed.

3. Fixed Agent References

All agent files now use:

• Correct relative paths (../../AGENTS.md not ../../../AGENTS.md)
• Direct links to guides (no broken anchor references)
• Consistent format across all 7 agents

Benefits

✅ Zero Tool Lock-In

Works with any AI coding assistant (GitHub Copilot, Cursor, Cline, Claude, etc.)

✅ Massive Performance Improvement

• Simple tasks: Load only 103 lines (vs 966) = 89% reduction
• Complex tasks: Load ~470 lines (vs 966) = 51% reduction

✅ Better Organization

• One topic per file
• Easy to find relevant information
• Clear separation of concerns

✅ Easier Maintenance

• Edit one file, commit, done
• No sync between multiple locations
• No tool-specific configurations to maintain

✅ Improved Developer Experience

• Faster agent responses
• Less token usage
• More focused guidance

File Structure

AGENTS.md (103 lines)           # Core rules, agent list, links
├── .ai/
│   └── agents/                 # 7 specialized agent definitions
│       ├── feature-orchestrator.agent.md
│       ├── spec-writer.agent.md
│       ├── graphql-specialist.agent.md
│       ├── ios-feature-developer.agent.md
│       ├── localization-specialist.agent.md
│       ├── testing-specialist.agent.md
│       └── mobile-security-specialist.agent.md
└── Docs/                       # Detailed guides (on-demand)
    ├── Architecture.md
    ├── GraphQL.md
    ├── Localization.md
    ├── Testing.md
    ├── Development.md
    ├── CodeStyle.md
    └── QuickReference.md

.github/copilot-instructions.md # Simple pointer to AGENTS.md

Changes Summary

Commits

1. Migrate to tool-agnostic agent structure - Move agents, remove tool-specific configs
2. Break down AGENTS.md into focused documentation - Create Docs/ guides
3. Update agent references - Point to AGENTS.md and Docs/

Files Changed

• 16 files changed (+926, -916)
• Removed: 7 files (.github/agents/, .cursorrules, .clinerules)
• Added: 7 files (Docs/ guides)
• Modified: 8 files (agent references, AGENTS.md)

Testing

✅ All agent file references validated (paths exist)
✅ No broken anchor links
✅ Backward compatible (GitHub Copilot still works via .github/copilot-instructions.md)
✅ Documentation hierarchy is clear and navigable

Migration Impact

For Developers

• ✅ No action required - Existing workflows continue to work
• ✅ Better docs - Easier to find specific information

For AI Agents

• ✅ Faster startup - Load only what's needed
• ✅ Better context - Focused guides for specific tasks
• ✅ Universal access - Works with any AI tool

Before & After Example

Simple Task (e.g., "Add a button")

Before: Load 966 lines
After: Load 103 lines
Improvement: 89% reduction

Complex Task (e.g., "Add GraphQL query")

Before: Load 966 lines
After: Load 103 (core) + 54 (GraphQL.md) = 157 lines
Improvement: 84% reduction

Feature Development

Before: Load 966 lines
After: Load 103 (core) + 144 (Development.md) + 359 (Architecture.md) = 606 lines
Improvement: 37% reduction (still significant for most common case)

Related Issues

• Addresses context overhead for AI agents
• Improves maintainability of agent documentation
• Enables multi-tool AI assistant support

---

Checklist

• [] Documentation restructured
• [] All file paths validated
• [] Agent references fixed
• [] Backward compatibility maintained
• [] Security content properly organized
• [] No broken links

[Copilot]

Pull request overview

This pull request restructures the AI agent documentation system to be tool-agnostic and optimizes context loading by breaking down a monolithic 966-line documentation file into focused guides. The restructure moves agents from .github/agents/ to .ai/agents/, removes tool-specific configuration files (.cursorrules, .clinerules), and splits comprehensive documentation into eight focused guides in the Docs/ directory.

Changes:

• Migrated to tool-agnostic agent structure compatible with any AI coding assistant
• Created focused documentation guides (Architecture, GraphQL, Localization, Testing, Development, CodeStyle, QuickReference) averaging 100-360 lines each
• Updated all agent files with correct relative path references to new documentation structure

Reviewed changes

Copilot reviewed 17 out of 18 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
AGENTS.md	Core AI agent system documentation (131 lines) with essential project context and links to detailed guides
.github/copilot-instructions.md	Simplified to 5-line redirect to AGENTS.md for GitHub Copilot compatibility
CLAUDE.md	Updated reference from copilot-instructions.md to AGENTS.md
Docs/Architecture.md	Comprehensive MVVM architecture, navigation, and module structure guide (360 lines)
Docs/GraphQL.md	GraphQL integration patterns and BFF workflow (55 lines)
Docs/Localization.md	L10n string catalog management guide (37 lines)
Docs/Testing.md	Testing patterns, mocking, and snapshot testing guide (55 lines)
Docs/Development.md	Feature development process and verification workflow (145 lines)
Docs/CodeStyle.md	SwiftLint rules, naming conventions, and best practices (96 lines)
Docs/QuickReference.md	Directory structure, commands, dependencies, and code review guidelines (131 lines)
Docs/Specs/README.md	Updated reference from copilot-instructions.md to AGENTS.md
.ai/agents/feature-orchestrator.agent.md	Updated documentation references with correct relative paths
.ai/agents/spec-writer.agent.md	New agent for creating feature specifications
.ai/agents/graphql-specialist.agent.md	Updated documentation references with correct relative paths
.ai/agents/ios-feature-developer.agent.md	Updated documentation references with correct relative paths
.ai/agents/localization-specialist.agent.md	Updated documentation references with correct relative paths
.ai/agents/testing-specialist.agent.md	Updated documentation references with correct relative paths
.ai/agents/mobile-security-specialist.agent.md	Updated documentation references with correct relative paths