roadmap phases

Roadmap — phases

Status: proposal, needs review. The phase numbering from the earlier planning was not recorded in this repo. The only fixed points I found are the Phase 2 pace checkpoint at the end of October 2026 and the launch window below (both from CLAUDE.md). The phases themselves are a proposal built from the decisions made so far; confirm or reshape them.

Constraints

• About 10–20 hours a week, alongside full-time work.
• Launch target: as early as late December 2026 (the January resolution surge), or realistically around March 2027 at this pace.
• iOS, iPadOS and macOS together in v1. A native Android app (Kotlin, not Flutter) is a later, separate effort after iOS traction.
• The paid Apple Developer Program ($99/year) is only needed at TestFlight-with-others, production CloudKit and App Store submission time.

Phase 1 — Docs and flows first (done)

Schema, journeys and the rules engine are specified; the earlier planning was reconciled into the repo; the design project was reviewed and its decisions folded in; the schema is a freeze candidate (Schema overview). All eleven journey walkthroughs are done: 89 gaps found, decided and applied, tested against the schema, which needed no further fields after the freeze work.

Phase 2 — Foundations (current; pace checkpoint end of October 2026)

• Wire ThreadsKit 1.1.0 or later into Jamaal.xcodeproj. Done.
• Add a build-and-test workflow (ci.yml). Done (JamaalCore tests and the app's unit tests on the xcode-27 runner).
• Day boundary first Done: CalendarDate (floating calendar dates) and DayBoundary (logical date, catch-up days, Night Planning's target day) are in JamaalCore, tests first.
• ThreadsKit 2.0.0 with the palette contract, the category colours, space, elevation, motion and the bundled fonts, then bump the app's dependency. Done.
• Implement the 14 models in JamaalCore with a versioned schema, tests first. Done: the 14 @Model classes, typed raw values with the unknown-value rule, VersionedSchema V1 with a migration plan, and a container factory, with Swift Testing coverage (defaults, relationships, delete rules, CloudKit constraints). Not yet verified against a real CloudKit container (needs the paid programme).
• First-launch seeding and the CloudKit dedup rules Done (Seeding, Dedup in JamaalCore/RulesEngine, idempotent, with mutation-checked tests).
• Capacity and load calculations (budgets, load state, weekday defaults) and the day rollover step Done (CapacityLoad, Rollover); free time, named gaps, overflow, suggested capacity and the fit flags are in too (FreeTime); wiring them into the rollover's DayPlan and the habit minutes come with the habit and Anchor slices.
• Habit rules: pauses, due-ness, density states, the read signal, weekly progress, today's windows and the shared engagement definition Done (HabitRules, HabitPauses, Engagement).
• Anchor rules, first slice: config decoding, scheduled generation (preview and sync), exceptions, window states, attendance logging Done (AnchorConfig, AnchorGenerator, AnchorAttendance). afterLast and the prayer windows (adhan-swift) are in too, which completes Anchor generation in JamaalCore.
• Task rules, first slice: priorities and ordering, importance rules, quick dates, deferral, Today's task list Done (TaskPriority, TaskRules, QuickDates, TaskDeferral, TodayTasks). Repeating tasks and complete / un-complete / drop are in too (TaskRepeat, TaskActions).
• Focus sessions: timer state machine, finish and undo, settle, closing with the task, timed-habit minutes, the rollover carry, the pick-up row, the approaching-Anchor line Done (FocusSessions, HabitSessions). Remaining engine modules: Night Planning orchestration, wellbeing, the notification planner.
• Night Planning, part 1: session lifecycle, Build, Load, Close Done (NightPlanning). Part 2 (the Review read model and Carry forward with undo) is in too. Wellbeing is complete (the score, gathering data, sparkline and trend; the four patterns, their actions and the inline card), and so is the notification planner with the access state and the trial. All eight rules-engine modules are now built in JamaalCore; what remains is the app layer: views, StoreKit, the system's notification and location APIs, and CloudKit sync.
• App shell and the engine tick Done: the adaptable TabView (tab bar on a phone, sidebar on iPad and Mac, Anchors its own sidebar item and a segment of Habits on compact width) with placeholder screens built from ThreadsKit tokens; the model container (CloudKit off until the paid programme); the tick on launch and when the app becomes active. Next: the first real screens (Today), from the Design v4 frames.
• Today, first slice Done: header and headline, the capacity meter and slider, the Tasks section (tick and untick) and Also today. Still to come on Today, each its own change: Anchors, Habits, banners, the toolbar (filter, Plan tomorrow, Add), the wellbeing strip, the companion card.
• Today: Anchors Done: plain and grouped rows, window bars, the tick, and the choices (Not today, Someone else did it, Mark as done after all, Undo). Still to come on Today: Habits, banners, the toolbar (filter, Plan tomorrow, Add), the wellbeing strip, the companion card.
• Today: Habits Done: group pills (opening in place for now), rows by kind (tick, stepper, minutes so far, Slip and Held today) and habit logging. Still to come on Today: Begin on timed habits (with the focus chip), banners, the toolbar (filter, Plan tomorrow, Add), the wellbeing strip, the companion card.
• Add a task Done: the add sheet (title, effort chips with the Other stepper, importance, quick dates and a date picker, category, repeat, a button that says what it will do) and Day is full · offer tomorrow; a glass + on Today. Still to come on Today: the Anchor side of the add switch, notes, the filter and Plan tomorrow in the toolbar, banners, the wellbeing strip, the companion card, Begin with the focus chip, the task detail sheet.
• Task detail and Defer Done: tapping a task opens its detail (category, title, the note's tappable checklist, Effort / Matters / Due / History, Mark done, Defer, Drop, Stop repeating); Defer moves to tomorrow the first two times and from the third opens the picker with the companion line, the easing note and optional reason chips. Still to come: Begin and the focus session screens (also Begin on timed habits), Edit note (TK-04), the Anchor side of the add switch, the filter and Plan tomorrow, banners, the wellbeing strip, the companion card.
• Focus sessions in the app Done: Begin (task detail; timed habit rows), the ambient chip above the tab bar on every tab (with the one Anchor line), the focus screen (timer against the estimate, the note's checklist, Pause / Resume, Finish), the finish sheet, the five-second Undo after Done, and the settle sheet for a second Begin. Still to come: pick-it-back-up after a rollover (TD-06), add minutes by hand (HB-09), Edit note (TK-04), the Anchor side of the add switch, the filter and Plan tomorrow, banners, the wellbeing strip, the companion card.
• Today: toolbar, filter, carried-over row, states Done: a glass capsule with the category filter and Add, the removable filter chip, the carried-over row, and the blank and all-done days. Still to come on Today: Plan tomorrow (with Night Planning), banners (TD-05: need StoreKit and notification permission), the morning card (TD-07), the wellbeing strip, the companion card, the Anchor side of the add switch, Edit note, add minutes by hand.
• Night Planning (compact) Done: the five steps (Review, Carry, Build, Load, Close), Skip tonight and Back/close at every step, resumable; the moon in the Today toolbar and Plan tomorrow once the day is done. Still to come: the one-off Anchor on Build, the normal-day suggestion line on Load, the morning card and shortened flow (TD-07), the wide canvas (NP-07), and the evening reminder entry.
• Night Planning entry points Done: the morning card (TD-07) with the shortened flow, the "Wednesday, unplanned." headline, and the quiet evening row. Still to come for Night Planning: the one-off Anchor on Build, the normal-day suggestion line on Load, the wide canvas (NP-07), and the evening and morning notifications as entry points (they need the notification permission and scheduling, a slice of their own).
• Habits tab: overview, detail, pause, archive Done: groups with a 14-day aggregate, ungrouped habits with a one-line status, Paused · reason · resumes date, Archived with Restore; the detail with today's control, the six-week density grid (the last 14 days tappable to correct), a plain read, schedule, reminder, Pause / Resume / Archive. Still to come for habits: add and edit a habit (HB-03/04) and groups (HB-05), minutes by hand (HB-09), the avoid detail pass; then the Anchors segment (AN-01…11).
• Add and edit a habit Done: the + on the Habits tab (What kind of habit? with presets) and the form: name, target, times of day (up to four, with hours and a reminder), schedule (every day, weekdays, chosen days, N a week), group (including a new one), note; the same form edits a habit with the kind fixed. Still to come for habits: minutes by hand (HB-09) and the avoid detail pass (HB-08); then the Anchors segment (AN-01…11).
• Anchors tab: rules, detail, scheduled form, exceptions, one-offs Done: the rules list (schedule, next Anchor, paused, needs attention, Archived with Restore), a rule's detail (exceptions, coming up, Edit / Pause / Archive), the type chooser and the scheduled form, and the Task | Anchor switch on the Add sheet. Still to come for Anchors: the prayer times form and location (AN-04, AN-11), the Anchor side on Night Planning's Build step, and reminders scheduling.
• Prayer times rule: form, location and city search Done: Prayer times in the type chooser, the form (location, method with its regional suggestion, Asr, prayers, Isha ends, Jumu'ah, time each takes, reminders, Advanced adjustments and high-latitude rule), Where are you praying? and city search, edit and breaks for a prayer rule, and the stored place following a travelling device. Still to come: reminders scheduling and the notification banners.
• Settings: home, Capacity and day, Categories Done: the Settings home (only the rows that exist), Capacity and day (normal day, usual level by weekday, working day, the rollover under Advanced, the planning note, the quiet normal-day suggestion) and Categories (rename, five colours, drag or Move up/down, archive and restore, at most eight). Still to come for Settings: Notifications and times (ST-03), Appearance, Subscription, iCloud, and Privacy and your data.
• Notifications: scheduling, permission states, Notifications and times, Today banner, tap routing Done: the reminder centre plans and applies the schedule (diffed, re-planned on foreground and after saves), the three permission states, this device's switch, Notifications and times (warning card, switch, evening planning and morning times), the Today banner, a quiet line on configured reminders, and routing a tap to Night Planning or Today. Still to come: the trial reminders' real wiring (needs StoreKit), onboarding's permission step (OB-05), the Anchor reminders while read-only decision, and background refresh.
• Wellbeing tab and the Today strip Done: gathering data (seven squares), the reading (score, trend in words, sparkline, plain read, rows) and the one calm card with its change and Not now, on the tab and once a day on Today; the slim strip on Today opens the tab. Still to come: a Wellbeing nudges on/off preference, and WB-04 (v1.1).
• Onboarding (OB-01 … OB-09) Done: the nine screens over the shell until completed, the saves in the engine (normal day, times and permission in context, first task, first habit, first Anchor), and the day-zero card on Today. Still to come: the real iCloud wait and Welcome back for a second device (needs CloudKit), and OB-01's frame (not drawn).
• Trial, paywall and Subscription (SB-01, ST-05, TD-05) Done: the access state wired through a StoreKit 2 storefront (plans, entitlement with an offline fallback, restore, transaction stream), the Subscription screen and its Settings row, the paywall (once a day, never during focus), the Today banners (read-only, trial ending) and the trial reminders in the planner. Locking every editing action behind the calm sheet Done (read-only mode now holds). Still to come: App Store Connect products and a real purchase (paid programme), and Delete my data.
• Privacy and your data, Appearance, recovery (ST-08, ST-07, SY-05) Done: Export my data (JSON), Delete my data behind two confirmations, the theme and the suggestion-cards switch, and a recovery screen for a store that won't open. Still to come: the iCloud copy's deletion and the iCloud status screen (need CloudKit).
• Edit note (TK-04) Done: the note editor with its glass toolbar (checklist, bold, italic, link, code), Return keeping a checklist going, and Add a note / Edit note on the task detail. Still to come from the gaps list: minutes by hand (HB-09), the avoid-habit detail pass (HB-08), a one-off Anchor from Night Planning's Build step, and the normal-day line on the Load step.
• Minutes by hand (HB-09) Done: an Add minutes sheet from a timed habit's row, its detail and a day in its grid, with entries that can be taken back out. Still to come from the gaps list: the avoid-habit detail pass (HB-08), a one-off Anchor from Night Planning's Build step, and the normal-day line on the Load step.
• Avoid habits (HB-08, Option A) Done: the three moments on the Today row (None yet · up to 1, 1 of 1 · still within, Held today · 1 slip with Undo), solid Slip and Held today pills, a held day's title in ink, and the detail's read in the frame's words. Option B is dropped.
• Night Planning's last gaps (NP-03, NP-04) Done: a one-off Anchor from Build (Add a task or Anchor) and the normal-day line on Load, offered at most once. Still to come from the gaps list: the avoid-habit detail pass (HB-08). The wide canvas (NP-07) is part of the iPad, Mac and Duo layouts.
• iPad: Today with a task detail panel Done (first regular-width slice): the list with the detail beside it, selection marked, a placeholder when none, tested on an iPad simulator. Pinned toolbar and the panel's ⋯ are done (#179); the sidebar's wordmark, Today count, Categories and Plan tomorrow are done (#182); Add as a panel is done (#186); the Habits tab header (pill switch and Add on one row) is done (#188); Night Planning's wide canvas with its step rail is done (#190), with the wide step bodies (Carry's inline choices, Build's day bar and two columns) (#192); Habits and Anchors as list + detail panes are done (#194), and Settings as the same (#196); the app builds and runs as a native Mac app (#198), with Night Planning and the other full-screen flows at a proper size (#200), the Mac sidebar, menu commands and ⌘, Settings (#202), and the Mac look: the sidebar's focus chip, the in-focus and hover rows, the title-bar title and right-click menus (#210), and a Mac UI test target (#212; keyboard list navigation, which it can now verify, and the data export come next); Wellbeing has no list to pick from and keeps its single pane. Still to come for the wide layouts: Add as a panel, Night Planning's one canvas with a step rail (NP-07), Habits/Wellbeing/Settings content panes, macOS (a destination, menu commands, the Settings scene) and the Duo outer-display checks.
• Implement the deterministic rules-engine modules in order of dependency, each with Swift Testing coverage: task scheduling, habit density, Anchor generation, capacity and load, focus sessions, then Night Planning orchestration, wellbeing and notification logic.
• Checkpoint: is the pace holding at 10–20 hours a week, and are the models and the first engine modules done or clearly on track? If not, the launch estimate moves toward March 2027 or scope moves to v1.1.

Phase 3 — The core loop

• Today, add task, deferral, importance and categories, the capacity meter, and repeating tasks.
• The focus timer: ambient chip and focus screen (Live Activity waits for v1.1).
• Habits: the four kinds, the density grid and pauses.
• Anchors: rules, one-offs, prayer times (using adhan-swift), exceptions and window states.
• Enrol in the paid Apple Developer Program and create the CloudKit container before any real-device sync testing (required for iCloud and push).
• Move the SwiftData store into an App Group container in the same change as the CloudKit container (no user ever migrates; widgets need it): see ADR 0003.
• Real-device iCloud spike (first thing after enrolment): verify what happens to the synced store on sign-out or an account change (G-80), and that two devices converge on the dedup keys.

Phase 4 — The evening ritual

• Night Planning in its five steps, including tomorrow's gaps and Skip tonight.
• Onboarding, with guided first Task, Habit and Anchor.
• Notifications and the in-app fallbacks.

Phase 5 — Ship preparation

• First TestFlight build (target 18 Oct 2026): see TestFlight readiness for what is ready, what waits for the paid programme and what needs your decision.

• Widgets (Next Anchor and Today on iPhone, iPad and Mac, with Lock Screen accessories; frames drawn in batch 8): WidgetSnapshot and the timeline logic are built and tested in JamaalCore (no entitlements needed; #214), and so is the jamaal:// link routing (#216); the extension target and the small Next Anchor widget are built (#231, it reads the shared store once the App Group is on); the Today widget and the Lock Screen accessories are next, then the App Group: see Widgets and the watch.

• iPad, Mac and iPhone Duo layouts; accessibility (Dynamic Type, VoiceOver for the custom components, no colour-only states) (first pass done in #227, see Accessibility; a VoiceOver listening pass on a device is still to do); right-to-left and Arabic-Indic numerals.

• Trial and paywall, with the read-only state.

• Privacy, data export and the App Store material.

• CloudKit production schema deploy — only after the schema freeze is signed off.

• TestFlight with others, then submission.

After v1

v1.1: a companion watchOS app (Today, Anchors, the habit counter, the focus timer, complications; fed by WidgetSnapshot over WatchConnectivity; frames drawn in batch 9), App Intents and interactive widgets, Control Center controls, Live Activity and Dynamic Island for the running session, detected habits (the offer to promote a repeating task), and sharing / referral if a real need shows up. Later: native Android.

Open items that could move things

Decisions still open are listed at the end of App flow: fonts, whether to read calendar events, and the accessibility and localisation plan. (Avoid-habit design is settled as Option A; widgets are in v1.)