Skip to content

feat(agents): add flutter-reviewer agent and skill#716

Merged
affaan-m merged 1 commit into
affaan-m:mainfrom
macstarosielec:feat/flutter-reviewer
Mar 20, 2026
Merged

feat(agents): add flutter-reviewer agent and skill#716
affaan-m merged 1 commit into
affaan-m:mainfrom
macstarosielec:feat/flutter-reviewer

Conversation

@macstarosielec

@macstarosielec macstarosielec commented Mar 20, 2026

Copy link
Copy Markdown

Summary

Adds a library-agnostic Flutter/Dart code reviewer agent and companion skill:

  • agents/flutter-reviewer.md — Reviews Flutter code for widget best practices, state management patterns, Dart idioms, performance, accessibility, security, and architecture. Adapts to the project's chosen state management solution (BLoC, Riverpod, Provider, GetX, MobX, Signals, or built-in).
  • skills/flutter-dart-code-review/SKILL.md — Comprehensive 15-section review checklist with a state management quick reference table mapping universal principles to solution-specific implementations.

Key design decisions:

  • Fully library-agnostic — no library is treated as mandatory
  • State management rules split into immutable-state (BLoC/Riverpod/Redux) and reactive-mutation (MobX/GetX/Signals) sub-sections
  • Architecture rules adapt to the project's chosen layering (Clean Architecture, MVVM, feature-first, etc.)
  • Security escalation to security-reviewer on CRITICAL findings
  • Noise control rules to keep reviews concise and actionable

Type

  • Agent
  • Skill
  • Hook
  • Command

Testing

  • Reviewed against kotlin-reviewer.md and code-reviewer.md for structural consistency
  • Cross-checked agent checklist against skill for parity
  • Verified no cross-platform/language assumptions leak in
  • Agent is 243 lines (matches code-reviewer at 237); skill is 435 lines (under 500 limit)

Checklist

  • Follows format guidelines
  • Tested with Claude Code
  • No sensitive info (API keys, paths)
  • Clear descriptions

Summary by cubic

Adds a library-agnostic Flutter/Dart code reviewer agent with a companion checklist skill. Improves review quality across widgets, state, performance, accessibility, security, and architecture, regardless of the chosen libraries.

  • New Features
    • agents/flutter-reviewer.md: Adaptive reviewer for any state management (BLoC, Riverpod, Provider, GetX, MobX, Signals) and architecture. Includes a clear workflow, concise reporting format, approval criteria, noise control, and CRITICAL security escalation to security-reviewer.
    • skills/flutter-dart-code-review/SKILL.md: 15-section checklist with a quick reference mapping universal principles to popular solutions. Covers widgets, Dart idioms, performance, testing, accessibility, i18n, security, DI, navigation, and dependencies.

Written for commit cb3da81. Summary will update on new commits.

Summary by CodeRabbit

  • Chores
    • Added Flutter and Dart code reviewer agent with comprehensive coverage for architecture, state management, performance, and security best practices.
    • Added extensive Flutter/Dart code review checklist covering project health, language idioms, widget composition, testing strategy, accessibility, and internationalization guidelines.

Library-agnostic Flutter/Dart code reviewer that adapts to the project's
chosen state management solution (BLoC, Riverpod, Provider, GetX, MobX,
Signals) and architecture pattern (Clean Architecture, MVVM, feature-first).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Mar 20, 2026

Copy link
Copy Markdown
Contributor
📝 Walkthrough

Walkthrough

Two new markdown files introduce a Flutter/Dart code review agent configuration and comprehensive best-practices checklist. The agent defines a structured workflow for reviewing Flutter and Dart code, covering architecture, state management, performance, security, and accessibility concerns. The checklist provides library-agnostic guidance across project health, language idioms, widgets, testing, and related domains.

Changes

Cohort / File(s) Summary
Flutter/Dart Code Review Infrastructure
agents/flutter-reviewer.md, skills/flutter-dart-code-review/SKILL.md
Established automated Flutter/Dart code review framework with agent configuration defining review workflow (git context retrieval, project inspection, security pre-checks, detailed file review) and comprehensive multi-domain checklist covering architecture, state management paradigms, performance, testing, accessibility, security, dependencies, navigation, error handling, and internationalization.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 Hops with glee through Flutter fields,
New checklists guard what each review yields,
From widgets wise to state held tight,
This rabbit's gift: code shining bright! ✨

🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'feat(agents): add flutter-reviewer agent and skill' clearly and accurately summarizes the main change: adding a new Flutter code reviewer agent and its accompanying skill checklist.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
📝 Coding Plan
  • Generate coding plan for human review comments

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Tip

