kickstart

name

kickstart

description

Initialize session from handoff document with context restore, file loading, environment verification. Use when user says /kickstart, load handoff, start from handoff, begin from handoff, resume from handoff, restore session, reload context, session init, fresh session, new session from handoff, continue from handoff, pick up where I left off, kickstart session. Reads handoff-*.md files created by /handoff skill. Verifies git branch, working directory, loads @file references, presents instructions summary.

Kickstart

Initialize a new session from a handoff document created by /handoff.

Core Principles

Context maximization: Clear conversation before loading to give handoff files maximum context budget Graceful degradation: Warn on mismatches but proceed — user decides whether to fix Companion to /handoff: Complete context handoff workflow: /handoff creates, /kickstart restores

Usage

/kickstart [path-to-handoff.md]
/kickstart                        # Uses most recent handoff-*.md in cwd

Examples:

• /kickstart handoff-oauth-tests-20260207.md
• /kickstart (auto-finds latest handoff file)

Execution

Step 0: Clear Context

Ask user to run /clear to flush conversation context. Wait for confirmation before proceeding.

Example prompt:

Before loading the handoff, please run /clear to free up context space.
Let me know when done and I'll continue.

Step 1: Find Handoff File

If path provided: Use that file directly.

If no path provided: Find most recent handoff file in the current working directory:

find . -maxdepth 1 -name 'handoff-*.md' -print0 | xargs -0 ls -t 2>/dev/null | head -1

If no handoff file found, report error:

No handoff file found. Specify a path or ensure handoff-*.md exists in the current directory.

Step 2: Read and Parse Handoff Document

Read the handoff file and extract these sections:

• Session Metadata (HTML comment): Parent session ID, creation timestamp, project path
• Prompt: The goal/task for this session
• Instructions: Context bullet points
• Relevant Files: @file references to load
• Git Context: Branch, uncommitted files, recent commits
• Working Directory: Expected working directory

If required sections (Prompt, Relevant Files) are missing, warn but proceed:

Warning: Handoff file appears incomplete. Missing sections: Prompt
Proceeding with available information...

Step 3: Verify Environment

Run these checks in order (directory first, then git state):

Working Directory Check:

• Compare current working directory with handoff's Working Directory

• If different, warn:

  Warning: Working directory mismatch:
     Expected: /Users/dev/workspace/auth-service
     Current:  /Users/dev
  
  Consider: cd /Users/dev/workspace/auth-service
  

Git Branch Check:

• Run git branch --show-current to get current branch

• Compare with handoff's Git Context branch

• If different, warn:

  Warning: Git branch mismatch:
     Expected: fix/oauth-refresh-tests
     Current:  main
  
  Consider: git checkout fix/oauth-refresh-tests
  

Uncommitted Changes Check:

• Run git status --porcelain | wc -l to count uncommitted files
• If count differs significantly from handoff, note it (informational only)

Step 4: Load Context Files

For each @file in the Relevant Files section:

• Read the file using the Read tool
• If a file exceeds 500 lines, read only the first 200 lines and note the truncation
• Track results: files loaded successfully vs. files that failed (moved/deleted)
• If a file fails to load, log a warning and continue with remaining files

Report loading summary:

Loaded 4/5 files (1 not found: @src/auth/old-file.ts)

Step 5: Present Instructions

Read the Instructions section and present key context points as part of the initialization summary. These provide context about:

• What was being worked on
• Key decisions made
• Important constraints or requirements
• Blockers or issues discovered

Step 6: Confirm Ready

Output session initialization summary:

Session initialized from handoff-oauth-tests-20260207.md

Goal: Fix the failing OAuth token refresh tests in the authentication module

Context loaded:
- 5 instruction points
- 4/4 files loaded

Environment:
- Working directory: matches
- Git branch: fix/oauth-refresh-tests

Parent session: abc123-def456-session-id
Handoff created: 2026-02-07T14:30:00Z

Ready to begin. What's the first step?

If there were warnings (directory mismatch, branch mismatch, missing files), include them before "Ready to begin".

Error Handling

Handoff File Not Found:

Handoff file not found: handoff-missing.md

Try:
- Check the filename spelling
- Run: ls handoff-*.md to see available handoff files
- Run /kickstart without arguments to use the most recent handoff

Files No Longer Exist:

Warning: Some files from handoff no longer exist:
- @src/auth/old-file.ts (not found)

Loaded 3 of 4 files successfully.

Notes

• Companion to /handoff for a complete context handoff workflow
• Session metadata enables tracing session genealogy (parent -> child sessions)
• Environment checks are warnings only — user decides whether to switch directories/branches
• If running /kickstart in a fresh terminal, you may need to cd to the project first
• Files over 500 lines are partially loaded (first 200 lines) to avoid overwhelming context

Success Criteria

• Handoff file located and parsed successfully
• All required sections extracted (Prompt, Instructions, Relevant Files, Git Context)
• Environment verified (working directory, git branch, uncommitted changes)
• Context files loaded (with warnings for missing files)
• Initialization summary presented with goal, context count, and environment status
• User informed of any mismatches or warnings before starting work

Self-Improvement

Update triggers:

• New handoff format fields added by /handoff skill (keep parser in sync)
• Common failure patterns during kickstart (add to Error Handling)
• User feedback on missing context after kickstart (improve file loading strategy)

Discoveries: