feat: Auto-translate AI assistant guidelines (Cursor/Claude/Copilot) into enforceable rules

[dkargatzis]

Feature: Auto-translate AI assistant guidelines into pre-merge rules

Translate natural-language guidelines from Cursor, Claude, or Copilot Markdown files into enforceable pre-merge rules.

This is a high-impact, advanced task that plays to Watchflow's agentic strengths (LangGraph + GitHub events) and taps into the exploding trend of AI-agent hooks & governance. Perfect for someone wanting to ship real value and get deep into the codebase.

Goal

Build a feature that auto-detects Markdown files in repos containing AI-assistant instructions (e.g. .cursorrules, claude-guidelines.md, copilot-prompts.md), parses the rules using our agentic pipeline, translates them into .watchflow/rules.yaml format, and enforces them as pre-merge checks (PR comments / check runs).

Bonus: make it hook-driven so rules auto-update on relevant pushes.

Why this matters

• Teams using Cursor/Claude/Copilot often document rules in MD files — but those stay as "advice" instead of hard guards.
• This bridges that gap: AI-generated code gets auto-validated before merge.
• Aligns with the agentic hooks trend (reactive, self-improving workflows via webhooks + LangGraph).

Real-World Use Cases

When developers instruct their AI assistants using files like .cursorrules or .github/copilot-instructions.md, they often specify architectural or stylistic constraints. Here are examples of real rules we want to automatically enforce:

Case 1: Next.js Architecture Constraints
Instruction from .cursorrules: "Use React Server Components by default. Only use 'use client' directives at the leaf nodes of the component tree when interactivity (hooks like useState, useEffect) is strictly necessary."
Enforced as: A rule that flags PRs introducing 'use client' in high-level layout files or components that don't import React hooks.

Case 2: FastAPI Data Validation
Instruction from .github/copilot-instructions.md: "Never use raw dictionaries for API responses. Always define and return Pydantic models for data validation and OpenAPI schema generation."
Enforced as: A rule that blocks PRs where FastAPI route functions lack a response_model parameter or return raw dicts.

Case 3: Testing Standards
Instruction from .cursorrules: "Every new feature or bug fix must include corresponding tests using Pytest. Mock external API calls using responses or httpx-mock."
Enforced as: A rule requiring the PR to include modifications in the tests/ directory, specifically checking for pytest imports and mocking libraries.

Estimated Scope

Medium-hard. Start with an MVP (one AI tool + basic translation), then expand. A great first PR could be the parser + proof-of-concept agent chain.

Implementation Steps

1. Repo Scanning

• Hook into the existing analysis pipeline (extend /api/v1/rules/recommend or add a new endpoint).
• Use GitHub API to list files -> match patterns like .cursorrules, *rules*.md, *guidelines*.md.
• Keywords to detect: "Cursor rule:", "Claude:", "Always use", "Never commit", etc.

2. Agentic Parsing & Translation

Build a LangGraph chain/agent:

• Extractor Agent: Read MD content -> pull out rule-like statements (prompt engineering here is key).
• Translator Agent: Map to our YAML schema.

Example Translation:

# From .cursorrules: "Always use async/await for network calls"
- name: async-io-required
  on: [pull_request]
  condition: file:"*.py" AND has_io AND NOT uses_async_await
  action: fail_check "Use async/await for I/O operations"

# From .github/copilot-instructions.md: "New features must have unit tests"
- name: tests-for-features
  on: [pull_request]
  require: linked_issue AND has_tests_for_changed_code

Fallback: If ambiguous, post a PR comment asking for confirmation.

3. Pre-Merge Enforcement

• Trigger on pull_request (opened/synchronize) webhook events.
• Run translated rules -> create Check Run (success/failure) or comment with violations.
• Block merge if critical rules fail (configurable severity).

4. Agentic Hooks Bonus

• Add support for push events: if an MD rules file changes -> auto-re-run translator -> suggest/commit updated .watchflow/rules.yaml.
• Creates a self-improving loop: AI enforces rules that AI teams write.

Getting Started

• Look at existing LangGraph agents in the code for inspiration.
• Start small: prototype the MD -> YAML translation in a standalone script/notebook, then integrate.
• Tests: add cases with sample MD inputs (we can add fixtures together).
• Questions? Drop them here or open a draft PR / issue — happy to pair/review.

Stretch Goals

• Support multiple AI tools with different prompt styles.
• Add confidence scoring (e.g., "80% sure this is a rule — approve?").
• UI hint in watchflow.dev to scan for these MD files during repo analysis.

[dkargatzis]

Suggested UX Funnel: Contextual & Just-in-Time

For developer tools, a Reactive (Just-in-Time) approach is significantly better than a proactive spam approach (e.g., creating 100 PRs across an org immediately upon installation). The best UX engages developers exactly when they are thinking about their code: when they open a PR.

Here is what the ideal, "magical" UX flow should look like for this feature:

1. Silent Installation

The admin installs the GitHub app. Nothing happens immediately. No spam.

2. The Contextual Trigger (First PR)

A developer opens a PR in a repository that does not have a .watchflow/rules.yaml file.

3. The Smart Scan

Watchflow receives the PR webhook. Before posting the standard "Rules not configured" comment, it does a quick scan of the repository root for .cursorrules, claude.md, etc.

4. The Tailored Comment

• Scenario A (AI Rules Found): Watchflow posts a highly targeted comment:

  🪄 Watchflow detected your .cursorrules!
  We noticed you have AI assistant guidelines configured for this repository. Watchflow can automatically translate these guidelines into hard, enforceable pre-merge checks.

  👉 Click here to auto-translate your .cursorrules into Watchflow rules

• Scenario B (No AI Rules Found): Watchflow posts the standard comment we already have:

  ⚙️ Watchflow rules not configured
  Analyze your repository and generate rules

5. The Frontend Funnel (watchflow-landing)

When the user clicks the link and lands on watchflow.dev/analyze:

• The frontend shows a new loading state: "Scanning repository for AI guidelines (.cursorrules, etc)..."
• If found, the UI explicitly shows: "We found your .cursorrules. Translating natural language to Watchflow YAML..."
• The generated PR preview shows the translated rules.
• The user clicks "Create PR", merges it, and they are fully onboarded.

Why this is the best UX:

1. Zero Noise: Inactive repositories are never touched.
2. High Relevance: The developer is already in the context of a PR, so configuring rules to protect that PR makes sense right then.
3. Show, Don't Tell: Instead of telling them "we support Cursor rules", we are actively detecting their files and offering to do the work for them. It feels like a premium, intelligent product.