diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 67cd615..7eaf6bf 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -71,27 +71,27 @@ Which phases cover which requirements. Updated during roadmap creation. | Requirement | Phase | Status | |-------------|-------|--------| -| DECO-01 | — | Pending | -| DECO-02 | — | Pending | -| DECO-03 | — | Pending | -| DECO-04 | — | Pending | -| DECO-05 | — | Pending | -| DECO-06 | — | Pending | -| DECO-07 | — | Pending | -| DECO-08 | — | Pending | -| CONF-01 | — | Pending | -| CONF-02 | — | Pending | -| CONF-03 | — | Pending | -| DASH-01 | — | Pending | -| DASH-02 | — | Pending | -| DASH-03 | — | Pending | -| DASH-04 | — | Pending | -| DASH-05 | — | Pending | +| DECO-01 | Phase 1 | Pending | +| DECO-02 | Phase 1 | Pending | +| DECO-03 | Phase 1 | Pending | +| DECO-04 | Phase 1 | Pending | +| DECO-05 | Phase 1 | Pending | +| DECO-06 | Phase 1 | Pending | +| DECO-07 | Phase 1 | Pending | +| DECO-08 | Phase 1 | Pending | +| CONF-01 | Phase 2 | Pending | +| CONF-02 | Phase 2 | Pending | +| CONF-03 | Phase 2 | Pending | +| DASH-01 | Phase 3 | Pending | +| DASH-02 | Phase 3 | Pending | +| DASH-03 | Phase 3 | Pending | +| DASH-04 | Phase 3 | Pending | +| DASH-05 | Phase 3 | Pending | **Coverage:** - v1 requirements: 16 total -- Mapped to phases: 0 -- Unmapped: 16 +- Mapped to phases: 16 +- Unmapped: 0 --- *Requirements defined: 2026-02-09* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md new file mode 100644 index 0000000..b4b66ce --- /dev/null +++ b/.planning/ROADMAP.md @@ -0,0 +1,66 @@ +# Roadmap: Flynn Operator DX + +**Created:** 2026-02-09 +**Depth:** Quick (3 phases) +**Core Value:** Make Flynn easier to reason about, configure, and monitor + +## Overview + +Three phases, each delivering one complete capability. Phase 1 decomposes the monolithic daemon wiring file into focused modules — this must happen first because Phases 2 and 3 both touch daemon internals. Phase 2 adds multi-environment config overlays. Phase 3 builds the live ops dashboard with real-time metrics. + +## Phases + +### Phase 1: Daemon Decomposition + +**Goal:** daemon/index.ts is a thin composition root; each concern lives in its own module with the same public interface. + +**Dependencies:** None (first phase) + +**Requirements:** DECO-01, DECO-02, DECO-03, DECO-04, DECO-05, DECO-06, DECO-07, DECO-08 + +**Success Criteria:** +1. Running `pnpm test:run` passes 1077+ tests with zero regressions +2. daemon/index.ts is under 200 lines and contains only imports, wiring, and lifecycle — no business logic +3. Each extracted module (models, channels, agents, memory, tools, routing) can be understood in isolation — reading one file tells you everything about that concern +4. Adding a new model provider or channel adapter requires editing the relevant module file, not daemon/index.ts + +### Phase 2: Config Overlays + +**Goal:** Operator can manage dev/docker/production configs with a base file plus lightweight overlay files, selected by environment variable. + +**Dependencies:** Phase 1 (daemon is decomposed; config loading changes are lower risk) + +**Requirements:** CONF-01, CONF-02, CONF-03 + +**Success Criteria:** +1. Setting `FLYNN_ENV=docker` and starting Flynn loads config/docker.yaml merged on top of the base config — operator sees docker-specific settings active +2. Starting Flynn without FLYNN_ENV works exactly as before — existing config files unchanged, zero breakage +3. Running `flynn doctor` with `FLYNN_ENV=staging` (no staging.yaml) reports a clear error identifying the missing overlay file + +### Phase 3: Live Ops Dashboard + +**Goal:** Operator can open the web dashboard and see real-time system health — counters, model performance, event stream, and active requests — without tailing logs. + +**Dependencies:** Phase 1 (metrics hooks need to be wired into decomposed modules, not the god file) + +**Requirements:** DASH-01, DASH-02, DASH-03, DASH-04, DASH-05 + +**Success Criteria:** +1. Opening the dashboard shows live-updating counters for messages processed, active sessions, queue depth, and uptime — values change in real time as messages flow +2. After sending a message through any channel, the model call appears in the dashboard with latency, tokens/sec, and provider name within seconds +3. Triggering an error (e.g., bad model config) shows the error in the dashboard event stream with timestamp and context — no need to check terminal output +4. Hitting GET /health returns JSON with daemon status, uptime, and component readiness — usable for Docker HEALTHCHECK or monitoring + +## Progress + +| Phase | Status | Requirements | +|-------|--------|--------------| +| 1 — Daemon Decomposition | not_started | DECO-01..08 (8) | +| 2 — Config Overlays | not_started | CONF-01..03 (3) | +| 3 — Live Ops Dashboard | not_started | DASH-01..05 (5) | + +**Coverage:** 16/16 v1 requirements mapped ✓ + +--- +*Roadmap created: 2026-02-09* +*Last updated: 2026-02-09* diff --git a/.planning/STATE.md b/.planning/STATE.md new file mode 100644 index 0000000..ee4511f --- /dev/null +++ b/.planning/STATE.md @@ -0,0 +1,58 @@ +# State: Flynn Operator DX + +## Project Reference + +**Core Value:** Make Flynn easier to reason about, configure, and monitor +**Milestone:** Operator DX +**Phases:** 3 + +## Current Position + +**Phase:** 1 — Daemon Decomposition +**Plan:** Not yet created +**Status:** not_started +**Progress:** ░░░░░░░░░░ 0/3 phases + +## Phase Status + +| Phase | Status | Plans | +|-------|--------|-------| +| 1 — Daemon Decomposition | not_started | — | +| 2 — Config Overlays | not_started | — | +| 3 — Live Ops Dashboard | not_started | — | + +## Performance Metrics + +| Metric | Value | +|--------|-------| +| Test count | 1077 (baseline) | +| daemon/index.ts lines | 1087 (baseline) | + +## Accumulated Context + +### Key Decisions +- Decompose god file incrementally, not rewrite +- Config overlays over separate files +- Extend existing vanilla JS dashboard +- Skip structured logging — dashboard will reveal what metrics matter + +### Technical Notes +- daemon/index.ts handles: model clients, channel setup, agent factory, memory init, vector store, session pruning, lifecycle, shutdown +- Existing routing test file exists (decomposition already partially anticipated) +- Web dashboard is vanilla JS SPA at src/gateway/ui/ +- Config loader at src/config/loader.ts, schema at src/config/schema.ts (409 lines) + +### TODOs +_(none yet)_ + +### Blockers +_(none)_ + +## Session Continuity + +**Last session:** Initial roadmap creation +**Next action:** Plan Phase 1 (Daemon Decomposition) + +--- +*State initialized: 2026-02-09* +*Last updated: 2026-02-09*