docs: refresh roadmap and modularization contribution guidance

2026-11-12 16:12:27 +01:00 · 2026-11-11 16:42:22 +00:00
parent 0276e15f6e
commit a130611340
2 changed files with 109 additions and 75 deletions
@@ -76,10 +76,29 @@ Good pull requests usually include:
 - Screenshots or short recordings for UI changes.
 - Links to related issues, for example `Fixes #123`.
-Please keep PRs small. Large PRs that mix unrelated cleanup, formatting, refactors, and behavior changes are much harder to review.
+Keep PRs cohesive. Small, focused changes are the default. Larger, coordinated decompositions can be appropriate under the conditions below; unrelated cleanup, formatting, refactors, and behavior changes should not be mixed.
 > **Auto-generated PRs.** If you are running an LLM agent (Devin, Cursor, OpenHands, Claude Code, etc.) against this repo: please open an issue describing the problem first instead of opening a PR directly. Bulk agent-generated PRs that don't match the project's visual style or contribution format will be closed without review, even when the underlying fix is correct.
 ### Structural changes and modularization
 Small, focused PRs remain the default. However, a larger PR may be appropriate when it extracts one coherent responsibility from an oversized module and splitting that extraction across several PRs would create unnecessary conflicts or integration complexity.
 Before starting structural work:
 - Review existing issues and PRs, and coordinate the intended boundary with maintainers. Use #4071 for codebase modularization.
 - Keep the change limited to one coherent responsibility or subsystem. Do not combine unrelated rewrites, new features, formatting changes, or opportunistic cleanup.
 - Preserve observable behavior, existing interfaces, import compatibility, persistence contracts, and relevant runtime invariants unless a separate change has been explicitly approved.
 - Provide focused regression tests and runtime validation appropriate to the affected behavior. For frontend changes, include browser validation and screenshots or recordings where rendering may change.
 - Explain the extraction boundary, compatibility considerations, validation evidence, and any limitations in the PR description.
 There is no arbitrary line-count limit for a well-scoped structural PR. Reviewability, correctness, and integration risk determine whether its scope is acceptable.
 **Temporary agent-runtime coordination:** Harness V2 development affects `src/agent_loop.py` and related execution, authorization, orchestration, and context contracts. Unrelated changes to those areas are temporarily frozen and must be coordinated with maintainers. Other modules remain open for contributions. Urgent bug and security reports remain welcome.
 All changes must follow the existing [risk-based review policy](docs/maintainers/changes-and-review.md), repository protections, and PR template.
 ## Style and visual changes
 Odysseus has an intentional visual style. PRs that ignore it will be closed without merge, no matter how correct the underlying code is.
@@ -1,87 +1,102 @@
 # Roadmap / Help Wanted
-Odysseus is on a voyage, but not home yet. It works great for me (lol), but this ship is moving fast and feedback/help would be appreciated! (I don't know what I'm doing, help).
+Odysseus is an evolving self-hosted AI workspace. This roadmap highlights the areas where improvements and contributions are most useful.
-If you see weird CSS, strange layout behavior, or a suspiciously murky corner of
+It describes current direction, not a fixed release schedule or a complete issue backlog. Specific implementations should be coordinated through existing issues and pull requests.
 the codebase, you are probably right to stay away.
-## High Priority
+Contributions target `dev`. The `main` branch is curated for releases.
- SQUASH BUGS
+## Stabilization and reliability
 - Fresh install smoke tests on Linux, macOS, and Windows. Docker, native Python,
  and WSL all need coverage.
- Integration audit: do integrations even work? Confirm what works, what needs setup docs, and what should be removed or hidden. 
+Reliable operation across installations, platforms, providers, and supported hardware remains a priority.
 - Cookbook reliability on other computers. This is probably the area most likely to need work across different machines, GPUs, drivers, shells, and Python environments.
 - Cookbook SGLang support across platforms. Make sure SGLang setup/serve works
  predictably on Linux, Windows/WSL, macOS where possible, Docker, and common
  NVIDIA/AMD hardware paths.
 - Deep Research model presets by hardware. Recommend approved model/parameter
  profiles for small, medium, and large local setups so people with different
  hardware can use Deep Research without guessing. Surface this either in Deep
  Research settings or as a Cookbook scan/dropdown suggestion.
 - Cookbook model scan/download ranking. Prioritize newer architectures and
  better hardware-fit models instead of scoring everything almost the same.
  Ranking should account for architecture age, quant format, VRAM/RAM fit,
  backend support, vision/mmproj requirements, and likely serve reliability.
 - Cookbook error feedback and logging. Failed downloads, dependency installs,
  preflights, and serve jobs should show the actual command/output/error in the
  UI, with copyable logs and clear next steps instead of just "crashed".
 - Agent prompt/context bloat. Agent mode is too heavy for smaller local models:
  tool schemas, skills, memory, documents, and instructions can eat the context
  before the user request really starts. We need slimmer prompts, better tool
  selection, smaller default tool sets, and clearer guidance for models with
  4k/8k/16k context windows.
 - Local model speculative decoding support. For Odysseus-tuned local models,
  plan to ship or recommend a small same-tokenizer draft model when the serving
  backend supports it. Early vLLM testing showed a generic `Qwen3-0.6B` draft
  beside `Qwen3-8B` can materially reduce wall time, while an unsupported
  DSpark conversion performed poorly. Treat this as a supported draft-model lane
  first; keep MTP-specific packaging as future work only when the architecture
  and runtime support are real. Judge this by time-to-success, tool correctness,
  grammar, and unchanged target output, not tokens/sec alone.
 - Skill/tool prompt-injection audit. User-editable skills, notes, documents,
  fetched pages, and memories should be treated as untrusted data. Keep testing
  whether models follow malicious instructions from those surfaces.
 - Better degraded-state reporting for ChromaDB, SearXNG, email, ntfy, and provider probes.
 - Email performance audit. Fetching, searching, opening, deleting, and sending
  email can feel slow, especially over IMAP/SMTP providers with high latency.
  Need someone who knows mail performance to profile the current flow, identify
  whether the bottleneck is IMAP folder select/fetch, cache invalidation,
  attachment/body loading, SMTP handshakes, or frontend refresh behavior, then
  propose safer caching/prefetch/batching without breaking multi-account state.
 - Provider setup/probing audit for Anthropic, Gemini, Groq, xAI, OpenRouter, OpenAI, and DeepSeek.
-## Refactor Targets
+- **CI and validation:** Improve the reliability of automated checks, exact-revision validation, and release confidence. See #5932 and the confirmed docs-only CI regression, #7109.
- CSS cleanup. `static/style.css` basically Calypso's island atm.
+- **Test quality:** Continue improving deterministic tests, isolation, focused execution, and maintainable test structure. See #2523 and the [testing standard](tests/TESTING_STANDARD.md).
- Tour core helper. The onboarding tours have too much copy-pasted scaffolding; promote a shared `tour-core.js` helper before adding more tours.
+- **Fresh installations:** Expand smoke-test coverage for native Linux, macOS, Windows, WSL, and Docker. Verify clean startup, health reporting, and graceful handling of unavailable optional services. See #3968.
- Modal/window positioning cleanup. Some window controls have improved, but the
+- **Cookbook reliability:** Improve model installation, dependency management, hardware detection, and serving across supported platforms, GPUs, drivers, and execution backends.
-  underlying popup/dropdown/fixed-position behavior is still too fragile.
+- **Email integration:** Resolve remaining Google OAuth regressions, preserve account isolation, and improve cross-provider reliability. See #5637.
- Mobile media override discoverability. A lot of "CSS did not move" bugs are mobile `@media` overrides of the same selector; comments or linting around desktop/mobile paired rules would help.
+- **Storage integrity:** Investigate upload payloads, database growth, indexing, and file lifecycle without introducing unsafe or destructive cleanup. See #4889.
- Dead code pass for old routes, stale feature flags, and unused UI states.
+- **Security:** Continue hardening authorization, agent tool execution, prompt-injection boundaries, filesystem access, and handling of untrusted content.
 - **Integration diagnostics:** Verify provider and optional-service behavior, improve failure reporting, and ensure unavailable dependencies degrade predictably.
