Claude Cursor Skill

session-bridge

Universal context persistence across sessions. Auto-saves decisions, conventions, and progress to .rune/ files. Loads state at session start. Use when any skill makes architectural decisions or establishes patterns that must survive session boundaries.

LLM Mart · 0 points · 0 views 0 listing impressions 0 install-command copies
Download rune-kit-rune-skills_session-bridge-66ab37d.zip · 25 KB

Install

skills CLI npx skills add https://github.com/Rune-kit/rune/tree/master/skills/session-bridge
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install rune-kit-rune@llmmart
Git git clone https://github.com/Rune-kit/rune.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole rune-kit/rune collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

session-bridge

Purpose

Solve the #1 developer complaint: context loss across sessions. Session-bridge auto-saves critical context to .rune/ files in the project directory, and loads them at session start. Every new session knows exactly where the last one left off.

Triggers

  • Auto-trigger: when an architectural decision is made
  • Auto-trigger: when a convention/pattern is established
  • Auto-trigger: before context compaction
  • Auto-trigger: at session end (stop hook)
  • Signal: checkpoint.request — explicit checkpoint from cook/team mid-phase
  • /checkpoint — manual checkpoint (save exact resume point)
  • /rune status — manual state check

Calls (outbound)

Exception: L3→L3 coordination (same pattern as hallucination-guard → research)

  • integrity-check (L3): verify .rune/ file integrity before loading state

Called By (inbound)

  • cook (L1): auto-save decisions during feature implementation
  • rescue (L1): state management throughout refactoring
  • context-engine (L3): save state before compaction
  • context-pack (L3): coordinate state for sub-agent handoff
  • neural-memory (L3): sync key decisions back to .rune/ files after Capture Mode
  • adversary (L2): (oracle-mode) detach protocol when target model is opus-class for non-blocking dispatch
  • logic-guardian (L2): preserve logic-manifest state across sessions

State Files Managed

.rune/
├── decisions.md        — Architectural decisions log
├── conventions.md      — Established patterns & style
├── progress.md         — Task progress tracker
├── session-log.md      — Brief log of each session
├── instincts.md        — Learned project-specific patterns (trigger→action)
├── cumulative-notes.md — Living project understanding (profile, themes, relationships)
├── learnings.jsonl     — Structured learning log (append-only, queryable)
└── checkpoint.md       — Exact resume point for cross-session continuity

Execution

Save Mode (end of session or pre-compaction)

Step 1 — Gather state

Collect from the current session:

  • All architectural or technology choices made (language, library, approach)
  • Conventions established (naming patterns, file structure, coding style)
  • Tasks completed, in-progress, and blocked
  • A one-paragraph summary of what this session accomplished

Python project context (if pyproject.toml or setup.py detected):

  • Python version (from .python-version, pyproject.toml requires-python, or python --version)
  • Virtual environment path and type (venv, poetry, uv, conda)
  • Installed optional dependency groups (e.g., [dev], [test], [embeddings])
  • Last mypy error count (from most recent verification run, if available)
  • Last test coverage percentage (from most recent test run, if available)
  • DB migration version (if alembic, django migrations, or similar detected)

Step 2 — Update .rune/decisions.md

Use Glob to check if .rune/decisions.md exists. If not, use Write to create it with a # Decisions Log header.

For each architectural decision from this session, use Edit to append to .rune/decisions.md:

## [YYYY-MM-DD HH:MM] Decision: <title>

**Context:** Why this decision was needed
**Decision:** What was decided
**Rationale:** Why this approach over alternatives
**Impact:** What files/modules are affected

Step 3 — Update .rune/conventions.md

Use Glob to check if .rune/conventions.md exists. If not, use Write to create it with a # Conventions header.

For each pattern or convention established, use Edit to append to .rune/conventions.md:

## [YYYY-MM-DD] Convention: <title>

**Pattern:** Description of the convention
**Example:** Code example showing the pattern
**Applies to:** Where this convention should be followed

Python example:

## [YYYY-MM-DD] Convention: Async-First I/O

**Pattern:** All I/O functions use `async def`; blocking calls (`requests`, `open`, `time.sleep`) are forbidden in async modules
**Example:** `async def fetch_data(): async with httpx.AsyncClient() as client: ...`
**Applies to:** All modules in `src/` — sync wrappers only in CLI entry points

