Design Docs

Design docs explain why Routa is shaped the way it is. Read this section when product behavior, system boundaries, or long-lived invariants matter more than install steps.

If you are still trying to get Routa running, go back to Quick Start, Platforms, or Use Routa.

Choose A Reading Path

Architecture Start here when you need system boundaries, runtime topology, and the web/desktop parity model. Architecture Decisions Read the ADR index when you need the durable decisions behind providers, workspaces, Kanban automation, and specialist loading. Execution Modes Understand the product meaning of `Session`, `Kanban`, and `Team` before changing workflow behavior. Workspace-Centric Redesign Use this to understand the current product shape, shipped changes, and remaining transition debt. Core Beliefs Read the product and repository principles that should survive refactors and UI changes.

What You Get From This Section

Boundaries

System Shape

Learn which responsibilities belong to the web app, desktop runtime, server, and ACP layer.

Product Model

Core Concepts That Matter

Understand workspaces, repositories, providers, Sessions, Kanban, and Team as durable product objects.

Decision History

Why It Works This Way

Use ADRs and redesign notes when a change would otherwise fight an intentional system decision.

Focused Design Material

Use these when you already know the main product model and need a narrower topic:

• agentwatch-tui.md: TUI-first runtime model, information architecture, and keybindings for Harness Monitor
• harness-trace-learning-phase2.md: trace learning and playbook-driven guidance

Legacy Specs And Migration Status

Historical design material still exists under .kiro/specs/, but it is not automatically canonical. Keep using this page as the curated entry point instead of treating the raw archive as the source of truth.

Legacy Specs Inventory

Legacy Spec	Scope	Current Handling
.kiro/specs/docker-agent-execution/design.md	Docker-backed ACP agent execution architecture	indexed only
.kiro/specs/docker-agent-execution/requirements.md	Docker agent execution requirements	indexed only
.kiro/specs/docker-agent-execution/tasks.md	Docker agent execution task breakdown	indexed only
.kiro/specs/kanban-workspace-repository/requirements.md	Workspace repository requirements for Kanban	indexed only
.kiro/specs/playwright-page-snapshots/requirements.md	Page snapshot requirements	indexed only
.kiro/specs/workspace-centric-redesign/design.md	Workspace-first redesign architecture	indexed only
.kiro/specs/workspace-centric-redesign/requirements.md	Workspace-first redesign requirements	indexed only
.kiro/specs/workspace-centric-redesign/tasks.md	Workspace-first redesign task breakdown	indexed only

Curation Rules

• Migrate only reviewed, still-relevant knowledge from .kiro/specs/.
• Do not copy large historical specs verbatim into docs/ unless they are being actively normalized.
• When a legacy spec becomes canonical, create a focused document here and link back to the source in a short provenance note.
• Prefer one canonical document plus pointers over parallel copies with drift.

Related Docs

• Architecture
• Architecture Decision Records
• Product Specs
• Developer Guide