# 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.
- Shared packages include:
  - `core`
  - `design_system`
  - `feature_inventory`
  - `feature_wordpress`
  - `feature_orders`
  - `feature_policy`
- 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.

### 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`: `223/223 passed`
- latest reported count for `kell_web` dashboard tests: `5/5 passed`
- baseline commit: `8e7e4cb` (2026-04-11)

### Post-write consistency (Stage 2A) — on branch `feat/post-write-consistency`

- `dart analyze` clean
- `feature_wordpress` tests: `234/234 passed`
- controller `_refreshSelection()` preserves/refreshes selection after all writes
- 11 new post-write consistency tests added

### Next recommended branch

**`feat/publishing-ux-hardening`** — Stage 2B: Publishing workflow UX hardening.
Branch from `main` after merging `feat/post-write-consistency`. Stage 2A is complete on branch.

---

## 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

##### Goal

Make list/detail behavior predictable after edits and status changes.

##### Requirements

- preserve selection after update where sensible
- maintain search/filter/sort persistence after writes
- handle item repositioning under active sort cleanly
- ensure latest values refresh correctly
- verify last-modified updates behave consistently

##### Definition of done

- post-action behavior feels stable and predictable
- focused tests cover persistence and repositioning

#### Stage 2B — Publishing workflow UX hardening

##### Goal

Tighten the publishing workflow without broadening scope.

##### Requirements

- refine success/failure wording if needed
- improve inline validation messaging for single-field edits
- ensure disabled/loading states are consistent
- ensure page-level load errors remain separate from row-level action errors

##### Definition of done

- status/edit actions feel reliable and operator-friendly
- no architecture broadening

---

### 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)

##### Goal

Prepare for future bulk actions without implementing bulk writes yet.

##### Requirements

- add selection model for multiple items
- show selected-count UI
- allow clear selection
- preserve current single-item preview behavior where appropriate
- do not add bulk publish/edit/delete actions yet

##### Definition of done

- multi-select state exists and is tested
- no bulk writes introduced

#### Stage 3B — List efficiency improvements

##### Goal

Further improve operator productivity.

##### Candidate scope

- denser list/card presentation if justified
- quick visual indicators for stale products
- lightweight secondary metadata visibility
- improved keyboard/focus handling on web if easy to support

##### Definition of done

- measurable usability improvement using existing data only

---

### Stage 4 — 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 4A — 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

##### Definition of done

- app runs on Android emulator/device in FAKE mode
- shell, navigation, and core screens render
- analyze/tests remain clean

#### Stage 4B — 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 5 — Android operational maturity

#### Objective

Harden Android UX after the core feature surface works.

#### Branches

- `feat/android-feedback-polish`
- `feat/android-mobile-ux-hardening`

#### Stage 5A — 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 5B — 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 6 — 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

---

## 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.

---

## 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.
```