From bee610ca2c4bfa8fdc7b6858b67d684fcd7c298d Mon Sep 17 00:00:00 2001 From: Mike Kell Date: Fri, 22 May 2026 09:26:39 -0400 Subject: [PATCH] =?UTF-8?q?docs:=20add=20Stage=204=20=E2=80=94=20Platform?= =?UTF-8?q?=20foundations=20and=20cross-platform=20readiness?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/development/build_execution_tracker.md | 6 +- docs/development/master_development_brief.md | 121 +++++++++++++++++-- 2 files changed, 113 insertions(+), 14 deletions(-) diff --git a/docs/development/build_execution_tracker.md b/docs/development/build_execution_tracker.md index d287a85..c3e40d4 100644 --- a/docs/development/build_execution_tracker.md +++ b/docs/development/build_execution_tracker.md @@ -4,8 +4,8 @@ - main baseline updated through: list-efficiency-improvements (Stage 3 complete) - main baseline commit: merge of `feat/list-efficiency-improvements` (2026-05-22) -- next branch: feat/android-app-shell -- current stage: Stage 4 — Android application foundation +- next branch: feat/design-system-shared-widgets +- current stage: Stage 4 — Platform foundations and cross-platform readiness ## Slice tracker @@ -87,7 +87,7 @@ - analyze: passed - brief updated: yes -### feat/android-app-shell +### feat/design-system-shared-widgets - status: queued (Stage 4A — next) - inspection: pending diff --git a/docs/development/master_development_brief.md b/docs/development/master_development_brief.md index f3d8f83..1f37a09 100644 --- a/docs/development/master_development_brief.md +++ b/docs/development/master_development_brief.md @@ -112,7 +112,7 @@ Rules: ### Next recommended branch -**`feat/android-app-shell`** — Stage 4A: Android app shell and bootstrap. +**`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. --- @@ -207,7 +207,106 @@ Increase throughput for product triage and management using existing data. --- -### Stage 4 — Android application foundation +### 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 @@ -222,7 +321,7 @@ Business logic, domain logic, repositories, and feature application logic should - `feat/android-app-shell` - `feat/android-publishing-surface` -#### Stage 4A — Android app shell and bootstrap +#### Stage 5A — Android app shell and bootstrap ##### Goal @@ -247,7 +346,7 @@ Create the Android app entry and shell for the existing platform. - analyze/tests remain clean - `kell_mobile/pubspec.yaml` references shared packages -#### Stage 4B — Android publishing surface +#### Stage 5B — Android publishing surface ##### Goal @@ -267,7 +366,7 @@ Adapt the publishing workflow for mobile form factor. --- -### Stage 5 — Android operational maturity +### Stage 6 — Android operational maturity #### Objective @@ -278,7 +377,7 @@ Harden Android UX after the core feature surface works. - `feat/android-feedback-polish` - `feat/android-mobile-ux-hardening` -#### Stage 5A — Android feedback and action polish +#### Stage 6A — Android feedback and action polish ##### Goal @@ -290,7 +389,7 @@ Ensure action feedback patterns translate cleanly to Android. - adapt SnackBar/feedback timing and presentation appropriately - validate status/edit workflows on mobile -#### Stage 5B — Android mobile workflow hardening +#### Stage 6B — Android mobile workflow hardening ##### Goal @@ -304,7 +403,7 @@ Improve ergonomics on smaller screens. --- -### Stage 6 — Controlled bulk actions (only after groundwork) +### Stage 7 — Controlled bulk actions (only after groundwork) #### Objective @@ -353,7 +452,7 @@ The following packages exist as scaffolded stubs with no implementation. Each ne | `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 7 — Infrastructure package activation** to the roadmap covering `auth`, `data`, and `integrations` before expanding into new feature domains. +**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 @@ -370,7 +469,7 @@ The `design_system` package currently contains: - 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:** Before or during Stage 4 (Android), migrate reusable shell widgets into `design_system` and add responsive layout primitives. This prevents duplication between `kell_web` and `kell_mobile`. +**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 @@ -387,7 +486,7 @@ Currently, CI/CD exists only for MkDocs documentation publishing. There is no au - Flutter build validation (web + Android) - Test result reporting or quality gates -**Recommendation:** Add a **Stage 4 prerequisite or parallel track** to establish Flutter CI/CD in Forgejo Actions before the Android expansion adds more surfaces to validate. +**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