flint

name	flint
description	Orchestrates checklist-driven linting for code. Use when asked to lint, check code quality, find violations, or fix code issues. Coordinates check, review, plan, and fix phases using optimal models.
allowed-tools	Read, Glob, Grep, Edit, Write, Bash, Task
context	fork
agent	general-purpose

Flint - Checklist-Driven Linting Orchestrator

You orchestrate code quality checks by running subagents with optimal model selection for each phase.

Architecture

/flint src/
    │
    ▼
┌─────────────────────────────────────────────────────┐
│ Phase 1: CHECK (Explore agent - fast heuristics)    │
│ Run flint-check to scan with regex/ruff patterns    │
│ Output: Checklist with [!] filters and [?] hints    │
└─────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────┐
│ Phase 2: REVIEW (Haiku - cheap triage)              │
│ Quick pass to skip false positives and add findings │
│ Output: Triaged checklist with confirmations        │
└─────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────┐
│ Phase 3: PLAN (Sonnet - strategic planning)         │
│ Plan fixes, group by file, create independent tasks │
│ Output: Fix tasks that can run in parallel          │
└─────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────┐
│ Phase 4: FIX (Haiku swarm - parallel execution)     │
│ Spawn one worker per file, execute fix tasks        │
│ Output: Fixed code                                  │
└─────────────────────────────────────────────────────┘

Model Selection Strategy

Phase	Model	Why
Check	—	Heuristics only, no LLM
Review	Haiku	Fast triage, cheap, high volume
Plan	Sonnet	Strategic thinking, one-time cost
Fix	Haiku	Simple execution, parallelizable

Execution

Phase 1: Check

Spawn the check subagent to scan code with heuristics:

Task(subagent_type="Explore", model="haiku", prompt="""
Run flint-check on [paths].
Use Grep to find patterns from rules.
Output a checklist in markdown format.
""")

Output: Checklist with potential violations

Phase 2: Review

Spawn Haiku to quickly triage the checklist:

Task(subagent_type="general-purpose", model="haiku", prompt="""
Review this flint checklist. For each item:
- [!] high confidence: keep unless obviously wrong
- [?] hints: quick verify, skip if false positive
- Manual review rules: scan briefly, add findings if obvious

Be fast. Don't over-analyze. Trust the heuristics.

[checklist from Phase 1]
""")

Output: Triaged checklist with confirmed violations

Phase 3: Plan

Spawn Sonnet to plan the fixes strategically:

Task(subagent_type="Plan", model="sonnet", prompt="""
Plan fixes for these confirmed violations.
Group by file. Create independent tasks for parallel execution.
Each task should be self-contained with clear instructions.

[triaged checklist from Phase 2]
""")

Output: Fix tasks grouped by file

Phase 4: Fix

Spawn parallel Haiku workers, one per file:

# Spawn ALL fix tasks in parallel (single message, multiple Task calls)
Task(subagent_type="general-purpose", model="haiku", prompt="Fix task 1: utils.py ...")
Task(subagent_type="general-purpose", model="haiku", prompt="Fix task 2: api.py ...")
Task(subagent_type="general-purpose", model="haiku", prompt="Fix task 3: config.py ...")

Output: Fixed files

Checklist Format

# Flint Check: src/

- [ ] Rule description
  - [ ] file.py:42 `code snippet` [!]  ← high confidence
  - [ ] file.py:87 `another snippet` [?]  ← needs verify

## Manual Review Required
- [ ] Rule without heuristic filters

Found N violations in M rules: X high confidence, Y needs review.

Handling Different Scenarios

Quick Check Only

User asks "check my code" but doesn't want fixes:

• Run Phase 1 only
• Return the checklist

Full Lint + Fix

User asks "lint and fix":

• Run all 4 phases
• Return summary of fixes applied

Review Only

User provides existing checklist:

• Skip Phase 1
• Run Phases 2-4

Subagent Communication

Pass data between phases via the checklist format:

• Check outputs markdown checklist
• Review modifies the same checklist (marks items, adds findings)
• Plan reads checklist, outputs fix tasks
• Fix workers receive their specific task

Error Handling

• If check finds no violations: report "No issues found"
• If review rejects all items: report "All findings were false positives"
• If fix fails on a file: report error, continue with other files
• Never fail silently - always surface what happened

Performance Tips

1. Spawn fix workers in parallel - Use single message with multiple Task calls
2. Don't over-review - Haiku should be fast, not thorough
3. Trust high-confidence matches - [!] items rarely need verification
4. Group aggressively - Fewer files = fewer workers = faster

Example Session

User: /flint src/
Orchestrator: Starting flint check on src/
  → Phase 1: Spawning Explore agent for heuristic scan...
  → Found 12 potential violations in 5 rules

Orchestrator: Phase 2: Spawning Haiku for quick triage...
  → Confirmed 10 violations, skipped 2 false positives

Orchestrator: Phase 3: Spawning Sonnet for fix planning...
  → Created 4 fix tasks across 4 files

Orchestrator: Phase 4: Spawning 4 Haiku workers in parallel...
  → Task 1 (utils.py): Done
  → Task 2 (api.py): Done
  → Task 3 (config.py): Done
  → Task 4 (models.py): Done

Summary: Fixed 10 violations in 4 files.