103 lines
4.3 KiB
Markdown
103 lines
4.3 KiB
Markdown
# 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
|
||
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:
|
||
|
||
```bash
|
||
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.
|