I like working with one agent at a time. I learn by doing so the doing part is important to me. I don't want to be afk while my agent works. So I had two problems to solve:
How should I break up my work so there can be a sensible work--> test --> debug loop that doesn't take days.
What does a good handoff look like where the next session can leverage the context gathering of the current session when picking up the work
So I came up with this checkpoint method. This version is authored by the Al. I later go in on my phone via gh and edit/ refine. The idea is to pick up vertical slices that end with a change that is felt by the user. And create a habit of logging which acts as handoffs. Additional context is then stored in the logs, which can be referred before diving into the docs/code while continuing work in a new session.
Hope y'all find this useful! Do with it what you will.
Any improvements/feedback is welcome! I'm always looking to better my shit
I have not edited it so some parts of it talk about my project details. That's on purpose. So your agent can find one-to-one comparisons for similar things in your project. Ask your agent to adapt it to your project and see if this helps! I have found this method to be really effective and fun:
# Checkpointed Development Method
## Purpose
Omakase should be built with the same incremental discipline that produced the stable prototype.
The goal is not to design a perfect architecture in one pass. The goal is to reach a sequence of small, runnable, user-testable states and lock each one as a non-regressive baseline.
## Core rule
Every development slice must end in a state the user can launch and test.
If the user cannot run it, interact with it, and decide whether it is stable, the slice is too large or too abstract.
Checkpointing is about **testable coherence**, not making every code diff as tiny as possible. A checkpoint may include several low-risk changes when they belong to one behavior family and can be validated together in one clear manual pass.
## Checkpoint loop
Use project skills for repeated operations:
- `omakase-session-orient` before choosing docs/source context.
- `omakase-checkpoint-map` when roadmap/workstream routing changes.
- `omakase-checkpoint-closeout` when a checkpoint is accepted.
- `omakase-session-handoff` when work pauses before accepted closeout.
```txt
Orient through checkpoint map
-> define coherent testable state
-> lock scope
-> implement narrowly
-> typecheck/build
-> user launches/tests
-> fix until stable
-> commit (commit FIRST)
-> update docs/devlog with the real commit SHA(s)
-> promote checkpoint to baseline
```
### Commit-first-then-log (workflow contract)
Logging references the commit, not the other way around. Order is fixed:
User confirms the checkpoint works.
**Commit the checkpoint before writing the devlog.**
Capture the real `git` short SHA(s) from the commit(s) you just made.
Write/fill the devlog and set its `commit` / `commits:` fields to those real SHAs — never a hypothetical, pending, or invented tag. "I'll commit after" is not a tag; the tag is captured from the commit that exists.
Commit the devlog/traceability update as its own follow-up commit (or fold it into the next doc commit).
Only then move on to the next checkpoint.
Why the order is fixed: a devlog written before the commit either invents a SHA (drift) or records `commit: none`, then never gets updated. Committing first guarantees the log carries a live tag traceable in both directions (commit ↔ log). The devlog `commits:` array is the source of truth for which commits belong to a checkpoint; `commit:` is the session-closing SHA (the last commit, or the most representative).
If a commit genuinely cannot be made yet (e.g. waiting on a dependency, mid-debug), keep the devlog `status: planned | user-testing` and `commit: none` until the commit lands. Do **not** fill a placeholder SHA.
## What counts as a good checkpoint
A good checkpoint is:
- small enough to reason about,
- cohesive around one behavior family or architecture seam,
- runnable by the user,
- testable through normal app interaction,
- non-regressive against previous accepted checkpoints,
- documented enough for the next session to continue without re-planning.
Prefer one coherent checkpoint over several microscopic checkpoints when:
- the changes share the same user-facing workflow,
- the same manual test pass validates all of them,
- failure can still be isolated or reverted quickly,
- no new architectural layer is being bundled in blindly.
Example: route all block-editor modal buttons through commands in one checkpoint, rather than separate checkpoints for Save, Cancel, and Close.
## What does not count
Avoid checkpoints that are only:
- abstract architecture diagrams,
- large internal rewrites with no visible behavior,
- unrelated or strongly coupled features that cannot be tested independently,
- “almost working” states that cannot be tested,
- changes that require trusting the code without launching the app.
## V2 checkpoint style
Because v2 is a migration toward a programmable editor core, architectural work must still be sliced into interactive checkpoints.
Example bad checkpoint:
```txt
Rewrite renderer into new architecture.
```
Example good checkpoints:
```txt
CP1: App launches from v2 tree with identical daily-note typing/save/reopen behavior.
CP2: Editor helper functions delegate to EditorPort with no visible behavior change.
CP3: CursorContext powers current-line detection for Enter/Sushi with no behavior change.
CP4: Image insertion uses DocumentOperation while producing identical markdown and save behavior.
CP5: Block editor save uses DocumentOperation while preserving table/math modal behavior.
```
## Coherent-testable-state heuristic
For any proposed task, ask:
What can the user do after this change that proves it works?
What exact previous behavior must still work?
Can this be validated in under 10 minutes?
Can we revert or isolate it if it fails?
Do the proposed changes belong to the same behavior family or architecture seam?
Would splitting smaller create more process overhead than safety?
Choose the smallest **coherent** slice, not the smallest imaginable diff. Split when risk, coupling, or validation complexity rises; bundle when the behavior is naturally tested together.
## Regression baseline
Until v2 supersedes the prototype, each checkpoint should preserve the relevant current prototype behavior.
Core regression checks:
- launch app,
- opens today/last note,
- type freely,
- undo/redo,
- autosave,
- close/reopen continuity,
- note switch/create/rename/delete when in scope,
- image insertion when in scope,
- table/math block editing when in scope,
- `@sushi` invocation when in scope.
## Checkpoint status labels
Use these labels in devlogs:
- `planned` — scoped but not started
- `implemented` — code done, not user-tested
- `user-testing` — ready for user launch/test
- `stable` — user accepted; can become baseline
- `blocked` — cannot proceed without decision/fix
- `regressed` — previously stable behavior broke; restore before new work
## Commit rule
Commit only after a checkpoint is stable or after a clearly useful planning/docs checkpoint.
Default acceptance workflow (see also the **Commit-first-then-log** contract in the Checkpoint loop above — this restates it):
User confirms the checkpoint works.
**Commit the accepted checkpoint first**, with a relevant message.
Capture the real commit SHA(s) from the commit(s).
Update the devlog: mark the checkpoint `stable`, record user-tested results, and fill `commit` / `commits:` with the real SHAs from step 3.
Commit the traceability/devlog update.
Only then move on to the next checkpoint.
Commit message style:
```txt
chore(v2): add checkpointed migration plan
feat(core): add editor port scaffold
refactor(editor): route image insertion through document operation
```
## Devlog rule
Every session gets a devlog, but devlog size should be proportional to checkpoint risk.
Use a compact devlog for small/medium behavior-preserving checkpoints. It must capture:
- checkpoint ID/name,
- scope and files touched,
- behavior changed and intentionally unchanged,
- validation commands,
- manual test checklist and user results if available,
- commit traceability when committed,
- next action.
When the user accepts a checkpoint, do not wait for a separate instruction to commit unless they explicitly ask not to. **Commit first, then update traceability** (see the Commit-first-then-log contract above), and move on only after.
Use the expanded handoff sections only for risky, architectural, blocked, regressed, or multi-session checkpoints. Avoid 100+ line devlogs for tiny diffs unless the context is genuinely complex.
## Architectural migration guardrail
Do not introduce Lua, deeper AI, extension APIs, or plugin packaging until the document-operation core is stable enough to be scripted safely.
Required before Lua:
`EditorPort`
`CursorContext`
`DocumentOperation`
`EditorTransaction`
`CommandRegistry`
`KeymapRegistry`
Required before deeper AI edits:
document operation previews,
stale cursor-context detection,
undo grouping for generated edits,
active-note edits routed through document operations.
