coregen-cli 3.1.6__py3-none-any.whl

generators/helpers/validation.py

@@ -0,0 +1,364 @@
+"""Validation functions for CoreGen CLI input"""
+
+import re
+from typing import Optional, List, Tuple, Dict
+from pathlib import Path
+from .feature import find_domain_models, find_domain_models_with_class_names, find_enums
+from .utils import to_pascal_case
+
+
+# Dart reserved keywords
+DART_RESERVED_KEYWORDS = {
+    'abstract', 'as', 'assert', 'async', 'await', 'break', 'case', 'catch',
+    'class', 'const', 'continue', 'covariant', 'default', 'deferred', 'do',
+    'dynamic', 'else', 'enum', 'export', 'extends', 'extension', 'external',
+    'factory', 'false', 'final', 'finally', 'for', 'Function', 'get', 'hide',
+    'if', 'implements', 'import', 'in', 'interface', 'is', 'library', 'mixin',
+    'new', 'null', 'on', 'operator', 'part', 'required', 'rethrow', 'return',
+    'set', 'show', 'static', 'super', 'switch', 'sync', 'this', 'throw',
+    'true', 'try', 'typedef', 'var', 'void', 'while', 'with', 'yield'
+}
+
+# Valid Dart primitive types
+VALID_PRIMITIVE_TYPES = {
+    'string', 'String', 'int', 'double', 'bool', 'Bool', 'DateTime', 'datetime', 'date'
+}
+
+# Valid Dart collection types (without generic parameters)
+VALID_COLLECTION_TYPES = {
+    'List', 'list', 'Set', 'set', 'Map', 'map'
+}
+
+# Known value object types (no domain model lookup needed)
+KNOWN_VALUE_OBJECT_TYPES = {
+    'UniqueId'
+}
+
+
+def validate_field_name(field_name: str) -> Tuple[bool, Optional[str]]:
+    """
+    Validate a field name.
+    
+    Args:
+        field_name: The field name to validate
+        
+    Returns:
+        Tuple of (is_valid, error_message)
+    """
+    if not field_name:
+        return False, "Field name cannot be empty"
+    
+    # Check for reserved keywords
+    if field_name.lower() in DART_RESERVED_KEYWORDS:
+        return False, f"'{field_name}' is a Dart reserved keyword. Please use a different name."
+    
+    # Check for valid identifier characters (letters, numbers, underscore)
+    # Must start with letter or underscore
+    if not re.match(r'^[a-zA-Z_][a-zA-Z0-9_]*$', field_name):
+        return False, f"Invalid field name '{field_name}'. Field names must start with a letter or underscore and contain only letters, numbers, and underscores."
+    
+    return True, None
+
+
+def _find_matching_angle_bracket(field_type: str, open_idx: int) -> int:
+    """Return index of the `>` that closes the `<` at *open_idx*, or -1 if unbalanced."""
+    depth = 0
+    for j in range(open_idx, len(field_type)):
+        ch = field_type[j]
+        if ch == '<':
+            depth += 1
+        elif ch == '>':
+            depth -= 1
+            if depth == 0:
+                return j
+    return -1
+
+
+def parse_field_type(field_type: str) -> Tuple[str, Optional[str], Optional[str]]:
+    """
+    Parse a field type, handling generics like List<NoteItem>, List<String?>, Map<String, int>.
+
+    Uses balanced angle brackets so inner types may include `?` (e.g. List<String?>).
+
+    Args:
+        field_type: The field type string (e.g., "List<NoteItem>", "Map<String, int>", "string")
+
+    Returns:
+        Tuple of (base_type, generic_param1, generic_param2).
+        generic_param1/2 are None if not a generic type.
+        For Map<K, V>: returns (Map, K, V).
+        For List<T>/Set<T>: returns (List, T, None).
+    """
+    field_type = field_type.strip()
+    m_head = re.match(r'^(\w+)\s*<', field_type)
+    if not m_head:
+        return field_type, None, None
+    base = m_head.group(1)
+    open_idx = field_type.find('<')
+
+    close_idx = _find_matching_angle_bracket(field_type, open_idx)
+    if close_idx == -1 or close_idx != len(field_type) - 1:
+        return field_type, None, None
+
+    inner = field_type[open_idx + 1:close_idx].strip()
+    if base.lower() == 'map':
+        depth = 0
+        split_at = -1
+        for k, ch in enumerate(inner):
+            if ch == '<':
+                depth += 1
+            elif ch == '>':
+                depth -= 1
+            elif ch == ',' and depth == 0:
+                split_at = k
+                break
+        if split_at == -1:
+            return field_type, None, None
+        k_type = inner[:split_at].strip()
+        v_type = inner[split_at + 1:].strip()
+        return base, k_type, v_type
+    return base, inner, None
+
+
+def validate_field_type(field_type: str, lib_path: Optional[Path] = None, domain_folder: str = "domain") -> Tuple[bool, Optional[str], Optional[str]]:
+    """
+    Validate a field type.
+    
+    Args:
+        field_type: The field type to validate
+        lib_path: Optional path to lib/ directory for checking domain models
+        domain_folder: Domain folder name (default: "domain")
+        
+    Returns:
+        Tuple of (is_valid, error_message, normalized_type)
+        normalized_type is the type as it should appear in Dart code
+    """
+    if not field_type:
+        return False, "Field type cannot be empty", None
+    
+    field_type = field_type.strip()
+    
+    # Detect nullable suffix (e.g., String?, int?, SomeModel?)
+    is_nullable = field_type.endswith('?')
+    if is_nullable:
+        base_field_type = field_type[:-1].strip()
+    else:
+        base_field_type = field_type.strip()
+    
+    base_type, generic_param1, generic_param2 = parse_field_type(base_field_type)
+    
+    base_type_lower = base_type.lower()
+    
+    NORMALIZE_PRIMITIVE = {
+        'string': 'String',
+        'datetime': 'DateTime',
+        'date': 'DateTime',
+        'bool': 'bool',
+        'Bool': 'bool',
+    }
+    
+    def _normalize_primitive(t: str) -> str:
+        return NORMALIZE_PRIMITIVE.get(t.lower(), t)
+    
+    def _resolve_generic_type(gtype: str) -> Tuple[bool, Optional[str], Optional[str]]:
+        """Resolve a generic type parameter: primitive, known VO, enum, or domain model.
+
+        Inner nullability is allowed (e.g. ``String?``, ``Todo?`` inside ``List<...>``).
+        """
+        gtype = gtype.strip()
+        inner_nullable = gtype.endswith('?')
+        g_base = gtype[:-1].strip() if inner_nullable else gtype
+
+        def _with_inner_null(norm: str) -> str:
+            return f"{norm}?" if inner_nullable else norm
+
+        # Dart top types (e.g. Map<String, dynamic> for JSON blobs)
+        if g_base.lower() == 'dynamic':
+            return True, None, _with_inner_null('dynamic')
+        if g_base.lower() == 'object':
+            return True, None, _with_inner_null('Object')
+        if g_base.lower() in VALID_PRIMITIVE_TYPES:
+            return True, None, _with_inner_null(_normalize_primitive(g_base))
+        if g_base in KNOWN_VALUE_OBJECT_TYPES:
+            return True, None, _with_inner_null(g_base)
+        if lib_path:
+            known_enums = find_enums(lib_path, domain_folder)
+            if g_base in known_enums:
+                return True, None, _with_inner_null(g_base)
+            available_models = find_domain_models(lib_path, domain_folder)
+            models_with_classes = find_domain_models_with_class_names(lib_path, domain_folder)
+            if g_base in available_models:
+                return True, None, _with_inner_null(models_with_classes[g_base]['class_name'])
+            for _stem, info in models_with_classes.items():
+                if info['class_name'] == g_base:
+                    return True, None, _with_inner_null(g_base)
+            available_str = ', '.join([f"{k} ({v['class_name']})" for k, v in models_with_classes.items()]) if models_with_classes else 'none'
+            return False, f"Model '{g_base}' not found in domain. Available models: {available_str}. Create it first using: coregen add-domain --name {g_base.lower()}", None
+        return False, f"Model '{g_base}' cannot be validated (lib_path not provided). Please ensure the project path is correct.", None
+    
+    def _with_nullable(normalized: str) -> str:
+        return f"{normalized}?" if is_nullable else normalized
+    
+    # --- UniqueId (known value object, no generic) ---
+    if base_type in KNOWN_VALUE_OBJECT_TYPES:
+        if generic_param1:
+            return False, f"'{base_type}' does not take generic parameters", None
+        return True, None, _with_nullable(base_type)
+    
+    # --- Primitive types ---
+    if base_type_lower in VALID_PRIMITIVE_TYPES:
+        if generic_param1:
+            return False, f"Primitive type '{base_type}' cannot have generic parameters", None
+        return True, None, _with_nullable(_normalize_primitive(base_type))
+    
+    # --- Collection types: List<T>, Set<T>, Map<K, V> ---
+    if base_type_lower in VALID_COLLECTION_TYPES:
+        normalized_base = {'list': 'List', 'set': 'Set', 'map': 'Map'}.get(base_type_lower, base_type)
+        
+        if normalized_base == 'Map':
+            if not generic_param1 or not generic_param2:
+                return False, f"Map requires two generic parameters (e.g., Map<String, int>)", None
+            ok1, err1, norm_key = _resolve_generic_type(generic_param1)
+            if not ok1:
+                return False, f"Invalid Map key type: {err1}", None
+            ok2, err2, norm_val = _resolve_generic_type(generic_param2)
+            if not ok2:
+                return False, f"Invalid Map value type: {err2}", None
+            return True, None, _with_nullable(f"Map<{norm_key}, {norm_val}>")
+        else:
+            if not generic_param1:
+                return False, f"Collection type '{base_type}' requires a generic parameter (e.g., {normalized_base}<ItemType>)", None
+            if generic_param2:
+                return False, f"'{normalized_base}' takes only one generic parameter", None
+            ok, err, normalized_inner = _resolve_generic_type(generic_param1)
+            if not ok:
+                return False, err, None
+            return True, None, _with_nullable(f"{normalized_base}<{normalized_inner}>")
+    
+    # --- Enum type (PascalCase, found in domain/enums/) ---
+    if base_type[0].isupper() and base_type_lower not in VALID_PRIMITIVE_TYPES and lib_path:
+        known_enums = find_enums(lib_path, domain_folder)
+        if base_type in known_enums:
+            if generic_param1:
+                return False, f"Enum type '{base_type}' cannot have generic parameters.", None
+            return True, None, _with_nullable(base_type)
+    
+    # --- Domain model (PascalCase, not a known type) ---
+    if base_type[0].isupper() and base_type_lower not in VALID_PRIMITIVE_TYPES:
+        if generic_param1:
+            return False, f"Domain model type '{base_type}' cannot have generic parameters directly. Use List<{base_type}> for lists.", None
+        
+        if lib_path:
+            available_models = find_domain_models(lib_path, domain_folder)
+            models_with_classes = find_domain_models_with_class_names(lib_path, domain_folder)
+            
+            for _stem, info in models_with_classes.items():
+                if info['class_name'] == base_type:
+                    return True, None, _with_nullable(base_type)
+            
+            if base_type in available_models:
+                class_name = models_with_classes[base_type]['class_name']
+                return True, None, _with_nullable(class_name)
+            
+            available_str = ', '.join([f"{k} ({v['class_name']})" for k, v in models_with_classes.items()]) if models_with_classes else 'none'
+            return False, f"Model '{base_type}' not found in domain. Available models: {available_str}. Create it first using: coregen add-domain --name {base_type.lower()}", None
+        
+        return False, f"Model '{base_type}' cannot be validated (lib_path not provided). Please ensure the project path is correct.", None
+    
+    # --- Unknown type ---
+    suggestions = []
+    if base_type_lower.startswith('str'):
+        suggestions.append('String')
+    elif base_type_lower.startswith('int'):
+        suggestions.append('int')
+    elif base_type_lower.startswith('doub') or base_type_lower.startswith('floa'):
+        suggestions.append('double')
+    elif base_type_lower.startswith('bool'):
+        suggestions.append('bool')
+    elif base_type_lower.startswith('opt'):
+        suggestions.append('String? (use Type? for nullable)')
+    elif base_type_lower.startswith('uni'):
+        suggestions.append('UniqueId')
+    
+    suggestion_msg = f" Did you mean '{suggestions[0]}'?" if suggestions else ""
+    return False, f"Unknown type '{field_type}'. Valid types: String, int, double, bool, DateTime, UniqueId, dynamic, Object, List<T>, Set<T>, Map<K,V> (e.g. Map<String, dynamic>), enum names, or domain model names (PascalCase). Nullable: String?, Model?, List<T>?, Map<K,V>?, etc.{suggestion_msg}", None
+
+
+def validate_entity_name(name: str) -> Tuple[bool, Optional[str]]:
+    """
+    Validate an entity/model name.
+    
+    Args:
+        name: The entity name to validate
+        
+    Returns:
+        Tuple of (is_valid, error_message)
+    """
+    if not name:
+        return False, "Entity name cannot be empty"
+    
+    # Check for reserved keywords
+    if name.lower() in DART_RESERVED_KEYWORDS:
+        return False, f"'{name}' is a Dart reserved keyword. Please use a different name."
+    
+    # Allow PascalCase, camelCase, snake_case, or kebab-case
+    # PascalCase names are preserved as-is (e.g., "NoteItem" stays "NoteItem")
+    # snake_case/kebab-case are converted (e.g., "note_item" becomes "note_item" for folder, but entity class uses PascalCase)
+    if not re.match(r'^[a-zA-Z][a-zA-Z0-9_\-]*$', name):
+        return False, f"Invalid entity name '{name}'. Entity names must start with a letter and contain only letters, numbers, underscores, and hyphens."
+    
+    return True, None
+
+
+def parse_fields_string(fields_str: str) -> List[Tuple[str, str]]:
+    """
+    Parse a fields string into a list of (name, type) tuples.
+    Handles commas inside angle brackets (e.g., Map<String, int>).
+    
+    Args:
+        fields_str: Fields string in format "name:type,name:type"
+        
+    Returns:
+        List of (field_name, field_type) tuples
+    """
+    # Split on commas that are NOT inside angle brackets
+    tokens = []
+    current = []
+    depth = 0
+    for ch in fields_str:
+        if ch == '<':
+            depth += 1
+            current.append(ch)
+        elif ch == '>':
+            depth -= 1
+            current.append(ch)
+        elif ch == ',' and depth == 0:
+            tokens.append(''.join(current))
+            current = []
+        else:
+            current.append(ch)
+    if current:
+        tokens.append(''.join(current))
+    
+    fields = []
+    for field_str in tokens:
+        field_str = field_str.strip()
+        if not field_str:
+            continue
+        
+        if ':' not in field_str:
+            raise ValueError(f"Invalid field format: '{field_str}'. Expected format: name:type")
+        
+        parts = field_str.split(':', 1)
+        field_name = parts[0].strip()
+        field_type = parts[1].strip()
+        
+        if not field_name:
+            raise ValueError(f"Field name cannot be empty in: '{field_str}'")
+        if not field_type:
+            raise ValueError(f"Field type cannot be empty in: '{field_str}'")
+        
+        fields.append((field_name, field_type))
+    
+    return fields
+