-## Frontend
+Current stabilization work is coordinated through the [Stabilization & Modularization milestone](https://github.com/odysseus-dev/odysseus/milestone/1).
- Expand the Editor for quicker, more robust everyday use. Better file/document
+## Modularization and maintainability
  handling, smoother window behavior, clearer save/export flows, stronger image
  editing affordances, and fewer brittle edge cases.
 - Better AI integration for Notes and Todos. Notes should be easier for the
  agent to read, update, summarize, and turn into actions. Todos should be
  assignable to an agent from the UI, possibly through a button, task action,
  or dedicated skill/tool flow.
 - Mobile gallery/editor polish. Easier to launch/download inpaint model or any missing pieces.
 - Accessibility pass: keyboard navigation, focus states, contrast, reduced motion.
 - Improve empty states and error messages on fresh installs.
 - Tighten first-run setup, hints, and tours so they do not repeat or fight each other.
 - Vendor CDN assets eventually for a more fully self-hosted/offline mode.
-## Backend
+The goal is to make the codebase easier to navigate, test, review, and extend while preserving existing behavior and compatibility.
- More tests around endpoint probing and provider setup.
+The initial CSS extraction and substantial tool-domain decomposition have established a foundation, but responsibility boundaries still need improvement.
 - Better task scheduler defaults and visibility.
 - Backup/restore guide and helper flow for `data/`.
 - Security hardening around admin-only tools and clear docs for their risk.
-## Not The Focus Right Now
+Current areas of interest:
-I prob shouldnt add more themes.
+- **Frontend:** Continue focused decomposition of large document, gallery, settings, calendar, and other UI modules.
 - **CSS:** The former `static/style.css` has been split into ordered files under `static/css/`. Improve maintainability without inadvertently changing cascade order, theme behavior, or responsive layouts.
 - **Tools:** Continue clarifying ownership within `src/agent_tools/` and related implementations while preserving existing public contracts and compatibility.
 - **Backend:** Identify safe boundaries in large Cookbook routes, persistence modules, and feature-specific route handlers.
 - **Tests:** Keep test helpers, fixtures, and focused test ownership aligned with the implementation modules they exercise.
 - **UI infrastructure:** Reduce duplicated tour scaffolding, fragile modal/window positioning, stale feature flags, and cross-feature coupling.
 [#4071](https://github.com/odysseus-dev/odysseus/issues/4071) is the canonical coordination tracker for this work.
 Larger PRs can be appropriate for a single coherent decomposition when splitting the work into many smaller PRs would create unnecessary integration complexity. Coordinate the intended boundary before implementation and provide meaningful regression and runtime validation.
 ### Agent runtime and Harness V2
 Harness V2 is under active development.
 The agent runtime, including `src/agent_loop.py` and closely related execution, authorization, orchestration, and context contracts, is temporarily frozen for unrelated changes while that work is developed and validated.
 Agent-runtime refactors must be coordinated with maintainers. Urgent bug and security reports remain welcome.
 This restriction does not apply to unrelated application modules.
 ## AI, local models, and research
 The following improvements remain areas of product interest. Their exact implementations and priority relative to one another require normal issue triage and product decisions.
 - **Smaller-model agent efficiency:** Reduce unnecessary prompt, tool-schema, skill, memory, and document context overhead. Improve tool selection and behavior with constrained context windows.
 - **Cookbook SGLang support:** Improve setup and serving across relevant operating systems, hardware, and deployment methods.
 - **Model discovery and ranking:** Recommend appropriate models using architecture, quantization, RAM/VRAM availability, backend support, multimodal requirements, and expected serving reliability.
 - **Deep Research presets:** Explore hardware-appropriate model and parameter configurations for smaller and larger local systems.
 - **Cookbook diagnostics:** Expose actionable installation, download, preflight, and serving failures with useful, copyable logs.
 - **Speculative decoding:** Investigate supported draft-model configurations for compatible local backends. Evaluate end-to-end correctness and time to successful output, not throughput alone.
 - **Provider setup and probing:** Improve integration quality for supported local and hosted providers, including endpoint discovery and capability handling.
 ## Frontend and user experience
 - Improve document and file editing, window behavior, save/export flows, and image-editing reliability.
 - Expand agent-assisted workflows for Notes and Todos, including reading, updating, summarizing, and turning information into actionable tasks.
 - Improve the mobile gallery and editor experience.
 - Strengthen keyboard navigation, accessibility, focus behavior, contrast, and reduced-motion support.
 - Improve first-run setup, empty states, error messages, and onboarding guidance.
 - Improve desktop/mobile CSS maintainability and responsive behavior.
 - Continue reducing unnecessary external asset dependencies where practical for self-hosted and offline operation.
 ## Backend and operations
 - Improve email performance through measured investigation of fetching, caching, attachment handling, searching, and sending.
 - Expand regression coverage for provider setup, endpoint probing, and degraded service states.
 - Improve task-scheduler defaults, reliability, and operational visibility.
 - Improve backup and recovery guidance for persistent application data.
 - Continue reviewing administrative capabilities, sensitive integrations, and their authorization boundaries.
 ## Not a current priority
 - Adding more themes without a clear product need.
 - Broad rewrites without demonstrated value.
 - Framework migrations or architectural changes undertaken solely to reduce file counts.
 - Uncoordinated changes to the temporarily frozen agent-runtime contracts.
 ## Contributing
 Before starting work:
 1. Read [CONTRIBUTING.md](CONTRIBUTING.md).
 2. Search existing issues and PRs to avoid duplicating work.
 3. Coordinate structural changes through #4071 and stabilization work through the milestone.
 4. Open a focused issue where needed and follow the existing contribution templates.
 5. Provide relevant tests, runtime evidence, and screenshots or recordings for visual changes.
 For changes involving product direction or difficult-to-reverse contracts, follow the [feature proposal process](docs/maintainers/product-and-features.md).
 Security vulnerabilities must be reported privately through [SECURITY.md](SECURITY.md).