kell_creations/.vscode/workspace_rules.md

Workspace Development Rules: Kell Creations Platform

1. Core Operating Principles

1. Vertical Slice Discipline: Implement features in isolated, reviewable vertical slices on feature branches. Never push unverified, broad changes directly to main[cite: 3].
2. Inspection First: Always inspect the codebase, verify existing tests, and review existing contracts before writing or modifying code[cite: 3].
3. Environment Isolation: Maintain runtime environment modes (fake, wp, square, multi) specified exclusively via --dart-define keys[cite: 2, 3]. Never build hardcoded settings UIs or commit API keys/tokens to source control[cite: 3].
4. Strict Package Boundaries:
   • Feature packages (feature_*) must remain decoupled[cite: 1, 3].
   • Cross-feature communication must use shared abstractions in core, integrations, or data[cite: 1, 3].
   • Platform-specific UI code must reside in apps/kell_web or apps/kell_mobile[cite: 1, 3]. Re-use shared presenters and controllers[cite: 2, 3].

---

2. Code & Design Standards

Flutter & Dart Execution

• Strict typing required; avoid dynamic unless explicitly serializing raw JSON[cite: 2, 3].
• Use Material Design 3 guidelines[cite: 2, 3]. On mobile (kell_mobile), ensure all interactive targets adhere to a minimum 48×48dp target bounding box[cite: 2, 3].
• Wrap mobile screens in SafeArea to avoid system overlay clipping[cite: 2, 3].

Architecture Layering (per Package)

lib/ ├── src/ │ ├── domain/ # Entities, Value Objects, Repository Contracts (Pure Dart) │ ├── application/ # Use Cases, Controllers (ChangeNotifiers) │ ├── data/ # ApiClients, Mappers, Fake & Real Repositories │ └── presentation/ # Widgets, Pages, Dialogs, SnackBars └── feature_name.dart # Barrel File Exports

---

3. Standard Execution Workflow for AI Agents (Cline / VS Code)

Whenever initiating a new task or slice, execute the following workflow steps sequentially[cite: 3]:

1. Step 1: Context Verification

   • Read docs/development/master_development_brief.md and docs/development/build_execution_tracker.md to identify current status[cite: 2, 3].

2. Step 2: Pre-flight Validation

   • Run local test suite using the CI script:

     bash tools/run_all_tests.sh --analyze
     
     

   • Confirm all tests pass and static analysis is clean prior to editing[cite: 2, 3].

3. Step 3: Implementation

   • Create target feature branch (e.g., feat/square-catalog-sync)[cite: 2].
   • Implement domain models, repository contracts, API mappers, application logic, and UI components[cite: 2, 3].

4. Step 4: Testing & Hardening

   • Write unit tests for domain models and application controllers[cite: 2].

   • Write widget tests for presentation components[cite: 2].

   • Verify static analysis passes without warnings:

     dart analyze --fatal-infos
     

5. Step 5: Documentation & Tracking

   • Update docs/development/build_execution_tracker.md with:
     • Files modified/added[cite: 2].
     • Test counts and pass state[cite: 2].
     • Verification/analysis result[cite: 2].
   • Update docs/development/master_development_brief.md next branch indicator[cite: 2, 3].

---

4. Prompt Template for AI Sessions

Continue the Kell Creations Flutter operations platform workstream from current main.

Read docs/development/master_development_brief.md first and follow it as the authoritative planning document.

Constraints:

• Preserve strict package boundaries.
• Fake repositories remain in feature packages.
• Real integrations are incremental alongside fake ones.
• Runtime selection stays via --dart-define, not settings UI.
• No credentials hardcoded or committed.
• Keep WooCommerce details inside the WP repository layer.
• Keep Square details inside a dedicated Square integration layer.
• Multi-channel sync contracts before implementations.
• Use small, reviewable steps only.

Working rules:

1. Inspect first. Do not edit immediately.
2. Summarize current relevant state from main.
3. Propose the smallest implementation plan for the requested slice.
4. Implement only that slice.
5. Add/update focused tests.
6. Run validation (run_all_tests.sh --analyze).
7. Report changed files and validation results.
8. Update master_development_brief.md and build_execution_tracker.md.