generators/initializator.py

@@ -0,0 +1,68 @@
+import click
+from pathlib import Path
+
+def initialize_project(lib_path, project_path, has_login):
+    remove_default_files(lib_path, project_path)
+    click.echo("\n📁 Creating folder structure...")
+    create_folder_structure(lib_path, has_login)
+
+def remove_default_files(lib_path, project_path):
+     # Remove default main.dart and test files
+    default_main = lib_path / "main.dart"
+    if default_main.exists():
+        default_main.unlink()
+
+    # Remove default test folder if empty or contains only widget_test.dart
+    test_path = project_path / "test"
+    if test_path.exists():
+        widget_test = test_path / "widget_test.dart"
+        if widget_test.exists():
+            widget_test.unlink()
+        # Try to remove the test directory if it's empty
+        try:
+            test_path.rmdir()
+        except OSError:
+            pass  # Not empty, leave it be
+
+def create_folder_structure(lib_path, login):
+     # Create folder structure
+    folders = [
+        "apis/clients",
+        "apis/common", 
+        "apis/core",
+        "apis/interceptors",
+        "core",
+        "core/infrastructure",
+        "core/presentation",
+        "core/model",
+        "domain",  # Domain entities folder
+        "features",
+        "features/home",
+        "features/splash",
+        "logging",
+        "storage",
+        "widgets/common",
+    ]
+
+    # Add auth folders if login is enabled
+    # Domain entities (shared): model + infrastructure only
+    # Feature (use case): application + presentation
+    if login:
+        folders.extend([
+            # Domain entities (shared)
+            "domain/auth",
+            "domain/auth/infrastructure",
+            "domain/auth/model",
+            # Feature (use case with UI)
+            "features/auth",
+            "features/auth/application",
+            "features/auth/presentation",
+            "features/auth/sign_in_form",
+            "features/auth/sign_in_form/application",
+            "features/auth/sign_in_form/presentation",
+        ])
+
+    # Create all folders
+    for folder in folders:
+        folder_path = lib_path / folder
+        folder_path.mkdir(parents=True, exist_ok=True)

