Repository navigation
docs: one claude guide per app and package, roadmap phases i and j - #73
Merged
Merged
Conversation
axelhamil
commented
Oct 29, 2026
axelhamil
commented
Owner
- One CLAUDE.md per app and per package, the root one stays library agnostic
- ROADMAP gains Phase I (resync of the OpenUp foundations) and Phase J (front redesign before the review)
- Every roadmap phase follows the same shape
- Event totals and the list of what is left refreshed
…w one shape The roadmap now lists Phase I (resync on the OpenUp foundations, five ordered lots with their why, scope, dependency and a measurable exit criterion) as the next phase, behind the in-progress October 2026 dependency refresh and ahead of the review pass and the C.1 remainder. Every phase follows one shape (title, status, date, why, scope, references). The shipped table shrinks to one short line per milestone with a link to its as-built record, and the per-phase running event totals are gone: the catalog size is measured from packages/events (85 events, 35 public, 50 internal) instead of copied, which fixes the stale 82 / 35 / 47 and the 54/50/4 left in the privacy dashboard note. Also corrected: the surface map is 74 routes with 55 consumers, the entitlements catalog lives in shared/entitlements.ts, the env schema path, and the D.5 sweep debt that D.6 already closed. Detail that only existed in the roadmap moved to docs/HISTORY.md: the opt-in public API rationale, the rejected Resend Broadcasts and Topics, the bounded and fenced sweep rail, and the Biome and EXPLAIN notes of the toolchain refresh. The better-auth 1.7 move and the rules review pass (PR #70) were shipped but absent from the roadmap and are now listed, the latter with a new HISTORY entry.
README, FEATURES and OVERVIEW still cited 82 events (35 public, 47 internal) and the D.5 debts that D.6 closed. They now state 85 / 35 / 50, measured from packages/events, and list the current remainder: dependency refresh, Phase I, review pass and C.1.
The rules were spread over six CLAUDE.md files split by directory depth, so an agent editing a feature had to find two files for one concern, the root named app and package internals, and several statements had drifted from the code (a "2-file route" pattern retired long ago, a withOrg helper that does not exist, class names of files that were renamed, references to a private global rules file). Each app now has a single guide (api absorbs modules/ and shared/, app absorbs features/ and shared/). Rules that belong to a package moved to a new packages/<x>/CLAUDE.md for ddd-kit, drizzle, access-control, events, i18n and ui; packages without rules of their own (cookie-consent, policies, emails, test, typescript-config) get none, their playbooks stay in the skills. The root keeps only monorepo principles, tooling and release flow, plus a table pointing to each guide; rules 5 to 8 are reworded library-agnostic with the mechanics delegated down. Contradictions were resolved (mutation factory vs hook wrapper, who opens the transaction, port placement for pure transport), duplicated statements merged (shared kernel consumers, null at the port, personal org, capability model), and every cited path was checked against the tree. The unit-of-work and outbox rules were moved verbatim. Pointers in the skills, docs, README and the comments of check scripts and tests now target the new files; no code changed.
The app shell still wears the shadcn defaults it was scaffolded with and carries two measured defects: the top-nav header overflows by 33 px at 390 and 768 px, and the theme provider's inline script is reported by React on every navigation. Phase J rebuilds every screen on one token-only design system in @packages/ui, after Phase I and before the review pass so the review reads the new surface.
…dation # Conflicts: # CLAUDE.md # apps/api/src/shared/CLAUDE.md # docs/HISTORY.md # docs/MODULES.md
|
🎉 This PR is included in version 2.0.0 🎉 The release is available on GitHub release Your semantic-release bot 📦🚀 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.