rome / ios
CLAUDE.md904 starsChanged 4 days agoMITView on GitHub
The native iOS app (SwiftUI, iOS 17). It is an Xcode project, not a pnpm workspace member, so pnpm typecheck and pnpm test:unit never touch it. Screens live in Rome/Features, the API client and wire models in Rome/Networking, sign-in in Rome/Auth, and design tokens in Rome/Design. A WebSocket from URLSessionWebSocketTask sends no Origin, and the server refuses a cookie session on the socket without one. The REST calls still work, so the app looks fine but never receives a live…
In this repository18 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- docs/CLAUDE.mdCLAUDE.md
- rome_apps/CLAUDE.mdCLAUDE.md
- add-oauth-integrationSkill
- babysit-prSkill
- color-auditSkill
- dddSkill
- file-issueSkill
- imports-ofSkill
- loop-northstarSkill
- loop-reconcileSkill
- move-codeSkill
- release-rome-imageSkill
- respond-to-reviewSkill
- secondary-text-auditSkill
- todos-to-github-projectSkill
- ux-semantics-auditSkill
- validate-oauth-integrationSkill
The file
Show its rules and text
We split this CLAUDE.md into the rules it gives an agent
13 rules. About 0 are common, 2 are distinctive, and 11 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
11
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 7
Before building, testing or running the app, read README.md.
- Very specific: line 8
Before designing or changing a screen, read DESIGN.md, the interface principles every screen follows.
- Very specific: line 9
Before changing the transcript, a list, a store or anything that runs while a chat streams, read PERFORMANCE.md, and measure the change …
- Distinctive: line 10
When changing a screen, run the snapshot pass in README.md and look at both the light and dark images.
- Very specific: line 11
When reading a new wire field, add it to Rome/Networking/Models.swift as optional, so an older server keeps decoding.
- Very specific: line 12
When adding text, use romeFont(_:_:) from Rome/Design/Typography.swift, never .font(.system(size:)), so it scales with Dynamic Type.
- Very specific: line 13
When adding a color, add a light and dark pair to Palette in Rome/Design/Theme.swift.
- Very specific: line 14
When you need the Simulator, boot it headless (xcrun simctl boot) and drive and watch it through the Claude app's Simulator panel.
- Very specific: line 15
When building, pass -derivedDataPath under /tmp/rome-*, as the README.md commands do, so a build never lands in …
- Very specific: line 17
When adding text, write it in English, following docs/ui/VOICE.md, and add its Simplified Chinese to Rome/Localizable.xcstrings.
- Distinctive: line 18
When writing user-facing copy, call the main conversation Chat, never Concierge, in zh-Hans too (Chat, never Concierge or 管家).
- Very specific: line 19
When changing Rome/Info.plist, change Config/Info-Debug.plist the same way.
- Very specific: line 32
A stored
approval_cardpart always sayspending: Only GET /approvals/:id knows whether it was answered, so a card shows its buttons …
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
ios/
The native iOS app (SwiftUI, iOS 17). It is an Xcode project, not a pnpm workspace member, so pnpm typecheck and pnpm test:unit never touch it. Screens live in Rome/Features, the API client and wire models in Rome/Networking, sign-in in Rome/Auth, and design tokens in Rome/Design.
Playbook
- Before building, testing or running the app, read
README.md; it covers the simulator, Mac Catalyst, demo data and a local Rome. - Before designing or changing a screen, read
DESIGN.md, the interface principles every screen follows. - Before changing the transcript, a list, a store or anything that runs while a chat streams, read
PERFORMANCE.md, and measure the change withROME_PERF. - When changing a screen, run the snapshot pass in
README.mdand look at both the light and dark images. - When reading a new wire field, add it to
Rome/Networking/Models.swiftas optional, so an older server keeps decoding. - When adding text, use
romeFont(_:_:)fromRome/Design/Typography.swift, never.font(.system(size:)), so it scales with Dynamic Type. - When adding a color, add a light and dark pair to
PaletteinRome/Design/Theme.swift; the values come from the design boards. - When you need the Simulator, boot it headless (
xcrun simctl boot) and drive and watch it through the Claude app's Simulator panel; don't open Simulator.app (open -a Simulator), which pops a window over the user's desktop. - When building, pass
-derivedDataPathunder/tmp/rome-*, as theREADME.mdcommands do, so a build never lands in~/Library/Developer/Xcode/DerivedDataunder a name nobody can trace back. - When removing a worktree or archiving a worker, delete its
/tmp/rome-*build folders and snapshot folders too, and shut down any simulator it booted (xcrun simctl shutdown all). Each build folder holds a few hundred MB. Keep/tmp/rome-devicewhile the phone build is current, because a reinstall reuses it. - When adding text, write it in English, following
docs/ui/VOICE.md, and add its Simplified Chinese toRome/Localizable.xcstrings.LocalizationTestsfails on a key without zh-Hans text. Build once, then runxcrun xcstringstool syncwith the build's.stringsdatafiles to list new keys. - When writing user-facing copy, call the main conversation Chat, never Concierge, in zh-Hans too (Chat, never Concierge or 管家). Code and type names keep Concierge.
- When changing
Rome/Info.plist, changeConfig/Info-Debug.plistthe same way. Debug builds read the second one, which adds plain HTTP to a local Rome; Release must stay HTTPS only. - When reading the instance's API, rely on it staying backward compatible. The app works with any instance at or above
UpdateGate.minimumInstanceVersion. Below it, the update page blocks. Above it, a newer release is only offered, through a banner and a drawer line. Raise the minimum only when the app starts calling an API that a newer release brought, to the firstv1.*tag that has it.
Traps
A WebSocket from URLSessionWebSocketTask sends no Origin, and the server refuses a cookie session on the socket without one. The REST calls still work, so the app looks fine but never receives a live event. APIClient.socketRequest sets Origin to the instance's own origin; keep it.
The server never announces the guardian's own message on chat.session:<id>. A pending bubble waits for a fetch, not an event. TranscriptStore marks it sent when the POST returns and reloads the newest page.
A turn that fails in the middle leaves no reply, only its trace. The instance stores a model error as a reply (an error part) only when the model could not be resolved before the turn ran. A failure after that (a provider limit, a crash) is in the trace message's turnStatus: "error" and terminalError. TranscriptBuilder draws a line from the trace unless a stored error part has the same turn, so a failure never shows twice and never shows nothing.
A task's question or approval in the Chat is drawn from its part's card, never from the task chat. The instance fills card into every task_chat part that shows one, each time it hands the message out, and chat_card_settled replaces it live (TaskAskCard). A part with no card (an older instance) draws as one quiet "no longer available" line; there is no paging fallback. Whether a card waits is read from the card alone: no outcome, not expired, not closed (TaskAskCard.waits); only the task's newest such card takes an answer (TaskAskMode). No task list is read for it. A task card's line says only Working or Needs you, from the chat list (TaskChatsStore).
A stored approval_card part always says pending. Only GET /approvals/:id knows whether it was answered, so a card shows its buttons only after that record arrives.
Pushing a second task chat over the first reuses the same view. Its @State store keeps the first chat. The route destination sets .id(chatId).
A literal reaches the catalog only where Swift types it as LocalizedStringKey or String(localized:). Text("Done") is looked up; Text(flag ? "Running" : tone.label) is a String and shows as written, and so does a literal passed to a String parameter. Give a view's text parameters the type LocalizedStringKey, and wrap literals headed for a String in String(localized:).
A SwiftUI view in a UIHostingConfiguration cell does not inherit the SwiftUI environment around the collection view. The transcript's rows read many environment values (openTaskChat, assetLoader, shareTurns), and they arrive empty in a cell. TranscriptList hands context.environment to every cell. For the same reason a row cannot read a coordinate space named outside the list; the list reports positions itself, as it does for the unread line.
A hosted cell's default self-sizing came out a line short for wrapped text. Rows overlapped the ones below them. TranscriptCell measures its content at the list's width itself.
Message times are whole seconds. Rows written in the same second tie, so sorting by time alone gives a random order that can change on each load. TranscriptStore orders rows the way the server does: by turn, then time, then the order they arrived.
Two onGeometryChange readings of the same type on one view do not both fire. The second never runs. Read both values in one closure.
Mac Catalyst runs the app but cannot capture a system sheet. Snapshot runs draw the Tasks sheet in a stand-in frame; the sheet on a phone is the system one.
The async forms of UNUserNotificationCenterDelegate crash the app when a notification is tapped. Under Swift 6 the generated thunk returns UIKit's completion off the main thread, and UIKit aborts in _performBlockAfterCATransactionCommitSynchronizes. A banner in the foreground still works, so the crash shows only on a tap. AppDelegate implements the completion-handler forms on the main actor.
A simulated push is opened from Notification Center with a swipe to the right, not a tap. On the simulator a tap on the lock-style list only expands the stack. Pull Notification Center down from the top edge, then swipe the notification right.
A screen that waits for the live socket to say it is back stays stale when the socket never comes back. After a return to the foreground the socket may be slow, refused, or a leftover that looks open and delivers nothing; SwiftUI's scene phase may not even report the trip. AppDelegate reads UIKit's lifecycle notifications, ForegroundGate decides (any background trip, or a second inactive), and LiveEventsSocket.resume() asks listeners to refetch right away and rebuilds the socket whether or not it was paused. Stores share one reload per burst of requests (resync()).
The swipe home starts on the transcript and reads as a drag away from the bottom. So does Notification Center pulled down over the app. Rows refetched on return then land below the screen, which looks like a stale chat. TranscriptList goes by whether the bottom was on screen when the app resigned active, and a tapped push always shows the newest rows.
A fling's glide wins over a programmatic scroll. The tap reaches the button and the scroll starts, but the list keeps decelerating the other way, so a tap mid-glide seems to do nothing. A Simulator tap after a slow drag does not show it; a real fling does. TranscriptList stops the deceleration before it scrolls to the bottom or to a quoted message.
A page that stays mounted keeps its animations running. Chat stays in the tree, faded out, under the other sections, and a TimelineView(.animation) draws every frame there for no one. Pass paused: offScreen; see PERFORMANCE.md.
A system switch ignores the Simulator panel's tap. The tap has no duration, and a Toggle waits for a touch that lasts. Use touch_path with two samples at the same point about 120 ms apart; the simulator log (xcrun simctl spawn booted log show) tells whether the app received anything.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

