435 lines
20 KiB
Markdown
435 lines
20 KiB
Markdown
# ByteLyst Agentic Notes — Master Roadmap
|
|
|
|
Version: 2.0
|
|
Date: March 10, 2026
|
|
Status: Draft
|
|
Companion Docs: `docs/PRD.md`
|
|
|
|
# 1. Purpose
|
|
|
|
This is the **master execution tracker** for the notes platform.
|
|
|
|
Use this document to:
|
|
|
|
- track phase status,
|
|
- understand sequencing and dependencies,
|
|
- assign workstreams to coding agents,
|
|
- link out to smaller roadmap documents with focused execution detail.
|
|
|
|
Detailed implementation plans live under `docs/roadmaps/`.
|
|
|
|
# Status Legend
|
|
|
|
- **Scaffolded** — package/app/module structure exists and boots.
|
|
- **Mock-backed** — UI/workflow exists but currently runs on mock or fallback data.
|
|
- **Local-only** — behavior exists in client/local state without real backend persistence.
|
|
- **Integrated** — wired to the intended backend/platform dependency.
|
|
- **Verified** — exercised by build, typecheck, tests, or smoke checks.
|
|
|
|
# 2. Confirmed Stack
|
|
|
|
- **Web**
|
|
- Next.js 16
|
|
- React 19
|
|
- TypeScript
|
|
|
|
- **Backend**
|
|
- Fastify 5
|
|
- TypeScript ESM
|
|
- Zod
|
|
|
|
- **Mobile MVP**
|
|
- React Native + Expo
|
|
|
|
- **Shared Services**
|
|
- `platform-service`
|
|
- `extraction-service`
|
|
- `mcp-server`
|
|
|
|
# 3. Roadmap Document Index
|
|
|
|
- [ ] `docs/roadmaps/00_MASTER_EXECUTION_PLAN.md`
|
|
- [ ] `docs/roadmaps/01_FOUNDATIONS_AND_DECISIONS.md`
|
|
- [x] `docs/roadmaps/02_BACKEND_ROADMAP.md`
|
|
- [x] `docs/roadmaps/03_WEB_ROADMAP.md`
|
|
- [x] `docs/roadmaps/04_MOBILE_ROADMAP.md`
|
|
- [x] `docs/roadmaps/05_MCP_AGENT_ROADMAP.md`
|
|
- [ ] `docs/roadmaps/06_PLATFORM_INTEGRATIONS_ROADMAP.md`
|
|
- [x] `docs/roadmaps/07_QA_RELEASE_DOCS_ROADMAP.md`
|
|
|
|
# 4. Master Phase Tracker
|
|
|
|
## Phase 0 — Foundations and Decisions
|
|
|
|
### Goals
|
|
|
|
- finalize product identity and product manifest inputs
|
|
- choose the single MVP mobile path
|
|
- define repo structure and ownership boundaries
|
|
- define initial domain objects and module boundaries
|
|
- lock reuse strategy against the ByteLyst workspace
|
|
|
|
### Checklist
|
|
|
|
- [ ] product name finalized
|
|
- [ ] `productId` finalized
|
|
- [ ] backend port assigned
|
|
- [ ] domain / bundle identifiers assigned
|
|
- [ ] token namespace requested
|
|
- [ ] mobile path confirmed as React Native MVP
|
|
- [ ] repo folder structure finalized
|
|
- [ ] initial Cosmos container strategy defined
|
|
- [ ] operator vs shared admin boundary defined
|
|
- [ ] PRD and roadmap aligned
|
|
|
|
### Owner Docs
|
|
|
|
- `docs/roadmaps/00_MASTER_EXECUTION_PLAN.md`
|
|
- `docs/roadmaps/01_FOUNDATIONS_AND_DECISIONS.md`
|
|
|
|
## Phase 1 — Core Product Skeleton
|
|
|
|
### Goals
|
|
|
|
- stand up web, backend, and mobile skeletons
|
|
- complete auth, app shells, and first persistence layer
|
|
- establish notes/workspaces as end-to-end vertical slices
|
|
|
|
### Checklist
|
|
|
|
- [x] web app boots with authenticated shell
|
|
- [x] backend boots with health and first modules
|
|
- [x] mobile app boots with auth and navigation shell
|
|
- [ ] notes CRUD works end-to-end
|
|
- [ ] workspaces CRUD works end-to-end
|
|
- [ ] first telemetry events are flowing
|
|
|
|
### Owner Docs
|
|
|
|
- `docs/roadmaps/02_BACKEND_ROADMAP.md`
|
|
- `docs/roadmaps/03_WEB_ROADMAP.md`
|
|
- `docs/roadmaps/04_MOBILE_ROADMAP.md`
|
|
- `docs/roadmaps/06_PLATFORM_INTEGRATIONS_ROADMAP.md`
|
|
|
|
## Phase 2 — Notes Product MVP
|
|
|
|
### Goals
|
|
|
|
- complete human-facing notes product MVP
|
|
- add relationships, tasks, artifacts, and useful mobile parity
|
|
- harden auditability for meaningful write paths
|
|
|
|
### Checklist
|
|
|
|
- [ ] note CRUD complete
|
|
- [ ] workspace switching and permissions work
|
|
- [ ] note relationships work
|
|
- [ ] tasks can be extracted and linked
|
|
- [ ] artifact upload/download works
|
|
- [ ] mobile quick capture and retrieval are functional
|
|
- [ ] audit log exists for important write paths
|
|
|
|
### Owner Docs
|
|
|
|
- `docs/roadmaps/02_BACKEND_ROADMAP.md`
|
|
- `docs/roadmaps/03_WEB_ROADMAP.md`
|
|
- `docs/roadmaps/04_MOBILE_ROADMAP.md`
|
|
- `docs/roadmaps/06_PLATFORM_INTEGRATIONS_ROADMAP.md`
|
|
- `docs/roadmaps/07_QA_RELEASE_DOCS_ROADMAP.md`
|
|
|
|
## Phase 3 — Agentic Layer
|
|
|
|
### Goals
|
|
|
|
- ship safe MCP tools
|
|
- add approval and audit workflows
|
|
- support AI-assisted and AI-mediated knowledge flows
|
|
|
|
### Checklist
|
|
|
|
- [ ] core MCP tools work end-to-end
|
|
- [ ] agent write paths support approval where required
|
|
- [ ] audit and review UX is functional
|
|
- [ ] extraction-backed workflows have fallback behavior
|
|
- [ ] operator workflows are documented
|
|
|
|
### Owner Docs
|
|
|
|
- `docs/roadmaps/05_MCP_AGENT_ROADMAP.md`
|
|
- `docs/roadmaps/02_BACKEND_ROADMAP.md`
|
|
- `docs/roadmaps/03_WEB_ROADMAP.md`
|
|
- `docs/roadmaps/07_QA_RELEASE_DOCS_ROADMAP.md`
|
|
|
|
## Phase 4 — Search and Knowledge Acceleration
|
|
|
|
### Goals
|
|
|
|
- make search, retrieval, and context navigation genuinely strong
|
|
- support scalable knowledge workflows for humans and agents
|
|
|
|
### Checklist
|
|
|
|
- [ ] search is fast and useful
|
|
- [ ] linked-note navigation is meaningful
|
|
- [ ] retrieval is scoped and explainable
|
|
- [ ] search telemetry is measurable
|
|
- [ ] web UX supports dense knowledge usage
|
|
|
|
### Owner Docs
|
|
|
|
- `docs/roadmaps/02_BACKEND_ROADMAP.md`
|
|
- `docs/roadmaps/03_WEB_ROADMAP.md`
|
|
- `docs/roadmaps/04_MOBILE_ROADMAP.md`
|
|
- `docs/roadmaps/05_MCP_AGENT_ROADMAP.md`
|
|
- `docs/roadmaps/06_PLATFORM_INTEGRATIONS_ROADMAP.md`
|
|
|
|
## Phase 5 — Production Readiness and Release
|
|
|
|
### Goals
|
|
|
|
- ensure builds, tests, release flows, and runbooks are stable
|
|
- prepare the repo for continued multi-agent execution
|
|
|
|
### Checklist
|
|
|
|
- [ ] build/test/release flows documented
|
|
- [ ] core smoke tests pass on all chosen surfaces
|
|
- [ ] production-readiness checklist passes
|
|
- [ ] deferred list documented
|
|
- [ ] roadmap status updated after implementation
|
|
|
|
### Owner Docs
|
|
|
|
- `docs/roadmaps/07_QA_RELEASE_DOCS_ROADMAP.md`
|
|
- all workstream docs
|
|
|
|
# 5. Parallelization Rules
|
|
|
|
## Safe Parallel Tracks After Phase 0
|
|
|
|
- **Agent 1**
|
|
- backend core modules
|
|
|
|
- **Agent 2**
|
|
- web shell and notes/workspace routes
|
|
|
|
- **Agent 3**
|
|
- mobile shell and quick capture flows
|
|
|
|
- **Agent 4**
|
|
- MCP tool schemas and read-only tools
|
|
|
|
- **Agent 5**
|
|
- platform integrations, telemetry, diagnostics, extraction wiring
|
|
|
|
- **Agent 6**
|
|
- QA docs, smoke plans, release-readiness docs
|
|
|
|
## High-Collision Areas
|
|
|
|
- shared product config files
|
|
- root package/dependency manifests
|
|
- shared route registration
|
|
- top-level navigation/layout files
|
|
- shared token/theme entrypoints
|
|
- shared auth setup
|
|
|
|
## Merge Order
|
|
|
|
- [ ] foundations
|
|
- [ ] backend core modules
|
|
- [ ] web shell and CRUD flows
|
|
- [ ] mobile shell and core flows
|
|
- [ ] MCP core tools
|
|
- [ ] integrations and enrichments
|
|
- [ ] QA hardening and release docs
|
|
|
|
# 6. Suggested First Sprint
|
|
|
|
- [ ] finalize product identity and mobile path
|
|
- [ ] scaffold `web/`, `mobile/`, and `backend/`
|
|
- [x] implement backend `notes` and `workspaces`
|
|
- [x] build web authenticated shell and note list/detail pages
|
|
- [x] build mobile shell and quick capture
|
|
- [x] define MCP tool schemas for list/get/search/create-draft
|
|
- [ ] wire telemetry, diagnostics, and extraction clients
|
|
|
|
# 7. Definition of Done
|
|
|
|
- [ ] web app supports real end-to-end note workflows
|
|
- [ ] mobile app supports meaningful capture/retrieval for MVP
|
|
- [ ] backend modules are tested and production-shaped
|
|
- [ ] MCP tools exist for core note workflows
|
|
- [ ] shared platform integrations are stable
|
|
- [ ] roadmap, PRD, and build/test commands are aligned
|
|
- [ ] release readiness is documented and repeatable
|
|
|
|
# 8. Progress Notes
|
|
|
|
- 2026-03-10 — Web workstream materially advanced:
|
|
- `learning_ai_notes/web/` was scaffolded from scratch
|
|
- authenticated shell and core route surfaces now exist
|
|
- dashboard, workspaces, note detail, search, settings, and error states now mix backend-backed data with a smaller set of still-derived operator/saved-view summaries
|
|
- the web roadmap is now tracking real implementation state instead of draft-only planning
|
|
- 2026-03-10 — Backend workstream materially advanced:
|
|
- `learning_ai_notes/backend/` was scaffolded from scratch
|
|
- Fastify 5 + TypeScript ESM service bootstrap now exists with shared `@bytelyst/*` package wiring
|
|
- `/health` and readiness-capable service bootstrap were added via `@bytelyst/fastify-core`
|
|
- `notes`, `workspaces`, `note-relationships`, `note-tasks`, `note-artifacts`, and `note-agent-actions` modules now exist with schemas, repositories, routes, and starter tests
|
|
- explicit `/notes/search` support now exists in the backend
|
|
- product bootstrap identity currently uses provisional values pending final product naming and manifest alignment
|
|
- 2026-03-10 — Web/backend verification materially advanced:
|
|
- `web/` dependencies are now installed
|
|
- `web` `npm run typecheck` passes
|
|
- `web` `npm run build` passes after fixing the auth `BaseUser` shape and guarding demo session init from server-side `localStorage`
|
|
- `backend/` dependencies are now installed
|
|
- `backend` `npm run typecheck` passes after normalizing Fastify type boundaries for `file:` workspace deps
|
|
- `backend` `npm test` passes after fixing hoisted Vitest mock patterns and stale route registration count assertions, though the current route tests are still mostly registration-focused rather than deep API-behavior coverage
|
|
- 2026-03-10 — Web operator/search density materially advanced:
|
|
- saved views are now represented across dashboard, workspaces, and search
|
|
- search results now expose a denser operational layout with status, owner, and workspace metadata
|
|
- operator workflow summary surfaces now exist on dashboard and reviews
|
|
- workspace cards now expose ownership context for denser navigation
|
|
- `web/` verification passed again after wiring the richer saved-view/search/operator workflow slice (`npm run typecheck`, `npm test`, `npm run build`)
|
|
- 2026-03-10 — MCP design work materially advanced:
|
|
- product-side MCP core tool contracts now exist under `backend/src/mcp/`
|
|
- namespace, role gating, read-only vs mutating classification, workspace scoping, and dry-run/idempotency/correlation expectations are now encoded for the first core tool set
|
|
- 2026-03-10 — MCP execution and registration materially advanced:
|
|
- product-side executable note MCP tools now exist for list/get/search/create-draft
|
|
- the mutating create-draft path now records a `note-agent-actions` audit/proposal document
|
|
- product-side MCP note tools now export through a registration adapter compatible with the shared `mcp-server` tool model
|
|
- backend typecheck passes and backend tests pass with MCP execution coverage included
|
|
- 2026-03-10 — Mobile workstream materially advanced:
|
|
- `learning_ai_notes/mobile/` was scaffolded from scratch
|
|
- Expo + TypeScript root config and Expo Router entrypoints now exist
|
|
- auth shell, tab navigation, home/recent notes, search, quick capture, inbox, and note detail surfaces now exist
|
|
- shared mobile wiring now exists for auth, platform client, offline queue, token-based theme usage, and first-pass Zustand stores
|
|
- mobile currently uses provisional product config values, but quick capture and note retrieval/edit flows are now wired to the product backend for the core note/workspace slice
|
|
- 2026-03-10 — Mobile utility materially advanced:
|
|
- home/search/capture are workspace-aware, and home exposes a retrieval summary surface
|
|
- capture exposes offline queue readiness details for the scaffold
|
|
- note detail supports lightweight backend-backed editing, artifact summary, and first-pass loading polish
|
|
- inbox supports simple approval/reject flows plus a lightweight activity feed
|
|
- 2026-03-10 — Real note/workspace vertical slice materially advanced (`5995b6c`):
|
|
- mobile quick capture now persists notes to the product backend instead of saving local-only drafts
|
|
- mobile note editing continues to flow through backend note update endpoints for persisted notes
|
|
- web dashboard, workspaces, search, and reviews now derive their operator/saved-view side panels from live note/workspace/review data instead of static mock fixtures
|
|
- web note detail now hydrates linked notes from the backend `note-relationships` endpoint with graceful fallback when relationship data is unavailable
|
|
- verification passed for this slice with:
|
|
- `web` `npm run typecheck`
|
|
- `web` `npm test`
|
|
- `mobile` `npm run typecheck`
|
|
- 2026-03-10 — Mobile approval/activity integration materially advanced (`8f14698`):
|
|
- mobile inbox approvals now hydrate from backend `note-agent-actions` instead of seeded local Zustand data
|
|
- mobile approve/reject actions now persist proposal state back through the backend review route
|
|
- mobile activity feed now derives from real backend agent-action history across workspaces
|
|
- verification passed for this slice with:
|
|
- `mobile` `npm run typecheck`
|
|
- 2026-03-10 — Mobile note detail truthfulness improved (`2a93b5b`):
|
|
- the mobile note detail screen now reflects persisted note status, workspace, and last-updated state instead of scaffold-era hardcoded metadata
|
|
- placeholder note-body copy was removed in favor of truthful empty-state messaging for real backend-backed notes
|
|
- verification passed for this slice with:
|
|
- `mobile` `npm run typecheck`
|
|
- 2026-03-10 — Mobile capture workspace selection materially advanced (`8e57799`):
|
|
- the mobile capture screen now exposes live workspace selection instead of relying on hidden active-workspace state
|
|
- backend-backed note creation now reflects the workspace chosen directly from the capture surface
|
|
- verification passed for this slice with:
|
|
- `mobile` `npm run typecheck`
|
|
- 2026-03-10 — Mobile all-workspace view materially advanced (`7d23793`):
|
|
- the mobile home surface now supports returning to an explicit all-workspaces view instead of forcing the first hydrated workspace
|
|
- mobile capture now requires an explicit workspace selection before save when no workspace is active
|
|
- verification passed for this slice with:
|
|
- `mobile` `npm run typecheck`
|
|
- 2026-03-10 — Mobile review actions hardened (`7a80094`):
|
|
- mobile approve/reject actions now disable while the backend update is in flight and expose per-item pending labels
|
|
- the mobile review surface no longer leaves approve/reject open to duplicate taps during async state changes
|
|
- verification passed for this slice with:
|
|
- `mobile` `npm run typecheck`
|
|
- 2026-03-10 — Active surface copy truthfulness improved (`5458090`):
|
|
- active landing, workspace, note-detail, and 404 surfaces now describe the backend-backed product state instead of stale scaffold/placeholder wording
|
|
- mobile note save now awaits the persisted update before exiting edit mode
|
|
- verification passed for this slice with:
|
|
- `web` `npm run typecheck`
|
|
- `mobile` `npm run typecheck`
|
|
- 2026-03-10 — Web review decisions materially advanced (`1bb220b`):
|
|
- the web review surface now approves and rejects proposals through the backend `note-agent-actions` review route
|
|
- proposal comparison cards now expose real approve/reject actions instead of read-only before/after scaffolding
|
|
- the approval queue and timeline now update in-session after a review decision is applied
|
|
- verification passed for this slice with:
|
|
- `web` `npm run typecheck`
|
|
- `web` `npm test`
|
|
- 2026-03-10 — Web note editing materially advanced (`cdc03e3`):
|
|
- the web note detail surface now saves title/body edits through the backend `PATCH /notes/:id` route
|
|
- the note detail page now refreshes the live note state after save instead of leaving edits local-only in the form
|
|
- the editor now exposes an explicit save action and saving state instead of passive editable fields
|
|
- verification passed for this slice with:
|
|
- `web` `npm run typecheck`
|
|
- `web` `npm test`
|
|
- 2026-03-10 — Web artifact creation materially advanced (`ef82747`):
|
|
- the web note detail surface now creates artifact records through the backend `note-artifacts` route
|
|
- artifact creation is no longer display-only; users can add artifact metadata directly from the note detail surface
|
|
- newly created artifacts refresh into the live note detail state after creation
|
|
- verification passed for this slice with:
|
|
- `web` `npm run typecheck`
|
|
- `web` `npm test`
|
|
- 2026-03-10 — Web task creation materially advanced (`c99390e`):
|
|
- the web note detail surface now creates manual note tasks through the backend `note-tasks` route
|
|
- task review is no longer labeled as mock extraction; the task panel now supports backend-backed task creation
|
|
- newly created tasks refresh into the live note detail state after creation
|
|
- verification passed for this slice with:
|
|
- `web` `npm run typecheck`
|
|
- `web` `npm test`
|
|
- 2026-03-10 — Web search integration materially advanced (`4748ed3`):
|
|
- the web search page now queries the backend note search path instead of filtering a preloaded full note list client-side
|
|
- the search surface now reflects backend lexical matching for title/body search while preserving saved search summaries
|
|
- verification passed for this slice with:
|
|
- `web` `npm run typecheck`
|
|
- `web` `npm test`
|
|
- 2026-03-10 — Workspace filtering materially advanced (`ab15950`):
|
|
- the workspaces page filter input now actively filters workspace cards by workspace fields and note content instead of rendering as passive UI
|
|
- verification passed for this slice with:
|
|
- `web` `npm run typecheck`
|
|
- `web` `npm test`
|
|
- 2026-03-10 — Dashboard entrypoints materially advanced (`9f2670c`):
|
|
- recent note activity cards on the dashboard now link directly into the backend-backed note detail surface instead of rendering as read-only summary cards
|
|
- verification passed for this slice with:
|
|
- `web` `npm run typecheck`
|
|
- `web` `npm test`
|
|
- 2026-03-10 — Dashboard saved views materially advanced (`99484a5`):
|
|
- dashboard saved-view cards now navigate into real destinations instead of rendering as passive summary cards
|
|
- the search surface now accepts seeded `q` query params so dashboard shortcuts can open directly into backend-backed filtered results
|
|
- verification passed for this slice with:
|
|
- `web` `npm run typecheck`
|
|
- `web` `npm test`
|
|
- 2026-03-10 — Sidebar navigation cleanup materially advanced (`4376519`):
|
|
- the web sidebar no longer points primary navigation at a single hardcoded note record
|
|
- verification passed for this slice with:
|
|
- `web` `npm run typecheck`
|
|
- `web` `npm test`
|
|
- 2026-03-10 — Review queue selection materially advanced (`5ce9401`):
|
|
- the web review surface now lets you choose which queued proposal is featured for review instead of forcing the first queue entry
|
|
- verification passed for this slice with:
|
|
- `web` `npm run typecheck`
|
|
- `web` `npm test`
|
|
- 2026-03-10 — Dashboard workflow entrypoints materially advanced (`6222fda`):
|
|
- dashboard operator workflow cards now route into the corresponding operational surfaces instead of rendering as passive status summaries
|
|
- verification passed for this slice with:
|
|
- `web` `npm run typecheck`
|
|
- `web` `npm test`
|
|
- 2026-03-10 — Mobile verification materially advanced:
|
|
- mobile dependencies now install successfully with corrected sibling `@bytelyst/*` package paths
|
|
- `npm run typecheck`, `npm run lint`, and `npm test` now pass in `learning_ai_notes/mobile/`
|
|
- token-backed placeholder and border colors replaced the remaining raw hardcoded mobile color fallbacks
|
|
|
|
# 9. Current Known Blockers / Deferrals
|
|
|
|
- **Blocker**
|
|
- Product identity and backend contract details are still not finalized in the planning docs, so the web app currently uses provisional config values and still derives some operator/saved-view summaries client-side.
|
|
- **Blocker**
|
|
- `@bytelyst/react-native-platform-sdk` is part of the intended mobile architecture, but the current workspace package does not appear ready for direct runtime consumption in this app yet.
|
|
- **Deferred**
|
|
- Complete real end-to-end CRUD wiring across every web/mobile surface
|
|
- Blob-backed artifacts and upload/download flows
|
|
- Fully integrated approval/review/audit UX across every surface
|
|
- Persisted saved views, keyboard shortcut expansion, and deeper performance hardening
|