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:
plan.md — task scope, success criteria, files in scope, what must not
break. Update when scope changes; never fork a second plan file.
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.
evidence.md — validation commands run and their outcomes (pass/fail plus
the load-bearing output lines, not full logs).
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:
- Re-read the task's artifacts. They are authoritative over your memory of
the conversation.
- Do not re-litigate
decisions.md entries or redo work evidence.md
already proves, absent new evidence or a user request.
- 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.
- 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.
1---2name: durable-session-state3description: >4 Persist plans, scope decisions, evidence, and reviewer/critic verdicts to5 durable files during long or multi-phase tasks so work survives context6 compaction, session resumes, and handoffs. Use for swarm-mode tasks, before7 context grows large, when recording approval gates, and when resuming after8 compaction or a session restart.9metadata:10 source: https://skillmd.com/skills/zaxbyhub/durable-session-state11 audience: swarm-plugin12---1314# Durable Session State1516Long swarm-mode sessions outlive their context window. Compaction summarizes17history, and summaries lose exactly the things the swarm gates depend on:18which diff a reviewer approved, what evidence was recorded, which decisions19are settled. Without durable artifacts, a resumed session re-litigates settled20decisions or — worse — treats a stale approval as current. Persist state to21files as you go; treat the conversation as cache, not storage.2223## Where artifacts live2425- Generic swarm tasks: `.claude/session/tasks/<task-slug>/` in the project.26- Issue-tracer work: `.agents/issue-traces/<issue-slug>/` (that skill's own schema27 — `08b-implementation-review.md`, `09-final-critic.md` — wins for its work).28- Never write task artifacts to the repo root, and never under `.swarm/` —29 that directory is the OpenCode plugin's runtime state, not Claude Code's.30- These artifacts are working state, not deliverables: do not commit them31 unless the user asks. Before committing, check `git status` and exclude32 them explicitly.3334## What to persist3536Keep it to four small files per task; update in place:37381. `plan.md` — task scope, success criteria, files in scope, what must not39 break. Update when scope changes; never fork a second plan file.402. `decisions.md` — one line per settled decision with a one-line rationale41 ("chose X over Y because Z"). Settled means: do not reopen without new42 evidence or a user request.433. `evidence.md` — validation commands run and their outcomes (pass/fail plus44 the load-bearing output lines, not full logs).454. `gates.md` — the approval ledger. One entry per reviewer/critic verdict:4647 ```48 ## <gate> — <APPROVE|NEEDS_REVISION|BLOCKED>49 when: <ISO timestamp or turn marker>50 head: <git rev-parse HEAD>51 diff: <git diff --stat summary>52 items: <blocking items, or none>53 ```5455## When to write5657- At phase boundaries (scope settled, plan built, implementation done, each58 gate verdict received).59- Before ending a turn while background subagents are running.60- Whenever you notice the conversation is long — write ahead of compaction,61 not after it.6263## Resume protocol6465On resuming (after compaction, a restart, or a handoff), before doing new66work:67681. Re-read the task's artifacts. They are authoritative over your memory of69 the conversation.702. Do not re-litigate `decisions.md` entries or redo work `evidence.md`71 already proves, absent new evidence or a user request.723. Check gate staleness: if `git rev-parse HEAD` or the working-tree diff no73 longer matches the latest APPROVE entry in `gates.md`, that approval is74 invalid — re-run the affected reviewer/critic gate on the current diff.754. If artifacts and the summarized conversation disagree, trust the artifacts76 and say so.7778## Relationship to swarm gates7980The swarm-mode contract invalidates any approval issued before the latest81edit. The `gates.md` ledger is what makes that rule *checkable* instead of82vibes: record the HEAD and diff summary at approval time, compare on resume83and before final synthesis. If you cannot demonstrate approval-after-last-edit84from the ledger, the gate is not satisfied.