diff --git a/docs/development/master_development_brief.md b/docs/development/master_development_brief.md new file mode 100644 index 0000000..0184def --- /dev/null +++ b/docs/development/master_development_brief.md @@ -0,0 +1,453 @@ +# 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. + +### Current narrow edit capabilities on `main` + +- update product status through controlled workflow +- update product price only +- update product name only + +### Latest known validation state on `main` + +- `flutter analyze` clean +- `feature_wordpress` tests passing +- `kell_web` dashboard tests passing +- latest reported count for `feature_wordpress`: `195/195 passed` +- latest reported count for `kell_web` dashboard tests: `10/10 passed` + +--- + +## 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 + +##### Goal + +Allow updating product description only. + +##### Requirements + +- Inspect the existing price-only and name-only edit implementations first. +- Mirror the narrow pattern for description update. +- Add one repository method or equivalent narrow path only if needed. +- Fake and WP repositories evolve in parallel. +- Use existing controller result/feedback patterns. +- Keep WooCommerce payload logic in WP repo only. +- Do not expose any other editable fields. +- Keep description editing plain and controlled. +- Do not add a rich text editor. + +##### Expected artifacts + +- repository contract update +- fake repo implementation +- WP repo implementation +- use case +- controller action/result handling +- preview panel inline description edit UI +- targeted repo/controller/widget tests + +##### Definition of done + +- product description updates end-to-end in FAKE and WP modes +- no generic update API introduced +- tests/analyze clean + +#### Stage 1B — Category-only product edit + +##### Goal + +Allow updating product category only. + +##### Requirements + +- Use existing category representation only. +- Do not create full taxonomy management. +- Keep write mapping narrow inside WP repository. +- Use a simple constrained UI. +- Reuse the established narrow single-field edit pattern. + +##### Definition of done + +- category can be updated through a controlled workflow +- no taxonomy subsystem added +- tests/analyze clean + +--- + +### 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. +```