durable-session-state — Claude Code skill: what it does
The durable-session-state skill keeps task plans, decisions, validation results, and review verdicts in project files. Use it to pick up long-running work after context compaction or a handoff.
MIT ★ 539 updated 2026-10-29
npx skills add ZaxbyHub/opencode-swarm --skill durable-session-state -a claude-codeWhat durable-session-state does
The skill uses four files for each task: plan.md for scope and success criteria, decisions.md for settled choices, evidence.md for validation commands and outcomes, and gates.md for reviewer verdicts. Update them at phase boundaries and before a turn ends while subagents are still working.
When work resumes, the agent reads the files first and compares the current HEAD and diff with the latest approval. If either has changed, the affected review gate must run again. Generic task artifacts go in .claude/session/tasks/<task-slug>/; they are working files, so leave them out of commits unless the user asks. In swarm work, an approval from before the latest edit no longer counts.
What it helps with
- carry a task plan across sessions
- record decisions so settled choices stay settled
- save validation results without copying full logs
- check whether a review approval still matches the current diff
Example prompts for the agent
- Save this task's scope and success criteria in the session files.
- Record the validation commands and reviewer verdict for the current diff.
- Resume this task by reading its saved decisions and checking the latest approval against the current code.
How to install durable-session-state
1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill durable-session-state -a claude-code2Manually: put the files in place
~/.claude/skills/durable-session-state/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/durable-session-state/
1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill durable-session-state -a codex2Manually: put the files in place
.agents/skills/durable-session-state/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill durable-session-state -a cursor2Manually: put the files in place
.cursor/skills/durable-session-state/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install ZaxbyHub/opencode-swarm .claude/skills/durable-session-state2Manually: put the files in place
.github/skills/durable-session-state/SKILL.md1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill durable-session-state -a gemini-cli2Platform CLI
gemini skills install https://github.com/ZaxbyHub/opencode-swarm --path .claude/skills/durable-session-stateManually: put the files in place
.devin/skills/durable-session-state/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill durable-session-state -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about durable-session-state
How do I install durable-session-state in Claude Code?
Run npx skills add ZaxbyHub/opencode-swarm --skill durable-session-state -a claude-code. The skill file is at ~/.claude/skills/durable-session-state/SKILL.md.
What does durable-session-state do?
It stores task state in four files and uses those records when work resumes. It also checks whether a review approval is still valid after code changes.
Where does durable-session-state store task files?
For generic swarm tasks, it uses .claude/session/tasks/<task-slug>/. Issue-tracer work uses .agents/issue-traces/<issue-slug>/ and that skill's schema.
Source text
SKILL.md · MIT
---
name: durable-session-state
description: >
Persist plans, scope decisions, evidence, and reviewer/critic verdicts to
durable files during long or multi-phase tasks so work survives context
compaction, session resumes, and handoffs. Use for swarm-mode tasks, before
context grows large, when recording approval gates, and when resuming after
compaction or a session restart.
metadata:
audience: swarm-plugin
---
# Durable Session State
Long swarm-mode sessions outlive their context window. Compaction summarizes
history, and summaries lose exactly the things the swarm gates depend on:
which diff a reviewer approved, what evidence was recorded, which decisions
are settled. Without durable artifacts, a resumed session re-litigates settled
decisions or — worse — treats a stale approval as current. Persist state to
files as you go; treat the conversation as cache, not storage.
## Where artifacts live
- Generic swarm tasks: `.claude/session/tasks/<task-slug>/` in the project.
- Issue-tracer work: `.agents/issue-traces/<issue-slug>/` (that skill's own schema
— `08b-implementation-review.md`, `09-final-critic.md` — wins for its work).
- Never write task artifacts to the repo root, and never under `.swarm/` —
that directory is the OpenCode plugin's runtime state, not Claude Code's.
- These artifacts are working state, not deliverables: do not commit them
unless the user asks. Before committing, check `git status` and exclude
them explicitly.
## What to persist
Keep it to four small files per task; update in place:
1. `plan.md` — task scope, success criteria, files in scope, what must not
break. Update when scope changes; never fork a second plan file.
2. `decisions.md` — one line per settled decision with a one-line rationale
("chose X over Y because Z"). Settled means: do not reopen without new
evidence or a user request.
3. `evidence.md` — validation commands run and their outcomes (pass/fail plus
the load-bearing output lines, not full logs).
4. `gates.md` — the approval ledger. One entry per reviewer/critic verdict:
```
## <gate> — <APPROVE|NEEDS_REVISION|BLOCKED>
when: <ISO timestamp or turn marker>
head: <git rev-parse HEAD>
diff: <git diff --stat summary>
items: <blocking items, or none>
```
## When to write
- At phase boundaries (scope settled, plan built, implementation done, each
gate verdict received).
- Before ending a turn while background subagents are running.
- Whenever you notice the conversation is long — write ahead of compaction,
not after it.
## Resume protocol
On resuming (after compaction, a restart, or a handoff), before doing new
work:
1. Re-read the task's artifacts. They are authoritative over your memory of
the conversation.
2. Do not re-litigate `decisions.md` entries or redo work `evidence.md`
already proves, absent new evidence or a user request.
3. Check gate staleness: if `git rev-parse HEAD` or the working-tree diff no
longer matches the latest APPROVE entry in `gates.md`, that approval is
invalid — re-run the affected reviewer/critic gate on the current diff.
4. If artifacts and the summarized conversation disagree, trust the artifacts
and say so.
## Relationship to swarm gates
The swarm-mode contract invalidates any approval issued before the latest
edit. The `gates.md` ledger is what makes that rule *checkable* instead of
vibes: record the HEAD and diff summary at approval time, compare on resume
and before final synthesis. If you cannot demonstrate approval-after-last-edit
from the ledger, the gate is not satisfied.
© ZaxbyHub · MIT · ZaxbyHub/opencode-swarm