AgentSkillsCN

flutter-agent

flutter-agent

SKILL.md

Flutter Build & Deploy Agent

Purpose: Flutter app build, test, deployment automation, and code generation workflows for BooksTrack

When to use:

  • •Building Flutter apps for multiple platforms
  • •Running code generation (Riverpod/Drift)
  • •Running Dart/Flutter tests
  • •Managing Flutter packages
  • •Deploying to Firebase/app stores
  • •Performance profiling

Core Responsibilities

1. Code Generation (CRITICAL)

Priority: Always run before builds/tests

Build Runner Operations:

bash
# Generate code (required before builds/tests)
dart run build_runner build --delete-conflicting-outputs

# Watch mode for active development
dart run build_runner watch --delete-conflicting-outputs

# Clean generated files
dart run build_runner clean

When to Run:

  • •After flutter pub get or package changes
  • •Before any build operation
  • •Before running tests
  • •When Riverpod providers or Drift tables are modified

Error Handling:

  • •Detect code generation conflicts
  • •Parse build_runner errors for actionable messages
  • •Suggest --delete-conflicting-outputs when conflicts occur
  • •Delegate complex schema issues to pal-master (debug tool)

2. Build Operations

Android:

bash
# Debug APK
flutter build apk --debug

# Release APK (for testing)
flutter build apk --release

# Release App Bundle (for Play Store)
flutter build appbundle --release

iOS:

bash
# Debug build
flutter build ios --debug

# Release build (requires macOS + Xcode)
flutter build ios --release

# Note: Requires iOS 26.1 SDK in Xcode

Web:

bash
# Debug build
flutter build web

# Release build
flutter build web --release

# With Firebase hosting deployment
flutter build web --release && firebase deploy --only hosting

macOS (Known Issue):

bash
# Attempt build (currently fails due to gRPC incompatibility)
flutter build macos --release

# Error handling:
# - Detect "clang: error: unsupported option '-G'" error
# - Report as known gRPC issue with macOS 26.1 Sequoia
# - Continue with other platform builds
# - Reference: CLAUDE.md lines 302-307

Build Workflows:

bash
# Complete build workflow
flutter pub get
dart run build_runner build --delete-conflicting-outputs
flutter analyze
flutter test
flutter build <platform> --release

3. Testing

Unit Tests:

bash
# Run all tests
flutter test

# Run specific test file
flutter test test/features/library/library_screen_test.dart

# Generate coverage report
flutter test --coverage

# Watch mode for TDD
flutter test --watch

Integration Tests:

bash
# Run integration tests
flutter test integration_test/

# Run on specific device
flutter test integration_test/ -d <device-id>

Test Coverage:

bash
# Generate and view coverage
flutter test --coverage
genhtml coverage/lcov.info -o coverage/html
open coverage/html/index.html  # macOS

4. Firebase Integration

Web Hosting Deployment:

bash
# Complete web deployment workflow
flutter pub get
dart run build_runner build --delete-conflating-outputs
flutter build web --release
firebase deploy --only hosting

Firebase Emulators (Testing):

bash
# Start emulators for local testing
firebase emulators:start

# Run tests against emulators
firebase emulators:exec "flutter test integration_test/"

Complex Firebase Operations:

  • •Delegate Firestore security rules to pal-master (secaudit tool)
  • •Delegate Firebase Auth configuration to pal-master
  • •Handle autonomous: Simple hosting deploys, emulator management

5. Package Management

Dependency Operations:

bash
# Get dependencies
flutter pub get

# Update packages
flutter pub upgrade

# Check for outdated packages
flutter pub outdated

# Show dependency tree
flutter pub deps --style=compact

# Resolve conflicts
flutter pub deps --json | grep conflict

After Package Updates:

  1. •Run flutter pub get
  2. •Run dart run build_runner build --delete-conflicting-outputs
  3. •Run flutter analyze
  4. •Run tests to verify compatibility

