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:-${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 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	Name
1	Discover
2	Define
3	Develop
4	Deliver

Phase 6: Intelligent Routing

Step 1: Route Based on Status

Status	Action	Message
in_progress	Continue current phase	"Continue with current phase. Context loaded."
blocked	Review blockers	"Review blockers first: /octo:issues"
complete	Ready for next phase	"Phase complete. Ready for /octo:ship"
paused	Resume project	"Project paused. Resume with /octo:embrace"
ready	Begin workflow	"Ready to begin. Run /octo:embrace to start."
planning	Continue planning	"Continue planning. Use /octo:define to refine."
building	Continue building	"Continue implementation. Use /octo:develop."
shipped	Project delivered	"Project delivered! Review lessons in LESSONS.md."
complete_with_gaps	Review gaps	"Phase complete with gaps. Review ISSUES.md before proceeding."

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

### Ready to Continue

Continue with current phase. Context loaded.

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

Example 3: Blocked Project Restoration

## Session Restored

**Project:** E-commerce Platform
**Last Active:** 2026-02-01T18:00:00Z
**Phase:** 3 - Develop
**Position:** implement-payment-gateway
**Status:** blocked

### Where You Left Off

- [2026-02-01T18:00:00Z] Phase 3: Payment integration blocked (blocked)
- [2026-02-01T15:30:00Z] Phase 3: Started payment gateway integration (in_progress)
- [2026-02-01T12:00:00Z] Phase 3: Completed user auth implementation (complete)

### Current Blockers

- Missing Stripe API credentials
- Payment webhook endpoint not configured
- SSL certificate pending for payment domain

### Ready to Continue

Review blockers first: `/octo:issues`

**To unblock:**
1. Configure Stripe API credentials in environment
2. Set up webhook endpoint at /api/webhooks/stripe
3. Complete SSL certificate setup for payments subdomain

Example 4: Paused Project Restoration

## Session Restored

**Project:** Data Analytics Dashboard
**Last Active:** 2026-01-28T09:00:00Z
**Phase:** 2 - Define
**Position:** requirements-gathering
**Status:** paused

### Where You Left Off

- [2026-01-28T09:00:00Z] Phase 2: Project paused by user (paused)
- [2026-01-27T16:00:00Z] Phase 2: Stakeholder feedback pending (in_progress)
- [2026-01-27T10:00:00Z] Phase 1: Discovery complete (complete)

### Current Blockers

- Waiting for stakeholder availability

### Ready to Continue

Project paused. Resume with `/octo:embrace`

When ready to continue:
1. Review `.octo/PROJECT.md` for project context
2. Check `.octo/STATE.md` for pause reason
3. Run `/octo:embrace` to resume workflow

Best Practices

1. Always Use octo-state.sh for State Reading

Good:

./scripts/octo-state.sh read_state
./scripts/octo-state.sh get_context_tier auto

Poor:

# Parse STATE.md manually
grep "Current Phase" .octo/STATE.md

2. Provide Full Context Restoration

Good:

• Load adaptive context tier
• Show last 3 history entries
• Display any blockers
• Give phase-specific guidance

Poor:

• Only show current phase
• Ignore history
• No next steps

3. Route Intelligently Based on Status

Good:

Status: blocked → "Review blockers first: /octo:issues"

Poor:

Status: blocked → "Continue working"

Red Flags - Don't Do This

Action	Why It's Wrong
Skip .octo/ existence check	Will fail with confusing errors
Ignore blockers on resume	User won't know why they stopped
Restart from beginning	Loses all previous context and progress
Skip history display	User loses continuity of what was done
Use hardcoded context tier	Should adapt based on current status

Integration with Other Skills

With /octo:status

/octo:resume → Full restoration with context
/octo:status → Quick dashboard without restoration

With /octo:embrace

No .octo/ exists → /octo:resume suggests /octo:embrace
.octo/ exists but paused → /octo:resume suggests resuming with /octo:embrace

With flow-* skills

User runs /octo:resume
→ Context restored
→ User continues with /octo:develop (or appropriate phase skill)

Quick Reference

User Input	Action Required
"resume"	Resolve state with octopus state-path → Load context → Display summary → Route
"continue"	Same as resume
"pick up where I left off"	Same as resume
"what was I doing"	Same as resume, emphasize history
"restore session"	Same as resume

The Bottom Line

Run `octopus state-path` → Read state → Load adaptive context → Show history + blockers → Route intelligently
Otherwise → User loses previous context and wastes time re-discovering where they were

Never restart from beginning if state exists. Restore context, show history, route intelligently.

Context Recovery After Compaction

When context is cleared (compaction, plan mode exit, new session), detect and reload automatically:

# Auto-detect context loss without writing into the project checkout.
# The plugin executable resolves its own installation root on every host.
if ! WORKFLOW_STATE_FILE="$(octopus state-path)" || [[ -z "$WORKFLOW_STATE_FILE" ]]; then
    echo "Unable to resolve persistent workflow state; refusing an incomplete resume." >&2
    exit 1
fi
if [[ -f "$WORKFLOW_STATE_FILE" ]] && [[ -z "${WORKFLOW_CONTEXT_LOADED}" ]]; then
    echo "⚠️  Context was cleared — reloading from persistent state..."
    NEEDS_RESUME=true
fi

What survives context clearing:

• Host-workspace project state (decisions, context, metrics; resolve with octopus state-path)
• context/*.md beside the path returned by octopus state-path (phase outputs)
• Native tasks (TaskList still works)
• Git commits and WIP checkpoints
• Multi-AI synthesis files in ~/.claude-octopus/results/

After resume completes, set export WORKFLOW_CONTEXT_LOADED=true to prevent duplicate reloads.

State persists in files. Context clearing is not a problem. Files outlive memory.