🧬 kbird.ai

AGENTS

6 min read

Convergence - AGENTS.md

Project Overview

Convergence is a Flutter mobile application implementing “The Convergence Protocol — 40 Nodes of Cognitive Counter-Hacking”. It is a self-improvement and mindfulness application that provides users with 40 cognitive techniques (called “nodes”) organized into 5 thematic suites to help resist digital manipulation and improve cognitive hygiene.

The app follows a gamified approach with streaks, progress tracking, and weekly reflections to encourage consistent practice of cognitive defense techniques.

Technology Stack

  • Framework: Flutter (SDK >=3.0.0 <4.0.0)
  • Language: Dart
  • State Management: Provider pattern (provider package)
  • Database: SQLite via sqflite package
  • UI Design: Material Design 3 with custom theming

Key Dependencies

PackagePurpose
sqfliteLocal SQLite database for practice logs
path_providerAccess to filesystem paths for database
shared_preferencesSimple key-value storage for settings
flutter_local_notificationsLocal push notifications
intlInternationalization and date formatting
fl_chartData visualization (radar charts for progress)
home_widgetHome screen widgets support
flutter_svgSVG image support
flutter_lintsDart/Flutter linting rules

Project Structure

convergence/
├── android/              # Android platform configuration (minimal)
├── ios/                  # iOS platform configuration (minimal)
├── assets/               # Static assets
│   └── images/           # Image assets (empty currently)
├── lib/
│   ├── data/
│   │   └── nodes_data.dart      # Static data for all 40 nodes
│   ├── models/
│   │   └── node.dart            # Data models (Node, PracticeLog, etc.)
│   ├── providers/
│   │   └── app_provider.dart    # State management and business logic
│   ├── screens/
│   │   ├── home_screen.dart           # Main dashboard
│   │   ├── node_detail_screen.dart    # Individual node details
│   │   ├── log_practice_screen.dart   # Practice logging UI
│   │   ├── pattern_screen.dart        # Stats and progress visualization
│   │   └── weekly_convergence_screen.dart # Weekly review
│   ├── services/
│   │   └── database_service.dart      # SQLite database operations
│   ├── widgets/
│   │   └── streak_counter.dart        # Reusable streak UI component
│   └── main.dart                      # Application entry point
└── pubspec.yaml          # Project configuration and dependencies

Architecture Overview

The app follows a layered architecture with clear separation of concerns:

1. Data Layer (data/)

  • NodesData class contains static configuration for all 40 nodes
  • Each node includes: id, title, activation phrase, warning sign, description, suite assignment, and optional marginalia
  • 5 Node Suites: Recognition, Resistance, Reconstruction, Relationship, Renewal

2. Model Layer (models/)

  • Node: Immutable data class representing a cognitive technique
  • PracticeLog: Record of user practice sessions
  • NodeSuite: Enum defining the 5 thematic suites
  • WeeklyConvergence & UserStats: Supporting data structures

3. Service Layer (services/)

  • DatabaseService: Singleton pattern for SQLite operations
  • Tables: practice_logs, weekly_convergences, user_settings
  • Handles streak calculation, practice counting, and data persistence

4. Provider Layer (providers/)

  • AppProvider: Main state management using ChangeNotifier
  • Aggregates data from database and exposes to UI
  • Calculates derived state (streaks, progress, top/bottom nodes)
  • Handles practice logging and data refresh

5. Presentation Layer (screens/, widgets/)

  • Screen widgets are stateless where possible, stateful when needed
  • Use Consumer<AppProvider> or context.read<AppProvider>() for state access
  • Material Design 3 components with custom theming

Key Features

  1. Daily Node: Rotates through 40 nodes based on day of year
  2. Practice Logging: Record practice intensity (1-5) and context
  3. Streak Tracking: Current and longest streak calculation
  4. Progress Visualization: Radar chart showing progress by suite
  5. Weekly Convergence: Weekly review of all 40 nodes with reflection
  6. Pattern Analysis: Top 3 and bottom 3 nodes by practice count

Build and Run Commands

Prerequisites

  • Flutter SDK (>=3.0.0)
  • Dart SDK
  • Android SDK (for Android builds)
  • Xcode (for iOS builds, macOS only)

Development Commands

# Get dependencies
flutter pub get
 
# Run in debug mode
flutter run
 
# Run on specific device
flutter run -d <device_id>
 
# Build APK (Android)
flutter build apk
 
# Build app bundle (Android)
flutter build appbundle
 
# Build iOS app (macOS only)
flutter build ios
 
