Requirements: Flynn Operator DX

Defined: 2026-02-09 Core Value: Make Flynn easier to reason about, configure, and monitor

v1 Requirements

Requirements for this milestone. Each maps to roadmap phases.

DECO-01: Model client creation logic extracted from daemon/index.ts into src/daemon/models.ts with the same public interface
DECO-02: Channel adapter setup logic extracted into src/daemon/channels.ts
DECO-03: Agent cache and factory logic extracted into src/daemon/agents.ts
DECO-04: Memory store and vector store initialization extracted into src/daemon/memory.ts
DECO-05: Tool registration and policy wiring extracted into src/daemon/tools.ts
DECO-06: Message routing logic extracted into src/daemon/routing.ts (test file already exists)
DECO-07: daemon/index.ts reduced to a thin composition root that imports and wires extracted modules
DECO-08: All 1077+ existing tests continue to pass after decomposition

CONF-01: User can set FLYNN_ENV environment variable to select a config overlay (e.g., docker, production)
CONF-02: Config loader merges environment-specific overlay file on top of base config with deep merge
CONF-03: flynn doctor validates that the selected environment overlay file exists when FLYNN_ENV is set

DASH-01: Dashboard shows core counters: messages processed, active sessions, queue depth, daemon uptime
DASH-02: Dashboard shows model call metrics: per-call latency, tokens/sec throughput, error rates by provider
DASH-03: Dashboard shows live event stream: scrollable log of errors and events with timestamps and context
DASH-04: Dashboard shows active request tracking: in-flight requests, recent tool executions, active agent sessions
DASH-05: Gateway exposes /health endpoint returning JSON status for liveness/readiness checks

Deferred to future milestone. Tracked but not in current roadmap.

OBSV-01: Structured JSON logging framework (pino or similar) replacing console.log
OBSV-02: Request tracing with correlation IDs across channel → agent → model → tool chain
OBSV-03: Prometheus-compatible metrics endpoint for external monitoring

CONF-04: Deep merge semantics for overlay files (objects merge, arrays replace)
CONF-05: Convention-based overlay file discovery (config/default.yaml + config/{env}.yaml)
CONF-06: Hot reload of config changes without daemon restart

QUAL-01: ESLint configuration with @typescript-eslint/recommended
QUAL-02: Reduce as any casts by creating proper mock factories and wrapper types
QUAL-03: Test coverage for security-sensitive file tools

Feature	Reason
New channel adapters	Not the focus — separate milestone
Agent intelligence (sub-agents, planning)	Separate milestone
Companion apps (macOS, iOS, Android)	Massive scope, different project
Skill registry / marketplace	Community feature, premature
Onboard wizard	Operator already knows the system
Multi-tenant / team features	Single-operator tool

Which phases cover which requirements. Updated during roadmap creation.

Coverage:

Requirements defined: 2026-02-09 Last updated: 2026-02-09 after initial definition