generators/main.py

@@ -0,0 +1,81 @@
+import click
+import subprocess
+import sys
+import shutil
+
+from pathlib import Path
+
+from .assets import copy_assets
+from .config import generate_config_files
+from .templates import generate_files
+from .initializator import initialize_project
+from generators.helpers.config import load_config
+
+def run_cmd(cmd, capture_output=False):
+    """Executes a shell command and displays output"""
+    try:
+        result = subprocess.run(cmd, shell=True, check=True, capture_output=capture_output)
+        return result.returncode
+    except subprocess.CalledProcessError as e:
+        click.echo(f"❌ Errore nell'esecuzione del comando {cmd}: {e}")
+        click.echo(f"Output: {e.stdout}")
+        click.echo(f"Error: {e.stderr}")
+        sys.exit(1)
+    except FileNotFoundError:
+        click.echo("❌ Comando non trovato. Assicurati che sia installato e nel PATH.")
+        sys.exit(1)
+
+def init(flutter_name, login, cursor_setup=True):
+    # Controlla se esiste già una cartella con lo stesso nome del progetto
+    project_dir = Path(flutter_name)
+    if project_dir.exists():
+        click.echo(f"⚠️ Folder named '{flutter_name}' already exists in this directory.")
+        if click.confirm("Do you want to overwrite the existing folder?", default=False):
+            # Rimuovi la cartella esistente
+            shutil.rmtree(project_dir)
+            click.echo("✅ Previous folder removed.")
+        else:
+            click.echo("❌ Operation canceled.")
+            sys.exit(1)
+    
+    
+    click.echo(f"\n🚀 Creating Flutter project: {flutter_name}")
+
+    # Create the base Flutter project
+    run_cmd(f"flutter create {flutter_name} --org com.example --project-name {flutter_name} --template app", capture_output=False)
+    
+    # Project path
+    project_path = Path(flutter_name)
+    lib_path = project_path / "lib"
+    
+    # Initialize the project (remove default files, create folders, etc.)
+    initialize_project(lib_path, project_path, login)
+
+    # Load configuration (will use defaults + global config if exists)
+    cfg = load_config(project_path)
+
+    # Generate files in various folders
+    generate_files(lib_path, login, flutter_name, cfg.primary_color, cfg.secondary_color)
+    
+    # Generate configuration files (pubspec.yaml, analysis_options.yaml)
+    generate_config_files(lib_path, login, flutter_name)
+
+    # Copy assets to the lib/assets folder
+    copy_assets(flutter_name)
+
+    if cursor_setup:
+        from generators.cursor import copy_cursor_ecosystem
+        copy_cursor_ecosystem(project_path, login, flutter_name)
+        click.echo("\n📎 Cursor ecosystem (rules, agents, skills) added.")
+
+    click.echo("\n✅ Project created successfully!")
+    click.echo(f"\n📋 Summary:")
+    click.echo(f"   Name: {flutter_name}")
+    click.echo(f"   Path: {project_path.absolute()}")
+    if login:
+        click.echo(f"   Login: ✅ Email/Password")
+    else:
+        click.echo(f"   Login: ❌ None")
+
+    click.echo(f"\n🚀 Dependencies and code generation will be handled automatically!")
+    click.echo(f"   flutter run")

