session-bridge

Files (1)

• SKILL.md

SKILL.md (first lines)

<!-- sage-metadata
cost-tier: haiku
activation: auto
tags: [context, persistence, session, continuity]
inputs: [codebase]
outputs: [session-state]
-->

# Session Bridge

Maintain continuity across sessions using the plan file as the source of truth.

**Core Principle:** The file system is the source of truth. What artifacts
exist in `.sage/work/` and their frontmatter status tells you where things
stand. decisions.md provides reasoning context that helps find the active work quickly.
State updates happen at checkpoints (Rule 7), not per-task.

## State Architecture

Two levels of state, each with a different purpose:

### Ground Truth: Artifacts in .sage/work/

`.sage/work/<feature>/` contains artifacts with YAML frontmatter:
- `brief.md`, `spec.md`, `plan.md` — each with `status` and `phase`
- Status field: `pending`, `in-progress`, `completed`, `blocked`
- The EXISTENCE of artifacts and their frontmatter status IS the state

**This is always accurate** because artifacts are created and updated
as part of the workflow. No separate "save" action needed.

### Context: decision logs

Each initiative's `.sage/work/[initiative]/decisions.md` is the
per-cycle log; the global `.sage/decisions.md` is a shared
cross-initiative log. Both are places where the agent and human
write significant decisions and context. It provides reasoning that
artifact frontmatter doesn't capture — WHY decisions were made,
what alternatives were considered, and what the human's priorities are.

## Loading (Start of Session)

When resuming work, run the generated brief FIRST:

```bash
python3 sage/runtime/tools/manifest.py resume
```

(Plugin installs: `python3 "${CLAUDE_PLUGIN_ROOT}/tools/manifest.py" resume`.)

It performs Steps 1–3 below mechanically — selection, evidence, decisions —
and prints the resume authority order (cycle-protocol.md). Only fall back to
the manual steps when the tool is unavailable (no python3, or a manifest-less
pre-v1.0.9 project).

### Step 1: Scan artifacts for state (fallback)

Scan `.sage/work/` for active initiatives. Read frontmatter from
manifest.md, brief.md, spec.md, or plan.md (whichever exists). Note
title, status, phase. If a plan exists, scan the task checkboxes to
understand how far implementation progressed.

This is the source of truth — what artifacts exist tells you where
the project stands.

**Branch matching (git projects):** read the current branch and
match it against the **recorded `branch:` field** in each
initiative's manifest frontmatter (git-discipline records it at
branch creation — match on the recorded field, never re-derive from
branch or directory names). Prefer the initiative whose recorded
branch matches HEAD in the resume menu; if HEAD is on the default
branch while initiative branches exist, list them.

**Owner exclusion (parallel worktrees):** exclude initiatives whose
manifest carries an `owner:` pointing at a different checkout —
compare `git rev-parse --show-toplevel` against the recorded
`owner:` after path normalization (trailing slashes, symlinks).
They belong to another worktree's session. A session opened inside
a worktree auto-resumes that worktree's checked-out initiative by
the same branch-matching rule.

### Step 2: Read decisions for context

Read the matched initiative's own decision log first —
`.sage/work/[initiative]/decisions.md` — then the global
`.sage/decisions.md` (cross-initiative decisions; older projects
may have only the global file). Read the last 3-5 entries of each.
These capture recent decisions and direction changes — WHY the
project is in its current state, not just WHAT state it's in.

### Step 3: Verify against the codebase

If artifacts and the codebase disagree (e.g., plan says "spec phase"
but implementation files exist), trust the codebase. The file system
is the ultimate source of truth. Update artifacts to match reality.

### Step 4: Report to human

**Sage:** Resuming [feature name]. [Phase] phase.
[Summary of what exists and what's next.]

## Saving (At Checkpoints)

State updates happen ONLY at checkpoints (Rule 7), not per-task:

### At each checkpoint:

Prepend significant decisions to the initiative's decision log
(`.sage/work/[initiative]/decisions.md`; cross-initiative decisions
go to the global `.sage/decisions.md`):
```markdown
### 2025-03-13 — Token storage decision
Chose httpOnly cookies over localStorage for JWT storage.
XSS protection outweighs CSRF handling cost.
spec.md updated with cookie-based auth approach.
```

Update artifact frontmatter if status changed.

From xoai/sage, MIT.

More from xoai/sage