dev-skills

Appearance

Session Continuity Protocol ​

A file-based protocol that gives AI agents perfect continuity across independent sessions using three artifacts and a strict session loop.

Problem ​

AI agents lose all context between sessions. Without a deliberate protocol, this leads to:

  • Duplicated work — agents redo tasks already completed in prior sessions
  • Premature completion — agents see existing progress and declare the project finished, missing substantial remaining work
  • Broken state — agents make changes that conflict with prior work because they don't understand what came before

The Pattern ​

Three Artifacts ​

Every long-running agent project uses exactly three persistence mechanisms:

  • TASKS.md — source of truth for what needs doing
  • LOG.md — append-only session log
  • Git — versioned ground truth

TASKS.md ​

A markdown file with rich prose describing each task. Each task represents one end-to-end capability (not a substep) and contains a fenced metadata block tracking completion status:

markdown
## Implement user authentication

Users can log in with email and password. The system rejects invalid
credentials and locks accounts after 3 failed attempts.

\`\`\`yaml
done: false
evidence:
\`\`\`

Agents may only edit the metadata block (done, evidence). They may not rewrite descriptions, delete tasks, reorder tasks, or add new tasks unless explicitly instructed.

LOG.md ​

One entry per session documenting what happened, what was verified, and which commits were produced. Agents may only append — never edit or delete past entries. This is the primary orientation tool for the next session.

markdown
## Session 2025-11-27T14:30Z

**Task:** Implement user authentication
**Outcome:** Completed. Login, rejection, and lockout all verified.
**Commits:** a1b2c3d — implement auth flow; e4f5g6h — update task status
**Notes:** Rate limiter config is in `config/auth.yaml`. Password hashing
uses bcrypt with cost factor 12.

Git ​

All work happens on a single designated branch. Git commits are the authoritative record of what changed. Each session must end with at least one commit referenced in LOG.md.

The Session Loop: Orient, Execute, Report ​

Every session follows exactly this sequence. No skipping, no merging steps.

Phase 1: Orient ​

Goal: understand current state and choose one task.

  1. Read the prompt/instructions fully
  2. Read LOG.md from the bottom up to understand recent work
  3. Read TASKS.md and identify tasks with done: false
  4. Inspect recent git history on the working branch (git log -10)
  5. Choose exactly one task to work on this session

If no tasks remain, stop and report completion in LOG.md.

Phase 2: Execute ​

Goal: complete the chosen task.

Allowed: run the project, run tests, modify application code for the chosen task only.

Prohibited: update TASKS.md, write to LOG.md, commit, or start additional tasks. These all happen in Report.

Phase 3: Report ​

Goal: leave a clean, unambiguous record for the next session.

There are three outcomes — completed, partial, or blocked — but the sequence is the same regardless:

  1. Verify — re-run all required tests
  2. Update TASKS.md — if the task is fully verified, mark done: true and add evidence; if incomplete, leave done: false and add a status note describing what remains
  3. Commit — code changes + task update in one commit
  4. Append to LOG.md — include commit hash, outcome, and (if incomplete) what the next session should do
  5. Commit the log — separate log-only commit

Branch Rules ​

  • All agent work happens on a single branch (e.g., agent/main)
  • No feature branches — one branch keeps the protocol simple
  • No rebasing or history rewriting — the log must be trustworthy
  • Each session produces at least one commit

Stop Conditions ​

End the session immediately when any of these occurs:

  • The selected task is completed and reported
  • Remaining context drops below 50%
  • Tests cannot be made to pass within reasonable effort
  • The task is larger than expected and needs to be split

In all cases, the agent must still produce a Report. An incomplete task gets documented honestly — this is far more valuable than a rushed, broken completion.

Non-Negotiable Rules ​

  • One task per session
  • No task marked done without verification
  • No session ends without a report
  • Never edit past log entries
  • Never rewrite git history
  • Optimize for clarity and continuity, not speed

When to Use ​

  • Multi-session projects where an agent works incrementally across many independent invocations
  • Tasks too large for a single context window
  • Projects where multiple agents (or agent + human) collaborate asynchronously
  • Any workflow where session-to-session continuity is critical

Trade-offs ​

Benefits:

  • Perfect continuity — every session picks up exactly where the last left off
  • Auditable — LOG.md and git history provide a complete record
  • Recoverable — if an agent produces bad work, the clear commit history makes it easy to revert
  • Simple — three files and one loop; no external infrastructure needed

Costs:

  • Overhead — the Orient phase and Report phase consume context that could go toward implementation
  • Rigidity — one-task-per-session may feel slow for simple tasks
  • Requires discipline — the protocol only works if the prompt enforces it strictly; agents will cut corners if given room

References ​