# 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.
- ✅ Design system expansion and shared widget migration landed (Stage 4A complete — merged `feat/design-system-shared-widgets` → `main`, 2026-05-22).
- ✅ Cross-platform shell composition strategy landed (Stage 4B complete — merged `feat/shared-composition-pattern` → `main`, 2026-05-22).

### 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
- `core` tests passing
- `design_system` tests passing
- `feature_wordpress` tests passing
- `kell_web` tests passing
- latest reported count for `core`: `20/20 passed`
- latest reported count for `design_system`: `41/41 passed`
- latest reported count for `feature_wordpress`: `294/294 passed`
- latest reported count for `kell_web`: `24/24 passed`
- baseline commit: merge of `feat/shared-composition-pattern` (2026-05-22)

### Next recommended branch

**`feat/flutter-cicd`** — Stage 4C: Flutter CI/CD pipeline.
Branch from latest `main`. Stage 4B (cross-platform shell composition) 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~~ ✅ COMPLETE

> Merged `feat/design-system-shared-widgets` → `main` (2026-05-22).
> Migrated `EmptyStatePanel`, `SectionHeader`, and `SummaryCard` from `kell_web/lib/shell/widgets/` into `design_system` as `KcEmptyState`, `KcSectionHeader`, and `KcSummaryCard`. Added `KcTypography` shared typography scale, `KcBreakpoints` responsive layout breakpoint utilities, `KcLoadingState` and `KcErrorState` shared state widgets. Updated `kell_web` dashboard to use design_system widgets directly; shell widget files now contain backward-compatible typedefs. Theme updated to use `KcTypography.applyKcTypography()`. 41 new design_system tests added (41 total `design_system` tests, 294 `feature_wordpress` tests, 24 `kell_web` tests — all passing). Analyze clean.

#### 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            | ✅ Expanded (theme, typography, layout, 7 widgets) | 41      | **Foundation ready** |
| `core`              | ✅ Partial   | N/A               | N/A         | N/A            | N/A                                                | 20      | **Foundation ready** |
