/skill-resume

name: skill-resume
description: "Pick up where you left off from a previous session — use after context resets, compaction, or new conversations"
disable-model-invocation: true

> **Host: Codex CLI** — This skill was designed for Claude Code and adapted for Codex. > Cross-reference commands use installed skill names in Codex rather than `/octo:*` slash commands. > Use the active Codex shell and subagent tools. Do not claim a provider, model, or host subagent is available until the current session exposes it. > For host tool equivalents, see `skills/blocks/codex-host-adapter.md`.

Session Restoration

Overview

Restore context from a previous session and seamlessly continue the workflow where you left off.

**Core principle:** Check state → Load adaptive context → Display restoration summary → Route to appropriate action.

When to Use

**Use this skill when user says:**

• "Resume" or "continue working"
• "Pick up where I left off"
• "What was I doing?"
• "Restore session"
• "Continue from last time"

**Do NOT use for:**

• Starting new projects (use /octo:embrace)
• Checking current status only (use /octo:status)
• Modifying state directly (use octo-state.sh)

The Process

Phase 0: Check Session Handoff File (v9.6.0)

Step 0: Check for the session handoff file

Before checking `.octo/`, look for a session handoff file. This is written automatically by PreCompact and SessionEnd hooks and contains a human-readable summary of the last session. It lives beside the workflow state returned by `octopus state-path`, outside the project checkout. Older releases wrote `.octo-continue.md` into the project root instead; read that copy only when no relocated handoff exists, and never modify, move, or delete it.

HANDOFF_FILE=""
if WORKFLOW_STATE_FILE="$(octopus state-path)" && [[ -n "$WORKFLOW_STATE_FILE" ]]; then
    HANDOFF_FILE="$(dirname "$WORKFLOW_STATE_FILE")/continue.md"
fi
if [[ -n "$HANDOFF_FILE" && -f "$HANDOFF_FILE" ]]; then
    cat "$HANDOFF_FILE"
elif [[ -f ".octo-continue.md" ]]; then
    cat ".octo-continue.md"
fi

**If a handoff file was found**, display its contents to the user as context. Then continue to Phase 1 to load the full state. The handoff file provides a quick overview; `.octo/STATE.md` provides the authoritative state. If the legacy `.octo-continue.md` was shown, tell the user it is no longer updated and can be deleted from the project.

Phase 1: Check Project Initialization

Repository feature recovery

Before looking for a transcript or machine-local `.octo` state, inspect portable feature artifacts:

OCTO_ROOT="${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-${HOME}/.claude-octopus/plugin}}"
python3 "$OCTO_ROOT/scripts/helpers/feature-contract.py" resume --root "$(pwd -P)" --explicit "<feature directory or spec path, empty when omitted>"

An unambiguous feature recovers intent, decisions, open markers and stable completed/pending task IDs from the repository. Historical completion is context and needs fresh verification. Missing raw runtime files are expected. If several unrelated features exist, ask the user to select one; never choose by recency. Pass the selected feature to the existing `agent-resume` orchestrator path. Explicit Claude agent IDs retain transcript continuation.

A feature with a spec only resumes planning. A feature with plan/tasks resumes pending implementation through the same policy, clarification, analysis and wave-validation gates. Run the returned decision batch once through the host's native question tool before the next plan/develop boundary. Keep skipped decisions open.

Step 1: Verify .octo/ Directory Exists

if [[ ! -d ".octo" ]]; then
    echo "No project state found"
    exit 1
fi

**If .octo/ does not exist but Step 0 found a handoff file**, display its contents and offer to start a new session based on that context.

**If neither exists, display:**

## Session Restoration Failed

**No project state found.**

There is no machine-local `.octo/` directory. Check the portable feature artifacts before treating this as a fresh project.

### Get Started

Run `/octo:embrace [your project description]` to start a new project.

**Example:**

/octo:embrace build a REST API with user authentication

This will:
1. Initialize .octo/ directory with STATE.md, PROJECT.md, ROADMAP.md
2. Begin the Double Diamond workflow
3. Create session state you can resume later

**Stop here** - do not proceed to Phase 2.

Phase 2: Read Current State

Step 1: Execute octo-state.sh read_state

./scripts/octo-state.sh read_state

**Expected output format:**

schema=2.0
last_updated=2026-02-02T10:30:00Z
current_phase=2
current_position=define-requirements
status=in_progress

Step 2: Parse State Variables

Extract these key values:

• `current_phase` - Phase number (1-4)
• `current_position` - Description of current position within phase
• `status` - Workflow status (in_progress, blocked, complete, paused, etc.)
• `last_updated` - Timestamp of last state modification

Phase 3: Load Adaptive Context

Step 1: Get Context Tier (Auto Mode)

./scripts/octo-state.sh get_context_tier auto

This automatically selects the appropriate context tier based on current status:

| Status | Tier Selected | Context Loaded | |--------|---------------|----------------| | ready, planned, planning, complete, shipped | planning | STATE.md + PROJECT.md + ROADMAP.md | | building, in_progress | execution | + phase plans + recent summaries | | blocked, paused | execution | + phase plans + recent summaries |

Step 2: Store Context for Reference

The context returned includes:

• Current state details
• Project vision and requirements
• Phase-specific plans and summaries
• Codebase analysis (if brownfield project)

Phase 4: Extract History and Blockers

Step 1: Read Last 3 History Entries from STATE.md

# Extract history section fr