Step 4 — Update .rune/progress.md

Use Glob to check if .rune/progress.md exists. If not, use Write to create it with a # Progress header.

Use Edit to append the current task status to .rune/progress.md:

## [YYYY-MM-DD HH:MM] Session Summary

**Completed:**
- [x] Task description

**In Progress:**
- [ ] Task description (step X/Y)

**Blocked:**
- [ ] Task description — reason

**Next Session Should:**
- Start with X
- Continue Y from step Z

**Python Context** (if Python project):
- Python: [version] ([venv type])
- Installed extras: [list of optional dependency groups]
- mypy: [error count] ([strict/normal])
- Coverage: [percentage]%
- Migration: [version or N/A]

Step 5 — Update .rune/session-log.md

Use Glob to check if .rune/session-log.md exists. If not, use Write to create it with a # Session Log header.

Use Edit to append a one-line entry to .rune/session-log.md:

[YYYY-MM-DD HH:MM] — [brief description of session accomplishments]

Step 5.5 — Autonomous Loop Notes (when inside team or headless)

Full detail moved to references/save-extensions.md (progressive disclosure). Read that file before executing this section.

Step 5.7 — Instinct Extraction (Project-Scoped Learning)

Full detail moved to references/save-extensions.md (progressive disclosure). Read that file before executing this section.

Step 5.8 — Learnings Log (Structured JSONL)

Full detail moved to references/save-extensions.md (progressive disclosure). Read that file before executing this section.

Step 5.9 — Cumulative Project Notes (Structured Memory)

Full detail moved to references/save-extensions.md (progressive disclosure). Read that file before executing this section.

Step 6 — Cross-Project Knowledge Extraction (Neural Memory Bridge)

Full detail moved to references/save-extensions.md (progressive disclosure). Read that file before executing this section.

Step 7 — Commit

Stage and commit all updated state files:

git add .rune/ && git commit -m "chore: update rune session state"

If git is not available or the directory is not a repo, skip the commit and emit a warning.


Load Mode (start of session)

Step 1 — Check existence

Use Glob to check for .rune/ directory:

