flint-generate

name	flint-generate
description	Generate flint rules from CLAUDE.md, AGENTS.md, or other project documentation. Use to bootstrap rules from existing conventions.
allowed-tools	Read, Glob, Write
context	fork
agent	general-purpose
model	sonnet

Flint Generate - Rule Extraction

Extract linting rules from project documentation for Flint, a checklist-driven linting tool.

When to Use

• Setting up flint for a new project
• Project has CLAUDE.md, AGENTS.md, or similar docs with conventions
• Want to enforce existing guidelines automatically

Source Files to Scan

• CLAUDE.md
• AGENTS.md
• .cursorrules
• .claude/rules/*.md
• Custom files if specified

Output Format

Output a YAML list of rules. NO top-level rules: key - just the list directly.

Simple Rule (just a description)

- Prefer pathlib over os.path

Full Rule Object

- description: Use 'is None' not '== None'
  severity: warn
  tags: [comparisons, style]
  check:
    any:
      - contains: "== None"
      - contains: "!= None"
  fix: "Replace '== None' with 'is None'"

Rule Fields

Field	Required	Description
description	Yes	What the rule checks for (imperative: "Use X", "Avoid Y")
severity	No	error (must fix), warn (should fix, default), note (consider)
tags	No	Categories like [style], [security], [performance]
check	No	Pattern string or composable check object for detection
fix	No	How to fix violations of this rule
paths	No	Glob pattern to limit scope, e.g., "**/*.py"

Check Format

Checks can be:

1. Simple pattern string (regex):

check: "except\\s*:"

2. Composable checks with any, all, none:

check:
  any:
    - matches: "\\beval\\s*\\("
    - matches: "\\bexec\\s*\\("

check:
  all:
    - contains: "MIT"
    - not_contains: "GPL"

Rules without checks require manual LLM review for every file.

Severity Guidelines

• error: "never", "must not", "always", "required" → strong mandates
• warn: "should", "prefer", "avoid", "recommended" → best practices (default)
• note: "consider", "may want to", "optionally" → suggestions

What to Extract

• Code style rules ("Use f-strings", "Prefer pathlib")
• Error handling ("Never use bare except")
• Security practices ("Validate user input")
• Testing requirements ("Write tests for public APIs")
• Naming conventions ("Use snake_case for functions")
• Architecture rules ("Keep modules under 500 lines")

What to Skip

• Setup instructions ("Run npm install")
• Environment config ("Set DATABASE_URL")
• Deployment steps ("Push to main branch")
• Tool-specific config ("Configure ESLint")
• Non-actionable guidelines ("Write clean code")

Pattern Writing Tips

1. Escape special regex characters: \\. for literal dot
2. Use \\s* for optional whitespace
3. Use \\b for word boundaries
4. Use [^)]* for "anything except closing paren"

Common Patterns

# Function calls
"\\beval\\s*\\("           # eval(
"os\\.path\\.join\\("      # os.path.join(

# Imports
"from typing import.*List" # typing List import
"import os\\.path"         # os.path import

# Comparisons
"== None"                  # None comparison
"== True"                  # Boolean comparison

# Definitions
"def \\w+\\([^)]*=\\s*\\[\\]"  # Mutable default []
"class \\w+:"                   # Class definition

Example Extraction

Input (from CLAUDE.md)

## Code Style
- Always use pathlib instead of os.path for file operations
- Prefer f-strings over .format() for string formatting
- Never use bare except clauses - always catch specific exceptions

## Security
- Never use eval() or exec() with user input

Output

# Code Style
- description: Use pathlib instead of os.path
  severity: warn
  tags: [style, pathlib]
  check: "os\\.path\\.(join|dirname|basename|exists)"
  fix: "Replace os.path.X with pathlib.Path equivalents"

- description: Use f-strings instead of .format()
  severity: warn
  tags: [style, strings]
  check: "\\.format\\("
  fix: "Convert to f-string: f\"text {var}\""

- description: Never use bare except clauses
  severity: error
  tags: [exceptions, error-handling]
  check: "except\\s*:"
  fix: "Catch specific exception types"

# Security
- description: Never use eval() with untrusted input
  severity: error
  tags: [security]
  check:
    any:
      - matches: "\\beval\\s*\\("
      - matches: "\\bexec\\s*\\("
  fix: "Use ast.literal_eval() or safer alternatives"

Workflow

# 1. Initialize flint
flint init

# 2. Generate rules from docs
flint generate rules

# 3. Review generated rules
cat rules/generated.yaml

# 4. Run check
flint check src/

Manual Refinement

After generation, refine rules:

1. Remove duplicates or overly similar rules
2. Add paths to scope rules to specific directories
3. Adjust severity based on team preferences
4. Add checks for rules that can be detected automatically
5. Split complex rules into specific, actionable items