evotraders/docs/development-roadmap.md

Development Roadmap

This roadmap describes the next engineering steps based on the current code-supported architecture, not on historical compatibility layers.

The current architecture source of truth is current-architecture.md. The matching visual diagram lives in current-architecture.excalidraw.

Guiding Principle

The repo should converge on one clear runtime model:

split services + gateway + run-scoped runtime state under runs/<run_id>/

That means future work should reduce ambiguity between:

• design-time workspaces/
• runtime runs/<run_id>/
• compatibility gateway paths
• older root-level runtime directories

Phase 1: Documentation And Startup Convergence

Goal: make the supported system shape unambiguous for contributors and operators.

Planned work:

• keep docs/current-architecture.md as the primary architecture fact source
• keep docs/current-architecture.excalidraw aligned with code changes
• make README, service docs, and deploy docs point to the same runtime model
• explicitly describe agent_service, runtime_service, trading_service, news_service, gateway, and OpenClaw boundaries
• remove or mark statements that imply workspaces/ is the runtime source of truth

Definition of done:

• a new contributor can identify the supported local startup path in under five minutes
• architecture wording is consistent across top-level docs

Phase 2: Runtime Model Consolidation

Goal: ensure the runtime state model is centered on runs/<run_id>/.

Planned work:

• review remaining reads and writes that still assume root-level live/, backtest/, or production/ directories are canonical
• keep compatibility exports such as team_dashboard/*.json, but document them as exports rather than primary state
• continue moving runtime metadata, assets, and bootstrap configuration behind run-scoped helpers
• keep the control plane and runtime APIs conceptually separate

Definition of done:

• run-scoped helpers are the default path for runtime state access
• compatibility directories are no longer required for normal development

Phase 3: Compatibility Surface Reduction

Goal: preserve only intentional compatibility layers.

Planned work:

• identify any remaining deployment docs that still lag the split-service topology
• classify compatibility surfaces into:
  • stable and intentional
  • temporary and shrinking
  • removable once replacements are fully active
• reduce env-dependent fallback ambiguity for read-only service routing where practical
• document the difference between OpenClaw WebSocket integration and the small set of CLI-backed gateway read helpers

Definition of done:

• compatibility surfaces have explicit ownership
• the repo no longer mixes migration leftovers with recommended defaults

Phase 4: EvoAgent Runtime Cutover

Goal: move from selective EvoAgent rollout to a cleaner default runtime path.

Planned work:

• continue supporting staged rollout through explicit agent selection
• close functional gaps that still require falling back to legacy analyst/risk/PM implementations
• keep run-scoped workspace assets and prompt reload behavior aligned between legacy and EvoAgent paths
• avoid reintroducing generic workspace-loading shortcuts on the pipeline layer

Definition of done:

• EvoAgent selection is predictable, test-backed, and no longer treated as an experimental side path for the supported roles

Phase 5: Contract Tests And Operational Confidence

Goal: increase confidence that the split-service architecture remains coherent.

Planned work:

• expand service-surface tests around runtime_service, trading_service, news_service, and migration boundaries
• keep smoke coverage for staged EvoAgent runtime startup
• add validation around docs/script consistency where low-cost checks are possible
• tighten deploy docs so checked-in production examples are clearly described as either compatibility topology or first-class topology

Definition of done:

• service boundaries are testable and understandable without tracing legacy code
• startup, deploy, and smoke paths tell the same story

Immediate Focus

The next practical priority order should be:

1. documentation and startup convergence
2. runtime model consolidation around runs/<run_id>/
3. compatibility surface reduction
4. EvoAgent runtime cutover
5. broader contract and smoke confidence