skill-session-state

name	skill-session-state
description	Persist and restore agent session context (Mode, Task, Summary) to survive resets.
tier	0
version	1

Session State Management

This skill provides the mechanism to persist your current working state to a file. This allows you to "reboot" from a seamless context state if the session window is reset.

1. The Session File

• Path: .agent/sessions/latest.yaml — resolved from the repo root regardless of the invocation CWD (walk-up to .git, CLAUDE_PROJECT_DIR fallback; SS-1).
• Purpose: Stores the exact arguments from your last task_boundary call, plus session metadata.
• Persistence: surviving session clears, allowing you to pick up exactly where you left off.
• Never committed: this is per-machine runtime data — .agent/sessions/ is gitignored (SS-2). Do not git add it and do not ship a committed "seed" state.

2. Boot Protocol (Start of Session)

IF .agent/sessions/latest.yaml exists AND you are starting a new session (blank context):

1. READ the file using read_file or view_file.
2. RESTORE your state:
   • Set your internal Mode to the file's mode.
   • Set your TaskName and TaskStatus to the file's current_task.
   • Read the context_summary to understand what you were doing.
   • Check active_blockers to see if you were blocked.

3. Update Protocol (During Work)

First: can you execute at all? This skill is TIER 0 — it loads into every role, including the read-only reviewers and critics (task-reviewer, plan-reviewer, architecture-reviewer, critic-*), which are declared without an execution tool on purpose. If you have no way to run a command, this section does not apply to you: session state is the ORCHESTRATOR's to persist, you have no phase boundary of your own to record, and you should proceed to your actual task. Do not spend your turn attempting the command — a mandatory-sounding instruction that a role cannot satisfy is how a subagent burns its whole turn and returns nothing (skill-parallel-orchestration §2.4).

WHENEVER you call the task_boundary tool, you MUST immediately follow it with a call to the update_state.py script.

Command Syntax

python3 .agent/skills/skill-session-state/scripts/update_state.py \
  --mode "[Mode]" \
  --task "[TaskName]" \
  --status "[TaskStatus]" \
  --summary "[TaskSummary]" \
  --predicted_steps [PredictedTaskSize]

Protocol Rules

1. Sync: The arguments passed to the script MUST match the arguments you just passed to task_boundary.
2. Atomic: Always call task_boundary first, then update_state.py.
3. No Hallucinations: Do not invent values. Use the exact ones from your current context.

4. Task Switching Logic

If you finish one task and start another in the same session:

1. Archive History: Ensure the old docs/TASK.md is archived (via skill-archive-task).
2. Update State: Call task_boundary with the NEW Task Name.
3. Persist & Track:
   • Call update_state.py with the new task details.
   • CRITICAL: Add the flag --add_completed_task "[Old Task Name]" to preserve history.
   • Example: ...scripts/update_state.py ... --add_completed_task "Optimizing Database"
   • This ensures latest.yaml shows: Current Task = UI Bug, Completed = [Database]

5. Advanced Usage

Adding Decisions

If you make a critical decision (e.g., "Chose Redux over Context API"), you can append it to the session log:

python3 ...scripts/update_state.py ... --add_decision "Chose Redux over Context API"

Managing Blockers

• Add Blocker: --add_blocker "Waiting for API key"
• Clear Blockers: --clear_blockers (Use when unblocked)

6. Shared State Protocol (v2 - Concurrent)

For Parallel Agents: When multiple agents run simultaneously, they must NOT overwrite each other's state in latest.yaml.

Locking Mechanism

The update_state.py script now implements Atomic File Locking (fcntl.lockf on Unix).

• Read: Shared Lock (allow others to read).
• Write: Exclusive Lock (wait for others to finish).

Safe Usage Pattern

1. Read State:

   # Pseudo-code
   with FileLock("latest.yaml", "r"):
       state = load()
   

2. Write State:

   # Pseudo-code
   with FileLock("latest.yaml", "w"):
       state = load() # Re-read to get latest
       state.update(my_changes)
       save(state)