# 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](./current-architecture.md). The matching visual
diagram lives in [current-architecture.excalidraw](./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 startup scripts and deploy artifacts that still center on
  `backend.main` as a monolithic entrypoint
- 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 optional REST facade

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