Weeks 1 through 4 are with Malcolm and stay as they are. Everything after them is resequenced and rewritten from the thirty annotations, with every button and label in the new steps checked against the app first. Two small app changes ride along: Presence moves up in the Foundation display, and the layer menu says Refine with AI instead of Update.
The problem
The later weeks were written before several surfaces settled, and the annotations show it: the Foundation week asks for one weak layer to be fixed when the reader needs to manage all nine; Blueprints spends a step on source-checking nobody will do while saying nothing about how /cr-entry and background maintenance keep them current; Mira's week covers three of her six cards; Meetings comes after Mira although two of Mira's cards convene meetings; the testing week predates the Documents hub and the Your Turn widget; and the Spark Inbox has a week to itself while six other areas have no mention at all. The shared "the lap continues" line reads as filler on every page it appears on.
Proposed sequence
| Set | File | What it teaches |
|---|---|---|
| Week 1 | week-1-first-lap.html | unchanged |
| Weeks 2–3 | weeks-2-3-same-lap-again.html | unchanged |
| Week 4 | week-4-chronicle.html | unchanged, next link repointed |
| Week 5 | week-5-documents.html | Documents hub, /cr-testing, /cr-review, /cr-flowmap and /cr-digest, Your Turn |
| Weeks 6–7 | weeks-6-7-foundation.html | Foundation, eight steps |
| Week 8 | week-8-blueprints.html | Blueprints, four steps |
| Week 9 | week-9-meetings.html | Expert Meetings, five steps |
| Week 10 | week-10-mira.html | Mira, six steps, one per card |
| Week 11 | week-11-tour.html | The rest of Code Raven, one step per area |
| Week 12 | week-12-personal.html | The Personal project |
Ten pages, twelve weeks. Weeks 2–3 and 6–7 each share one page.
Approach
Every new step rests on a surface found in source
Before this plan was written, each control the annotations ask for was located: the layer context menu and the Refine with AI button, the Export menu's Copy Complete Foundation, the Foundation Context section on notes and tasks, My app has changed and Foundation Check-in, the health banner's four reasons, the Features statuses and Feature History, the Auto-update blueprints interval, Mira's six cards (all live), the five Meeting Lead directives, the Conversation Length settings, the Documents hub's eight segments, and the Your Turn widget's four actions. The 2026-08-26 audit rule holds: nothing gets taught that cannot be clicked.
Two small generator fields instead of hand-built HTML
An optional x field renders a collapsed list after a step's Read block, for the expert roster and the nineteen Rookery seats. An optional v field renders a three-way verdict row per layer for the Foundation week. Both persist like everything else and land in the copied notes. Neither is required; the fallback is prose and the notes box.
Per-week lap lines
The shared "the lap continues" line becomes a one-line note per page saying how that week's feature meets the loop: the Foundation arrives in every session's context, blueprints are named in /cr-entry's recommendations, meetings write into the Chronicle.
Decisions made for you
Documents week goes before Foundation, as week 5
Its material depends on plans and Chronicle records, which exist by week 4, and on nothing the Foundation supplies. Weeks 1 through 5 then cover the working loop and the documents it leaves behind; weeks 6 through 10 cover context and the people who read it. Reversible by swapping two rows in statics.py and two filenames.
Foundation spans two weeks on one page
Eight steps is twice any other week, and weeks 2–3 already set the precedent for a two-week page. One file keeps one storage key and one row in the index.
"Confirm" is taught as a verdict, not a button
No layer-level confirm control exists. The step says a layer that looks good needs nothing done and moves on. Adding a "Mark reviewed" control is out of scope unless you want it.
Presence moves to fourth in the Foundation display order
Display only: the compact widget and the edit tabs. Generation order is untouched because Presence generation may read Features, which is generated later.
The work
Phase 0 — Generator support
3 tasksLands first; every later phase renders through it.- Add an optional
xfield to the step spec, rendered after the Read block as a collapsed<details class="more">list, for the expert roster and the Rookery seats - Add an optional
vfield (verdicts) rendering one row per named item with three pills, Looks good / Mostly right / Mostly wrong, persisted in state and written into the copied notes - Update
_generator/README.mdfor the two new fields and the twelve-week count
Phase 1 — Sequence
5 tasks- Rename and renumber the spec dicts and filenames to the new order (week-5-documents, weeks-6-7-foundation, week-8-blueprints, week-9-meetings, week-10-mira, week-11-tour, week-12-personal) with fresh storage keys
- Point week 4's
nextHrefat week-5-documents.html and rebuild it - Update
statics.pyWEEKS, ROWS, the "eleven weeks" strings and the closing line for twelve weeks - Replace the shared LAP line with a per-week
lapline on every page from week 5 on - Delete the built pages whose filenames no longer exist (
git rmweek-5-foundation, week-6-blueprints, week-7-mira, week-8-testing-and-todos, week-10-spark-inbox, week-11-personal)
Phase 2 — Week 5: Documents & Your Turn
6 tasks- Write step 1: the Documents hub and its segments (Plans, Flowmaps, Reviews, Digests, Guides, Mockups, Testing, Claude)
- Write step 2: generate a test page with /cr-testing and work through it (from old week 8 steps 1 and 3)
- Write step 3: fold results back in with /cr-testing import (old week 8 step 4)
- Write step 4: /cr-review, a directed-feedback artifact reacted to card by card
- Write step 5: /cr-flowmap and /cr-digest, when each earns its place
- Write step 6: the Your Turn widget, where test pages and reviews wait until finished
Phase 3 — Weeks 6–7: Foundation
10 tasksThe longest page in the series.- Rewrite the header: h1, lede and banner say what the Foundation is and that this set is long and important
- Write step 1: generate it
- Write step 2: the four core layers (Mission, Personas, Character, Presence), what to read closely in each, with a verdict per layer
- Write step 3: act on each verdict with Confirm, Refine with AI or Regenerate
- Write step 4: the Features layer (statuses, clusters, Feature History, Open Features Lab)
- Write step 5: the remaining four layers (Visual Design, UI/UX, Code, Cognitive), what to check, then Confirm, Refine or Regenerate
- Write step 6: use the Foundation (Copy Complete Foundation and Export Foundation; Foundation Context on a note or task)
- Write step 7: keep it current (My app has changed, Foundation Check-in, the health banner and its reasons, what changes and what does not)
- Write step 8: Foundation-adjacent artifacts (Position & Strategy, Market Intelligence, Financial Model, Journeys)
- Verify Journeys generation path in source before writing step 8
Phase 4 — Week 8: Blueprints
5 tasks- Rewrite the header: h1 "Blueprints" and a banner written for this week
- Keep step 1 (Scan & Generate) and step 2 (open the one that matters)
- Write step 3: add anything discovery missed, and Add Custom any time as the project grows
- Write step 4: how /cr-entry advises on blueprints, background updates on the Auto-update blueprints interval, and manual refresh from the row menu or /cr-blueprint
- Cut the old step 3 (Check it against the source)
Phase 5 — Week 9: Expert Meetings
5 tasks- Rewrite the header: h1 "Expert Meetings", lede saying experts know the project and bring their own expertise
- Add the expandable expert roster to step 1, grouped by category
- Move the follow-up and @name chip items into step 3 after "Start it and…"
- Write new step 4: the Meeting Lead and its directive buttons (Move Forward, Summarize, Action Items, Assign & Draft, Handoff Check) and the document panel
- Rewrite step 5 (close it out): name the natural-end turn budget as a setting under Agent Settings, Conclude and the Implementation Handoff
Phase 6 — Week 10: Mira
7 tasksOne step per card.- Rewrite the lede: she reads plans, Chronicle, Foundation, open notes and, for drift, the blueprints
- Fold the old steps 1 and 2 into one: open her room and let her open the conversation, with the shortcuts as a tip
- Write a step for Tell me what you'd do next
- Write a step for Put a room together
- Write a step for Run it without me
- Write a step for Show me what's drifted
- Write a step for Pick up where we left off, including shelving
Phase 7 — Week 11: The rest of Code Raven
10 tasksWide and shallow by design.- Write the header and one-step-each structure
- Write step: Spark Inbox (condensed from the old week 10, unlock caveat kept)
- Write step: Ideation Studio
- Write step: Design Studio
- Write step: Launch Studio
- Write step: Mockup Lab
- Write step: Developer Profile
- Write step: small things (Commit on the Overview, the Workbench, the Capture button)
- Write step: Usage tracking
- Verify each studio's entry point and gating in source before writing its step
Phase 8 — Week 12: The Personal project
4 tasks- Rename the header: h1 "The Personal project", lede ending "for everything that does not belong to a code-based project"
- Add /cr-entry to step 4 (send the script to Claude Code)
- Add the expandable list of the nineteen Rookery seats to step 7
- Update the banner, next line and the closing "twelve weeks" text
Phase 9 — App changes
3 tasks- Move Presence to fourth in the Foundation display order (widget and edit tabs) without changing generation order
- Rename the layer context-menu item "Update {Layer}…" to "Refine {Layer} with AI…" so the menu, the edit view and the notes sheet use one word
- Build with xcodebuild and verify the product
Phase 10 — Build and check
2 tasks- Rebuild all pages, run lintpages.py, confirm every page is under the 64 KB scanner budget
- Verify every button and label named in the new steps against source (the 2026-08-26 audit rule)
Phase 11 — Meeting Room follow-up
3 tasksFrom the meeting-rooms checkin of 2026-09-05, after the first build.- Rewrite week 9 for the single Meeting Room: question, Who sits (I choose / Mira chooses), the table, five benches, Consult 1:1 profiles, the Rookery guest bench, and Mira as lead with no toggle
- Tie week 10's Put a room together card to Mira chooses on the room
- Add the one-seat sitting-or-consultation choice and the collapsed development room to week 12 step 7
Manual Testing
3 tasksYours.- Verify both meeting rooms in the relaunched app against week 9 and week 12 before sending them (the checkin's five manual checks are still open)user
- Open start-here and each new page in a browser and read them end to enduser
- Resend week 4 to Malcolm, since its next-week link changeduser
Risks & edge cases
Week 4 is already handed off and its next link changes
Until Malcolm gets the rebuilt copy, the button at the bottom of week 4 points at a file he will never receive under that name.
Design Studio is your active work
The tour step describes it only, from the nav bar and what the entry surface shows. Any detail beyond that gets verified on the day it is written.
Presence display reorder touches two enums that must stay in step
The compact widget iterates FoundationLayer.allCases; the edit tabs use FoundationTab. Changing only one leaves the widget and the tabs in different orders.
"Update" versus "Refine" is inconsistent in the app today
The guide will use Refine with AI throughout, which matches the edit view but not the context menu until Phase 9 lands.
The tour week is wide and shallow
Eight areas at one step each means each step is a pointer, not a walkthrough. That is the brief, and the reflect questions should ask which areas deserve a week of their own.
Two new render paths across ten pages
The x and v fields are small, but each is new code in a build that has been stable.
Out of scope
- A "Mark reviewed" control on Foundation layers.
- Rewriting weeks 1 through 4 beyond the one link.
- Any runtime change to Design Studio, Launch Studio or the studios' gating.
- Regenerating the in-app Living Guide entries to match the new sequence.
Final review
The plan turns thirty scattered annotations into one sequence with a reason for each move, and every step it promises rests on a button or label already found in source. Its weakest point is size: about forty steps of prose written to the house voice, each needing the same verification pass the earlier weeks had. The second weakness is the two generator features, which are convenient but not required; the fallback for both is plain prose and the notes box. If pushed, drop the verdict pickers first and keep the expandable lists.
The sequence is defensible and the surfaces are verified. The number is not higher because Documents-before-Foundation is a judgment call you may reverse, and because the Foundation page at eight steps will be the longest in the series and may read as heavy in practice.