Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add ZaxbyHub/opencode-swarm --skill durable-session-state -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/durable-session-state/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/durable-session-state/

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

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set121

The whole set →
gate-attribution gate-attribution assigns reviewer and test engineer verdicts to individual plan tasks during swarm batch runs. Activates when dispatches return multi-task rows. CX Codex +1 ★ 539repo stars merge-queue-readiness The merge-queue-readiness skill simulates a PR merged with the latest main before it enters a GitHub merge queue. Use it to catch integration failures that isolated PR checks can miss. CX Codex +1 ★ 539repo stars issue-tracer issue-tracer — a subagent that carries a GitHub issue from report to fix plan. It collects evidence, pinpoints the root cause, and touches no code until you approve the plan. CX Codex +1 ★ 539repo stars qa-reviewer The qa-reviewer subagent reviews pull requests before merge, checking logic, security, error handling, style, and test coverage without changing code. CX Codex +1 ★ 539repo stars swarm-pr-feedback swarm-pr-feedback — a skill that works through PR feedback you already have: review notes, GitHub threads, failing checks, conflicts. Everything is verified against the code before a single edit lands. CX Codex +1 ★ 539repo stars swarm-pr-feedback swarm-pr-feedback — a skill that resolves pull request review comments, CI failures, and branch conflicts through structured verification stages. CX Codex +1 ★ 539repo stars commit-pr commit-pr — a portable skill that verifies your code before push, writes conventional commits, and fills in a PR body. Guards against accidentally committing generated files or secrets. CX Codex +1 ★ 539repo stars test-file-split test-file-split breaks an oversized test file into parts along describe() boundaries when it nears the 500-line cap or blows past it. CX Codex +1 ★ 539repo stars

Project sponsors

Companies that keep this analytics open