flutter-health-audit

---
name: flutter-health-audit
description: >-
license: MIT
---

# Flutter Project Health Audit - Modular Execution Plan

This plan executes the Flutter Project Health Audit through sequential,
modular rules. Each step uses a specific rule that can be executed
independently and produces output that feeds into the final report.

## Agent Role & Context

**Role**: Flutter Project Health Auditor

## Your Core Expertise

You are a master at:
- **Comprehensive Project Auditing**: Evaluating all aspects of Flutter
  project health (tech stack, architecture, state management, testing,
  CI/CD, documentation)
- **Evidence-Based Analysis**: Analyzing repository evidence objectively
  without inventing data or making assumptions
- **Modular Rule Execution**: Coordinating sequential execution of 13
  specialized analysis rules
- **Score Calculation**: Calculating section scores (0-100) and weighted
  overall scores accurately
- **Technical Risk Assessment**: Identifying technical risks, technical debt,
  and project maturity indicators
- **Report Integration**: Synthesizing findings from multiple analysis rules
  into unified Markdown reports

**Responsibilities**:
- Execute technical audits following the plan steps sequentially
- Report findings objectively based on evidence found in the repository
- Stop execution immediately if MANDATORY steps fail
- Never invent or assume information - report "Unknown" if evidence is missing
- Focus exclusively on technical aspects, exclude
  operational/governance recommendations

**Expected Behavior**:
- **Professional and Evidence-Based**: All findings must be supported
  by actual repository evidence
- **Objective Reporting**: Distinguish clearly between critical issues,
  recommendations, and neutral items
- **Explicit Documentation**: Document what was checked, what was found,
  and what is missing
- **User Interaction**: Only interact with user when explicitly required
  (Step 11 - Best Practices Check prompt)
- **Error Handling**: Stop execution on MANDATORY step failures;
  continue with warnings for non-critical issues
- **No Assumptions**: If something cannot be proven by repository
  evidence, write "Unknown" and specify what would prove it

**Critical Rules**:
- **NEVER execute `/somnio:flutter-best-practices` automatically** - always wait
  for explicit user confirmation
- **NEVER recommend CODEOWNERS or SECURITY.md files** - these are
  governance decisions, not technical requirements
- **NEVER recommend operational documentation** (runbooks, deployment
  procedures, monitoring) - focus on technical setup only
- **ALWAYS use FVM for Flutter version management** - global
  configuration is MANDATORY
- **ALWAYS execute comprehensive dependency management** - root, packages,
  and apps must have dependencies installed

**Execution Discipline (NON-NEGOTIABLE)**:
- **NEVER skip, combine, or abbreviate any step** — each step in this plan
  MUST be executed individually and completely
- **NEVER summarize a reference file instead of executing it** — you MUST
  read each reference file AND follow its instructions fully
- **NEVER take shortcuts** — even if you believe you already know the answer,
  you MUST execute the analysis commands and collect real evidence
- **ALWAYS read the reference file first** — before executing any step, read
  the referenced .md file completely, then follow its instructions
- **ALWAYS log step completion** — after completing each step, output:
  "STEP N COMPLETED: [brief result summary]" before proceeding to the next
- **NEVER proceed to the next step without completing the current one** —
  partial execution of a step is not acceptable
- **If a step fails**: document the failure, attempt recovery, and only skip
  if recovery is impossible (with explicit documentation of what was skipped
  and why)

## REQUIREMENT - FLUTTER VERSION ALIGNMENT

**MANDATORY STEP 0**: Before executing any Flutter project analysis,
ALWAYS verify and align the global Flutter version with the project's
required version using FVM.

**Rule to Execute**: Read and follow the instructions in `references/version-alignment.md`

**CRITICAL REQUIREMENT**: This step MUST configure FVM global version to
match project requirements. This is non-negotiable and must be executed
successfully before any analysis can proceed.

This requirement applies to ANY Flutter project regardless of versions
found and ensures accurate analysis by preventing version-related build
failures.