generators/static/assets/mock/auth_user.json

@@ -0,0 +1,5 @@
+{
+  "id": "mock-user-1",
+  "name": "Demo User",
+  "emailAddress": "demo@example.com"
+}

generators/static/assets/svgs/apple.svg

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?><!-- Uploaded to: SVG Repo, www.svgrepo.com, Generator: SVG Repo Mixer Tools -->
+<svg fill="#000000" width="800px" height="800px" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+<path d="M18.71 19.5C17.88 20.74 17 21.95 15.66 21.97C14.32 22 13.89 21.18 12.37 21.18C10.84 21.18 10.37 21.95 9.09997 22C7.78997 22.05 6.79997 20.68 5.95997 19.47C4.24997 17 2.93997 12.45 4.69997 9.39C5.56997 7.87 7.12997 6.91 8.81997 6.88C10.1 6.86 11.32 7.75 12.11 7.75C12.89 7.75 14.37 6.68 15.92 6.84C16.57 6.87 18.39 7.1 19.56 8.82C19.47 8.88 17.39 10.1 17.41 12.63C17.44 15.65 20.06 16.66 20.09 16.67C20.06 16.74 19.67 18.11 18.71 19.5ZM13 3.5C13.73 2.67 14.94 2.04 15.94 2C16.07 3.17 15.6 4.35 14.9 5.19C14.21 6.04 13.07 6.7 11.95 6.61C11.8 5.46 12.36 4.26 13 3.5Z"/>
+</svg>

