# Kell Creations Operations Platform — Master Development Brief ## Recommended repo location Place this document in the repository at: `docs/development/master_development_brief.md` Why this location: - keeps it versioned with the code - makes it easy for Cline to read and update - separates implementation planning from feature code - works for both web and Android roadmap tracking If `docs/development/` does not exist yet, create it. --- ## Purpose This document is the master implementation brief for continuing development of the Kell Creations Flutter operations platform across **web** and **Android**. It is intended for use by Cline in Windows 11 VS Code. This brief should be treated as the working source of truth for planned development after the current completed slices already landed on `main`. --- ## Working model Development must proceed in **small, reviewable vertical slices**. Rules: - Branch from current `main` for each stage or sub-slice. - Implement on a feature branch. - Validate locally. - Open a PR into `main`. - Merge only after tests/analyze are clean. - Do not stack broad unfinished work directly on `main`. - After each merged slice, update this brief so it remains aligned to `main`. --- ## Current confirmed baseline on `main` ### Platform structure - `apps/kell_web` exists — active, wired to shared packages. - `apps/kell_mobile` exists — scaffolded as default Flutter template, **not yet integrated** with shared packages. - Shared packages include: - `core` — shared domain/application abstractions - `design_system` — theme (colors, spacing, theme) and shared widgets (KcCard, KcStatusChip) - `feature_inventory` — domain, application, data (fake), and presentation layers - `feature_wordpress` — domain, application, data (fake + WooCommerce), and presentation layers (most mature feature) - `feature_orders` — domain, application, data (fake), and presentation layers - `feature_policy` — domain, application, data (fake), and presentation layers - Scaffolded but **empty stub** packages (created, no implementation yet): - `auth` — authentication/authorization (stub only) - `data` — shared data layer (stub only) - `integrations` — shared integration abstractions (stub only) - `feature_finance` — financial analysis feature (stub only) - `feature_mrp` — craft manufacturing/MRP feature (stub only) - `feature_social` — social media management feature (stub only) - `tools/` directory exists but is empty. - App shell, routing, dashboard, reusable shell widgets, `AppServices`, and `AppScope` are implemented. - Dashboard uses app-composed repository data. - Vertical slices exist for Inventory, Products/Publishing, Orders, and Policy/Governance. - Cross-feature navigation handoffs and shared filtering/search/selection persistence are implemented. - Runtime bootstrap uses: - `KC_ENV` - `KC_WC_SITE_URL` - `KC_WC_CONSUMER_KEY` - `KC_WC_CONSUMER_SECRET` - App supports `FAKE` and `WP` modes with visible shell badge. ### Product publishing workflow already landed on `main` - Controlled WooCommerce publish action landed. - `ProductDraft.copyWith` landed. - `unpublished -> draft` UI exposure landed. - `pendingReview -> draft` UI exposure landed. - `unpublished` semantics clarified as a read-only abstraction. - Status action success/failure feedback landed. - Publishing page polish landed. - Richer read-side detail preview landed. - Price-only product edit landed. - Search/filter/sort refinement landed. - Name-only product edit landed. - ✅ Description-only product edit landed (Stage 1A complete — merged `feat/description-only-edit` → `main` at `cebac4c`, 2026-04-11). - ✅ Category-only product edit landed (Stage 1B complete — merged `feat/category-only-edit` → `main` at `8e7e4cb`, 2026-04-11). Stage 1 complete. - ✅ Post-write consistency hardening landed (Stage 2A complete — merged `feat/post-write-consistency` → `main` at `7acff83`, 2026-04-11). - ✅ Publishing workflow UX hardening landed (Stage 2B complete — merged `feat/publishing-ux-hardening` → `main` at `b81016d`, 2026-04-11). Stage 2 complete. - ✅ Multi-select groundwork landed (Stage 3A complete — merged `feat/multi-select-groundwork` → `main`, 2026-05-22). - ✅ List efficiency improvements landed (Stage 3B complete — merged `feat/list-efficiency-improvements` → `main`, 2026-05-22). Stage 3 complete. ### Current narrow edit capabilities on `main` - update product status through controlled workflow - update product price only - update product name only - update product description only - update product category only ### Latest known validation state on `main` - `dart analyze` clean - `feature_wordpress` tests passing - `kell_web` dashboard tests passing - latest reported count for `feature_wordpress`: `294/294 passed` - latest reported count for `kell_web` dashboard tests: `5/5 passed` - baseline commit: merge of `feat/list-efficiency-improvements` (2026-05-22) ### Next recommended branch **`feat/design-system-shared-widgets`** — Stage 4A: Design system expansion and shared widget migration. Branch from latest `main`. Stage 3 (web application operator efficiency) is complete. --- ## Non-negotiable architectural constraints These must be preserved in all future work: - Preserve **strict package boundaries**. - Fake repositories remain in feature packages. - Real integrations are incremental alongside fake ones. - Runtime selection stays via `--dart-define`, not a settings UI. - No credentials hardcoded or committed. - Do **not** broaden into generic product editing prematurely. - Keep WooCommerce details inside the WP repository layer. - Keep diffs small and reviewable. - Prefer inspection-first development. - Android support should reuse shared feature/domain/application layers rather than fork logic. --- ## Development stages ### Stage 1 — Web application completion: controlled product editing #### Objective Extend the publishing workflow with additional **single-field** edit capabilities using the same narrow pattern already established by price-only and name-only update. #### Branching model Use one branch per edit slice: - `feat/description-only-edit` - `feat/category-only-edit` #### ~~Stage 1A — Description-only product edit~~ ✅ COMPLETE > Merged `feat/description-only-edit` → `main` at `cebac4c` (2026-04-11). > All artifacts delivered: repository contract, fake/WP repo implementations, use case, controller action/result handling, preview panel inline description edit UI, and targeted tests (212 total `feature_wordpress` tests passing). #### ~~Stage 1B — Category-only product edit~~ ✅ COMPLETE > Merged `feat/category-only-edit` → `main` at `8e7e4cb` (2026-04-11). > All artifacts delivered: repository contract, fake/WP repo implementations, use case, controller action/result handling, preview panel inline category edit UI, snack bar feedback, and targeted tests (223 total `feature_wordpress` tests passing). Stage 1 complete. --- ### Stage 2 — Web application operational hardening #### Objective Improve operator consistency, predictability, and usability after writes. #### Branches - `feat/post-write-consistency` - `feat/publishing-ux-hardening` #### ~~Stage 2A — Post-write consistency hardening~~ ✅ COMPLETE > Merged `feat/post-write-consistency` → `main` at `7acff83` (2026-04-11). > Added `_refreshSelection()` to `ProductPublishingController` to preserve/refresh selection after all write-triggered reloads. 11 new post-write consistency tests added (234 total `feature_wordpress` tests passing). #### ~~Stage 2B — Publishing workflow UX hardening~~ ✅ COMPLETE > Merged `feat/publishing-ux-hardening` → `main` at `b81016d` (2026-04-11). > Added inline validation error messages for all four single-field edits (name, price, description, category), disabled text fields and save buttons during `isUpdating`, and appended error detail to failure snack bars. 13 new tests added (247 total `feature_wordpress` tests passing). Stage 2 complete. --- ### Stage 3 — Web application operator efficiency #### Objective Increase throughput for product triage and management using existing data. #### Branches - `feat/multi-select-groundwork` - `feat/list-efficiency-improvements` #### ~~Stage 3A — Multi-select groundwork (read/state only first)~~ ✅ COMPLETE > Merged `feat/multi-select-groundwork` → `main` (2026-05-22). > Added multi-selection state to `ProductPublishingController` (`toggleMultiSelect`, `clearMultiSelection`, `selectAllVisible`, `isMultiSelected`, `multiSelectedIds`, `multiSelectedCount`). Updated `ProductDraftCard` with optional leading checkbox for multi-select mode. Added `_MultiSelectBar` to `ProductPublishingPage` with selected-count display, Select All, and Clear actions. Single-item preview selection preserved independently. 15 new multi-select tests added (262 total `feature_wordpress` tests passing). No bulk writes introduced. #### ~~Stage 3B — List efficiency improvements~~ ✅ COMPLETE > Merged `feat/list-efficiency-improvements` → `main` (2026-05-22). > Added compact/standard view toggle (`ListDensity` enum), staleness detection (`isStale()`, `staleCount()` with 30-day threshold), keyboard navigation (`selectNextDraft`/`selectPreviousDraft` with wrapping), description snippet in standard card, and stale indicator icon. Updated `ProductDraftCard` with compact two-row layout variant and `Flexible` overflow handling. Page wires up `Focus`+`onKeyEvent` for arrow keys and density toggle button. 32 new tests added (294 total `feature_wordpress` tests passing). Stage 3 complete. --- ### Stage 4 — Platform foundations and cross-platform readiness #### Objective Strengthen the shared platform infrastructure before expanding to Android. This stage implements the key recommendations from the codebase analysis to reduce technical debt, prevent duplication, and establish quality gates. #### Key principle Invest in shared foundations now so that the Android expansion (Stage 5) and all future feature work benefits from a mature design system, shared composition patterns, automated CI/CD, and proper test coverage tracking. #### Branches - `feat/design-system-shared-widgets` - `feat/flutter-cicd` - `feat/shared-composition-pattern` #### Stage 4A — Design system expansion and shared widget migration ##### Goal Expand the `design_system` package with reusable widgets and responsive layout primitives so both `kell_web` and `kell_mobile` share a common component library. ##### Requirements - migrate `EmptyStatePanel`, `SectionHeader`, and `SummaryCard` from `kell_web/lib/shell/widgets/` into `design_system` - add shared typography scale to `design_system` - add responsive layout breakpoint utilities for web vs mobile - add shared loading state and error state widget patterns - update `kell_web` imports to reference `design_system` instead of local shell widgets - preserve existing visual behavior — no regressions ##### Definition of done - shared widgets live in `design_system` package - `kell_web` references `design_system` for all migrated widgets - responsive layout utilities exist for future mobile use - analyze clean, existing tests passing #### Stage 4B — Cross-platform shell composition strategy ##### Goal Extract or document a shared app composition pattern so `kell_mobile` can mirror the `kell_web` architecture without forking logic. ##### Requirements - evaluate whether `AppServices`, `AppScope`, `AppConfig`, and `Bootstrap` should move to a shared package (e.g., `core` or new `app_shell`) or remain duplicated with a documented contract - if extracting: create shared composition abstractions in the chosen package - if duplicating: document the contract explicitly so `kell_mobile` follows the same pattern - do not change runtime behavior of `kell_web` ##### Definition of done - composition strategy is decided and documented - shared abstractions extracted or duplication contract documented - `kell_web` still works identically - analyze clean, existing tests passing #### Stage 4C — Flutter CI/CD pipeline ##### Goal Establish automated validation for Flutter applications in Forgejo Actions. ##### Requirements - add Forgejo Actions workflow for `dart analyze` on PRs - add Forgejo Actions workflow for `flutter test` execution on PRs (per package) - add basic test result reporting (pass/fail count per package) - ensure workflows work for both web and Android targets - populate `tools/` directory with any CI helper scripts if needed ##### Definition of done - PRs trigger automated analyze and test runs - test counts are reported in workflow output - workflow files committed under `.forgejo/workflows/` - `tools/` directory populated or removed if not needed #### Stage 4D — Test coverage visibility ##### Goal Introduce lightweight test coverage tracking across packages. ##### Requirements - add coverage measurement to CI pipeline (at minimum: total tests and pass rate per package) - document current baseline coverage in this brief or a companion document - do not enforce minimum thresholds yet — visibility first ##### Definition of done - coverage data is generated and visible in CI output - baseline coverage documented - no regressions in existing tests --- ### Stage 5 — Android application foundation #### Objective Bring the current operations platform capabilities to Android using shared packages first and platform-specific UI only where required. #### Key principle Business logic, domain logic, repositories, and feature application logic should remain shared. Android should primarily add a dedicated app shell and mobile-optimized presentation. #### Branches - `feat/android-app-shell` - `feat/android-publishing-surface` #### Stage 5A — Android app shell and bootstrap ##### Goal Create the Android app entry and shell for the existing platform. ##### Requirements - add or adapt app target for Android - reuse shared packages and feature modules - preserve runtime environment selection model - ensure FAKE mode works cleanly on Android first - mobile shell/navigation should stay simple and consistent with shared app structure ##### Current state note > `kell_mobile` exists as a default Flutter counter template. It does **not** yet reference any shared packages (`core`, `design_system`, `feature_*`). This stage must replace the template with a proper app shell that mirrors the `kell_web` composition pattern (`AppServices`, `AppScope`, routing, shell). ##### Definition of done - app runs on Android emulator/device in FAKE mode - shell, navigation, and core screens render - analyze/tests remain clean - `kell_mobile/pubspec.yaml` references shared packages #### Stage 5B — Android publishing surface ##### Goal Adapt the publishing workflow for mobile form factor. ##### Requirements - reuse shared controller/use case/repository layers - optimize preview/edit interactions for smaller screens - keep feature parity for current publishing workflow where feasible - do not fork business rules for Android ##### Definition of done - Android supports browsing, filtering, status changes, and existing narrow edits - mobile presentation is usable and tested where practical --- ### Stage 6 — Android operational maturity #### Objective Harden Android UX after the core feature surface works. #### Branches - `feat/android-feedback-polish` - `feat/android-mobile-ux-hardening` #### Stage 6A — Android feedback and action polish ##### Goal Ensure action feedback patterns translate cleanly to Android. ##### Requirements - reuse shared action result model where possible - adapt SnackBar/feedback timing and presentation appropriately - validate status/edit workflows on mobile #### Stage 6B — Android mobile workflow hardening ##### Goal Improve ergonomics on smaller screens. ##### Requirements - verify scrolling/selection/edit flows - ensure touch targets and inline edit behavior are mobile-friendly - refine layout without changing shared domain/application contracts --- ### Stage 7 — Controlled bulk actions (only after groundwork) #### Objective Add carefully scoped bulk operations once single-item workflows are stable across web and Android. #### Branches - `feat/bulk-status-actions` - `feat/bulk-operator-workflows` #### Entry criteria Do not begin until: - single-item edit/status flows are stable - multi-select groundwork is complete - post-write consistency is hardened - Android core publishing surface exists #### Candidate first bulk action - bulk move to draft #### Explicitly defer - bulk generic edit - bulk category management - destructive bulk deletion unless separately justified --- ## Suggested improvements (identified from codebase analysis) This section captures structural improvements, coverage gaps, and maturity enhancements identified through codebase analysis against the architecture documentation and current implementation state. Items here are candidates for future stages or can be woven into existing stages as appropriate. ### 1. Stub package activation roadmap The following packages exist as scaffolded stubs with no implementation. Each needs an activation plan aligned to architecture documentation: | Package | Architecture Reference | Priority | Notes | | ----------------- | --------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------- | | `auth` | Enterprise Identity & Access Architecture | High | No auth layer exists; all access is currently uncontrolled. Required before any multi-user or production deployment. | | `data` | Enterprise Data Architecture | Medium | Shared data abstractions/caching could reduce duplication across feature repositories. | | `integrations` | Enterprise Integration & Orchestration Architecture | Medium | Shared integration contracts could formalize API client patterns currently embedded in `feature_wordpress`. | | `feature_finance` | Financial Analysis Components | Low | Architecture docs exist but no implementation. Defer until core WordPress/Inventory workflows mature. | | `feature_mrp` | Craft Manufacturing / MRP Components | Low | Architecture docs exist but no implementation. Defer until inventory workflows mature. | | `feature_social` | Social Media Management Components | Low | Architecture docs exist but no implementation. Defer until core platform stabilizes. | **Recommendation:** Add a **Stage 8 — Infrastructure package activation** to the roadmap covering `auth`, `data`, and `integrations` before expanding into new feature domains. ### 2. Design system expansion The `design_system` package currently contains: - Theme: `KcColors`, `KcSpacing`, `KcTheme` - Widgets: `KcCard`, `KcStatusChip` **Gaps identified:** - No shared typography scale - No shared button/action component library - No responsive layout utilities for cross-platform (web + mobile) - No shared empty state, loading state, or error state patterns - Shell widgets (`EmptyStatePanel`, `SectionHeader`, `SummaryCard`) live in `kell_web` app rather than `design_system` **Recommendation:** Now addressed in **Stage 4A** (Design system expansion and shared widget migration). Migrate reusable shell widgets into `design_system` and add responsive layout primitives before the Android expansion in Stage 5. ### 3. Cross-platform shell composition strategy `kell_web` uses a well-structured composition pattern (`AppServices`, `AppScope`, `AppConfig`, `Bootstrap`). `kell_mobile` has none of this — it's a default counter app. **Recommendation:** Extract a shared shell composition pattern or at minimum define a documented convention so that `kell_mobile` mirrors the `kell_web` architecture. Consider whether `AppServices`, `AppScope`, and bootstrap logic should move to a shared `core` or `app_shell` package, or remain duplicated with a documented contract. ### 4. CI/CD for Flutter applications Currently, CI/CD exists only for MkDocs documentation publishing. There is no automated pipeline for: - Flutter `dart analyze` on PRs - Flutter test execution on PRs - Flutter build validation (web + Android) - Test result reporting or quality gates **Recommendation:** Now addressed in **Stage 4C** (Flutter CI/CD pipeline). Establish Flutter CI/CD in Forgejo Actions before the Android expansion in Stage 5 adds more surfaces to validate. ### 5. Test coverage visibility and quality gates Test counts are tracked manually in this brief (e.g., `294/294 passed`). There is no: - Automated test count reporting - Coverage measurement - Minimum coverage threshold enforcement - Test trend tracking across slices **Recommendation:** Introduce coverage tooling and reporting as part of CI/CD establishment. Even lightweight coverage tracking (total tests, pass rate per package) would improve confidence during the Android expansion. ### 6. Build execution tracker synchronization The `build_execution_tracker.md` is stale: - Shows `feat/multi-select-groundwork` as "queued" when it was merged 2026-05-22 - Does not include `feat/list-efficiency-improvements` at all - `current status` section references Stage 3 as current when Stage 3 is complete **Recommendation:** Update the tracker immediately and consider whether the tracker should be auto-generated or at minimum updated as part of the standard slice completion checklist. ### 7. Image and media management Architecture documentation (`traceability-index.md` coverage gaps) identifies "Product image / media synchronization workflow" as a gap. The current publishing workflow handles text fields only. **Recommendation:** Plan a future stage for image/media management once existing narrow edits are stable on both platforms. This aligns with the architecture gap analysis. ### 8. Error tracking and observability No monitoring, error tracking, or analytics strategy exists for the Flutter applications. In production use: - Runtime errors are invisible unless the operator sees them - No crash reporting - No usage analytics to guide prioritization **Recommendation:** Add lightweight error reporting and observability as a future stage, particularly important before any production WP-mode deployment beyond a single operator. ### 9. Empty tools directory The `tools/` directory under `kell_creations_apps` exists but contains nothing. **Recommendation:** Either populate with development tooling (code generation scripts, analysis helpers, CI scripts) or remove to avoid confusion. If CI/CD scripts are planned, this is a natural home. ### 10. Missing feature parity documentation The architecture documentation describes rich capabilities across all domains (Inventory, MRP, WordPress, Social Media, Financial Analysis), but actual implementation maturity varies dramatically. Only `feature_wordpress` has substantial implementation. **Recommendation:** Add a **feature maturity matrix** to this brief or a companion document that maps architecture aspirations to actual implementation status per feature package. This would make prioritization conversations clearer. --- ## Required development workflow for every slice For every branch/stage: 1. Start from latest `main`. 2. Inspect first. 3. Write a brief inspection report. 4. Propose the smallest implementation plan. 5. Implement only the current slice. 6. Run targeted tests. 7. Run `flutter analyze` or `dart analyze` as appropriate. 8. Summarize changed files and validation results. 9. Open PR into `main`. 10. Merge only after clean review and validation. 11. **Update this brief and the build execution tracker** after merge. --- ## Standard Cline operating prompt Use this at the start of any new slice: ```text 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. - Do not broaden into generic product editing prematurely. - Keep WooCommerce details inside the WP repository layer. - Use small, reviewable steps only. - Work is being driven through Cline in Windows 11 VS Code. 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. 7. Report changed files and validation results. 8. Update master_development_brief.md and build_execution_tracker.md after merge. ``` --- ## Appendix: Feature maturity matrix | Package | Domain Layer | Application Layer | Data (Fake) | Data (Real) | Presentation | Tests | Maturity | | ------------------- | ------------ | ----------------- | ----------- | -------------- | ------------------------------ | ------- | -------------------- | | `feature_wordpress` | ✅ Complete | ✅ Complete | ✅ Complete | ✅ WooCommerce | ✅ Complete | 294 | **Production-ready** | | `feature_inventory` | ✅ Complete | ✅ Complete | ✅ Complete | ❌ None | ✅ Complete | Minimal | **Fake-only MVP** | | `feature_orders` | ✅ Complete | ✅ Complete | ✅ Complete | ❌ None | ✅ Complete | Some | **Fake-only MVP** | | `feature_policy` | ✅ Complete | ✅ Complete | ✅ Complete | ❌ None | ✅ Complete | Minimal | **Fake-only MVP** | | `feature_finance` | ❌ Stub | ❌ Stub | ❌ Stub | ❌ None | ❌ Stub | None | **Scaffolded only** | | `feature_mrp` | ❌ Stub | ❌ Stub | ❌ Stub | ❌ None | ❌ Stub | None | **Scaffolded only** | | `feature_social` | ❌ Stub | ❌ Stub | ❌ Stub | ❌ None | ❌ Stub | None | **Scaffolded only** | | `auth` | ❌ Stub | ❌ Stub | ❌ Stub | ❌ None | N/A | None | **Scaffolded only** | | `data` | ❌ Stub | N/A | N/A | ❌ None | N/A | None | **Scaffolded only** | | `integrations` | ❌ Stub | N/A | N/A | ❌ None | N/A | None | **Scaffolded only** | | `design_system` | N/A | N/A | N/A | N/A | ✅ Partial (theme + 2 widgets) | Minimal | **Foundation only** | | `core` | ✅ Partial | N/A | N/A | N/A | N/A | Minimal | **Foundation only** |