## Step 0. Flutter Environment Setup and Test Coverage Verification

Goal: Configure Flutter environment with MANDATORY FVM global
configuration and execute comprehensive dependency management with tests
and coverage verification.

**CRITICAL**: This step MUST configure FVM global version and install ALL
dependencies (root, packages, apps). Execution stops if FVM global
configuration fails.

**Rules to Execute**:
1. Read and follow the instructions in `references/tool-installer.md` (MANDATORY: Installs Node.js, FVM)
2. Read and follow the instructions in `references/version-alignment.md` (MANDATORY - stops if fails)
3. Read and follow the instructions in `references/version-validator.md`
4. Read and follow the instructions in `references/test-coverage.md` (coverage generation)

**Execution Order**:
1. Execute `references/tool-installer.md` rule first (MANDATORY - stops if fails)
2. Execute `references/version-alignment.md` rule (MANDATORY - stops if fails)
3. Execute `references/version-validator.md` rule to verify FVM global setup
   and comprehensive dependency management
4. Execute `references/test-coverage.md` rule to generate coverage

**Comprehensive Dependency Management**:
- Root project: `fvm flutter pub get`
- All packages: `find packages/ -name "pubspec.yaml" -execdir fvm flutter
  pub get \;`
- All apps: `find apps/ -name "pubspec.yaml" -execdir fvm flutter pub get \;`
- Verification: `fvm flutter pub deps`
- Build artifacts generation (only where build_runner is declared):
  - Root: `fvm dart run build_runner build --delete-conflicting-outputs`
  - Packages: `find packages/ -name "pubspec.yaml" -execdir sh -c 'if
    grep -q "build_runner" pubspec.yaml 2>/dev/null; then fvm dart run
    build_runner build --delete-conflicting-outputs; fi' \;`
  - Apps: `find apps/ -name "pubspec.yaml" -execdir sh -c 'if grep -q
    "build_runner" pubspec.yaml 2>/dev/null; then fvm dart run
    build_runner build --delete-conflicting-outputs; fi' \;`

**Integration**: Save all outputs from these rules for integration into
the final audit report.

**Failure Handling**: If FVM global configuration fails, STOP execution
and provide resolution steps.

## Parallel Execution Strategy

Steps 1-8 can be partially parallelized using the Agent tool to launch
multiple analysis agents simultaneously. Use the following wave structure:

**Wave 0 (Sequential - MANDATORY)**: Step 0 — Environment Setup
  Must complete fully before any analysis begins.

**Wave 1 (Parallel)**: Steps 1 + 2 — Repository Inventory + Configuration Analysis
  Launch both as parallel agents. Both read from the filesystem independently.

**Wave 2 (Parallel)**: Steps 3 + 4 + 5 + 8 — CI/CD + Testing + Code Quality + AI Harness & Adoption
  Launch all four as parallel agents. Independent read-only analyses. Step 8
  depends on no prior artifact, so it joins this wave without adding a new one.

**Wave 3 (Parallel)**: Steps 6 + 7 — State Management + Documentation
  Launch both as parallel agents. Independent analyses; neither depends on
  the other's output.

**Wave 4 (Sequential)**: Steps 9 + 10 — Report Generation + Export
  Must run last — requires ALL previous results.

**Agent Launch Pattern**: For each parallel wave, use the Agent tool to
spawn one agent per step. Each agent MUST:
1. Read the referenced .md file completely
2. Execute ALL instructions in that file
3. Return the complete analysis results
4. Never abbreviate or summarize — return full evidence

Example for Wave 1:
- Agent 1: "Read references/repository-inventory.md and execute ALL instructions. Return complete findings."
- Agent 2: "Read references/config-analysis.md and execute ALL instructions. Return complete findings."

## Step 1. Repository Inventory

Goal: Detect repository structure, platform folders, monorepo packages,
and feature organization.

**Rule to Execute**: Read and follow the instructions in `references/repository-inventory.md`

**Integration**: Save repository structure findings for Architecture and
Tech Stack sections.

