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.
Install
npx skills add https://github.com/Rune-kit/rune/tree/master/skills/session-bridge
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install rune-kit-rune@llmmart
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 implementationrescue(L1): state management throughout refactoringcontext-engine(L3): save state before compactioncontext-pack(L3): coordinate state for sub-agent handoffneural-memory(L3): sync key decisions back to.rune/files after Capture Modeadversary(L2): (oracle-mode) detach protocol when target model is opus-class for non-blocking dispatchlogic-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.tomlrequires-python, orpython --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 integrityfor 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
- MUST save decisions, conventions, and progress — not just a status line
- MUST verify saved context can be loaded in a fresh session — test the round-trip
- MUST NOT overwrite existing bridge data without merging
- (Detach) MUST be idempotent — same sessionId or bundleHash returns existing record, never dispatches twice
- (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>.jsonwith valid schema - Idempotency verified: duplicate bundleHash returned existing sessionId, no duplicate dispatch
- Reattach API returns
complete/pending/failedbased on record status + timeout - Orphan cleanup runs at session start (records >24h deleted)
oracle.failedemitted withreason=timeoutif 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.
Reviews (0)
No reviews yet.
No comments yet.