Add agent maintenance infrastructure for SDK documentation sync

[steffanc]

Overview

This PR introduces a comprehensive system for keeping Claude agent documentation synchronized with Flutter SDK changes.

What's Added

🤖 Agent & Configuration

• .claude/agents/cloudx-flutter-agent-maintainer.md: Autonomous agent for detecting SDK changes and syncing agent documentation
• .claude/maintenance/SDK_VERSION.yaml: Source of truth for SDK version (v0.18.0) and critical API signatures

🔄 GitHub Workflows

• .github/workflows/sync-agent-repo.yml: Detects API changes on push/PR and notifies developers to sync agent docs
• .github/workflows/validate-maintainer-agent.yml: Validates SDK version consistency between pubspec.yaml and SDK_VERSION.yaml

📜 Scripts

• scripts/sync_to_agent_repo.sh: Helper script to clone agent repository for syncing

Key Features

Maintainer Agent

• ✅ Autonomously detects SDK version changes (pubspec.yaml → SDK_VERSION.yaml)
• ✅ Auto-detects API changes by diffing public API files
• ✅ Updates agent documentation with version strings and API signatures
• ✅ Validates changes before committing

Sync Workflow

• ✅ Triggers on push/PR to main when SDK files change
• ✅ Creates tracking issues for direct commits (assigned to committer)
• ✅ Posts PR comments for pull requests
• ✅ Includes failure handling with detailed error reporting

Validation Workflow

• ✅ Ensures SDK_VERSION.yaml stays in sync with pubspec.yaml
• ✅ Validates maintainer agent documentation structure
• ✅ Detects API changes requiring agent sync in PRs

Documentation Updates

SDK_VERSION.yaml Updates

• ✅ Current SDK version: 0.18.0 (previously 0.1.2)
• ✅ Fixed initialize() parameter: testMode (was incorrectly documented as allowIosExperimental)
• ✅ Complete widget constructors with all parameters (CloudXBannerView, CloudXMRECView)
• ✅ New CloudXAdViewController documentation
• ✅ Updated iOS support status (not_supported vs experimental)
• ✅ Comprehensive API signatures for all public methods

Maintainer Agent Updates

• ✅ Flutter-specific file paths and patterns
• ✅ Version 0.18.0 examples throughout
• ✅ Correct widget references (removed non-existent CloudXNativeView)
• ✅ Updated repository name (cloudx-flutter)

Workflow Improvements

Both workflows now include:

• ✅ Explicit permissions (security best practice)
• ✅ Dual trigger support (push + pull_request)
• ✅ Conditional logic based on event type
• ✅ Main branch only (removed develop branch)

⚠️ Known Issues

Validation Workflow Will Fail

The validate-maintainer-agent.yml workflow currently checks for sections that don't exist in the maintainer agent:

• ❌ Checks for "Cross-Repository Sync Mode" section (doesn't exist)
• ❌ Checks for "Environment Variables" section (doesn't exist)

Actual sections in maintainer agent:

• Core Responsibilities
• Autonomous Workflow
• Common Update Scenarios
• Flutter-Specific Considerations
• etc.

Options to fix:

1. Update validation to check for actual sections
2. Remove documentation validation step entirely
3. Add the missing sections to the maintainer agent

Decision needed: Should be addressed in a follow-up PR or before merging this one.

Script Not Yet Implemented

The scripts/sync_to_agent_repo.sh script is referenced but may need:

• Environment variables or secrets for GitHub access
• Logic to clone the cloudx-sdk-agents repository
• Error handling

Testing

• Verify validation workflow passes (SDK version check) ✅
• Test sync workflow on API changes
• Decide on validation section fix
• Test/implement sync_to_agent_repo.sh script

Related

This matches the infrastructure in the Android SDK repo for consistency.

---

🤖 Generated with Claude Code