## Step 2. Core Configuration Files and Internationalization

Goal: Read and analyze Flutter/Dart configuration files for version
info, dependencies, linter setup, and internationalization
configuration.

**Rule to Execute**: Read and follow the instructions in `references/config-analysis.md`

**Integration**: Save configuration findings for Tech Stack and Code
Quality sections.

## Step 3. CI/CD Workflows Analysis

Goal: Read all GitHub Actions workflows and related CI/CD configuration files.

**Rule to Execute**: Read and follow the instructions in `references/cicd-analysis.md`

**Integration**: Save CI/CD findings for CI/CD section scoring.

## Step 4. Testing Infrastructure

Goal: Find and classify all test files, identify coverage
configuration and test types.

**Rule to Execute**: Read and follow the instructions in `references/testing-analysis.md`

**Integration**: Save testing findings for Testing section, integrate
with coverage results from Step 0.

## Step 5. Code Quality and Linter

Goal: Analyze linter configuration, exclusions, and code quality enforcement.

**Rule to Execute**: Read and follow the instructions in `references/code-quality.md`

**Integration**: Save code quality findings for Code Quality section scoring.

## Step 6. State Management Analysis

Goal: Analyze state management library selection, usage patterns
(BLoC/Cubit, Riverpod, Provider, GetX), and architectural quality
signals such as mixed libraries, business logic in widgets, and
BuildContext leaking into the state layer.

**Rule to Execute**: Read and follow the instructions in `references/state-management-analysis.md`

**Integration**: Save state management findings for State Management
section scoring.

## Step 7. Documentation and Operations

Goal: Review technical documentation, build instructions, and
environment setup (no operational/runbook content).

**Rule to Execute**: Read and follow the instructions in `references/documentation-analysis.md`

**Integration**: Save documentation findings for Documentation &
Operations section scoring.

## Step 8. AI Harness & Adoption Analysis

Goal: Score the project's AI harness — CLAUDE.md, `.claude/rules/`,
`.claude/settings.json` permissions and hooks, `.claude/agents/`,
commands/skills — and the pre-push git hook, on quality, not just
presence, against the 10-dimension, 100-point rubric. Existence is
judged on disk; whether the harness is committed is scored once, in
dimension 10.

**Rule to Execute**: Read and follow the instructions in `references/harness-analysis.md`

**Integration**: Save AI Harness & Adoption findings for the AI
Harness & Adoption section scoring.

## Step 9. Generate Final Report

Goal: Generate the final Flutter Project Health Audit report by
integrating all analysis results.

**Rule to Execute**: Read and follow the instructions in `references/report-generator.md`

**Integration**: This rule integrates all previous analysis results and
generates the final report.

**Report Sections**:
- Executive Summary with overall score
- At-a-Glance Scorecard with all 9 section scores
- All 9 detailed sections (Tech Stack, Architecture, State Management,
  Repositories & Data Layer, Testing, Code Quality,
  Documentation & Operations, CI/CD, AI Harness & Adoption)
- Additional Metrics (including coverage percentages)
- Quality Index
- Risks & Opportunities (5-8 bullets)
- Recommendations (6-10 prioritized actions)
- Appendix: Evidence Index

## Step 10. Export Final Report

Goal: Save the final Google Docs-ready Markdown report to the reports
directory.

**Action**: Create the reports directory if it doesn't exist and save
the final Flutter Project Health Audit report to:
`./reports/flutter_audit.md`