You can customize the high-level summary generated by CodeRabbit.

Configure the reviews.high_level_summary_instructions setting to provide custom instructions for generating the high-level summary.

@greptile-apps

greptile-apps Bot commented Mar 20, 2026

Copy link
Copy Markdown
Contributor

Greptile Summary

This PR introduces a flutter-reviewer agent and a companion flutter-dart-code-review skill, extending the ECC library with Flutter/Dart code review capabilities. The content is well-researched, library-agnostic, and structurally aligned with existing language reviewers like kotlin-reviewer.

Key observations:

  • Missing AGENTS.md registration — the flutter-reviewer agent is not added to the root AGENTS.md table (where all 27 other agents are listed) nor is the agent count updated from 27→28. Without this, orchestration rules that rely on AGENTS.md will not know when to invoke the agent for Flutter projects.
  • Skill format gapSKILL.md skips the standard When to Use / How It Works / Examples preamble that CLAUDE.md prescribes for all skills, making the skill structurally inconsistent with the rest of the library.
  • Minor step numbering — the agent workflow jumps from Step 2 directly to Step 2b without a Step 2a, an inconsistency inherited from kotlin-reviewer.md.
  • The state management quick-reference table and library-agnostic architecture checks are well-designed additions. The security escalation to security-reviewer on CRITICAL findings follows the established convention from other language reviewers correctly.

Confidence Score: 3/5

  • Safe to merge after adding the flutter-reviewer entry to the root AGENTS.md and updating the agent count.
  • The content of both files is high quality and follows established patterns. The primary blocker is a missing registration in AGENTS.md — without it the agent is functionally invisible to orchestration, which defeats the purpose of the contribution. The skill format gap and step numbering issue are minor but worth addressing for consistency. No security, logic, or runtime concerns exist in documentation-only files.
  • Root AGENTS.md needs a new row for flutter-reviewer and a count update (27→28) — this file was not changed in the PR but is required for the agent to be discoverable.

Important Files Changed

Filename Overview
agents/flutter-reviewer.md New Flutter/Dart code reviewer agent — well-structured with a comprehensive checklist, library-agnostic design, and proper security escalation. Key issue: the agent is not registered in the root AGENTS.md, making it undiscoverable to the orchestration system. Minor: workflow step numbering skips "Step 2a".
skills/flutter-dart-code-review/SKILL.md Comprehensive 15-section review checklist with a state management quick reference table. Content quality is high and the library-agnostic approach is well-executed. Minor: missing the standard "When to Use / How It Works / Examples" preamble sections required by the project's skill format convention.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A([Invoked]) --> B[Step 1: git diff / git log\nIdentify changed Dart files]
    B --> C[Step 2: Read project config\npubspec.yaml · analysis_options.yaml\nCLAUDE.md · melos · state mgmt · DI/routing]
    C --> D[Step 2b: Security Pre-check\nHardcoded secrets · insecure storage\ncleartext HTTP · exported components]
    D --> E{CRITICAL\nsecurity\nfound?}
    E -- Yes --> F([Hand off to security-reviewer\nSTOP])
    E -- No --> G[Step 3: Read changed files fully\nApply 13-section review checklist]
    G --> H[Step 4: Report findings\n>80% confidence only\nConsolidate similar issues]
    H --> I([Output: findings + Review Summary table\nVerdict: APPROVE / BLOCK])

    style F fill:#ff4444,color:#fff
    style I fill:#22aa44,color:#fff
Loading

Last reviewed commit: "feat(agents): add fl..."

Comment on lines +1 to +6
---
name: flutter-reviewer
description: Flutter and Dart code reviewer. Reviews Flutter code for widget best practices, state management patterns, Dart idioms, performance pitfalls, accessibility, and clean architecture violations. Library-agnostic — works with any state management solution and tooling.
tools: ["Read", "Grep", "Glob", "Bash"]
model: sonnet
---

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Agent not registered in AGENTS.md

The root AGENTS.md file is the single source of truth for agent discovery and orchestration — it's what Claude uses to decide when to delegate to a specialized agent. Every other language reviewer (kotlin-reviewer, go-reviewer, python-reviewer, java-reviewer, rust-reviewer, typescript-reviewer, etc.) is listed there with a clear purpose and "When to Use" column. flutter-reviewer is missing entirely.

Additionally, the preamble in AGENTS.md currently reads:

"providing 27 specialized agents, 114 skills, 59 commands…"

This count needs to be updated to 28 after this PR merges.

Without adding the entry to AGENTS.md, the orchestration system has no signal to invoke this agent for Flutter projects, making it effectively invisible to the pipeline.

Suggested addition to the Available Agents table in AGENTS.md:

| flutter-reviewer | Flutter/Dart code review | Flutter/Dart projects |

Comment on lines +1 to +11
---
name: flutter-dart-code-review
description: Library-agnostic Flutter/Dart code review checklist covering widget best practices, state management patterns (BLoC, Riverpod, Provider, GetX, MobX, Signals), Dart idioms, performance, accessibility, security, and clean architecture.
origin: ECC
---

# Flutter/Dart Code Review Best Practices

Comprehensive, library-agnostic checklist for reviewing Flutter/Dart applications. These principles apply regardless of which state management solution, routing library, or DI framework is used.

---

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Skill format diverges from project convention

CLAUDE.md documents the expected skill format as:

"Skills: Clear sections (When to Use, How It Works, Examples)"

All skills are expected to open with those three standard sections so consumers know at a glance when the skill applies and how to invoke it. This file opens directly with a flat checklist under ## 1. General Project Health — there is no ## When to Use, ## How It Works, or ## Examples section.

While the checklist content is thorough, omitting the standard preamble sections means this skill doesn't follow the same discoverability contract as the rest of the skill library. Consider adding the three standard sections (even if brief) before the numbered checklist to keep the format consistent.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

Comment on lines +34 to +43
### Step 2b: Security Review

Check before continuing — if any CRITICAL security issue is found, stop and hand off to `security-reviewer`:
- Hardcoded API keys, tokens, or secrets in Dart source
- Sensitive data in plaintext storage instead of platform-secure storage
- Missing input validation on user input and deep link URLs
- Cleartext HTTP traffic; sensitive data logged via `print()`/`debugPrint()`
- Exported Android components and iOS URL schemes without proper guards

### Step 3: Read and Review

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Step numbering skips "Step 2a"

The workflow goes Step 2Step 2b with no Step 2a in between. While functionally harmless (the intent is clear), the label 2b strongly implies a 2a exists somewhere. Readers may scan upward looking for it.

The kotlin-reviewer.md has the same pattern, so this is an inherited inconsistency in the project. Consider either renaming Step 2b to Step 3 and re-numbering subsequent steps, or labelling the preceding step Step 2a explicitly — whichever aligns with the pattern you'd prefer to standardise across all language reviewers.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
skills/flutter-dart-code-review/SKILL.md (1)

1-10: Consider adding standard skill sections.

The skill is formatted as a comprehensive checklist, which is well-organized and appropriate for a review rubric. However, coding guidelines specify that skills should include "When to Use, How It Works, and Examples" sections. Consider adding a brief introductory section that explains:

  • When to Use: When reviewing Flutter/Dart code in PRs, before commits, or during code audits
  • How It Works: Apply the 15-section checklist systematically to the codebase
  • Examples: Could reference the code examples already present (lines 113-137)

This would make the skill more accessible to users unfamiliar with Flutter review practices while maintaining the checklist format.

As per coding guidelines: "Skills should be formatted as Markdown with clear sections for When to Use, How It Works, and Examples."

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@skills/flutter-dart-code-review/SKILL.md` around lines 1 - 10, Add the
required "When to Use", "How It Works", and "Examples" sections to the
flutter-dart-code-review skill (SKILL.md): create a brief "When to Use"
describing contexts (PR reviews, pre-commit, audits), a concise "How It Works"
instructing users to apply the 15-section checklist systematically, and an
"Examples" section that references and links to the existing code examples
already in the document (the examples block near the checklist). Ensure headings
match the specified titles and keep each section short and actionable so the
checklist remains the primary content.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@skills/flutter-dart-code-review/SKILL.md`:
- Around line 1-10: Add the required "When to Use", "How It Works", and
"Examples" sections to the flutter-dart-code-review skill (SKILL.md): create a
brief "When to Use" describing contexts (PR reviews, pre-commit, audits), a
concise "How It Works" instructing users to apply the 15-section checklist
systematically, and an "Examples" section that references and links to the
existing code examples already in the document (the examples block near the
checklist). Ensure headings match the specified titles and keep each section
short and actionable so the checklist remains the primary content.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6d3ba204-8034-499d-9f3c-557e96d7400f

📥 Commits

Reviewing files that changed from the base of the PR and between e8495aa and cb3da81.

📒 Files selected for processing (2)
  • agents/flutter-reviewer.md
  • skills/flutter-dart-code-review/SKILL.md

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

2 issues found across 2 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="agents/flutter-reviewer.md">

<violation number="1" location="agents/flutter-reviewer.md:122">
P1: The Dart Idioms section incorrectly lists `requireNotNull` as a preferred null-safety alternative. This is a Kotlin function that does not exist in Dart's standard library. The agent will recommend invalid code to Flutter/Dart developers.</violation>
</file>

