---
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

```markdown
# 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.
```