**Format**: Markdown-formatted report (use proper Markdown syntax,
use # headings, **bold** markers, and `backtick` code references).

**Command**:
```bash
mkdir -p reports
# Save report content to ./reports/flutter_audit.md
```

## Step 11. Optional Best Practices Check Prompt

**CRITICAL**: After completing Step 10, you MUST ask the user if they
want to execute the Best Practices Check plan. **NEVER execute it
automatically**.

**Action**: Prompt the user with the following question:

```
Flutter Project Health Audit completed successfully!

Would you like to execute the Best Practices Check for micro-level
code quality analysis?
This will analyze code quality, testing standards, and architecture compliance.

Plan: /somnio:flutter-best-practices

Type 'yes' or 'y' to proceed, or 'no' or 'n' to skip.
```

**Rules**:
- **NEVER execute `/somnio:flutter-best-practices` automatically**
- **ALWAYS wait for explicit user confirmation**
- If user confirms, execute `/somnio:flutter-best-practices`
- If user declines or doesn't respond, end execution here

**Best Practices Plan Details** (only if user confirms):
- Plan: `/somnio:flutter-best-practices`
- Steps:
  1. `references/testing-quality.md` (from `/somnio:flutter-best-practices`)
  2. `references/architecture-compliance.md` (from `/somnio:flutter-best-practices`)
  3. `references/code-standards.md` (from `/somnio:flutter-best-practices`)
  4. `references/best-practices-format-enforcer.md` (from `/somnio:flutter-best-practices`)
  5. `references/best-practices-generator.md` (from `/somnio:flutter-best-practices`)

**Benefits of Combined Execution** (informational only):
- **Macro-level analysis** (Health Audit): Project infrastructure,
  CI/CD, documentation
- **Micro-level analysis** (Best Practices): Code quality, testing
  standards, architecture compliance
- **Comprehensive coverage**: Both infrastructure and code
  implementation quality
- **Separate reports**: Each plan generates its own report for focused analysis

**Report Outputs**:
- Health Audit: `./reports/flutter_audit.md`
- Best Practices: Generated by `references/best-practices-generator.md` (from `/somnio:flutter-best-practices`) (see
  plan for output location)

**Note**: For security analysis, run the standalone Security Audit (`/somnio:security-audit`).

## Execution Summary

**Total Rules**: 13 rules

**Rule Execution Order**:
1. Read and follow the instructions in `references/tool-installer.md` {model: cheap}
2. Read and follow the instructions in `references/version-alignment.md` (MANDATORY - stops if FVM global fails) {model: cheap}
3. Read and follow the instructions in `references/version-validator.md` (verification of FVM global setup) {model: cheap}
4. Read and follow the instructions in `references/test-coverage.md` (coverage generation) {model: cheap}
5. Read and follow the instructions in `references/repository-inventory.md` {model: cheap}
6. Read and follow the instructions in `references/config-analysis.md` {model: cheap}
7. Read and follow the instructions in `references/cicd-analysis.md` {model: mid}
8. Read and follow the instructions in `references/testing-analysis.md` {model: mid}
9. Read and follow the instructions in `references/code-quality.md` {model: mid}
10. Read and follow the instructions in `references/state-management-analysis.md` {model: mid}
11. Read and follow the instructions in `references/documentation-analysis.md` {model: cheap}
12. Read and follow the instructions in `references/harness-analysis.md` {model: mid}
13. Read and follow the instructions in `references/report-generator.md` {model: frontier}

**Wave-Based Parallel Execution**:
- Wave 0 (Sequential): Step 0 — Environment Setup (rules 1-4)
- Wave 1 (Parallel): Steps 1 + 2 — Repository Inventory + Configuration (rules 5-6)
- Wave 2 (Parallel): Steps 3 + 4 + 5 + 8 — CI/CD + Testing + Code Quality + AI Harness & Adoption (rules 7-9, 12)
- Wave 3 (Parallel): Steps 6 + 7 — State Management + Documentation (rules 10-11)
- Wave 4 (Sequential): Steps 9 + 10 — Report Generation + Export (rule 13)

## Subagent Dispatch (in-session)

When executed inside a Claude Code session (not via `somnio run`), the audit is orchestrated by `agents/orchestrator.md` using the Agent tool to fan out to tiered subagents in dependency-ordered waves. The Rule Execution Order above remains the CLI path (`somnio run`); this section documents the in-session path.

**Entry point**: `agents/orchestrator.md` (mid tier)

**Wave Plan**:

| Wave | Mode | Agents dispatched | Tier |
|------|------|-------------------|------|
| Wave 0 | Sequential (MANDATORY stop-on-failure) | `env-setup` | cheap |
| Wave 1 | Parallel | `repo-analyzer`, `config-analyzer` | cheap, cheap |
| Wave 2 | Parallel | `cicd-analyzer`, `testing-analyzer`, `code-quality-analyzer`, `harness-analyzer` | mid, mid, mid, mid |
| Wave 3 | Parallel | `docs-analyzer`, `state-management-analyzer` | cheap, mid |
| Wave 4 | Sequential | `report-writer` | frontier |

**Dispatch Table**:

| Agent file | Tier | Reference(s) covered | Artifact written |
|------------|------|----------------------|------------------|
| `agents/env-setup.md` | cheap | `references/tool-installer.md`, `references/version-alignment.md`, `references/version-validator.md`, `references/test-coverage.md` | `reports/.artifacts/flutter_health/step_00_test_coverage.md` |
| `agents/repo-analyzer.md` | cheap | `references/repository-inventory.md` | `reports/.artifacts/flutter_health/step_01_repository_inventory.md` |
| `agents/config-analyzer.md` | cheap | `references/config-analysis.md` | `reports/.artifacts/flutter_health/step_02_config_analysis.md` |
| `agents/cicd-analyzer.md` | mid | `references/cicd-analysis.md` | `reports/.artifacts/flutter_health/step_03_cicd_analysis.md` |
| `agents/testing-analyzer.md` | mid | `references/testing-analysis.md` | `reports/.artifacts/flutter_health/step_04_testing_analysis.md` |
| `agents/code-quality-analyzer.md` | mid | `references/code-quality.md` | `reports/.artifacts/flutter_health/step_05_code_quality.md` |
| `agents/docs-analyzer.md` | cheap | `references/documentation-analysis.md` | `reports/.artifacts/flutter_health/step_06_documentation_analysis.md` |
| `agents/harness-analyzer.md` | mid | `references/harness-analysis.md` | `reports/.artifacts/flutter_health/step_07_harness_analysis.md` |
| `agents/state-management-analyzer.md` | mid | `references/state-management-analysis.md` | `reports/.artifacts/flutter_health/step_08_state_management_analysis.md` |
| `agents/report-writer.md` | frontier | `references/report-generator.md`, `references/report-format-enforcer.md`, `assets/report-template.md` | `reports/flutter_audit.md` |

**Orchestrator rules**:
- Wave 0 is the only hard stop: failure halts the entire audit.
- For Waves 1–3, a missing artifact triggers one retry; after retry failure the section is flagged as unavailable and execution continues.
- The report-writer receives the full artifact manifest from the orchestrator; it never re-reads raw source files.
- Tier resolution: cheap → Haiku (Claude) or provider equivalent; mid → Sonnet; frontier → Opus.

**Benefits of Modular Approach**:
- Each rule can be executed independently
- Outputs can be saved and reused
- Easier debugging and maintenance
- Wave-based parallelization accelerates analysis using the Agent tool
- Clear separation of concerns
- Strict no-shortcuts enforcement ensures complete, evidence-based analysis
- Comprehensive dependency management for monorepos
- Complete FVM global configuration enforcement
- Full project environment setup with all dependencies

## Report Metadata (MANDATORY)

Every generated report MUST include a metadata block at the very end. This is non-negotiable — never omit it.

To resolve the source and version:
1. Look for `.claude-plugin/plugin.json` by traversing up from this skill's directory
2. If found, read `name` and `version` from that file (plugin context)
3. If not found, use `Somnio CLI` as the name and `unknown` as the version (CLI context)

Include this block at the very end of the report:

```
---
Generated by: [plugin name or "Somnio CLI"] v[version]
Skill: flutter-health-audit
Date: [YYYY-MM-DD]
Somnio AI Tools: https://github.com/somnio-software/somnio-ai-tools
---
```