generators/static/assets/svgs/google.svg

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="utf-8"?><!-- Uploaded to: SVG Repo, www.svgrepo.com, Generator: SVG Repo Mixer Tools -->
+<svg width="800px" height="800px" viewBox="-3 0 262 262" xmlns="http://www.w3.org/2000/svg" preserveAspectRatio="xMidYMid"><path d="M255.878 133.451c0-10.734-.871-18.567-2.756-26.69H130.55v48.448h71.947c-1.45 12.04-9.283 30.172-26.69 42.356l-.244 1.622 38.755 30.023 2.685.268c24.659-22.774 38.875-56.282 38.875-96.027" fill="#4285F4"/><path d="M130.55 261.1c35.248 0 64.839-11.605 86.453-31.622l-41.196-31.913c-11.024 7.688-25.82 13.055-45.257 13.055-34.523 0-63.824-22.773-74.269-54.25l-1.531.13-40.298 31.187-.527 1.465C35.393 231.798 79.49 261.1 130.55 261.1" fill="#34A853"/><path d="M56.281 156.37c-2.756-8.123-4.351-16.827-4.351-25.82 0-8.994 1.595-17.697 4.206-25.82l-.073-1.73L15.26 71.312l-1.335.635C5.077 89.644 0 109.517 0 130.55s5.077 40.905 13.925 58.602l42.356-32.782" fill="#FBBC05"/><path d="M130.55 50.479c24.514 0 41.05 10.589 50.479 19.438l36.844-35.974C195.245 12.91 165.798 0 130.55 0 79.49 0 35.393 29.301 13.925 71.947l42.211 32.783c10.59-31.477 39.891-54.251 74.414-54.251" fill="#EB4335"/></svg>

