From df6b19834d3c18ece4e3d66076b9fc3b029b7e21 Mon Sep 17 00:00:00 2001 From: Jake Date: Fri, 24 Apr 2026 11:43:48 +0100 Subject: [PATCH] docs(roadmap): feature-complete plan for v0.1, 10 phases from visual-countdown through Corbie rename + release --- ...6-04-23-corbie-feature-complete-roadmap.md | 267 ++++++++++++++++++ 1 file changed, 267 insertions(+) create mode 100644 docs/roadmap/2026-04-23-corbie-feature-complete-roadmap.md diff --git a/docs/roadmap/2026-04-23-corbie-feature-complete-roadmap.md b/docs/roadmap/2026-04-23-corbie-feature-complete-roadmap.md new file mode 100644 index 0000000..d16bf23 --- /dev/null +++ b/docs/roadmap/2026-04-23-corbie-feature-complete-roadmap.md @@ -0,0 +1,267 @@ +--- +name: Corbie — feature-complete roadmap +description: Build plan from 2026-04-23 baseline to full feature-complete v0.1 release +type: roadmap +tags: [roadmap, planning, corbie, release] +created: 2026/04/23 +status: active +author: Wren (CORBEL's resident agent) on behalf of Jake Sames +--- + +# Corbie — Feature-Complete Roadmap + +> **What Corbie is.** A local-first, cognitive-load-aware dictation + task-capture desktop app. Vulkan-accelerated Whisper / Parakeet speech-to-text, a local LLM (Qwen3 tiers) for transcript cleanup and task extraction, an MCP server for integration with Claude Desktop / Cline / Cursor, and a UI designed around ADHD / executive-dysfunction needs. Tauri 2 + Svelte 5 + Rust. Zero telemetry. +> +> **Formerly known as Kon.** Rebrand in flight; repo names at `jakejars/kon` + `git.corbel.consulting/jake/kon` still carry the Kon name and will rename together with the codebase sweep in the final phase. + +## Baseline — where we are (2026/04/23) + +**Core MVP (from `docs/brief/feature-set.md`):** 9 of 10 complete. + +One gap: **visual time representation** (the spec's "#1 community-requested feature" — shrinking colour disks / progress rings, externalising time passage). The rest — local transcription, auto-populating tasks, WIP limits, history + search, light/dark theming, templates, vocabulary profiles, file upload, open-format markdown export — all shipped. + +**Post-MVP (designed, not yet prioritised):** 1 of 9 complete. + +MicroSteps is shipped; its "just-start" timer button emits an event that currently has no listener anywhere in the codebase. The differentiating ADHD-specific features (Margot nudges, energy-aware sequencing, rituals, if-then intentions, forgiving gamification, TTS, human-in-the-loop feedback) are all documented in the brief but not started. + +**Release-blockers:** 1 — RB-08 macOS power-assertion, pending manual verification on a real Mac (Jake's friend Rachmann has a Mac and can run this offline). + +**Workspace state:** main is clippy-zero-warnings, 245/245 tests passing, fmt clean, svelte-check clean, npm build clean. Three dependabot bumps landed this session plus a clippy cleanup pass and a needless_range_loop refactor. One orphan design-system WIP branch parked on github as archive. + +## Approach + +> **Layer 1 first** (per Jake's standing rule): build the features roughly, in series, through Phase 1 – Phase 8. Do polish passes in Phase 9 and QC + release in Phase 10. **Do not mix make-it-work and make-it-neat passes** — every phase ships end-to-end (event wired, UI rendered, store state committed, tests updated) but does not chase aesthetic polish until Phase 9. + +> **Ordering rationale.** Phase 1 closes the Core MVP gap and unblocks the already-half-wired just-start timer. Phase 2 enables model improvement by collecting human feedback — useful even while later phases are being built. Phases 3–8 build the differentiating ADHD-specific features from highest-utility-per-effort to lowest. Phase 9 is polish debt. Phase 10 is release prep (including Rachmann's RB-08 verification and the Kon → Corbie codebase rename). + +--- + +## Phase 1 — Visual countdown + Just-Start timer + +**Why now.** Closes the one remaining Core MVP gap. Unblocks the dangling `kon:start-timer` emit from MicroSteps. Directly combats time blindness, which the brief names as the single biggest lever for the target audience. + +**Scope.** +- `FocusTimer.svelte` — a progress-ring countdown component. Shrinking colour ring (not digital). Subtle colour shift across the last 15%. Remaining time label inside the ring for users who want the number; small enough that the ring dominates the visual field. +- `focusTimer.svelte.ts` store — single active timer, running / paused / completed state, elapsed / remaining computed, event dispatch on state transitions. +- Mount in `+layout.svelte` so the timer persists across page navigation (dictation → tasks → settings). +- Listener for `window` event `kon:start-timer` with `{ durationSeconds, label }` payload. +- Trigger from MicroSteps row (already exists). Trigger from task-row context button (new). +- Floating position top-right of main content, above everything, not intrusive when idle (hidden until a timer is running). +- On completion: gentle chime + 3-second ring flourish + OS notification via `tauri-plugin-notification`. No modal. No guilt copy. +- Store survives window close/reopen via localStorage. + +**Out of scope for Phase 1.** Rhythmic voice anchoring (part of Margot, Phase 6). Custom-duration picker (fixed 2 / 5 / 10 / 15 min presets for now). Multi-timer UI. + +**Acceptance.** From a MicroStep row, clicking the timer button (a) shows the ring visible somewhere on screen, (b) it counts down, (c) at 0 it fires completion + notification, (d) works across page switches, (e) survives a window close + reopen mid-countdown. + +**Estimated effort.** Half day. + +--- + +## Phase 2 — Human-in-the-loop feedback + +**Why here.** AI output quality is the single biggest determinant of whether Corbie feels useful. Thumbs-up / thumbs-down on AI-generated micro-steps and task extractions costs almost nothing to add and gives us a feedback corpus the moment anyone uses it. Enables later retraining / prompt tuning. + +**Scope.** +- Thumbs-up / thumbs-down buttons on every AI-generated item (micro-step row, extracted task, cleanup paragraph). +- "Edit" path already exists for text; the feedback is additive. +- `feedback` table in SQLite: `item_id`, `item_type`, `rating`, `timestamp`, optional `correction_text`. +- Rust command `record_feedback` + `list_feedback` (for later export). +- No UI surface for viewing feedback yet. Just capture. A future export pass to JSONL feeds prompt-engineering or fine-tuning. + +**Out of scope.** Retraining loop, per-user profile adjustment, any UI to view feedback history. + +**Acceptance.** Thumbs visible on AI-generated items. Clicking records to SQLite. `cargo test` on storage covers migration + insert + list. + +**Estimated effort.** Half day to 1 day. + +--- + +## Phase 3 — Energy-aware task sequencing + +**Why here.** Next-highest-utility post-MVP feature. Replaces the cut-for-OS-reasons temptation-bundling feature. Small surface, clear user-facing outcome. + +**Scope.** +- `energy` column on tasks: nullable enum `High | Medium | BrainDead`. +- Migration + Rust CRUD. +- Tag chip on task rows; tap to cycle / set. +- Sort / filter option on the tasks page: "Match my energy" → AI surfaces tasks matching a user-set current energy, falls back to `Medium` if unset. +- No automatic energy detection. Pure user input. + +**Out of scope.** Time-of-day heuristics, calendar integration, AI-predicted user energy. + +**Acceptance.** User tags a task, sets their current energy via a header control, tasks page filter respects it. + +**Estimated effort.** 1 day. + +--- + +## Phase 4 — Read Page Aloud (TTS) + +**Why here.** Small and self-contained. Engages auditory processing which the brief specifically calls out as a retention lever for the target audience. Uses OS-native TTS (no new dependencies, no model download). Clean single-tap affordance. + +**Scope.** +- Rust command `tts_speak(text: String, rate: f32, voice: Option)` — platform dispatch: + - Linux: `spd-say` (speech-dispatcher is available on most distros; graceful fallback to `espeak` if missing). + - macOS: `say` (built in). + - Windows: PowerShell `System.Speech.Synthesis.SpeechSynthesizer`. +- Small "speaker" icon on any text view (transcript viewer, micro-step list, cleanup result). +- Single-tap play; second tap stops. No pause/resume in v1. +- Settings: voice picker (populated from OS), rate slider (0.5–2.0). + +**Out of scope.** Premium voices. Cloud TTS. Concurrent-speaking queue. SSML. + +**Acceptance.** Tap speaker icon on a transcript → hear it read on Linux + expected-to-work-on macOS+Windows (test matrix in Phase 10). + +**Estimated effort.** Half day. + +--- + +## Phase 5 — Start / shutdown rituals + +**Why here.** Meaningful UX but larger surface. Needs calm copy, gentle flow, and a default-off toggle because rituals can feel parental if not optional. + +**Scope.** +- Morning triage: on first launch after 06:00, show a modal / dedicated page: "yesterday's incomplete tasks" (from SQLite query: `completed = false AND created_at < today`), with checkbox pick-list, and "pick 1–3 for today" constraint that refuses selections > 3. +- Evening shutdown: user-triggerable (not scheduled) review: "what got done today", "open loops to close", "separate work from rest" copy. No automation; ritual as reflection. +- Both off by default in settings. When off, no modal, no pressure. +- Skip-for-today button on morning triage; never shows guilt copy. + +**Out of scope.** Calendar integration, automatic sleep detection, weekly / monthly reviews. + +**Acceptance.** Morning modal shows correct tasks. Selecting > 3 is prevented with a gentle message. Skip works and doesn't re-prompt same day. Evening shutdown opens a reflective page, doesn't block closing the app. + +**Estimated effort.** 1 – 2 days. + +--- + +## Phase 6 — Soft-touch nudging (Margot protocol) + +**Why here.** This is the big differentiator and it's intentionally scheduled late because it depends on the phases before it (it nudges *about* tasks, timers, rituals) and on a careful copy pass to not feel like a push notification. The brief explicitly calls out: reminders must not function as standard push notifications; they must be anticipatory guidance. + +**Scope.** +- Context-aware trigger engine in Rust: watches activity signals (keyboard activity, active window, last-interaction timestamp) and fires `nudge` events when triggers match. +- Trigger set for v1: `inactivity_with_active_timer` (timer running, no UI interaction for 90 s), `pending_morning_triage` (past 10:00 and triage untouched), `micro_step_idle` (micro-step generated, not acted on within 15 min). +- Delivery: OS notification via `tauri-plugin-notification`. Platform sounds: `Glass` on macOS, `message-new-instant` on Linux, `Default` on Windows. Haptic cue on mobile (not yet in scope; desktop first). +- Suppression rules: no nudge if user typed in last 5 s, no nudge during a running timer's first 60 s, hard cap at 3 nudges per hour, instant mute button in settings. +- Rhythmic voice anchoring: piggy-back on Phase 4 TTS. Optional "speak nudges aloud" toggle. Default off. When on, short calm lines ("Time to move on", "Your list is still here"). No branding voice, no personality yet — that's a Phase 9 polish item. + +**Out of scope.** Custom trigger editor (user-facing rule UI is Phase 7). Cross-device delivery. Biometric signals (HRV, fidget detection, etc.). Any Margot-as-character visual. + +**Acceptance.** Nudges fire on each trigger in a dogfood walkthrough. Suppression rules observed. Mute button kills everything immediately. + +**Estimated effort.** 1 – 2 days. + +--- + +## Phase 7 — Implementation intentions (if-then automation) + +**Why here.** Leans on Phase 6's trigger engine. The user-facing rule editor is its own thing, but the execution path is the nudge pipeline with user-defined conditions. + +**Scope.** +- Rule editor UI: minimal. `if [when-condition], then [action]`. +- When-conditions for v1: `time of day = HH:MM`, `after a task completes`, `morning triage finishes`. +- Actions for v1: `surface task X`, `start a 5-min timer`, `speak a line aloud`. +- Rules stored in SQLite. On/off per rule. Global mute respected. +- No location triggers (desktop app, no geolocation). No app-running detection in v1 (fragile cross-platform; revisit in v0.2). + +**Out of scope.** Calendar triggers, cross-app automation, macro-style action chains, shared/community rules. + +**Acceptance.** User can write "at 09:00, speak 'time to plan the day' and surface inbox", save it, and have it fire next morning at 09:00. Delete works. + +**Estimated effort.** 1 day. + +--- + +## Phase 8 — Forgiving gamification + +**Why here.** Last feature phase because it's the lowest-risk and the furthest from make-or-break. Neatly rounds out the spec list. + +**Scope.** +- Completion count per day (non-punitive: no streaks, no chain-breaking). "You've completed 4 tasks today. Three in the afternoon. Want to call it?" +- Grace days: the badge logic ignores up-to-3 consecutive days of no activity without reset. +- Visual: soft-edged numeric badges on the tasks header, no leaderboards, no social comparison. +- Zero loss language. Never "you lost your streak". Framing is always "look what you did". + +**Out of scope.** Leaderboards. Shared challenges. Streak repair purchases. XP systems. + +**Acceptance.** Complete 3 tasks → header shows "3 today". Open the app after 4 days off → no negative framing, header reads today's count only. + +**Estimated effort.** Half day to 1 day. + +--- + +## Phase 9 — Polish debt + +> **All Phase 9 work is paused until Phase 1 – Phase 8 are closed.** Per Jake's rule: features first, polish second. + +**Contents.** +- File-system `.md` save dialog (replace clipboard-only export). Rust `write_text_file` command; platform dialog via `tauri-plugin-dialog`. +- Bulk select + bulk export in History. +- LLM-powered content tags (`topic:*`, `intent:*`). Slot into the existing `kon-llm` stub. +- Settings UX overhaul: bundle high-traffic settings into a "Start here" group; hide advanced behind a disclosure. +- Visual polish pass on all Phase 1 – Phase 8 surfaces: spacing, typography, motion curves, colour, dark-mode parity. +- Accessibility pass: keyboard navigation, screen reader labels, focus order, colour contrast audit against WCAG AA. + +**Estimated effort.** 1 – 2 days. + +--- + +## Phase 10 — QC + rename + release + +**Prerequisite:** Phase 1 – Phase 9 complete. + +**QC block.** +- Full dogfood walkthrough: record a real brain-dump → clean transcript → task extraction → micro-step one task → run a focus timer → tag energy → complete → check evening shutdown. +- RB-08 macOS power-assertion verification: **Rachmann runs this offline** on his Mac. He runs `pmset -g assertions` while a live session is active; expected: entry for `PreventSystemSleep` attributed to Corbie's bundle id. Once confirmed, mark RB-08 closed and delete `docs/issues/power-assertion-macos-objc2.md` or move to resolved. +- Cross-platform build matrix (CI already runs): Linux / macOS / Windows, ensure all three are green. +- Accessibility regression check: keyboard-only traversal of each new surface. +- Freshly-clean install test on a spare user account: no stray data leaks from dev. + +**Kon → Corbie codebase rename sweep.** Runs after QC once Jake has renamed the two repos: +- `package.json` name `kon@0.1.0` → `corbie@0.1.0`. +- Cargo crate names: `kon`, `kon-audio`, `kon-storage`, `kon-transcription`, `kon-llm`, `kon-ai-formatting`, `kon-core`, `kon-cloud-providers`, `kon-hotkey`, `kon-mcp` → `corbie-*`. Mass-rename via `Cargo.toml` + `use`-path sweep. +- Binary + product names: `src-tauri/tauri.conf.json`, bundle identifier, `.desktop` file, Windows product name, macOS bundle name. +- Install paths: `~/.local/share/kon/` → `~/.local/share/corbie/`. **Migration shim required**: first-run check for old dir, move contents, write a sentinel. Document in the release notes. +- Database filename: `kon.db` → `corbie.db`. Handled by the same migration shim. +- Window titles, tray tooltip, About-dialog text, README body, docs/brief/ references where they refer to the product (leave historical brief content talking about "Kon" as-is — it's a historical document). +- Event names: `kon:start-timer` → `corbie:start-timer` and similar. Kept `kon:` through Phase 1 – Phase 9 so any dogfood doesn't need to re-learn them mid-cycle. +- Logs, error messages, user-facing copy. +- Remotes: `ssh://git.corbel.consulting:2222/jake/kon.git` + `github.com:jakejars/kon.git` → `…/corbie.git` on both, after Jake has clicked rename in the web UIs. Update `git remote set-url` locally. + +**Release.** +- Bump `Cargo.toml` and `package.json` to `0.1.0`. Tag `v0.1.0` on the commit. +- Write `CHANGELOG.md` (seed it with everything from this roadmap's phases). +- Write release notes in plain language — what it does, who it's for, the data-migration note. +- Push tag to both remotes. GitHub Actions release workflow (already in place for cross-platform CI) should auto-build artefacts for Linux / macOS / Windows. + +**Estimated effort.** 1 day (QC + rename + release ceremony), plus Rachmann's slot on his Mac (parallel, not blocking). + +--- + +## Totals + +- Phase 1 – 8 feature build: **6.5 – 9.5 days** of focused work +- Phase 9 polish: **1 – 2 days** +- Phase 10 QC + rename + release: **1 day + Rachmann's Mac session** + +**Total to v0.1.0 feature-complete release:** **~9 – 13 days of focused work**, depending on how much polish time Jake wants in Phase 9. + +## Explicit non-goals + +- Mobile apps. Corbie is desktop-first; a mobile companion is post-v0.1. +- Cloud sync. Local-first is the floor, not a feature. Sync is out of scope through v0.1. +- Premium voices, paid tiers, subscription. Licensing + monetisation is a separate track tracked in memory `project_marketplace_creem`. +- AI body doubling (low-fi focus rooms) — validated but parked to post-v0.1. +- Temptation bundling — cut (OS-integration impossible cross-platform; replaced by Phase 3 energy-aware sequencing). + +## Anchors + +- Spec: [docs/brief/feature-set.md](docs/brief/feature-set.md) + [docs/brief/design-principles.md](docs/brief/design-principles.md) +- Current baseline: this session's HANDOVER.md +- Rebrand memory: `~/.claude/projects/-home-jake-Documents-CORBEL-Main/memory/project_corbie_rebrand.md` +- Release-blocker index: [docs/issues/README.md](docs/issues/README.md) + +--- + +*This roadmap is a living document. Update it at the end of each phase with actuals vs estimates and any scope revisions.*