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 .octo-continue.md

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.

if [[ -f ".octo-continue.md" ]]; then
    cat ".octo-continue.md"
fi

If .octo-continue.md exists, read it and 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.

Phase 1: Check Project Initialization

Step 1: Verify .octo/ Directory Exists

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

If .octo/ does not exist but .octo-continue.md exists, display the handoff file 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 `.octo/` directory in this project, which means no previous session state exists.

### 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:

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 from STATE.md
grep -A 4 "^## History" .octo/STATE.md | tail -n 3

Expected format:

- [2026-02-02T10:30:00Z] Phase 2: Completed requirements review (complete)
- [2026-02-02T09:15:00Z] Phase 2: Started define phase (in_progress)
- [2026-02-01T16:45:00Z] Phase 1: Completed discovery (complete)

Step 2: Extract Blockers from STATE.md

# Extract blockers section
sed -n '/^## Blockers/,/^## /p' .octo/STATE.md | head -n -1 | tail -n +2

Expected format:

• If blockers exist: List of blocker items
• If no blockers: (none)

Step 3: Read Project Title from PROJECT.md

# Get project title (first H1)
head -n 5 .octo/PROJECT.md | grep "^# " | head -1 | sed 's/^# //'

Phase 5: Display Restoration Summary

Step 1: Build and Display Summary

## Session Restored

**Project:** {project_title from PROJECT.md}
**Last Active:** {last_updated from STATE.md}
**Phase:** {current_phase} - {phase_name}
**Position:** {current_position}
**Status:** {status}

### Where You Left Off

{Last 3 entries from STATE.md history}

### Current Blockers

{Blockers from STATE.md or "None"}

### Ready to Continue

{Intelligent suggestion based on status - see routing table below}

Step 2: Map Phase Number to Name

Phase 6: Intelligent Routing

Step 1: Route Based on Status

Step 2: Phase-Specific Guidance (for in_progress status)

Phase 1 (Discover):

Continue research and exploration.
- Use `/octo:research [topic]` for multi-AI research
- Use `/octo:debate [question]` for decision support
- Check `.octo/phases/phase1/` for research notes

Phase 2 (Define):

Continue requirements clarification.
- Use `/octo:prd` to write product requirements
- Use `/octo:define` to refine scope
- Check `.octo/phases/phase2/` for requirements docs

Phase 3 (Develop):

Continue implementation.
- Use `/octo:develop` to build features
- Use `/octo:tdd` for test-driven development
- Check `.octo/phases/phase3/` for implementation plan

Phase 4 (Deliver):

Continue validation and delivery.
- Use `/octo:deliver` for final review
- Use `/octo:security` for security audit
- Use `/octo:ship` to finalize delivery

Example Outputs

Example 1: No Project State Found

## Session Restoration Failed

**No project state found.**

There is no `.octo/` directory in this project, which means no previous session state exists.

### Get Started

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

Example 2: Successful Restoration (In Progress)

## Session Restored

**Project:** User Authentication System
**Last Active:** 2026-02-02T10:30:00Z
**Phase:** 2 - Define
**Position:** define-requirements
**Status:** in_progress

### Where You Left Off

- [2026-02-02T10:30:00Z] Phase 2: Started requirements review (in_progress)
- [2026-02-01T16:45:00Z] Phase 1: Completed discovery (complete)
- [2026-02-01T14:20:00Z] Phase 1: Research synthesis complete (in_progress)

### Current Blockers

None

##