Glob pattern: .rune/*.md

If no files found: suggest running /rune onboard to initialize the project. Exit load mode.

Step 1.5 — Integrity verification

Before loading state files, invoke integrity-check (L3) to verify .rune/ files haven't been tampered:

REQUIRED SUB-SKILL: rune:integrity-check
→ Invoke integrity-check on all .rune/*.md files found in Step 1.
→ Capture: status (CLEAN | SUSPICIOUS | TAINTED), findings list.

Handle results:

  • CLEAN → proceed to Step 2 (load files)
  • SUSPICIOUS → present warning to user with specific findings. Ask: "Suspicious patterns detected in .rune/ files. Load anyway?" If user approves → proceed. If not → exit load mode.
  • TAINTED → BLOCK load. Report: ".rune/ integrity check FAILED — possible poisoning detected. Run /rune integrity for details."

Step 1.7 — Load invariants (auto-discipline)

Full detail moved to references/load-invariants.md (progressive disclosure). Read that file before executing this section.

Step 2 — Load files

Use Read on all four state files in parallel:

Read: .rune/decisions.md
Read: .rune/conventions.md
Read: .rune/progress.md
Read: .rune/session-log.md
Read: .rune/cumulative-notes.md

Step 3 — Summarize

Present the loaded context to the agent in a structured summary:

"Here's what happened in previous sessions:"

  • Last session: [last line from session-log.md]
  • Key decisions: [last 3 entries from decisions.md]
  • Active conventions: [count from conventions.md]
  • Current progress: [in-progress and blocked items from progress.md]
  • Project understanding: [Active Topics + Attention Points from cumulative-notes.md]
  • Next task: [first item under "Next Session Should" from progress.md]

Step 4 — Resume

Identify the next concrete task from progress.md → "Next Session Should" section. Present it as the recommended starting point to the calling orchestrator.

Checkpoint Mode (explicit save-and-resume point)

Unlike Save Mode (which captures session state broadly), Checkpoint Mode creates an exact resume point — a single file that tells the next session precisely where to pick up, what's in-flight, and what decisions are load-bearing.

Trigger: User says /checkpoint, or cook/team emits checkpoint.request signal when pausing mid-phase.

Step 1 — Capture resume state

Collect into a structured checkpoint:

# Checkpoint — [YYYY-MM-DD HH:MM]

## What I Was Doing
[1-2 sentences: the exact task and sub-step in progress]

## Current Git State
- Branch: [branch name]
- Last commit: [short hash + message]
- Uncommitted changes: [list of modified/untracked files, or "clean"]
- Stashed: [yes/no — if yes, stash message]

## Decisions Made This Session (Load-Bearing)
[Only decisions that affect the remaining work — not all decisions]
- [Decision 1]: [choice + why]
- [Decision 2]: [choice + why]

## What's Left (Ordered)
1. [Next immediate step — be specific: file, function, what to change]
2. [Step after that]
3. [Remaining steps...]

## Context the Next Session Needs
[Critical info that's NOT in the code or git history — mental model, gotchas discovered, things tried and failed]
- [Item 1]
- [Item 2]

## Resume Command
[Exact instruction for the next session to pick up — e.g., "Continue Phase 2 Task 3: implement the retry logic in src/api/client.ts, the happy path is done, need error handling"]

Step 2 — Write checkpoint file

Write to .rune/checkpoint.md (overwrite — only one active checkpoint at a time).

Step 3 — Confirm to user

## Checkpoint Saved
- **Resume point**: [1-line summary of what to continue]
- **Git state**: [branch] @ [commit hash] — [clean/N uncommitted files]
- **Remaining tasks**: [count]
- Next session will auto-detect this checkpoint and offer to resume.

Checkpoint Resume (in Load Mode)

At Load Mode Step 1, after checking .rune/*.md existence, also check for .rune/checkpoint.md:

  • If checkpoint exists, read it FIRST (before other state files)
  • Present the resume point prominently:
    ## Checkpoint Detected — [date]
    **Resume**: [Resume Command from checkpoint]
    **Git state**: [branch] @ [commit] — [clean/dirty]
    **Tasks remaining**: [count]
    
  • After successful resume (user confirms they've picked up where they left off), rename checkpoint:
    mv .rune/checkpoint.md .rune/checkpoint-[date].resolved.md
    
  • Keep last 3 resolved checkpoints for history, delete older ones

Why: Save Mode captures everything broadly. Checkpoint captures the exact needle position — like a bookmark in a book vs. a summary of chapters read. The next session doesn't need to scan all state files to figure out what to do; the checkpoint tells it directly.

Output Format

Save Mode

## Session Bridge — Saved
- **decisions.md**: [N] decisions appended
- **conventions.md**: [N] conventions appended
- **progress.md**: updated (completed/in-progress/blocked counts)
- **session-log.md**: 1 entry appended
- **Git commit**: [hash] | skipped (no git)

Load Mode

## Session Bridge — Loaded
- **Last session**: [date and summary]
- **Checkpoint**: [detected — resume point] | [none]
- **Invariants**: [N loaded from .rune/INVARIANTS.md] | [none] | [stale — run rune onboard --refresh]
- **Decisions on file**: [count]
- **Conventions on file**: [count]
- **Learnings on file**: [count] (top 5 surfaced if 10+)
- **Next task**: [task description]

Checkpoint Mode

## Checkpoint Saved
- **Resume point**: [1-line summary]
- **Git state**: [branch] @ [hash] — [clean/N files]
- **Remaining tasks**: [count]

Detach Mode (v0.8.0)

Full detail moved to references/detach-mode.md (progressive disclosure). Read that file before executing this section.

Constraints

  1. MUST save decisions, conventions, and progress — not just a status line
  2. MUST verify saved context can be loaded in a fresh session — test the round-trip
  3. MUST NOT overwrite existing bridge data without merging
  4. (Detach) MUST be idempotent — same sessionId or bundleHash returns existing record, never dispatches twice
  5. (Detach) MUST clean up orphaned pending records (age >24h) on session start

Sharp Edges

Known failure modes for this skill. Check these before declaring done.

Failure Mode Severity Mitigation
Overwriting existing .rune/ files instead of appending HIGH Constraint 3: use Edit to append entries — never Write to overwrite existing state
Saving only a status line, missing decisions/conventions HIGH Constraint 1: all three files (decisions, conventions, progress) must be updated
Load mode presenting stale context without age marker MEDIUM Mark each loaded entry with its session date — caller knows how fresh it is
Silent failure when git unavailable MEDIUM Note "no git available" in report — do not fail silently or skip without logging
Loading poisoned .rune/ files without verification CRITICAL Step 1.5 integrity-check MUST run before loading — TAINTED = block load
Learnings JSONL grows unbounded MEDIUM Auto-compact at 100 entries — keep only latest-winner per key+type
Checkpoint stale after code changes MEDIUM Checkpoint includes git state — if branch/commit differ at resume, warn user that checkpoint may be outdated
Multiple checkpoints overwrite each other LOW By design — only one active checkpoint. Resolved ones archived with date suffix
(Detach) Pending file orphaned forever — process crashed mid-dispatch MEDIUM Step D6 cleanup runs every session start; records >24h auto-deleted
(Detach) Two adversary calls dispatch same bundle simultaneously MEDIUM Step D2 idempotency: bundleHash-keyed lookup returns existing sessionId
(Detach) Reattach polls indefinitely without timeout HIGH Step D5 enforces timeoutAt — exceeded → emit oracle.failed reason=timeout, free the primary agent

Done When (Save Mode)

  • decisions.md updated with all architectural decisions made this session
  • conventions.md updated with all new patterns established
  • progress.md updated with completed/in-progress/blocked task status
  • session-log.md appended with one-line session summary
  • learnings.jsonl appended with 1-3 structured entries (if transferable learnings exist)
  • Git commit made (or "no git" noted in report)
  • Session Bridge Saved report emitted

Done When (Load Mode)

  • .rune/*.md files found and read
  • Checkpoint detected and presented (if exists)
  • Learnings surfaced (top 5 if 10+ entries)
  • Last session summary presented
  • Current in-progress and blocked tasks identified
  • Next task recommendation from progress.md (or checkpoint resume command)
  • Session Bridge Loaded report emitted

Done When (Checkpoint Mode)

  • Git state captured (branch, commit, uncommitted files)
  • Load-bearing decisions documented
  • Remaining tasks listed in execution order
  • Resume command written (specific enough for a fresh session to act on)
  • checkpoint.md written to .rune/
  • Checkpoint Saved report emitted

Done When (Detach Mode)

  • Pending record written to .rune/oracle-pending/<sessionId>.json with valid schema
  • Idempotency verified: duplicate bundleHash returned existing sessionId, no duplicate dispatch
  • Reattach API returns complete / pending / failed based on record status + timeout
  • Orphan cleanup runs at session start (records >24h deleted)
  • oracle.failed emitted with reason=timeout if timeoutAt exceeded

Cost Profile

~100-300 tokens per save. ~500-1000 tokens per load. Always haiku. Negligible cost.

Files (rune)
  • references
    • detach-mode.md 3.1 KB
      Loading…
    • detach-protocol.md 5.3 KB
      Loading…
    • evolutionary-memory-patterns.md 11.1 KB
      Loading…
    • load-invariants.md 2.4 KB
      Loading…
    • save-extensions.md 9 KB
      Loading…
  • scripts
    • load-invariants.js 12.7 KB
      Loading…
  • SKILL.md 16.7 KB
    ---
    name: session-bridge
    description: "Universal context persistence across sessions. Auto-saves decisions, conventions, and progress to .rune/ files. Loads state at session start. Use when any skill makes architectural decisions or establishes patterns that must survive session boundaries."
    metadata:
      author: runedev
      version: "0.8.0"
      layer: L3
      model: haiku
      group: state
      tools: "Read, Write, Edit, Glob, Grep"
      listen: phase.complete, checkpoint.request, oracle.dispatched
      emit: invariants.loaded, oracle.failed
    ---
    
    # session-bridge
    
    ## Purpose
    
    Solve the #1 developer complaint: context loss across sessions. Session-bridge auto-saves critical context to `.rune/` files in the project directory, and loads them at session start. Every new session knows exactly where the last one left off.
    
    ## Triggers
    
    - Auto-trigger: when an architectural decision is made
    - Auto-trigger: when a convention/pattern is established
    - Auto-trigger: before context compaction
    - Auto-trigger: at session end (stop hook)
    - Signal: `checkpoint.request` — explicit checkpoint from cook/team mid-phase
    - `/checkpoint` — manual checkpoint (save exact resume point)
    - `/rune status` — manual state check
    
    ## Calls (outbound)
    
    # Exception: L3→L3 coordination (same pattern as hallucination-guard → research)
    - `integrity-check` (L3): verify .rune/ file integrity before loading state
    
    ## Called By (inbound)
    
    - `cook` (L1): auto-save decisions during feature implementation
    - `rescue` (L1): state management throughout refactoring
    - `context-engine` (L3): save state before compaction
    - `context-pack` (L3): coordinate state for sub-agent handoff
    - `neural-memory` (L3): sync key decisions back to `.rune/` files after Capture Mode
    - `adversary` (L2): (oracle-mode) detach protocol when target model is opus-class for non-blocking dispatch
    - `logic-guardian` (L2): preserve logic-manifest state across sessions
    
    ## State Files Managed
    
    ```
    .rune/
    ├── decisions.md        — Architectural decisions log
    ├── conventions.md      — Established patterns & style
    ├── progress.md         — Task progress tracker
    ├── session-log.md      — Brief log of each session
    ├── instincts.md        — Learned project-specific patterns (trigger→action)
    ├── cumulative-notes.md — Living project understanding (profile, themes, relationships)
    ├── learnings.jsonl     — Structured learning log (append-only, queryable)
    └── checkpoint.md       — Exact resume point for cross-session continuity
    ```
    
    ## Execution
    
    ### Save Mode (end of session or pre-compaction)
    
    #### Step 1 — Gather state
    
    Collect from the current session:
    - All architectural or technology choices made (language, library, approach)
    - Conventions established (naming patterns, file structure, coding style)
    - Tasks completed, in-progress, and blocked
    - A one-paragraph summary of what this session accomplished
    
    **Python project context** (if `pyproject.toml` or `setup.py` detected):
    - Python version (from `.python-version`, `pyproject.toml` `requires-python`, or `python --version`)
    - Virtual environment path and type (venv, poetry, uv, conda)
    - Installed optional dependency groups (e.g., `[dev]`, `[test]`, `[embeddings]`)
    - Last mypy error count (from most recent verification run, if available)
    - Last test coverage percentage (from most recent test run, if available)
    - DB migration version (if alembic, django migrations, or similar detected)
    
    #### Step 2 — Update .rune/decisions.md
    
    Use `Glob` to check if `.rune/decisions.md` exists. If not, use `Write` to create it with a `# Decisions Log` header.
    
    For each architectural decision from this session, use `Edit` to append to `.rune/decisions.md`:
    
    ```markdown
    ## [YYYY-MM-DD HH:MM] Decision: <title>
    
    **Context:** Why this decision was needed
    **Decision:** What was decided
    **Rationale:** Why this approach over alternatives
    **Impact:** What files/modules are affected
    ```
    
    #### Step 3 — Update .rune/conventions.md
    
    Use `Glob` to check if `.rune/conventions.md` exists. If not, use `Write` to create it with a `# Conventions` header.
    
    For each pattern or convention established, use `Edit` to append to `.rune/conventions.md`:
    
    ```markdown
    ## [YYYY-MM-DD] Convention: <title>
    
    **Pattern:** Description of the convention
    **Example:** Code example showing the pattern
    **Applies to:** Where this convention should be followed
    ```
    
    Python example:
    ```markdown
    ## [YYYY-MM-DD] Convention: Async-First I/O
    
    **Pattern:** All I/O functions use `async def`; blocking calls (`requests`, `open`, `time.sleep`) are forbidden in async modules
    **Example:** `async def fetch_data(): async with httpx.AsyncClient() as client: ...`
    **Applies to:** All modules in `src/` — sync wrappers only in CLI entry points
    ```
    
    #### Step 4 — Update .rune/progress.md
    
    Use `Glob` to check if `.rune/progress.md` exists. If not, use `Write` to create it with a `# Progress` header.
    
    Use `Edit` to append the current task status to `.rune/progress.md`:
    
    ```markdown
    ## [YYYY-MM-DD HH:MM] Session Summary
    
    **Completed:**
    - [x] Task description
    
    **In Progress:**
    - [ ] Task description (step X/Y)
    
    **Blocked:**
    - [ ] Task description — reason
    
    **Next Session Should:**
    - Start with X
    - Continue Y from step Z
    
    **Python Context** (if Python project):
    - Python: [version] ([venv type])
    - Installed extras: [list of optional dependency groups]
    - mypy: [error count] ([strict/normal])
    - Coverage: [percentage]%
    - Migration: [version or N/A]
    ```
    
    #### Step 5 — Update .rune/session-log.md
    
    Use `Glob` to check if `.rune/session-log.md` exists. If not, use `Write` to create it with a `# Session Log` header.
    
    Use `Edit` to append a one-line entry to `.rune/session-log.md`:
    
    ```
    [YYYY-MM-DD HH:MM] — [brief description of session accomplishments]
    ```
    
    #### Step 5.5 — Autonomous Loop Notes (when inside team or headless)
    
    > Full detail moved to [`references/save-extensions.md`](references/save-extensions.md) (progressive disclosure). **Read that file before executing this section.**
    
    #### Step 5.7 — Instinct Extraction (Project-Scoped Learning)
    
    > Full detail moved to [`references/save-extensions.md`](references/save-extensions.md) (progressive disclosure). **Read that file before executing this section.**
    
    #### Step 5.8 — Learnings Log (Structured JSONL)
    
    > Full detail moved to [`references/save-extensions.md`](references/save-extensions.md) (progressive disclosure). **Read that file before executing this section.**
    
    #### Step 5.9 — Cumulative Project Notes (Structured Memory)
    
    > Full detail moved to [`references/save-extensions.md`](references/save-extensions.md) (progressive disclosure). **Read that file before executing this section.**
    
    #### Step 6 — Cross-Project Knowledge Extraction (Neural Memory Bridge)
    
    > Full detail moved to [`references/save-extensions.md`](references/save-extensions.md) (progressive disclosure). **Read that file before executing this section.**
    
    #### Step 7 — Commit
    
    Stage and commit all updated state files:
    
    ```bash
    git add .rune/ && git commit -m "chore: update rune session state"
    ```
    
    If git is not available or the directory is not a repo, skip the commit and emit a warning.
    
    ---
    
    ### Load Mode (start of session)
    
    #### Step 1 — Check existence
    
    Use `Glob` to check for `.rune/` directory:
    
    ```
    Glob pattern: .rune/*.md
    ```
    
    If no files found: suggest running `/rune onboard` to initialize the project. Exit load mode.
    
    #### Step 1.5 — Integrity verification
    
    Before loading state files, invoke `integrity-check` (L3) to verify `.rune/` files haven't been tampered:
    
    ```
    REQUIRED SUB-SKILL: rune:integrity-check
    → Invoke integrity-check on all .rune/*.md files found in Step 1.
    → Capture: status (CLEAN | SUSPICIOUS | TAINTED), findings list.
    ```
    
    Handle results:
    - `CLEAN` → proceed to Step 2 (load files)
    - `SUSPICIOUS` → present warning to user with specific findings. Ask: "Suspicious patterns detected in .rune/ files. Load anyway?" If user approves → proceed. If not → exit load mode.
    - `TAINTED` → **BLOCK load**. Report: ".rune/ integrity check FAILED — possible poisoning detected. Run `/rune integrity` for details."
    
    #### Step 1.7 — Load invariants (auto-discipline)
    
    > Full detail moved to [`references/load-invariants.md`](references/load-invariants.md) (progressive disclosure). **Read that file before executing this section.**
    
    #### Step 2 — Load files
    
    Use `Read` on all four state files in parallel:
    
    ```
    Read: .rune/decisions.md
    Read: .rune/conventions.md
    Read: .rune/progress.md
    Read: .rune/session-log.md
    Read: .rune/cumulative-notes.md
    ```
    
    #### Step 3 — Summarize
    
    Present the loaded context to the agent in a structured summary:
    
    > "Here's what happened in previous sessions:"
    > - Last session: [last line from session-log.md]
    > - Key decisions: [last 3 entries from decisions.md]
    > - Active conventions: [count from conventions.md]
    > - Current progress: [in-progress and blocked items from progress.md]
    > - Project understanding: [Active Topics + Attention Points from cumulative-notes.md]
    > - Next task: [first item under "Next Session Should" from progress.md]
    
    #### Step 4 — Resume
    
    Identify the next concrete task from `progress.md` → "Next Session Should" section. Present it as the recommended starting point to the calling orchestrator.
    
    ### Checkpoint Mode (explicit save-and-resume point)
    
    Unlike Save Mode (which captures session state broadly), Checkpoint Mode creates an **exact resume point** — a single file that tells the next session precisely where to pick up, what's in-flight, and what decisions are load-bearing.
    
    **Trigger**: User says `/checkpoint`, or `cook`/`team` emits `checkpoint.request` signal when pausing mid-phase.
    
    #### Step 1 — Capture resume state
    
    Collect into a structured checkpoint:
    
    ```markdown
    # Checkpoint — [YYYY-MM-DD HH:MM]
    
    ## What I Was Doing
    [1-2 sentences: the exact task and sub-step in progress]
    
    ## Current Git State
    - Branch: [branch name]
    - Last commit: [short hash + message]
    - Uncommitted changes: [list of modified/untracked files, or "clean"]
    - Stashed: [yes/no — if yes, stash message]
    
    ## Decisions Made This Session (Load-Bearing)
    [Only decisions that affect the remaining work — not all decisions]
    - [Decision 1]: [choice + why]
    - [Decision 2]: [choice + why]
    
    ## What's Left (Ordered)
    1. [Next immediate step — be specific: file, function, what to change]
    2. [Step after that]
    3. [Remaining steps...]
    
    ## Context the Next Session Needs
    [Critical info that's NOT in the code or git history — mental model, gotchas discovered, things tried and failed]
    - [Item 1]
    - [Item 2]
    
    ## Resume Command
    [Exact instruction for the next session to pick up — e.g., "Continue Phase 2 Task 3: implement the retry logic in src/api/client.ts, the happy path is done, need error handling"]
    ```
    
    #### Step 2 — Write checkpoint file
    
    Write to `.rune/checkpoint.md` (overwrite — only one active checkpoint at a time).
    
    #### Step 3 — Confirm to user
    
    ```
    ## Checkpoint Saved
    - **Resume point**: [1-line summary of what to continue]
    - **Git state**: [branch] @ [commit hash] — [clean/N uncommitted files]
    - **Remaining tasks**: [count]
    - Next session will auto-detect this checkpoint and offer to resume.
    ```
    
    #### Checkpoint Resume (in Load Mode)
    
    At Load Mode Step 1, after checking `.rune/*.md` existence, also check for `.rune/checkpoint.md`:
    
    - If checkpoint exists, read it FIRST (before other state files)
    - Present the resume point prominently:
      ```
      ## Checkpoint Detected — [date]
      **Resume**: [Resume Command from checkpoint]
      **Git state**: [branch] @ [commit] — [clean/dirty]
      **Tasks remaining**: [count]
      ```
    - After successful resume (user confirms they've picked up where they left off), rename checkpoint:
      ```bash
      mv .rune/checkpoint.md .rune/checkpoint-[date].resolved.md
      ```
    - Keep last 3 resolved checkpoints for history, delete older ones
    
    **Why**: Save Mode captures everything broadly. Checkpoint captures the **exact needle position** — like a bookmark in a book vs. a summary of chapters read. The next session doesn't need to scan all state files to figure out what to do; the checkpoint tells it directly.
    
    ## Output Format
    
    ### Save Mode
    ```
    ## Session Bridge — Saved
    - **decisions.md**: [N] decisions appended
    - **conventions.md**: [N] conventions appended
    - **progress.md**: updated (completed/in-progress/blocked counts)
    - **session-log.md**: 1 entry appended
    - **Git commit**: [hash] | skipped (no git)
    ```
    
    ### Load Mode
    ```
    ## Session Bridge — Loaded
    - **Last session**: [date and summary]
    - **Checkpoint**: [detected — resume point] | [none]
    - **Invariants**: [N loaded from .rune/INVARIANTS.md] | [none] | [stale — run rune onboard --refresh]
    - **Decisions on file**: [count]
    - **Conventions on file**: [count]
    - **Learnings on file**: [count] (top 5 surfaced if 10+)
    - **Next task**: [task description]
    ```
    
    ### Checkpoint Mode
    ```
    ## Checkpoint Saved
    - **Resume point**: [1-line summary]
    - **Git state**: [branch] @ [hash] — [clean/N files]
    - **Remaining tasks**: [count]
    ```
    
    ## Detach Mode (v0.8.0)
    
    > Full detail moved to [`references/detach-mode.md`](references/detach-mode.md) (progressive disclosure). **Read that file before executing this section.**
    
    ## Constraints
    
    1. MUST save decisions, conventions, and progress — not just a status line
    2. MUST verify saved context can be loaded in a fresh session — test the round-trip
    3. MUST NOT overwrite existing bridge data without merging
    4. (Detach) MUST be idempotent — same sessionId or bundleHash returns existing record, never dispatches twice
    5. (Detach) MUST clean up orphaned pending records (age >24h) on session start
    
    ## Sharp Edges
    
    Known failure modes for this skill. Check these before declaring done.
    
    | Failure Mode | Severity | Mitigation |
    |---|---|---|
    | Overwriting existing .rune/ files instead of appending | HIGH | Constraint 3: use Edit to append entries — never Write to overwrite existing state |
    | Saving only a status line, missing decisions/conventions | HIGH | Constraint 1: all three files (decisions, conventions, progress) must be updated |
    | Load mode presenting stale context without age marker | MEDIUM | Mark each loaded entry with its session date — caller knows how fresh it is |
    | Silent failure when git unavailable | MEDIUM | Note "no git available" in report — do not fail silently or skip without logging |
    | Loading poisoned .rune/ files without verification | CRITICAL | Step 1.5 integrity-check MUST run before loading — TAINTED = block load |
    | Learnings JSONL grows unbounded | MEDIUM | Auto-compact at 100 entries — keep only latest-winner per key+type |
    | Checkpoint stale after code changes | MEDIUM | Checkpoint includes git state — if branch/commit differ at resume, warn user that checkpoint may be outdated |
    | Multiple checkpoints overwrite each other | LOW | By design — only one active checkpoint. Resolved ones archived with date suffix |
    | (Detach) Pending file orphaned forever — process crashed mid-dispatch | MEDIUM | Step D6 cleanup runs every session start; records >24h auto-deleted |
    | (Detach) Two adversary calls dispatch same bundle simultaneously | MEDIUM | Step D2 idempotency: bundleHash-keyed lookup returns existing sessionId |
    | (Detach) Reattach polls indefinitely without timeout | HIGH | Step D5 enforces `timeoutAt` — exceeded → emit `oracle.failed` reason=`timeout`, free the primary agent |
    
    ## Done When (Save Mode)
    
    - decisions.md updated with all architectural decisions made this session
    - conventions.md updated with all new patterns established
    - progress.md updated with completed/in-progress/blocked task status
    - session-log.md appended with one-line session summary
    - learnings.jsonl appended with 1-3 structured entries (if transferable learnings exist)
    - Git commit made (or "no git" noted in report)
    - Session Bridge Saved report emitted
    
    ## Done When (Load Mode)
    
    - .rune/*.md files found and read
    - Checkpoint detected and presented (if exists)
    - Learnings surfaced (top 5 if 10+ entries)
    - Last session summary presented
    - Current in-progress and blocked tasks identified
    - Next task recommendation from progress.md (or checkpoint resume command)
    - Session Bridge Loaded report emitted
    
    ## Done When (Checkpoint Mode)
    
    - Git state captured (branch, commit, uncommitted files)
    - Load-bearing decisions documented
    - Remaining tasks listed in execution order
    - Resume command written (specific enough for a fresh session to act on)
    - checkpoint.md written to .rune/
    - Checkpoint Saved report emitted
    
    ## Done When (Detach Mode)
    
    - Pending record written to `.rune/oracle-pending/<sessionId>.json` with valid schema
    - Idempotency verified: duplicate bundleHash returned existing sessionId, no duplicate dispatch
    - Reattach API returns `complete` / `pending` / `failed` based on record status + timeout
    - Orphan cleanup runs at session start (records >24h deleted)
    - `oracle.failed` emitted with `reason=timeout` if timeoutAt exceeded
    
    ## Cost Profile
    
    ~100-300 tokens per save. ~500-1000 tokens per load. Always haiku. Negligible cost.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.