generators/static/cursor/AGENTS.md.jinja

@@ -0,0 +1,37 @@
+# [[project_name]]
+
+Flutter project generated with **CoreGen** (DDD / clean architecture).
+
+## Stack
+
+- `flutter_bloc`, `freezed`, `injectable`, `get_it`, `go_router`, `dio`, `retrofit`, `dartz`, `caravaggio_ui` **1.0.6**
+
+## Where code goes
+
+| Need | Location |
+|------|----------|
+| Shared domain entity | `lib/domain/<entity>/model/` + `infrastructure/` |
+| Enum | `lib/domain/enums/` |
+| Feature with BLoC | `lib/features/<feature>/application/` + `presentation/` |
+| Reusable UI component | `lib/features/components/<name>/` |
+| App-wide widgets | `lib/widgets/common/` |
+
+## How to build features
+
+Use skill **`/epic-delivery`** with a high-level description. Epics are tracked in `docs/epics/`.
+
+For presentation UI use skill **`/caravaggio-ui`** and read `docs/architecture/CARAVAGGIO_COMPONENTS.md`.
+
+Agents write Dart **directly** — do not run `coregen` CLI.
+
+## Documentation
+
+- Architecture: `docs/architecture/`
+- Mock vs remote data: `docs/architecture/MOCK_AND_REMOTE_DATA.md`
+- CaravaggioUI catalog: `docs/architecture/CARAVAGGIO_COMPONENTS.md`
+- Widget policy: `docs/architecture/WIDGETS_AND_CARAVAGGIO.md`
+- Layer-specific: `lib/domain/AGENTS.md`, `lib/features/AGENTS.md`, `lib/widgets/AGENTS.md`
+
+## Quality
+
+Run `flutter analyze` before completing work. Run `build_runner` after Freezed/Injectable changes.

