| name | continuity |
| description | Preserve the OPERATIONAL THREAD across coding sessions with a repo-local, inspectable .continuity/ surface and a resume -> work -> finalize lifecycle. Not another memory store — a thin lifecycle layer over the memory you already have. Use at the START of substantial work on a repo ("resume", "where were we", "pick up") and at the END ("finalize", "hand off", "wrap up") so the next session starts from bounded, evidence-weighted state instead of re-orienting from scratch. Complements (never replaces) Serena/Svod/codebase-memory/auto-memory. |
Continuity — resume → work → finalize
The bottleneck between coding sessions is not memory volume, it is the lost
operational thread: what is mid-flight, what already failed, what to do next.
Big context, vector recall, and chat history all "remember more" yet still miss the
one fact that matters (this command already failed). This skill keeps that thread
in a small repo-local artifact and runs a lifecycle over it.
Core loop: resume (bounded start surface) → work → finalize (leave evidence).
Without the lifecycle, memory is passive archaeology. With it, memory becomes execution.
When to Use This Skill (and When NOT to)
| Use this skill for | Use a simpler approach for |
|---|
| Multi-session work on one repo (feature, refactor, migration) | A one-shot question or single-file edit — just answer |
| Picking up work where re-orientation would otherwise eat the first 10 min | A repo you'll touch once and never return to |
| Recording why a decision/dead-end happened so it isn't repeated | Facts already better held elsewhere (arch → Serena, cross-project → Harbormaster, durable policy → Svod) |
| Handing a repo to another agent or teammate | Ephemeral session chatter — let auto-memory handle it |
Start simple. Reach for this skill only when the work spans more than one session
on the same repo. Do NOT create a .continuity/ for throwaway or single-shot tasks —
that is the sixth-memory-store trap this skill is explicitly built to avoid.
The artifact
Repo-local .continuity/ (scaffold with the script below):
.continuity/STATE.md — the bounded resume surface AND the finalize target
(one living, compacted doc — not an append-only journal). Portable → committable/shareable..continuity/local/ — gitignored, machine-specific operational scratch. Local-only.
Every fact carries an evidence tag (weight, not decoration):
[observed] [validated] [user] — trust · [claimed] [contradicted] [unknown] — low trust.
Full section spec, tag semantics, and a worked example: references/format.md.
Actions
resume (session start)
- If
.continuity/STATE.md is absent → offer init (don't force it; see "When NOT to").
- Read STATE.md. Emit a compact surface (≤ ~12 lines): Now · Next action ·
top Known-failures · Validation expectations · Entry points.
- Surface uncertainty: flag
[claimed]/[unknown]/[contradicted] items as low-trust,
and warn if _Last finalized: is stale (> ~14 days) — verify before trusting.
- Then start work from the Next action.
finalize (session end)
Synthesize the session INTO STATE.md (compact, don't append endlessly):
- Now ← current mid-flight state · Next action ← the single next step
- Decisions / Known failures / Validation expectations / Entry points / Unresolved risks
— update in place, each bullet evidence-tagged. Demote anything later work contradicted to
[contradicted]; delete what's resolved and no longer load-bearing.
- Update the
_Last finalized: line (date + short session tag).
- Then
lint (below). Keep STATE.md bounded — if it grows past ~1 screen, compact it.
init / lint (via the script)
python3 ~/.claude/skills/continuity/scripts/continuity.py init <repo>
python3 ~/.claude/skills/continuity/scripts/continuity.py lint <repo>
lint checks required sections, valid evidence tags, and the provenance line. Run it after
finalize; treat a non-zero exit as "the surface is malformed — fix before ending the session".
Relationship to existing memory (complement, not replace)
- Serena — stable architecture/conventions of a project. Continuity ≠ this; it's the live thread.
- Svod — durable, versioned, cross-session policies/facts with provenance. Promote a continuity
fact that outlives the task INTO Svod; leave transient operational state in
.continuity/.
- codebase-memory-mcp — structural repo map (use it to fill Entry points).
- auto-memory / MEMORY.md — ephemeral session facts. Continuity is the bounded, evidence-weighted
operational subset, co-located with the code and diffable.
Boundaries
Always
- Keep STATE.md bounded and evidence-tagged; make uncertainty visible.
- Prefer updating the existing surface over spawning a parallel one.
lint after finalize.
Ask first
- Committing
.continuity/STATE.md to a shared/team repo (it becomes visible in diffs & to teammates).
- Writing anything sensitive (tokens, internal URLs, credentials) — those never go in the portable STATE.md;
local-only scratch goes under
.continuity/local/.
Never
- Turn this into a general knowledge dump — it is the operational thread only.
- Create
.continuity/ for single-session/throwaway work.
- Trust a
[claimed]/[unknown] item or a stale surface without re-verifying.