# Run tests
flutter test
 
# Analyze code
flutter analyze
 
# Format code
flutter format lib/

Code Style Guidelines

Dart/Flutter Conventions

  • Follows flutter_lints rules (standard Flutter linting)
  • Use const constructors where possible
  • Prefer single quotes for strings
  • Use trailing commas for better diffs

Naming Conventions

  • Files: snake_case (e.g., home_screen.dart)
  • Classes: PascalCase (e.g., HomeScreen)
  • Variables/Functions: camelCase (e.g., currentStreak)
  • Constants: camelCase for local, PascalCase for enum-like constants

UI Patterns

  • Use CustomScrollView with SliverAppBar for scrollable screens
  • Theme-aware colors via Theme.of(context).colorScheme
  • Consistent padding: 16px for screen edges, 8px/12px/24px for internal spacing
  • Card-based layout with rounded corners (8px-16px radius)

State Management Patterns

// Reading from provider
final provider = context.read<AppProvider>();
 
// Listening to provider (rebuilds UI)
Consumer<AppProvider>(
  builder: (context, provider, child) {
    // Build UI with provider data
  },
)

Testing

Currently, the project has no test files. Testing infrastructure is available via flutter_test dev dependency.

test/
├── models/
│   └── node_test.dart
├── providers/
│   └── app_provider_test.dart
├── services/
│   └── database_service_test.dart
└── widgets/
    └── streak_counter_test.dart

Running Tests

# Run all tests
flutter test
 
# Run with coverage
flutter test --coverage
 
# Run specific test file
flutter test test/models/node_test.dart

Database Schema

practice_logs

ColumnTypeDescription
idINTEGER PRIMARY KEYAuto-increment ID
node_idINTEGERReference to node (1-40)
practiced_atTEXT (ISO8601)Timestamp of practice
intensityINTEGER1-5 intensity rating
contextTEXTOptional context notes

weekly_convergences

ColumnTypeDescription
idINTEGER PRIMARY KEYAuto-increment ID
week_startTEXT (ISO8601)Start of week
nodes_practicedTEXTJSON array of node IDs
most_avoidedINTEGERNode ID most avoided
commit_to_deepenINTEGERNode ID to focus on
reflectionTEXTUser reflection text

user_settings

ColumnTypeDescription
keyTEXT PRIMARY KEYSetting identifier
valueTEXTSetting value

The 40 Nodes

Nodes are organized into 5 suites of 8 nodes each:

  1. SUITE I: RECOGNITION (Perception Hygiene)

    • Pattern Recognition, Emotional Resonance, Source Verification, Temporal Displacement, Attention Architecture, Frequency Analysis, Urgency Decomposition, Novelty Assessment

  2. SUITE II: RESISTANCE (Response Protocols)

    • The Pause Protocol, Value Reaffirmation, Alternative Narrative, Cost Calculation, Identity Boundary Check, Emotional Audit, Temporal Zoom, Silence Practice

  3. SUITE III: RECONSTRUCTION (Meaning-Making)

    • First Principles Return, Analog Translation, Embodied Verification, Sleep Integration, Cross-Domain Application, Historical Parallel, Inversion Test, Stakeholder Mapping

  4. SUITE IV: RELATIONSHIP (Social Cognition)

    • Intergenerational Bridge, Non-Human Perspective, Asymmetric Empathy, Local Context Weighting, Synchronous Ritual, Conflict Preservation, Mentor Memory, Descendant Imagination

  5. SUITE V: RENEWAL (Maintenance)

    • Cognitive Spring Cleaning, Attention Diet, Boredom Reclamation, Manual Competence, Nature Exposure, Creative Output, Service Orientation, The Weekly Convergence

Security Considerations

  • All data is stored locally on device (SQLite)
  • No network requests are made by the application
  • No sensitive authentication or user identification
  • Data persists in app’s private storage
  • TODO: Consider export functionality for data backup

Known TODOs

  1. HomeScreen: Settings screen implementation
  2. PatternScreen: Export session data feature
  3. WeeklyConvergenceScreen: Save weekly convergence to database
  4. assets/images/: Add actual image assets

Development Notes

  • The app uses a green color scheme (0xFF2E7D32) as the seed color
  • Font family is set to ‘Inter’ (must be bundled for production)
  • Streak calculation is date-based (not time-based)
  • Today’s node is determined by dayOfYear % 40
  • Practice intensity colors: blue (1) → green (2) → orange (3) → deep orange (4) → red (5)

Graph View