flutter-health-audit

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 (15 numbered sections; no "Quality Index" — it was a duplicate of the scorecard and has been removed):

• Executive Summary with overall score
• At-a-Glance Scorecard with all 9 section scores, plus a Test Coverage line and a one-sentence interpretation of the Overall Score
• All 9 detailed sections (Tech Stack, Architecture, State Management, Repositories & Data Layer, Testing, Code Quality, Documentation & Operations, CI/CD, AI Harness & Adoption)
• Additional Metrics (no coverage percentages — those live only in the scorecard's Test Coverage line and Testing's Code Coverage / Coverage Breakdown fields)
• Risks & Opportunities (5-8 bullets)
• Recommendations (6-10 prioritized actions)
• Appendix: Evidence Index
• Appendix: Scoring Methodology (unnumbered — the weight table; the only place in the report where weights may appear)
• Report Metadata (unnumbered — see "Report Metadata (MANDATORY)" below)

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/<YYYY-MM-DD>-<project>-flutter-health-audit.md

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

Command:

mkdir -p reports
# Save report content to ./reports/<YYYY-MM-DD>-<project>-flutter-health-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/<YYYY-MM-DD>-<project>-flutter-health-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-audit/step_00_test_coverage.md
agents/repo-analyzer.md	cheap	references/repository-inventory.md	reports/.artifacts/flutter-health-audit/step_01_repository_inventory.md
agents/config-analyzer.md	cheap	references/config-analysis.md	reports/.artifacts/flutter-health-audit/step_02_config_analysis.md
agents/cicd-analyzer.md	mid	references/cicd-analysis.md	reports/.artifacts/flutter-health-audit/step_03_cicd_analysis.md
agents/testing-analyzer.md	mid	references/testing-analysis.md	reports/.artifacts/flutter-health-audit/step_04_testing_analysis.md
agents/code-quality-analyzer.md	mid	references/code-quality.md	reports/.artifacts/flutter-health-audit/step_05_code_quality.md
agents/docs-analyzer.md	cheap	references/documentation-analysis.md	reports/.artifacts/flutter-health-audit/step_06_documentation_analysis.md
agents/harness-analyzer.md	mid	references/harness-analysis.md	reports/.artifacts/flutter-health-audit/step_07_harness_analysis.md
agents/state-management-analyzer.md	mid	references/state-management-analysis.md	reports/.artifacts/flutter-health-audit/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/<YYYY-MM-DD>-<project>-flutter-health-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 File Name (MANDATORY)

The report file name is always:

<YYYY-MM-DD>-<project>-flutter-health-audit.md

• <YYYY-MM-DD> — the date of this run.
• <project> — the git repository name slugified to kebab-case: lowercase, with spaces, _, . and / turned into -, every other character dropped, and repeated - collapsed. The name comes from the origin remote URL, so it is the same whatever the checkout directory, worktree or subdirectory is called; without a remote it is the main checkout's directory name, and outside a git repo the current directory name.
• The trailing segment is this skill's name and never changes.

Derive it once, before writing anything:

mkdir -p reports
REPO="$(git remote get-url origin 2>/dev/null | sed -E 's#/+$##; s#.*[/:]##; s#\.git$##')"
if [ -z "$REPO" ]; then
  COMMON="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)"
  [ -n "$COMMON" ] && REPO="$(basename "${COMMON%/.git}" .git)"
fi
[ -n "$REPO" ] || REPO="$(basename "$PWD")"
REPORT="reports/$(date +%F)-$(printf '%s' "$REPO" \
  | tr '[:upper:]' '[:lower:]' | tr ' _./' '-' \
  | sed -E 's/[^a-z0-9-]//g; s/-+/-/g; s/^-|-$//g')-flutter-health-audit.md"

Everywhere this skill writes reports/<YYYY-MM-DD>-<project>-flutter-health-audit.md, it means that resolved path.

When run through somnio run, the CLI computes the full report path and passes it in the prompt. Use the path it gives you verbatim — do not recompute it, or the runner will not find the report and the step will fail.

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, as a Markdown table (the plain-text-between---- form is deprecated — the template already renders this as a table and this doc must match it):

## Report Metadata

| Field | Value |
|-------|-------|
| Generated by | [Plugin Name] v[Plugin Version] |
| Skill | flutter-health-audit |
| Date | [YYYY-MM-DD] |
| Somnio AI Tools | https://github.com/somnio-software/somnio-ai-tools |