generators/static/cursor/agents/doc-writer.md

@@ -0,0 +1,20 @@
+---
+name: doc-writer
+description: Writes inline Dart documentation, feature AGENTS.md files, and updates docs/epics/ after implementation. Run in background after integration-wiring.
+model: fast
+readonly: false
+is_background: true
+---
+
+Document completed epic work.
+
+## Responsibilities
+
+1. Add `///` dartdoc on public APIs created in the epic (entities, repositories, BLoCs, widgets).
+2. Create or update `lib/features/<feature>/AGENTS.md` with scope, files, and conventions for that feature.
+3. Update the epic file under `docs/epics/` with completion status and file list.
+
+## Style
+
+- Concise, factual, no duplication of `docs/architecture/` content.
+- Link to architecture docs where helpful.

generators/static/cursor/agents/epic-orchestrator.md

@@ -0,0 +1,28 @@
+---
+name: epic-orchestrator
+description: Unique entry point to implement an epic from docs/epics/EPIC-*.md. Reads epic file, creates folders, chooses small (feature-implementer) or large (layer pipeline) mode, coordinates subagents. Does not write layer or wiring code directly.
+model: inherit
+readonly: false
+is_background: false
+---
+
+You orchestrate a single epic implementation for a CoreGen DDD Flutter project.
+
+## Input
+
+- Path to epic file under `docs/epics/EPIC-NNN-<slug>.md`
+- Complexity tag: `small` or `large`
+
+## Responsibilities
+
+1. Read the epic file, `AGENTS.md`, and `docs/architecture/`.
+2. Create required folder structure under `lib/`.
+3. **small**: delegate to `feature-implementer`, then `integration-wiring`, then `doc-writer`, then `layer-guardian`.
+4. **large**: delegate sequentially to `layer-model` → `layer-infrastructure` → `layer-application` → `layer-presentation`, then `integration-wiring`, then `doc-writer`, then `layer-guardian`.
+5. Update epic file status when done.
+6. Ensure `flutter analyze` passes before closing.
+
+## Do not
+
+- Invoke `coregen` CLI commands.
+- Implement domain, feature, or wiring files yourself — delegate to specialized subagents.

generators/static/cursor/agents/feature-implementer.md

@@ -0,0 +1,29 @@
+---
+name: feature-implementer
+description: Fast path for small epics only — 1 domain entity and 1 UI use case. Implements domain model, infrastructure, application BLoC, and presentation in one pass. For multi-entity epics use the layer pipeline instead.
+model: inherit
+readonly: false
+is_background: false
+---
+
+Implement a **small** epic end-to-end in a single context.
+
+## Scope
+
+- `lib/domain/<entity>/model/` and `infrastructure/`
+- `lib/domain/enums/` if needed
+- `lib/features/<feature>/application/` and `presentation/`
+
+## Follow
+
+- `docs/architecture/FILE_TEMPLATES.md`
+- `docs/architecture/REFERENCE_IMPLEMENTATIONS.md`
+- `docs/architecture/WIDGETS_AND_CARAVAGGIO.md` for widget policy
+- `docs/architecture/CARAVAGGIO_COMPONENTS.md` for UI components
+
+## Do not
+
+- Modify `router.dart`, `injection.dart`, or `error_localizer.dart` — leave to `integration-wiring`.
+- Use `coregen` CLI.
+- Add widgets to `domain/`.
+- Use Material `Scaffold` on pages — use `CustomScaffold`.