Two commands exist for one intent, and each already tells the user “you do not need to pick correctly between these” — an admission that the split should never have been surfaced. /cr-entry survives; /cr-checkin is retired, in CodeRaven and in the VentureRaven fork. Crucially this touches only the command surface: the bridge JSON, the importer and task state are never in play.
The problem
A new user meets two commands and has to work out which applies, when the answer is always “it does not matter.” Teaching that costs real cognitive overhead for zero benefit. Worse, the app compounds it — the in-app Living Guide currently calls /cr-checkin “the one command to remember”, while /cr-entry is presented as its sibling.
The word is also wrong. “Entry” reads correctly whether the session advanced a plan or not; “checkin” only reads correctly for one of the two cases it handles.
Approach
Merge the instructions, keep the bridge
When a session advanced plan tasks, the consolidated /cr-entry still writes checkin-schema JSON to .claude/checkins/, exactly as today. CheckinBridge, CheckinBridgeImporter and PlanTaskStore are untouched — the importer neither knows nor cares which command wrote the file. This is the single decision that separates the mechanical work from the risky work.
Rejected: rename the internals too
Renaming CheckinBridge, WorkflowStage.checkedIn, PipelineBottleneck.needsCheckin and the .claude/checkins/ directory would multiply the task several times over, put the data path at risk, and deliver nothing a user can see. “Checkin” stays a valid internal noun for a kind of record.
Retire via the existing mechanism
CommandInstaller.deprecatedFilenames already deletes retired commands on launch, and only when the file carries a CodeRaven stamp. cr-status.md, cr-next.md and cr-summary.md went the same way. No new machinery.
Decisions made for you
Button labels keep saying “Check In”
The workflow banner CTA describes the user’s intent, not the command name. Relabelling it “Record Entry” would make the button vaguer to gain consistency nobody is looking for. Reversible in one line each.
Historical release notes are left alone
Existing FeatureHighlight entries describe what shipped at the time; rewriting them falsifies the record. A new highlight is added for this change instead.
CodeRaven first, VentureRaven after
VR is a fork with no independent users, so it can safely lag. Verifying CR in real use first means a bug found there is fixed once rather than twice.
The work
Phase 1 — Merge the command files (CodeRaven)
8 tasks Must land before Phase 2 — deleting the old file first breaks the surviving command.- Read both
Code Raven/Resources/Commands/cr-entry.md(213 lines) andcr-checkin.md(345 lines) in full before editing anything - Inline cr-checkin's unique instruction steps into cr-entry.md: git-activity analysis (step 4), per-task assessment (step 5), outcome determination (step 7), the "do NOT modify plan markdown checkboxes" rule (step 8), writing checkin JSON to
.claude/checkins/(step 9), and JSON validation (step 10) - Replace cr-entry.md's "read cr-checkin.md and follow it" delegation with a branch inside the merged file: session advanced plan tasks → write checkin-schema JSON to
.claude/checkins/; otherwise → write journal-entry JSON to.claude/entries/ - Carry over both JSON schemas verbatim into the merged file — the checkin schema and the journal-entry schema are different shapes and both must remain fully specified
- Preserve the
note onlyescape hatch, which forces a narrative-only record that never touches task state - Remove the "you do not need to pick correctly between /cr-checkin and /cr-entry" blockquote — there is no longer a choice to reassure anyone about
- Update the merged file's own usage text so it never instructs the user to run
/cr-checkin - Regenerate
~/.claude/commands/cr-entry.mdfrom the bundled source with a recomputed stamp, then verify the stamp reads as pristine
Phase 2 — Retire the command (CodeRaven)
5 tasks Uses the existing deprecated-command mechanism.- Add
"cr-checkin.md"toCommandInstaller.deprecatedFilenames(CommandInstaller.swift:51) - Remove the
BundledCommand(id: "cr-checkin", …)row from the installer registry (CommandInstaller.swift:23) - Delete
Code Raven/Resources/Commands/cr-checkin.md - In
CommandsSettingsView.swift:341, either remove the/cr-checkinentry or mark itisDeprecated: truewithdeprecationMessage: "Use /cr-entry"— match how the other retired commands in that file are presented - Fix the four existing entries in
CommandsSettingsView.swift(lines ~394, 410, 418, 434, 442) whosedeprecationMessagecurrently points users at/cr-checkin
Phase 3 — Repoint app surfaces (CodeRaven)
11 tasks The bulk of the work. 116 references across 40 files.WorkflowStatusBanner.swift— repoint the fourBannerCTA(… action: .command("/cr-checkin"))calls (lines ~481, 483, 485, 489) to/cr-entry; keep the "Check In" button labels, which describe the user's intent rather than the command nameWorkflowPipeline.swift— update the recommended-command strings (lines ~144–147, 156–159, 195, 197, 390) and the three bottleneck description strings (~129, 131, 133)SessionIdentityBarManager.swift— update the recommended command (~767, 771, 1026, 1033) and its doc comments explaining that the command routes itselfSessionIdleMonitor.swift— update every suggested command (~284, 323, 353, 358, 367, 398, 402, 410, 417, 428, 493, 500), including the priority-ranking switch that scores"/cr-checkin"LivingGuideContent.swift— rewrite the in-app guide: line ~120 currently reads "/cr-checkin— The one command to remember", which must become/cr-entry; also lines ~122, 130, 153, 159MiraWhisperCard.swift/MiraPanelHost.swift— repoint the whisper command buttons (~53, 67, 218) andWorkflowTransitionTrigger.swift:118, whose whisper text names the commandPlanSnapshotDetailView.swift— update the status hints (~2011–2018) and theCommandLauncher.launchCommand("/cr-checkin", …)call at ~2115PlanWorkflowGuide.swift:47,WorkflowGroupedPipeline.swift:153,WorkflowPipelineAssembler.swiftcomments- Sweep the remaining user-facing copy:
ChronicleWidget.swift,ChronicleView.swift,RecentChronicleSection.swift,JourneyRailView.swift,LinkExistingSummarySheet.swift,SessionEditSheet.swift,WorkflowPipelineWidget.swift,MiraBehaviorSpecContent.swift,ChronicleRecordEditSheet.swift,LinkToPlanSheet.swift - Leave existing
FeatureHighlight.swiftentries alone — they are historical release notes describing what shipped at the time, and rewriting history there is wrong. Add a new highlight for this consolidation instead, following the What's New release checklist - Verify no
/cr-checkinstring remains outsideFeatureHighlight.swift:grep -rn "cr-checkin" "Code Raven/" --include="*.swift"
Phase 4 — Mirror everything in VentureRaven
4 tasks VentureRaven has diverged — grep before editing, do not assume file parity.- Repeat Phase 1 against
VentureRaven/Resources/Commands/vr-entry.mdandvr-checkin.md, regenerating~/.claude/commands/vr-entry.mdwith a recomputed VentureRaven stamp - Repeat Phase 2 against VentureRaven's
CommandInstallerdeprecated list, bundled registry and commands settings view - Repeat Phase 3 across VentureRaven's 37 affected files — grep first, since VR has diverged and does not have
WorkflowStatusBanner.swift - Verify no
/vr-checkinstring remains outside VentureRaven'sFeatureHighlightequivalent
Phase 5 — Build and verify
3 tasks Both repos must build.- Build CodeRaven:
xcodebuild -scheme "Code Raven" -destination 'platform=macOS' build - Build VentureRaven with its own scheme
- Confirm both bundled command sets and
~/.claude/commands/agree, and that every regenerated stamp reads as pristine
Manual Testing
8 tasks Yours to run — none of this is verifiable from a build.- Launch CodeRaven and confirm
~/.claude/commands/cr-checkin.mdis deleted on launch, whilecr-entry.mdsurvives with a valid stampyou - Run
/cr-entryin a session that advanced tasks on a plan — confirm a checkin-schema file lands in.claude/checkins/and task progress updates in the appyou - Run
/cr-entryin a session with no plan — confirm a journal entry lands in.claude/entries/and appears in Chronicleyou - Run
/cr-entry note onlyin a plan session — confirm a narrative record is written and no task state changesyou - Click the workflow banner's Check In button and confirm it launches
/cr-entryin the terminal with the right plan contextyou - Trigger a Mira whisper on a plan at 100% and confirm its command button offers
/cr-entryyou - Open Settings → Commands and confirm
/cr-checkinis either absent or clearly marked retiredyou - Repeat the equivalent checks in VentureRavenyou
Risks & edge cases
/cr-entry reads cr-checkin.md at runtime
Step 1 of the current cr-entry.md instructs Claude to read ~/.claude/commands/cr-checkin.md and follow it. Deleting that file before Phase 1 lands breaks /cr-entry outright. Phase 1 must precede Phase 2.
The installer stamp
Each installed command carries a sha256 stamp truncated to 12 hex chars. On mismatch CommandInstaller treats the file as user-modified and skips it on every future update, permanently and with no visible symptom. Every regenerated file must have its stamp recomputed and verified.
219 string literals across 77 files
The dominant failure mode is a missed reference leaving the user staring at a command that no longer exists. The verification greps at the end of Phases 3 and 4 are the real safety net.
In-flight sessions and muscle memory
A session may already have /cr-checkin in its clipboard or session bar when the app updates. Consider leaving the command retired-but-present for one release so it fails loudly rather than mysteriously.
Out of scope
- Renaming
CheckinBridge,CheckinBridgeImporter,WorkflowStage.checkedIn,PipelineBottleneck.needsCheckin, or the.claude/checkins/directory - Changing the checkin JSON schema or the importer
- Rewriting historical
FeatureHighlightrelease entries - Any change to
/cr-complete, which stays a separate command
Final review
What it does well. It removes a user-facing choice the commands themselves already admit is not a real choice, without touching the bridge, the importer or task state — so the risky half of the system is never in play. The retirement path already exists and has been used repeatedly.
Where it is weakest. Scale. The bulk is string literals across two repos, and correctness depends on the verification greps actually being run rather than assumed.
What I would adjust if pushed. Land CodeRaven, use it for a week, then do VentureRaven — the plan is written so that split is clean.
High because the scope decision — leave the bridge and internal vocabulary alone — cleanly separates mechanical work from risky work, and because the retirement mechanism is precedent rather than invention. The deduction is entirely for scale: 219 references is where things get missed.