Overview

Create a new agent that analyzes repository structure, patterns, and contributing guidelines to automatically propose Watchflow rules. This will integrate with the watchflow.dev UI to provide personalized rule recommendations during onboarding.

Requirements

Core Functionality

• Analyze repository structure (file patterns, branch protection, existing workflows)
• Parse contributing guidelines (CONTRIBUTING.md, CODE_OF_CONDUCT.md) using LLM for flexible extraction
• Review commit history and PR patterns to identify common practices
• Generate rule recommendations based on detected patterns with confidence scores

Agent Architecture

• New RepositoryAnalysisAgent following existing agent patterns in src/agents/
• Use LangGraph for multi-step analysis workflow
• Leverage existing validators and rule patterns
• Return structured recommendations with confidence scores and reasoning
• Use factory pattern for agent instantiation via get_agent()

API Endpoint

• POST endpoint: /api/v1/rules/recommend
• Accepts: repository identifier (full_name or URL), optional installation_id
• Returns: list of recommended rules with metadata (YAML, confidence, reasoning, source pattern)
• Async handler for agent execution
• Rate limiting and caching for public endpoints

Integration Points

• API endpoint consumed by watchflow.dev UI
• Recommendations exported as valid .watchflow/rules.yaml format
• Seamless onboarding flow from analysis to rule installation

Implementation Notes

• Start by analyzing CONTRIBUTING.md files as primary input using LLM-based extraction
• Use existing GitHub API client for repository data access
• Follow existing codebase patterns (agent structure, API routes, error handling)
• Add comprehensive tests for recommendation accuracy
• Implement caching to avoid redundant repository analyses

Acceptance Criteria

• Agent analyzes repositories and generates valid rule recommendations
• Recommendations include confidence scores and clear reasoning
• API endpoint accepts repository identifier and returns structured recommendations
• Integration works with watchflow.dev UI requirements
• All recommendations are valid Watchflow rule YAML
• Proper error handling, validation, and rate limiting