<file name="skills/flutter-dart-code-review/SKILL.md">

<violation number="1" location="skills/flutter-dart-code-review/SKILL.md:419">
P2: Provider disposal documentation is oversimplified - disposal is only automatic with `create` constructor, not with `.value` which requires manual disposal</violation>
</file>

Since this is your first cubic review, here's how it works:

  • cubic automatically reviews your code and comments on bugs and improvements
  • Teach cubic by replying to its comments. cubic learns from your replies and gets better over time
  • Add one-off context when rerunning by tagging @cubic-dev-ai with guidance or docs links (including llms.txt)
  • Ask questions if you need clarification on any suggestion

Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.

### Dart Idioms (MEDIUM)

- **Missing type annotations / implicit `dynamic`** — Enable `strict-casts`, `strict-inference`, `strict-raw-types` to catch these
- **`!` bang overuse** — Prefer `?.`, `??`, `case var v?`, or `requireNotNull`

@cubic-dev-ai cubic-dev-ai Bot Mar 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1: The Dart Idioms section incorrectly lists requireNotNull as a preferred null-safety alternative. This is a Kotlin function that does not exist in Dart's standard library. The agent will recommend invalid code to Flutter/Dart developers.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At agents/flutter-reviewer.md, line 122:

<comment>The Dart Idioms section incorrectly lists `requireNotNull` as a preferred null-safety alternative. This is a Kotlin function that does not exist in Dart's standard library. The agent will recommend invalid code to Flutter/Dart developers.</comment>

<file context>
@@ -0,0 +1,243 @@
+### Dart Idioms (MEDIUM)
+
+- **Missing type annotations / implicit `dynamic`** — Enable `strict-casts`, `strict-inference`, `strict-raw-types` to catch these
+- **`!` bang overuse** — Prefer `?.`, `??`, `case var v?`, or `requireNotNull`
+- **Broad exception catching** — `catch (e)` without `on` clause; specify exception types
+- **Catching `Error` subtypes** — `Error` indicates bugs, not recoverable conditions
</file context>
Fix with Cubic

| UI consumer | `BlocBuilder` | `ConsumerWidget` | `Consumer` | `Obx`/`GetBuilder` | `Observer` | `Watch` | `setState` |
| Selector | `BlocSelector`/`buildWhen` | `ref.watch(p.select(...))` | `Selector` | N/A | computed | `computed()` | N/A |
| Side effects | `BlocListener` | `ref.listen` | `Consumer` callback | `ever()`/`once()` | `reaction` | `effect()` | callbacks |
| Disposal | auto via `BlocProvider` | `.autoDispose` | auto via `Provider` | `onClose()` | `ReactionDisposer` | manual | `dispose()` |

@cubic-dev-ai cubic-dev-ai Bot Mar 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Provider disposal documentation is oversimplified - disposal is only automatic with create constructor, not with .value which requires manual disposal

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At skills/flutter-dart-code-review/SKILL.md, line 419:

<comment>Provider disposal documentation is oversimplified - disposal is only automatic with `create` constructor, not with `.value` which requires manual disposal</comment>

<file context>
@@ -0,0 +1,435 @@
+| UI consumer | `BlocBuilder` | `ConsumerWidget` | `Consumer` | `Obx`/`GetBuilder` | `Observer` | `Watch` | `setState` |
+| Selector | `BlocSelector`/`buildWhen` | `ref.watch(p.select(...))` | `Selector` | N/A | computed | `computed()` | N/A |
+| Side effects | `BlocListener` | `ref.listen` | `Consumer` callback | `ever()`/`once()` | `reaction` | `effect()` | callbacks |
+| Disposal | auto via `BlocProvider` | `.autoDispose` | auto via `Provider` | `onClose()` | `ReactionDisposer` | manual | `dispose()` |
+| Testing | `blocTest()` | `ProviderContainer` | `ChangeNotifier` directly | `Get.put` in test | store directly | signal directly | widget test |
+
</file context>
Fix with Cubic

@affaan-m affaan-m merged commit 1975a57 into affaan-m:main Mar 20, 2026
4 checks passed
@coderabbitai coderabbitai Bot mentioned this pull request Mar 23, 2026
3 tasks
FrancescoRosciano pushed a commit to FRosciano-Mambo/everything-claude-code that referenced this pull request Jun 1, 2026
Library-agnostic Flutter/Dart code reviewer that adapts to the project's
chosen state management solution (BLoC, Riverpod, Provider, GetX, MobX,
Signals) and architecture pattern (Clean Architecture, MVVM, feature-first).

Co-authored-by: Maciej Starosielec <maciej@code-snap.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants