Krow-workspace/apps/docs/02-agent-development-rules.md

Agent Development Rules

These rules are NON-NEGOTIABLE. They are designed to prevent architectural degradation by automated agents.

1. File Creation & Structure

1. Feature-First Packaging:
   • DO: Create new features as independent packages in packages/features/<feature_name>.
   • DO NOT: Add features to packages/core or existing apps directly.
2. Path Conventions:
   • Entities: packages/domain/lib/src/entities/<entity>.dart
   • Repositories (Interface): packages/<feature>/lib/src/domain/repositories/<name>_repository_interface.dart
   • Repositories (Impl): packages/<feature>/lib/src/data/repositories_impl/<name>_repository_impl.dart
   • Use Cases: packages/<feature>/lib/src/application/<name>_usecase.dart
   • BLoCs: packages/<feature>/lib/src/presentation/blocs/<name>_bloc.dart
   • Pages: packages/<feature>/lib/src/presentation/pages/<name>_page.dart
3. Barrel Files:
   • DO: Use export in lib/<package_name>.dart only for public APIs.
   • DO NOT: Export internal implementation details (like mocks or helper widgets) in the main package file.

2. Naming Conventions

Follow Dart standards strictly.

Type	Convention	Example
Files	snake_case	user_profile_page.dart
Classes	PascalCase	UserProfilePage
Variables	camelCase	userProfile
Interfaces	terminate with Interface	AuthRepositoryInterface
Implementations	terminate with Impl	FirebaseDataConnectAuthRepositoryImpl
Mocks	terminate with Mock	AuthRepositoryMock

3. Logic Placement (Strict Boundaries)

• Business Rules: MUST reside in Use Cases (Domain/Feature Application layer).
  • Forbidden: Placing business rules in BLoCs or Widgets.
• State Logic: MUST reside in BLoCs.
  • Forbidden: setState in Pages (except for purely ephemeral UI animations).
• Data Transformation: MUST reside in Repositories (Data Connect layer).
  • Forbidden: Parsing JSON in the UI or Domain.
• Navigation Logic: MUST reside in Modular Routes.
  • Forbidden: Navigator.push with hardcoded widgets.

4. Data Connect Mocking Strategy

Since the backend does not exist, you must mock strictly:

1. Define Interface: Create abstract interface class <name>RepositoryInterface in packages/<feature>/lib/src/domain/repositories/<name>_repository_interface.dart.
2. Create Mock: Create class MockRepository implements IRepository in packages/data_connect/lib/src/mocks/.
3. Fake Data: Return hardcoded Futures with realistic dummy entities.
4. Injection: Register the MockRepository in the AppModule (in apps/client or apps/staff) until the real implementation exists.

DO NOT use mockito or mocktail for these runtime mocks. Use simple fake classes.

5. Prototype Migration Rules

You have access to prototypes/ folders. When migrating code:

1. Extract Assets:
   • You MAY copy icons, images, and colors. But they should be tailored to the current design system. Do not change the colours and typgorahys in the design system. They are final. And you have to use these in the UI.
     • When you matching colous and typography, from the POC match it with the design system and use the colors and typography from the design system. As mentioned in the docs/03-design-system-usage.md.
2. Extract Layouts: You MAY copy build methods for UI structure.
3. REJECT Architecture: You MUST NOT copy the GetX, Provider, or MVC patterns often found in prototypes. Refactor immediately to Bloc + Clean Architecture with Flutter Modular and Melos.

6. Handling Ambiguity

If a user request is vague:

1. STOP: Do not guess domain fields or workflows.
2. ANALYZE:

• For architecture related questions, refer to docs/01-architecture-principles.md or existing code.
• For design system related questions, refer to docs/03-design-system-usage.md or existing code.

3. DOCUMENT: If you must make an assumption to proceed, add a comment // ASSUMPTION: <explanation> and mention it in your final summary.
4. ASK: Prefer asking the user for clarification on business rules (e.g., "Should a 'Job' have a 'status'?").

7. Dependencies

• DO NOT add 3rd party packages without checking packages/core first.
• DO NOT add firebase_auth or cloud_firestore to any Feature package. They belong in data_connect only.

8. Follow Clean Code Principles

• Add doc comments to all classes and methods you create.