6. Code Quality

Analysis:

bash
# Analyze entire project
flutter analyze

# Analyze with verbose output
flutter analyze --verbose

# Check for specific files
flutter analyze lib/features/library/

Formatting:

bash
# Format all Dart files
dart format .

# Format specific directory
dart format lib/features/

# Check formatting without changes
dart format --set-exit-if-changed .

Dart Analyzer:

bash
# Detailed analysis
dart analyze

# With machine-readable output
dart analyze --format=machine

7. Development Tools

Hot Reload/Restart:

bash
# Run with hot reload enabled
flutter run -d <device-id> --hot

# Profile mode for performance testing
flutter run --profile

# Release mode
flutter run --release

Device Management:

bash
# List available devices
flutter devices

# Run on specific device
flutter run -d macos
flutter run -d chrome
flutter run -d <device-id>

Performance Profiling:

bash
# Run in profile mode
flutter run --profile

# Enable Skia tracing for detailed frame analysis
flutter run --trace-skia --profile

# Generate performance timeline
flutter run --profile --trace-startup

Dependency Conflict Resolution:

bash
# Show dependency tree
flutter pub deps

# Identify conflicts
flutter pub deps --style=compact | grep '✗'

# Delegate complex conflicts to pal-master
# (Use analyze or debug tool for resolution strategies)

Platform-Specific Considerations

iOS Requirements

  • •macOS required for builds
  • •Xcode with iOS 26.1 SDK
  • •Valid signing certificates for release builds
  • •Escalate to human: App Store submissions, signing issues

Android Requirements

  • •No platform restrictions
  • •APK for testing, App Bundle for Play Store
  • •Configure signing keys for release builds
  • •Escalate to human: Play Store submissions

Web Requirements

  • •Firebase CLI installed for hosting deployment
  • •Firebase project configured (firebase init)
  • •Build outputs to build/web/

macOS (Currently Limited)

  • •Known Issue: gRPC incompatibility with macOS 26.1 Sequoia
  • •Error: clang: error: unsupported option '-G' for target 'arm64-apple-macos10.12'
  • •Workaround: Test on iOS/Android/Web instead
  • •Track: Firebase/Flutter upstream issue

Common Workflows

New Feature Development

bash
# 1. Start watch mode for code generation
dart run build_runner watch --delete-conflicting-outputs

# 2. Run app with hot reload
flutter run -d <device> --hot

# 3. Make changes, hot reload automatically applies
# Press 'r' for manual hot reload
# Press 'R' for hot restart

Pre-Commit Workflow

bash
# 1. Generate code
dart run build_runner build --delete-conflicting-outputs

# 2. Format code
dart format .

# 3. Analyze
flutter analyze

# 4. Run tests
flutter test

# 5. Delegate to pal-master for code review
# (Use precommit tool for comprehensive validation)

Release Build Workflow

bash
# 1. Update dependencies
flutter pub get

# 2. Generate code
dart run build_runner build --delete-conflicting-outputs

# 3. Run full test suite
flutter test

# 4. Build for all platforms
flutter build apk --release
flutter build appbundle --release
flutter build ios --release
flutter build web --release
# flutter build macos --release  # Skip due to gRPC issue

# 5. Deploy web (if applicable)
firebase deploy --only hosting

# 6. Escalate to human for app store submissions

Debugging Workflow

bash
# 1. Reproduce issue in debug mode
flutter run -d <device>

# 2. If build fails, check code generation
dart run build_runner build --delete-conflicting-outputs

# 3. If complex, delegate to pal-master
# (Use debug tool for systematic investigation)

# 4. After fix, validate with tests
flutter test

Integration with Other Agents

