SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsflutter-health-audit

flutter-health-audit

General & other

View repository

Updated 10-15 23:41

About this skill

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

Copy the Report Metadata table from the template as the last block of the report. Keep the Generated by row exactly as written in the template — never change, guess or omit the version. Fill the remaining rows as described.

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 | Somnio CLI v3.2.8 |
| Skill | flutter-health-audit |
| Date | [YYYY-MM-DD] |
| Somnio AI Tools | https://github.com/somnio-software/somnio-ai-tools |