From b85b106b108db7ab1dedc14df565719db9ae5657 Mon Sep 17 00:00:00 2001 From: Val Alexander <68980965+BunsDev@users.noreply.github.com> Date: Sat, 25 Apr 2026 05:29:57 -0500 Subject: [PATCH] docs: add application modernization plan (#71528) * docs: add application modernization plan * docs: clarify frontend skill target --- .../gpt54-codex-agentic-parity-maintainers.md | 22 ++ .../application-modernization-plan.md | 210 ++++++++++++++++++ 2 files changed, 232 insertions(+) create mode 100644 docs/reference/application-modernization-plan.md diff --git a/docs/help/gpt54-codex-agentic-parity-maintainers.md b/docs/help/gpt54-codex-agentic-parity-maintainers.md index 6a776a9218b..c5e73564266 100644 --- a/docs/help/gpt54-codex-agentic-parity-maintainers.md +++ b/docs/help/gpt54-codex-agentic-parity-maintainers.md @@ -149,6 +149,28 @@ The parity harness is not the only evidence source. Keep this split explicit in - PR D owns the scenario-based GPT-5.4 vs Opus 4.6 comparison - PR B deterministic suites still own auth/proxy/DNS and full-access truthfulness evidence +## Quick maintainer merge workflow + +Use this when you are ready to land a parity PR and want a repeatable, low-risk sequence. + +1. Confirm evidence bar is met before merge: + - reproducible symptom or failing test + - verified root cause in touched code + - fix in the implicated path + - regression test or explicit manual verification note +2. Triage/label before merge: + - apply any `r:*` auto-close labels when the PR should not land + - keep merge candidates free of unresolved blocker threads +3. Validate locally on the touched surface: + - `pnpm check:changed` + - `pnpm test:changed` when tests changed or bug-fix confidence depends on test coverage +4. Land with the standard maintainer flow (`/landpr` process), then verify: + - linked issues auto-close behavior + - CI and post-merge status on `main` +5. After landing, run duplicate search for related open PRs/issues and close only with a canonical reference. + +If any one of the evidence bar items is missing, request changes instead of merging. + ## Goal-to-evidence map | Completion gate item | Primary owner | Review artifact | diff --git a/docs/reference/application-modernization-plan.md b/docs/reference/application-modernization-plan.md new file mode 100644 index 00000000000..3756b52362c --- /dev/null +++ b/docs/reference/application-modernization-plan.md @@ -0,0 +1,210 @@ +--- +summary: "Comprehensive application modernization plan with frontend delivery skill updates" +title: "Application modernization plan" +read_when: + - Planning a broad OpenClaw application modernization pass + - Updating frontend implementation standards for app or Control UI work + - Turning a broad product quality review into phased engineering work +--- + +# Application modernization plan + +## Goal + +Move the application toward a cleaner, faster, more maintainable product without +breaking current workflows or hiding risk in broad refactors. The work should +land as small, reviewable slices with proof for each touched surface. + +## Principles + +- Preserve current architecture unless a boundary is demonstrably causing churn, + performance cost, or user-visible bugs. +- Prefer the smallest correct patch for each issue, then repeat. +- Separate required fixes from optional polish so maintainers can land high + value work without waiting on subjective decisions. +- Keep plugin-facing behavior documented and backwards compatible. +- Verify shipped behavior, dependency contracts, and tests before claiming a + regression is fixed. +- Make the main user path better first: onboarding, auth, chat, provider setup, + plugin management, and diagnostics. + +## Phase 1: Baseline audit + +Inventory the current application before changing it. + +- Identify the top user workflows and the code surfaces that own them. +- List dead affordances, duplicate settings, unclear error states, and expensive + render paths. +- Capture current validation commands for each surface. +- Mark issues as required, recommended, or optional. +- Document known blockers that need owner review, especially API, security, + release, and plugin contract changes. + +Definition of done: + +- One issue list with repo-root file references. +- Each issue has severity, owner surface, expected user impact, and a proposed + validation path. +- No speculative cleanup items are mixed into required fixes. + +## Phase 2: Product and UX cleanup + +Prioritize visible workflows and remove confusion. + +- Tighten onboarding copy and empty states around model auth, gateway status, + and plugin setup. +- Remove or disable dead affordances where no action is possible. +- Keep important actions visible across responsive widths instead of hiding them + behind fragile layout assumptions. +- Consolidate repeated status language so errors have one source of truth. +- Add progressive disclosure for advanced settings while keeping core setup fast. + +Recommended validation: + +- Manual happy path for first-run setup and existing user startup. +- Focused tests for any routing, config persistence, or status derivation logic. +- Browser screenshots for changed responsive surfaces. + +## Phase 3: Frontend architecture tightening + +Improve maintainability without a broad rewrite. + +- Move repeated UI state transformations into narrow typed helpers. +- Keep data fetching, persistence, and presentation responsibilities separate. +- Prefer existing hooks, stores, and component patterns over new abstractions. +- Split oversized components only when it reduces coupling or clarifies tests. +- Avoid introducing broad global state for local panel interactions. + +Required guardrails: + +- Do not change public behavior as a side effect of file splitting. +- Keep accessibility behavior intact for menus, dialogs, tabs, and keyboard + navigation. +- Verify that loading, empty, error, and optimistic states still render. + +## Phase 4: Performance and reliability + +Target measured pain rather than broad theoretical optimization. + +- Measure startup, route transition, large list, and chat transcript costs. +- Replace repeated expensive derived data with memoized selectors or cached + helpers where profiling proves value. +- Reduce avoidable network or filesystem scans on hot paths. +- Keep deterministic ordering for prompt, registry, file, plugin, and network + inputs before model payload construction. +- Add lightweight regression tests for hot helpers and contract boundaries. + +Definition of done: + +- Each performance change records baseline, expected impact, actual impact, and + remaining gap. +- No perf patch lands solely on intuition when cheap measurement is available. + +## Phase 5: Type, contract, and test hardening + +Raise correctness at the boundary points users and plugin authors depend on. + +- Replace loose runtime strings with discriminated unions or closed code lists. +- Validate external inputs with existing schema helpers or zod. +- Add contract tests around plugin manifests, provider catalogs, gateway protocol + messages, and config migration behavior. +- Keep compatibility paths in doctor or repair flows instead of startup-time + hidden migrations. +- Avoid test-only coupling to plugin internals; use SDK facades and documented + barrels. + +Recommended validation: + +- `pnpm check:changed` +- Targeted tests for every changed boundary. +- `pnpm build` when lazy boundaries, packaging, or published surfaces change. + +## Phase 6: Documentation and release readiness + +Keep user-facing docs aligned with behavior. + +- Update docs with behavior, API, config, onboarding, or plugin changes. +- Add changelog entries only for user-visible changes. +- Keep plugin terminology user-facing; use internal package names only where + needed for contributors. +- Confirm release and install instructions still match the current command + surface. + +Definition of done: + +- Relevant docs are updated in the same branch as behavior changes. +- Generated docs or API drift checks pass when touched. +- The handoff names any skipped validation and why it was skipped. + +## Recommended first slice + +Start with a scoped Control UI and onboarding pass: + +- Audit first-run setup, provider auth readiness, gateway status, and plugin + setup surfaces. +- Remove dead actions and clarify failure states. +- Add or update focused tests for status derivation and config persistence. +- Run `pnpm check:changed`. + +This gives high user value with limited architecture risk. + +## Frontend skill update + +Use this section to update the frontend-focused `SKILL.md` supplied with the +modernization task. If adopting this guidance as a repo-local OpenClaw skill, +create `.agents/skills/openclaw-frontend/SKILL.md` first, keep the frontmatter +that belongs in that target skill, then add or replace the body guidance with +the following content. + +```markdown +# Frontend Delivery Standards + +Use this skill when implementing or reviewing user-facing React, Next.js, +desktop webview, or app UI work. + +## Operating rules + +- Start from the existing product workflow and code conventions. +- Prefer the smallest correct patch that improves the current user path. +- Separate required fixes from optional polish in the handoff. +- Do not build marketing pages when the request is for an application surface. +- Keep actions visible and usable across supported viewport sizes. +- Remove dead affordances instead of leaving controls that cannot act. +- Preserve loading, empty, error, success, and permission states. +- Use existing design-system components, hooks, stores, and icons before adding + new primitives. + +## Implementation checklist + +1. Identify the primary user task and the component or route that owns it. +2. Read the local component patterns before editing. +3. Patch the narrowest surface that solves the issue. +4. Add responsive constraints for fixed-format controls, toolbars, grids, and + counters so text and hover states cannot resize the layout unexpectedly. +5. Keep data loading, state derivation, and rendering responsibilities clear. +6. Add tests when logic, persistence, routing, permissions, or shared helpers + change. +7. Verify the main happy path and the most relevant edge case. + +## Visual quality gates + +- Text must fit inside its container on mobile and desktop. +- Toolbars may wrap, but controls must remain reachable. +- Buttons should use familiar icons when the icon is clearer than text. +- Cards should be used for repeated items, modals, and framed tools, not for + every page section. +- Avoid one-note color palettes and decorative backgrounds that compete with + operational content. +- Dense product surfaces should optimize for scanning, comparison, and repeated + use. + +## Handoff format + +Report: + +- What changed. +- What user behavior changed. +- Required validation that passed. +- Any validation skipped and the concrete reason. +- Optional follow-up work, clearly separated from required fixes. +```