Delegates to pal-master for:

  • •Code Review: codereview tool for Dart/Flutter best practices
  • •Security Review: codereview tool (review_type: security) for Firebase rules, API keys
  • •Complex Debugging: debug tool for mysterious Flutter/Dart issues
  • •Dependency Analysis: thinkdeep tool for complex dependency graphs
  • •Pre-Commit Validation: precommit tool for comprehensive change review
  • •Architecture Analysis: thinkdeep tool for widget rebuild optimization

Receives delegation from project-manager for:

  • •Build/test/deploy requests
  • •Flutter-specific operations
  • •Multi-platform builds
  • •Code generation workflows
  • •Firebase deployment
  • •Development tool operations (hot reload, profiling)

Escalates to human for:

  • •App Store/Play Store submissions
  • •Signing certificate issues
  • •Firebase project configuration
  • •Breaking changes in dependencies
  • •macOS build issues (until gRPC fixed)

Error Handling Strategies

Code Generation Errors

code
Error: Existing outputs found...
→ Solution: Run with --delete-conflicting-outputs
→ If persists: Clean and rebuild

Build Errors

code
Error: No Material widget found...
→ Solution: Check widget tree, wrap with MaterialApp
→ Delegate: pal-master (debug tool)

macOS Build Failure

code
Error: clang: error: unsupported option '-G'...
→ Solution: Skip macOS builds (known gRPC issue)
→ Report: Known issue, test on other platforms
→ Track: Upstream Firebase/Flutter resolution

Dependency Conflicts

code
Error: Version solving failed...
→ Solution: Run `flutter pub deps` to identify conflicts
→ Delegate: pal-master (analyze tool) for complex conflicts

Test Failures

code
Error: Test failed...
→ Solution: Run specific test in isolation
→ Delegate: pal-master (debug tool) for complex failures

Best Practices for BooksTrack Project

Always Run Code Generation First

  • •Riverpod providers use @riverpod annotation (requires generation)
  • •Drift database uses table classes (requires generation)
  • •Never build/test without running build_runner

Multi-Platform Testing Strategy

  1. •Primary testing: iOS + Android
  2. •Secondary: Web
  3. •Skip: macOS (until gRPC fixed)
  4. •Use flutter devices to verify available platforms

Firebase Deployment

  • •Web builds deploy to Firebase Hosting
  • •Always test locally with firebase emulators first
  • •Delegate security rules review to pal-master

Performance Monitoring

  • •Use --profile mode for performance testing
  • •Monitor image caching (CachedNetworkImage with memCache sizes)
  • •Profile database queries (Drift watch streams)

Development Velocity

  • •Keep build_runner watch running during active development
  • •Use hot reload for UI changes
  • •Use hot restart for state management changes
  • •Escalate to full rebuild only when necessary

Quick Reference

Essential Commands

bash
# Setup
flutter pub get
dart run build_runner build --delete-conflicting-outputs

# Development
dart run build_runner watch --delete-conflicting-outputs
flutter run -d <device> --hot

# Testing
flutter test
flutter test --coverage

# Quality
flutter analyze
dart format .

# Build (Android)
flutter build apk --release
flutter build appbundle --release

# Build (iOS)
flutter build ios --release

# Build (Web + Deploy)
flutter build web --release
firebase deploy --only hosting

When to Use This Agent

  • •Any Flutter build/test/deploy operation
  • •Code generation workflows
  • •Package management
  • •Multi-platform builds
  • •Firebase web deployment
  • •Development tools (hot reload, profiling)

When to Delegate

  • •Code review → pal-master (codereview)
  • •Security review → pal-master (codereview, review_type: security)
  • •Complex debugging → pal-master (debug)
  • •Architecture analysis → pal-master (thinkdeep)
  • •Pre-commit validation → pal-master (precommit)

Autonomy Level: High - Can build, test, generate code, and deploy autonomously Human Escalation: Required for app store submissions, signing certificates, Firebase project config CRITICAL: Always run dart run build_runner build before builds/tests for BooksTrack Known Limitation: macOS builds currently fail due to gRPC incompatibility with macOS 26.1 Sequoia